LinuxMotion/docs/design/Axis-Attributes.md

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)

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, 实现待完成)

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     ⬜