【技术文档】ZMotion - 运动控制模块

## 概述
`ZMotion` 是准易科技 VisionGroup 3 (VG3) 视觉平台提供的 Lua 运动控制模块。该模块封装了与 ZMotion 运动控制器（PLC）的通信接口，支持多轴参数配置、点位运动、输入输出控制、任务调度、寄存器读写等功能，为 Lua 脚本提供完整的运动控制能力。

## Lua API 函数列表

### 1. 连接与安全
| Lua 函数 | 参数 | 返回值 | 说明 |
|----------|------|--------|------|
| `ZMotion:ConnectState(mIndex)` | `mIndex`: 控制器索引（整数） | `int` | 连接状态（0 未连接，1 已连接） |
| `ZMotion:Emergency(mIndex)` | `mIndex`: 控制器索引（整数） | `int` | 紧急停止（所有轴） |
| `ZMotion:Rapidstop(mIndex, val)` | `mIndex`: 控制器索引（整数） `val`: 停止值（整数） | `int` | 快速停止（所有轴停止运动） |

### 2. 轴参数设置
| Lua 函数 | 参数 | 返回值 | 说明 |
|----------|------|--------|------|
| `ZMotion:SetAtype(mIndex, aIndex, val)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 轴类型值（整数） | `int` | 设置轴类型 |
| `ZMotion:SetAxisEnable(mIndex, aIndex, val)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 使能状态（整数） | `int` | 启用/禁用轴 |
| `ZMotion:SetUnits(mIndex, aIndex, val)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 脉冲当量（浮点数） | `int` | 设置脉冲当量（单位: 脉冲/单位） |
| `ZMotion:SetSpeed(mIndex, aIndex, val)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 速度值（浮点数） | `int` | 设置轴速度（单位: units/s） |
| `ZMotion:SetAccel(mIndex, aIndex, val)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 加速度值（浮点数） | `int` | 设置轴加速度（单位: units/s²） |
| `ZMotion:SetDecel(mIndex, aIndex, val)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 减速度值（浮点数） | `int` | 设置轴减速度（单位: units/s²） |
| `ZMotion:SetSramp(mIndex, aIndex, val)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: S曲线时间（浮点数） | `int` | 设置 S 曲线时间（单位: ms，梯形加减速） |
| `ZMotion:SetLspeed(mIndex, aIndex, val)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 低速值（浮点数） | `int` | 设置低速（单位: units/s） |
| `ZMotion:setSpeedVals(mIndex, aIndex, valSpeed, valAcc, valDec)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `valSpeed`: 速度值（浮点数） `valAcc`: 加速度值（浮点数） `valDec`: 减速度值（浮点数） | `int` | 同时设置速度、加速度、减速度 |

### 3. 轴参数读取
| Lua 函数 | 参数 | 返回值 | 说明 |
|----------|------|--------|------|
| `ZMotion:GetAtype(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `int` | 获取轴类型 |
| `ZMotion:GetAxisEnable(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `int` | 获取轴使能状态 |
| `ZMotion:GetUnits(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `float` | 获取脉冲当量 |
| `ZMotion:GetSpeed(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `float` | 获取轴速度 |
| `ZMotion:GetAccel(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `float` | 获取轴加速度 |
| `ZMotion:GetDecel(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `float` | 获取轴减速度 |
| `ZMotion:GetSramp(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `float` | 获取 S 曲线时间 |
| `ZMotion:GetLspeed(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `float` | 获取低速 |

### 4. 限位与输入设置
| Lua 函数 | 参数 | 返回值 | 说明 |
|----------|------|--------|------|
| `ZMotion:SetFsLimit(mIndex, aIndex, val)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 限位位置（浮点数） | `int` | 设置正向软限位位置 |
| `ZMotion:SetRsLimit(mIndex, aIndex, val)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 限位位置（浮点数） | `int` | 设置负向软限位位置 |
| `ZMotion:SetDatumIn(mIndex, aIndex, val, validState)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 输入信号（整数） `validState`: 有效电平（整数） | `int` | 设置原点输入信号及有效电平 |
| `ZMotion:SetFwdIn(mIndex, aIndex, val, validState)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 输入信号（整数） `validState`: 有效电平（整数） | `int` | 设置正向限位输入信号及有效电平 |
| `ZMotion:SetRevIn(mIndex, aIndex, val, validState)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 输入信号（整数） `validState`: 有效电平（整数） | `int` | 设置负向限位输入信号及有效电平 |
| `ZMotion:SetAlmIn(mIndex, aIndex, val, validState)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 输入信号（整数） `validState`: 有效电平（整数） | `int` | 设置轴报警输入信号及有效电平 |

### 5. 限位与输入读取
| Lua 函数 | 参数 | 返回值 | 说明 |
|----------|------|--------|------|
| `ZMotion:GetFsLimit(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `float` | 获取正向软限位位置 |
| `ZMotion:GetRsLimit(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `float` | 获取负向软限位位置 |
| `ZMotion:GetDatumIn(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `int` | 获取原点输入状态 |
| `ZMotion:GetFwdIn(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `int` | 获取正向限位输入状态 |
| `ZMotion:GetRevIn(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `int` | 获取负向限位输入状态 |
| `ZMotion:GetAlmIn(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `int` | 获取轴报警输入状态 |

### 6. 回零参数
| Lua 函数 | 参数 | 返回值 | 说明 |
|----------|------|--------|------|
| `ZMotion:SetCreep(mIndex, aIndex, val)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 爬行速度（浮点数） | `int` | 设置回零爬行速度 |
| `ZMotion:SetHomeWait(mIndex, aIndex, val)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 等待时间（整数） | `int` | 设置回零等待时间 |
| `ZMotion:GetCreep(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `float` | 获取回零爬行速度 |
| `ZMotion:GetHomeWait(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `int` | 获取回零等待时间 |

### 7. 轴状态查询
| Lua 函数 | 参数 | 返回值 | 说明 |
|----------|------|--------|------|
| `ZMotion:AxisHomeState(mIndex, axis)` | `mIndex`: 控制器索引（整数） `axis`: 轴索引（整数） | `int` | 轴回零状态（0 未回零，1 已回零） |
| `ZMotion:AxisMoveState(mIndex, axis)` | `mIndex`: 控制器索引（整数） `axis`: 轴索引（整数） | `int` | 轴运动状态（0 停止，1 运动中） |
| `ZMotion:AxisState(mIndex, axis)` | `mIndex`: 控制器索引（整数） `axis`: 轴索引（整数） | `int` | 轴综合状态（位掩码） |

### 8. 轴运动控制
| Lua 函数 | 参数 | 返回值 | 说明 |
|----------|------|--------|------|
| `ZMotion:AxisStop(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `int` | 停止指定轴运动 |
| `ZMotion:AxisVMove(mIndex, axis, direction)` | `mIndex`: 控制器索引（整数） `axis`: 轴索引（整数） `direction`: 方向（整数，0 负向，1 正向） | `int` | 持续运动 |
| `ZMotion:AxisMove(mIndex, axis, distance)` | `mIndex`: 控制器索引（整数） `axis`: 轴索引（整数） `distance`: 相对距离（浮点数） | `int` | 相对运动（单位: units） |
| `ZMotion:AxisMoveAbs(mIndex, axis, toLoction)` | `mIndex`: 控制器索引（整数） `axis`: 轴索引（整数） `toLoction`: 目标位置（浮点数） | `int` | 绝对运动（单位: units） |
| `ZMotion:AxisMoveHome(mIndex, aIndex, modeTyep)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `modeTyep`: 回零模式（整数） | `int` | 回零运动（模式由 modeTyep 指定） |

### 9. 位置读写
| Lua 函数 | 参数 | 返回值 | 说明 |
|----------|------|--------|------|
| `ZMotion:GetDpos(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `float` | 读取理论位置（单位: units） |
| `ZMotion:SetDpos(mIndex, aIndex, val)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 理论位置值（浮点数） | `int` | 设置理论位置（单位: units） |
| `ZMotion:GetMpos(mIndex, aIndex)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） | `float` | 读取实际位置（单位: units） |
| `ZMotion:SetMpos(mIndex, aIndex, val)` | `mIndex`: 控制器索引（整数） `aIndex`: 轴索引（整数） `val`: 实际位置值（浮点数） | `int` | 设置实际位置（单位: units） |

### 10. 输入输出控制
| Lua 函数 | 参数 | 返回值 | 说明 |
|----------|------|--------|------|
| `ZMotion:SetOut(mIndex, address, val)` | `mIndex`: 控制器索引（整数） `address`: 输出地址（整数） `val`: 输出值（整数） | `int` | 设置单个输出点 |
| `ZMotion:SetOuts(mIndex, address, vals)` | `mIndex`: 控制器索引（整数） `address`: 起始地址（整数） `vals`: 输出值数组（数组） | `int` | 设置连续多个输出点 |
| `ZMotion:GetOut(mIndex, address)` | `mIndex`: 控制器索引（整数） `address`: 输出地址（整数） | `int` | 读取单个输出点状态 |
| `ZMotion:GetIn(mIndex, address)` | `mIndex`: 控制器索引（整数） `address`: 输入地址（整数） | `int` | 读取单个输入点状态 |
| `ZMotion:GetOuts(mIndex, address, length)` | `mIndex`: 控制器索引（整数） `address`: 起始地址（整数） `length`: 读取长度（整数） | `数组` | 读取连续多个输出点状态 |
| `ZMotion:GetIns(mIndex, address, length)` | `mIndex`: 控制器索引（整数） `address`: 起始地址（整数） `length`: 读取长度（整数） | `数组` | 读取连续多个输入点状态 |

### 11. 任务控制
| Lua 函数 | 参数 | 返回值 | 说明 |
|----------|------|--------|------|
| `ZMotion:GetTaskState(mIndex, taskIndex)` | `mIndex`: 控制器索引（整数） `taskIndex`: 任务索引（整数） | `int` | 获取任务状态（0 停止，1 运行） |
| `ZMotion:StopTask(mIndex, taskIndex)` | `mIndex`: 控制器索引（整数） `taskIndex`: 任务索引（整数） | `int` | 停止指定任务 |
| `ZMotion:StartTaskString(mIndex, taskIndex, funcInfo)` | `mIndex`: 控制器索引（整数） `taskIndex`: 任务索引（整数） `funcInfo`: 任务命令字符串（字符串） | `int` | 启动任务并执行字符串命令 |
| `ZMotion:CallTaskString(mIndex, taskIndex, timeout, funcInfo)` | `mIndex`: 控制器索引（整数） `taskIndex`: 任务索引（整数） `timeout`: 超时时间（整数） `funcInfo`: 任务命令字符串（字符串） | `int` | 调用任务并等待返回（状态码） |
| `ZMotion:CallFloatTaskString(mIndex, taskIndex, timeout, retName, funcInfo)` | `mIndex`: 控制器索引（整数） `taskIndex`: 任务索引（整数） `timeout`: 超时时间（整数） `retName`: 返回值名称（字符串） `funcInfo`: 任务命令字符串（字符串） | `float` | 调用任务并等待返回浮点值 |
| `ZMotion:CallStringTaskString(mIndex, taskIndex, timeout, retName, retLen, funcInfo)` | `mIndex`: 控制器索引（整数） `taskIndex`: 任务索引（整数） `timeout`: 超时时间（整数） `retName`: 返回值名称（字符串） `retLen`: 返回字符串长度（整数） `funcInfo`: 任务命令字符串（字符串） | `字符串` | 调用任务并等待返回字符串 |

### 12. 寄存器读写（VR）
| Lua 函数 | 参数 | 返回值 | 说明 |
|----------|------|--------|------|
| `ZMotion:SetVR(mIndex, vrIndex, val)` | `mIndex`: 控制器索引（整数） `vrIndex`: VR寄存器索引（整数） `val`: 寄存器值（浮点数） | `int` | 设置单个 VR 寄存器值 |
| `ZMotion:GetVR(mIndex, vrIndex)` | `mIndex`: 控制器索引（整数） `vrIndex`: VR寄存器索引（整数） | `float` | 读取单个 VR 寄存器值 |
| `ZMotion:SetMulVR(mIndex, vrIndex, val)` | `mIndex`: 控制器索引（整数） `vrIndex`: 起始VR寄存器索引（整数） `val`: 寄存器值数组（数组） | `int` | 设置连续多个 VR 寄存器值 |
| `ZMotion:GetMulVR(mIndex, vrIndex, num)` | `mIndex`: 控制器索引（整数） `vrIndex`: 起始VR寄存器索引（整数） `num`: 读取数量（整数） | `数组` | 读取连续多个 VR 寄存器值 |

### 13. 其他类型寄存器
| Lua 函数 | 参数 | 返回值 | 说明 |
|----------|------|--------|------|
| `ZMotion:SetBit(mIndex, modIndex, val)` | `mIndex`: 控制器索引（整数） `modIndex`: 位寄存器索引（整数） `val`: 位值（布尔值） | `int` | 设置位寄存器值 |
| `ZMotion:GetBit(mIndex, modIndex)` | `mIndex`: 控制器索引（整数） `modIndex`: 位寄存器索引（整数） | `int` | 读取位寄存器值 |
| `ZMotion:SetUShortMod(mIndex, vrIndex, val)` | `mIndex`: 控制器索引（整数） `vrIndex`: 寄存器索引（整数） `val`: 无符号短整型值（整数） | `int` | 设置无符号短整型寄存器 |
| `ZMotion:GetUShortMod(mIndex, vrIndex)` | `mIndex`: 控制器索引（整数） `vrIndex`: 寄存器索引（整数） | `整数` | 读取无符号短整型寄存器 |
| `ZMotion:SetMulUShortMod(mIndex, vrIndex, val)` | `mIndex`: 控制器索引（整数） `vrIndex`: 起始寄存器索引（整数） `val`: 值数组（数组） | `int` | 设置连续多个无符号短整型寄存器 |
| `ZMotion:GetMulUShortMod(mIndex, vrIndex, num)` | `mIndex`: 控制器索引（整数） `vrIndex`: 起始寄存器索引（整数） `num`: 读取数量（整数） | `数组` | 读取连续多个无符号短整型寄存器 |
| `ZMotion:SetIntMod(mIndex, vrIndex, val)` | `mIndex`: 控制器索引（整数） `vrIndex`: 寄存器索引（整数） `val`: 整型值（整数） | `int` | 设置整型寄存器 |
| `ZMotion:GetIntMod(mIndex, vrIndex)` | `mIndex`: 控制器索引（整数） `vrIndex`: 寄存器索引（整数） | `整数` | 读取整型寄存器 |
| `ZMotion:SetMulIntMod(mIndex, vrIndex, val)` | `mIndex`: 控制器索引（整数） `vrIndex`: 起始寄存器索引（整数） `val`: 值数组（数组） | `int` | 设置连续多个整型寄存器 |
| `ZMotion:GetMulIntMod(mIndex, vrIndex, num)` | `mIndex`: 控制器索引（整数） `vrIndex`: 起始寄存器索引（整数） `num`: 读取数量（整数） | `数组` | 读取连续多个整型寄存器 |
| `ZMotion:SetFloatMod(mIndex, vrIndex, val)` | `mIndex`: 控制器索引（整数） `vrIndex`: 寄存器索引（整数） `val`: 浮点值（浮点数） | `int` | 设置浮点型寄存器 |
| `ZMotion:GetFloatMod(mIndex, vrIndex)` | `mIndex`: 控制器索引（整数） `vrIndex`: 寄存器索引（整数） | `float` | 读取浮点型寄存器 |
| `ZMotion:SetMulFloatMod(mIndex, vrIndex, val)` | `mIndex`: 控制器索引（整数） `vrIndex`: 起始寄存器索引（整数） `val`: 值数组（数组） | `int` | 设置连续多个浮点型寄存器 |
| `ZMotion:GetMulFloatMod(mIndex, vrIndex, num)` | `mIndex`: 控制器索引（整数） `vrIndex`: 起始寄存器索引（整数） `num`: 读取数量（整数） | `数组` | 读取连续多个浮点型寄存器 |
| `ZMotion:SetStringMod(mIndex, modIndex, length, val)` | `mIndex`: 控制器索引（整数） `modIndex`: 寄存器索引（整数） `length`: 字符串长度（整数） `val`: 字符串值（字符串） | `int` | 设置字符串寄存器 |
| `ZMotion:GetStringMod(mIndex, modIndex, length)` | `mIndex`: 控制器索引（整数） `modIndex`: 寄存器索引（整数） `length`: 读取长度（整数） | `字符串` | 读取字符串寄存器 |

### 14. 用户变量
| Lua 函数 | 参数 | 返回值 | 说明 |
|----------|------|--------|------|
| `ZMotion:SetUserVar(mIndex, userName, val)` | `mIndex`: 控制器索引（整数） `userName`: 用户变量名（字符串） `val`: 浮点值（浮点数） | `int` | 设置用户变量（浮点） |
| `ZMotion:GetUserVar(mIndex, userName)` | `mIndex`: 控制器索引（整数） `userName`: 用户变量名（字符串） | `float` | 读取用户变量（浮点） |
| `ZMotion:SetUserVarString(mIndex, userName, userLen, val)` | `mIndex`: 控制器索引（整数） `userName`: 用户变量名（字符串） `userLen`: 字符串长度（整数） `val`: 字符串值（字符串） | `int` | 设置用户变量（字符串） |
| `ZMotion:GetUserVarString(mIndex, userName, length)` | `mIndex`: 控制器索引（整数） `userName`: 用户变量名（字符串） `length`: 读取长度（整数） | `字符串` | 读取用户变量（字符串） |

### 15. Flash 存储
| Lua 函数 | 参数 | 返回值 | 说明 |
|----------|------|--------|------|
| `ZMotion:SetFlash(mIndex, flashid, val)` | `mIndex`: 控制器索引（整数） `flashid`: Flash存储区ID（整数） `val`: 浮点数组（数组） | `int` | 写入 Flash 存储区（浮点数组） |
| `ZMotion:GetFlash(mIndex, flashid, num)` | `mIndex`: 控制器索引（整数） `flashid`: Flash存储区ID（整数） `num`: 读取数量（整数） | `数组` | 读取 Flash 存储区（浮点数组） |

## 状态码说明
大部分函数返回 `int` 类型状态码：

| 返回值 | 含义 |
|--------|------|
| 0 | 成功 |
| 负值 | 错误（具体错误码参考 ZMotion 控制器手册） |

## 注意事项
1. **控制器索引**：`mIndex` 参数表示控制器索引，从 0 开始，对应 VG3 中配置的多个运动控制器。
2. **轴索引**：`aIndex` 参数表示轴索引，从 0 开始，每个控制器可管理多轴（通常 1‑8 轴）。
3. **单位系统**：位置、速度、加速度等参数的单位为 `units`，由 `SetUnits` 定义的脉冲当量决定（例：1 unit = 0.001 mm）。
4. **运动安全**：运动前务必设置合理的软限位，并确认原点已回零，避免超程碰撞。
5. **输入输出地址**：`address` 参数为硬件映射地址，具体定义需参考控制器 IO 映射表。
6. **寄存器范围**：VR、位寄存器等索引范围由控制器型号决定，超出范围会导致通信错误。
7. **任务调用**：`CallTaskString` 等函数会阻塞当前 Lua 线程直到任务完成或超时，超时时间需合理设置。
8. **Flash 寿命**：Flash 存储区有写入次数限制（通常 10 万次），避免频繁写入。
9. **错误处理**：所有函数调用后应检查返回值，非 0 时记录错误日志并采取相应处理。
10. **并发控制**：避免多个线程同时操作同一轴或同一寄存器，可能导致状态不一致。

## 使用示例（Lua）
```lua
-- 假设已获得 GMvZMotionFunc 实例 motionFunc

-- 1. 检查连接
local conn = ZMotion:ConnectState(0)
if conn == 0 then
    LuaLog:Debug("控制器未连接")
    return
end

-- 2. 轴参数设置（轴0）
ZMotion:SetUnits(0, 0, 100.0)      -- 脉冲当量 100 pulse/unit
ZMotion:SetSpeed(0, 0, 200.0)      -- 速度 200 units/s
ZMotion:SetAccel(0, 0, 2000.0)     -- 加速度 2000 units/s²
ZMotion:SetDecel(0, 0, 2000.0)     -- 减速度 2000 units/s²
ZMotion:SetSramp(0, 0, 100.0)      -- S 曲线时间 100ms

-- 3. 设置软限位
ZMotion:SetFsLimit(0, 0, 500.0)    -- 正向限位 500 units
ZMotion:SetRsLimit(0, 0, -500.0)   -- 负向限位 -500 units

-- 4. 回零
ZMotion:SetCreep(0, 0, 10.0)       -- 爬行速度 10 units/s
ZMotion:SetHomeWait(0, 0, 1000)    -- 等待时间 1000ms
local homeResult = ZMotion:AxisMoveHome(0, 0, 1)  -- 模式1回零
if homeResult == 0 then
    LuaLog:Debug("回零成功")
end

-- 5. 绝对运动
local moveResult = ZMotion:AxisMoveAbs(0, 0, 100.0)  -- 移动到 100 units
if moveResult == 0 then
    -- 等待运动完成
    while ZMotion:AxisMoveState(0, 0) == 1 do
        LuaSystem:WaitMs(10)
    end
    LuaLog:Debug("运动完成")
end

-- 6. 读取位置
local dpos = ZMotion:GetDpos(0, 0)  -- 理论位置
local mpos = ZMotion:GetMpos(0, 0)  -- 实际位置
LuaLog:Debug(string.format("理论位置: %.3f, 实际位置: %.3f", dpos, mpos))

-- 7. IO 控制
ZMotion:SetOut(0, 0, 1)            -- 输出点0置高
local inVal = ZMotion:GetIn(0, 0)   -- 读取输入点0

-- 8. 寄存器读写
ZMotion:SetVR(0, 100, 123.45)      -- VR100 = 123.45
local vrVal = ZMotion:GetVR(0, 100) -- 读取 VR100

-- 9. 任务调用
local taskResult = ZMotion:CallFloatTaskString(0, 1, 5000, "RET_VAL", "MOV X100")
if taskResult ~= 0 then
    LuaLog:Debug("任务返回值:", taskResult)
end

-- 10. 用户变量
ZMotion:SetUserVar(0, "TargetPos", 250.0)
local target = ZMotion:GetUserVar(0, "TargetPos")
```

## 高级用法

### 多轴同步运动
通过循环控制多个轴实现同步运动：
```lua
local axes = {0, 1, 2}
local positions = {100.0, 200.0, 150.0}
for i, axis in ipairs(axes) do
    ZMotion:AxisMoveAbs(0, axis, positions[i])
end
-- 等待所有轴停止
local allStopped = false
while not allStopped do
    allStopped = true
    for i, axis in ipairs(axes) do
        if ZMotion:AxisMoveState(0, axis) == 1 then
            allStopped = false
            break
        end
    end
    LuaSystem:WaitMs(10)
end
```

### 软限位动态调整
根据工艺要求动态调整软限位：
```lua
local safeMargin = 10.0
local currentPos = ZMotion:GetMpos(0, 0)
local newLimit = currentPos + safeMargin
if newLimit < 500.0 then -- 不超过硬件限位
 ZMotion:SetFsLimit(0, 0, newLimit)
end
```

### 输入信号触发运动
监控输入信号，触发相应运动：
```lua
local triggerIn = 0
while true do
    local val = ZMotion:GetIn(0, triggerIn)
    if val == 1 then
        ZMotion:AxisMoveAbs(0, 0, 100.0)
        while ZMotion:GetIn(0, triggerIn) == 1 do
            LuaSystem:WaitMs(10)  -- 等待信号释放
        end
    end
    sysFunc:WaitMs(50)
end
```

### 寄存器批量操作
使用批量读写提高效率：
```lua
-- 批量写入速度参数
local speeds = {200.0, 180.0, 220.0}
for i, speed in ipairs(speeds) do
    ZMotion:SetVR(0, 200 + i, speed)
end
-- 或使用 SetMulVR
-- ZMotion:SetMulVR(0, 200, speeds)
```

### 错误恢复机制
运动出错时自动恢复：
```lua
local function safeMove(axis, target)
    local result = ZMotion:AxisMoveAbs(0, axis, target)
    if result ~= 0 then
        LuaLog:Debug("运动出错，尝试恢复...")
        ZMotion:AxisStop(0, axis)
        LuaSystem:WaitMs(100)
        ZMotion:AxisMoveHome(0, axis, 1)
        sysFunc:WaitMs(2000)
        LuaSystem = ZMotion:AxisMoveAbs(0, axis, target)
    end
    return result
end
```

## 最佳实践
1. **参数初始化**：在脚本开始时，读取并保存当前轴参数，结束时恢复原状，避免影响其他流程。
2. **状态检查**：运动前检查轴使能、回零状态、报警状态，确保轴处于可运动状态。
3. **超时处理**：所有阻塞操作（如回零、运动完成等待）都应设置超时，避免脚本卡死。
4. **日志记录**：关键操作（参数修改、运动指令、错误发生）记录详细日志，便于故障排查。
5. **资源释放**：脚本结束时，停止所有运动，释放输出信号，确保设备处于安全状态。
6. **配置分离**：将轴参数、速度、位置等配置数据存放在全局变量或配置文件中，便于调整。
7. **模块化设计**：将常用运动序列封装为函数（如 `MoveToSafePosition`, `HomeAllAxes`），提高代码复用性。
8. **安全优先**：急停、限位等安全功能必须优先于运动逻辑，确保人员和设备安全。

## 相关模块
- `LuaSystem` – 系统功能，用于延时等待、流程控制
- `LuaIOCard` – IO 卡控制，可与运动控制配合实现完整自动化
- `LuaGlobalVar` – 全局变量，用于存储运动参数和状态
- `LuaLog` – 日志记录，记录运动过程中的关键事件

---
*文档版本：v1.0*  
*最后更新：2026‑04‑30*  
*适用平台：准易科技 VisionGroup 3 (VG3) 视觉平台*