# Axis 类必须属性

`Axis` 是 PLCopen 运动控制库的核心仿真类，实现 IEC 61131-3 单轴状态机与运动学。

## 设计决策

### 可见性：运动学属性为 `private`

功能块不直接读写轴内部状态，而是通过 `AXIS_REF` 调用公开接口。这是 IEC 61131-3 的标准模式——轴是功能块黑盒：

```
功能块 (MC_MoveAbsolute)           Axis
─────────────────────           ─────────────
  AXIS_REF → axis                 private:  position_, velocity_, ...
  axis.acceptCommand(cmd) ──────→ 只有 cycle() 能写运动学数据
  axis.readActualPosition() ←─── public:  getter 只读
```

> 运动控制线程定时调用 `cycle()` 独占写权限，避免数据竞争。

### 数值类型：浮点 `REAL` (double)

遵循 IEC 61131-3 / PLCopen 规范，使用 `double` 表示物理量（mm、°/s 等）。`double` 有 52 位尾数（约 15 位十进制有效数字），以 10ms 周期运行 1 小时，累积的浮点舍入误差在 $10^{-10}$ 量级，工程上可完全忽略。若未来对接真实驱动器，在数据交换层做脉冲数换算即可。

---

## 1. 当前已实现

### 1.1 轴标识与自引用 — `AXIS_REF _ref` (private)

| 字段 | 类型 | 说明 |
|------|------|------|
| `axisNo` | `UINT` | 轴编号，由用户在构造时指定，默认 1 |
| `axisName` | `std::string` | 轴名称，默认 `"Axis1"` |
| `axis` | `Axis*` | 指向自身实例的指针，供功能块间接访问轴对象 |

### 1.2 轴状态 — `MC_AXIS_STATE _state` (private)

当前状态，初始值 `Disabled`。新增辅助状态 `_resultingState` 用于记录指令完成后的目标状态。

状态转换由 `cycle()` 方法驱动（逻辑待实现）。

### 1.3 运动学属性 (private) ✅

`cycle()` 独占写入；外部通过 `readXxx()` 只读访问。

| 属性 | 类型 | 说明 |
|------|------|------|
| `_position` | `REAL` | 当前指令位置 |
| `_actualPosition` | `REAL` | 当前实际位置（含跟随误差仿真） |
| `_velocity` | `REAL` | 当前指令速度 |
| `_actualVelocity` | `REAL` | 当前实际速度 |
| `_acceleration` | `REAL` | 当前指令加速度 |
| `_actualAcceleration` | `REAL` | 当前实际加速度 |
| `_deceleration` | `REAL` | 减速度（尚未添加） |

### 1.4 功率与使能 (private) ✅

| 属性 | 类型 | 说明 |
|------|------|------|
| `_powerEnabled` | `BOOL` | 功率级是否使能 |
| `_homed` | `BOOL` | 是否已完成回零 |

### 1.5 错误管理 (private) ✅

| 属性 | 类型 | 说明 |
|------|------|------|
| `_errorId` | `MC_ERROR_ID` | 当前错误码，`mcNoError` 表示正常 |
| `_errorStop` | `BOOL` | 是否触发错误停止 |

### 1.6 构造函数 & cycle() (public)

```cpp
explicit Axis(UINT axisNo = 1, std::string name = "Axis1");
void cycle();   // 骨架已生成，逻辑待实现
```

初始化 `_ref` 并自绑定 `axis` 指针，`_state` 默认 `Disabled`。

---

## 2. 待实现的属性与方法

### 2.1 活动指令 — `MotionCommand _activeCommand` (private)

当前正在执行的运动指令参数快照，类型为 `MotionCommand`：

| 字段 | 类型 | 说明 |
|------|------|------|
| `type` | `MotionCommandType` | 指令类型（点到点 / 速度 / 停止 / 暂停 / 回零） |
| `targetPosition` | `REAL` | 目标位置 |
| `targetVelocity` | `REAL` | 目标速度 |
| `maxVelocity` | `REAL` | 最大速度 |
| `acceleration` | `REAL` | 加速度 |
| `deceleration` | `REAL` | 减速度 |
| `homePosition` | `REAL` | 回零位置 |
| `resultingState` | `MC_AXIS_STATE` | 指令完成后要进入的状态 |

### 2.2 待补充的运动学属性

| 属性 | 说明 |
|------|------|
| `_deceleration` | 减速度（已有 `_acceleration`，缺独立减速参数） |

### 2.3 轴状态机方法 — `cycle()` (public, 实现待完成)

```cpp
void cycle();
```

每周期由运动控制线程调用，待实现逻辑：
1. 根据 `_activeCommand` 计算运动学输出
2. 更新 `_position` / `_velocity` 等
3. 评估状态转换条件
4. 在离散运动到达目标时自动切换到 `Standstill`

### 2.4 功能块交互接口 (public, 全部待实现)

| 方法 | 可见性 | 说明 |
|------|--------|------|
| `acceptCommand(const MotionCommand&)` | public | 接收功能块下发的运动指令 |
| `doPower(BOOL enable)` | public | 功率使能/去使能 |
| `doStop()` / `doHalt()` | public | 停止 / 暂停 |
| `doReset()` | public | 从 ErrorStop 恢复 |
| `doHome(REAL homePos)` | public | 发起回零 |
| `readStatus()` | public | 读取当前状态快照 |
| `readActualPosition()` | public | 读取实际位置 |
| `readActualVelocity()` | public | 读取实际速度 |
| `readError()` | public | 读取当前错误码 |

---

## 3. 完整属性清单

```
                                    private
                                    ───────
Axis
├── _ref              (AXIS_REF)       ✅
├── _state            (MC_AXIS_STATE)  ✅
├── _resultingState   (MC_AXIS_STATE)  ✅ 指令完成目标状态
├── _position         (REAL)           ✅
├── _actualPosition   (REAL)           ✅
├── _velocity         (REAL)           ✅
├── _actualVelocity   (REAL)           ✅
├── _acceleration     (REAL)           ✅
├── _actualAcceleration (REAL)         ✅
├── _deceleration     (REAL)           ⬜ 待添加
├── _powerEnabled     (BOOL)           ✅
├── _homed            (BOOL)           ✅
├── _errorId          (MC_ERROR_ID)    ✅
├── _errorStop        (BOOL)           ✅
└── _activeCommand    (MotionCommand)  ⬜ 活动指令

                                    public
                                    ──────
    Axis(axisNo, name)                 ✅
    cycle()                            🟡 骨架已就绪
    acceptCommand(cmd)                 ⬜
    doPower / doStop / doHalt          ⬜
    doReset / doHome                   ⬜
    readStatus / readActualPosition    ⬜
    readActualVelocity / readError     ⬜
```