LinuxMotion/docs/design/MC_Power.md

# MC_Power 功能块设计

`MC_Power` 是 PLCopen 运动控制库的基础功能块，控制轴的功率级使能与去使能。

---

## 1. IEC 61131-3 接口定义

```
FUNCTION_BLOCK MC_Power
    VAR_IN_OUT
        Axis : AXIS_REF;              (* 轴引用 *)
    END_VAR
    VAR_INPUT
        Enable          : BOOL;       (* TRUE=使能, FALSE=去使能 *)
        Enable_Positive : BOOL;       (* 允许正向运动，本库保留 *)
        Enable_Negative : BOOL;       (* 允许负向运动，本库保留 *)
    END_VAR
    VAR_OUTPUT
        Status          : BOOL;       (* 轴已使能且就绪 *)
        Busy            : BOOL;       (* 功能块正在处理中 *)
        Error           : BOOL;       (* 错误标志 *)
        ErrorID         : MC_ERROR_ID;(* 错误码 *)
    END_VAR
```

## 2. C++ 类实现

### 2.1 类声明 — `MotionLib/Inc/MC_Power.h`

```cpp
#pragma once
#include "Types.h"

namespace plcopen {

class MC_Power {
public:
    /**
     * \brief 构造 MC_Power 实例
     * \param axisRef 轴引用 (VAR_IN_OUT)
     */
    explicit MC_Power(AXIS_REF& axisRef);

    /**
     * \brief 周期调用，执行功率控制逻辑
     *
     * 上位机每个运动控制周期调用一次。
     */
    void cycle();

    // --- 输入参数 (VAR_INPUT) ---
    BOOL Enable          = false;
    BOOL Enable_Positive = true;   // 本库默认允许
    BOOL Enable_Negative = true;   // 本库默认允许

    // --- 输出参数 (VAR_OUTPUT) ---
    BOOL Status          = false;
    BOOL Busy            = false;
    BOOL Error           = false;
    MC_ERROR_ID ErrorID  = MC_ERROR_ID::mcNoError;

private:
    AXIS_REF& _axisRef;             // 轴引用，不持有所有权
    bool _prevEnable = false;       // 上一周期的 Enable 值（边沿检测）
};

} // namespace plcopen
```

### 2.2 实现 — `MotionLib/Src/MC_Power.cpp`

```cpp
#include "MC_Power.h"
#include "Axis.h"

namespace plcopen {

MC_Power::MC_Power(AXIS_REF& axisRef)
    : _axisRef(axisRef) {}

void MC_Power::cycle() {
    // ① 有效性检查
    if (_axisRef.axis == nullptr) {
        Error = true;
        ErrorID = MC_ERROR_ID::mcInvalidParameter;
        Status = false;
        Busy = false;
        return;
    }

    Axis* axis = _axisRef.axis;
    Error   = false;
    ErrorID = MC_ERROR_ID::mcNoError;

    // ② Enable 上升沿 — 使能
    if (Enable && !_prevEnable) {
        axis->doPower(true);
        Busy = true;
    }

    // ③ Enable 下降沿 — 去使能
    if (!Enable && _prevEnable) {
        axis->doPower(false);
        Busy = false;
    }

    // ④ 持续使能状态 — 等待轴进入 Standstill
    if (Enable) {
        MC_AXIS_STATE state = axis->readState();

        if (state == MC_AXIS_STATE::Standstill) {
            Busy   = false;
            Status = true;        // 使能成功
        } else if (state == MC_AXIS_STATE::ErrorStop) {
            Busy   = false;
            Status = false;
            Error  = true;
            ErrorID = MC_ERROR_ID::mcPowerFailure;
        }
    } else {
        // 去使能后
        Status = false;
        Busy   = false;
    }

    // ⑤ 保存前置状态
    _prevEnable = Enable;
}

} // namespace plcopen
```

## 3. 行为时序

```
周期 | Enable | axis 状态      | Status | Busy | 说明
─────┼────────┼───────────────┼────────┼──────┼────────────────
  0  | FALSE  | Disabled      | FALSE  | FALSE| 初始状态
  1  | TRUE ↑ | Disabled      | FALSE  | TRUE | 上升沿，doPower(true)
  2  | TRUE   | Disabled      | FALSE  | TRUE | cycle() 待处理
  3  | TRUE   | Standstill    | TRUE   | FALSE| 使能完成 ✅
  4  | FALSE ↓| Standstill    | FALSE  | FALSE| 下降沿，doPower(false)
  5  | FALSE  | Disabled      | FALSE  | FALSE| 去使能完成
```

## 4. 与 Axis 的交互

```
MC_Power                          Axis
────────                          ────
  cycle()
    │
    ├── Enable↑ → axis->doPower(true) ──→ _powerEnabled = true
    │                                       _state 将在 cycle() 中切换
    │
    ├── Enable↓ → axis->doPower(false) ──→ _powerEnabled = false
    │                                        _state → Disabled
    │
    └── axis->readState() ←────────────── 读取 _state
         axis->readError() ←───────────── 读取 _errorId
```

## 5. Axis 侧需要的新方法

```cpp
// Axis.h — 新增方法

class Axis {
public:
    void doPower(BOOL enable);       // 功率使能控制
    MC_AXIS_STATE readState() const; // 读当前状态
    MC_ERROR_ID  readError() const;  // 读当前错误码
};
```

## 6. 设计要点

| 要点 | 说明 |
|------|------|
| 不持有 Axis | `_axisRef` 是引用，MC_Power 不负责轴的生命周期 |
| 上升/下降沿检测 | `_prevEnable` 确保 doPower() 只在边沿调用一次 |
| Busy 的语义 | 从 Enable↑ 到 Status=TRUE 之间为 Busy |
| Error 路径 | 轴进入 ErrorStop 时，Status→FALSE，Error→TRUE |
| Enable_Positive/Negative | IEC 完整规范字段，本库保留输入但暂不实现逻辑 |