【技术文档】VG3 Lua API 技术文档

# VG3 Lua API 技术文档

## 目录

| # | 模块 | 简介 | 详细文档 |
|---|------|------|----------|
| 1 | [全局变量 (LuaGlobalVar)](#1-全局变量-luaglobalvar) | 命名块中存储/读取数据 | [📄 GMvLuaGlobalVarFunc.md](http://218.76.30.1:30067/doc/692/) |
| 2 | [数组操作 (LuaArray)](#2-数组操作-luaarray) | 数组/列表创建与管理 | [📄 GMvLuaArrayFunc.md](GMvLuaArrayFunc.md) |
| 3 | [相机控制 (LuaCamera)](#3-相机控制-luacamera) | 相机采集、参数设置、图像显示 | [📄 GMvLuaCameraFunc.md](GMvLuaCameraFunc.md) |
| 4 | [通讯控制 (LuaCommu)](#4-通讯控制-luacommu) | 串口/网口通讯 | [📄 GMvLuaCommuFunc.md](GMvLuaCommuFunc.md) |
| 5 | [数据库 (LuaDataBase)](#5-数据库luadatabse) | SQLite 数据库操作 | [📄 GMvLuaDataBaseFunc.md](GMvLuaDataBaseFunc.md) |
| 6 | [IO卡控制 (LuaIOCard)](#6-io卡控制-luaiocard) | IO卡输入输出控制 | [📄 GMvLuaIOCardFunc.md](GMvLuaIOCardFunc.md) |
| 7 | [光源控制 (LuaLight)](#7-光源控制-luaght) | 光源/打光灯控制 | [📄 GMvLuaLightFunc.md](GMvLuaLightFunc.md) |
| 8 | [日志输出 (LuaLog)](#8-日志输出-lualog) | 日志和信息显示 | [📄 GMvLuaLogFunc.md](GMvLuaLogFunc.md) |
| 9 | [运动控制 (LuaMotion)](#9-运动控制-luamotion) | 运动控制卡轴运动控制 | [📄 GMvLuaMotionFunc.md](GMvLuaMotionFunc.md) |
| 10 | [字符串处理 (LuaString)](#10-字符串处理-luastring) | 字符串操作函数 | [📄 GMvLuaStringFunc.md](GMvLuaStringFunc.md) |
| 11 | [系统函数 (LuaSystem)](#11-系统函数-luasystem) | 系统级功能 | [📄 GMvLuaSystemFunc.md](GMvLuaSystemFunc.md) |
| 12 | [文件操作 (LuaFile)](#12-文件操作-luafile) | 文件/目录管理、文本/CSV/图像读写 | [📄 GMvLuaFileFunc.md](GMvLuaFileFunc.md) |
| 13 | [ZMotion PLC (ZMotion)](#13-zmotion-plc-zmotion) | ZMotion PLC 控制 | [📄 GMvZMotionFunc.md](GMvZMotionFunc.md) |

---

## 1. 全局变量 (LuaGlobalVar)

> **详细文档**：[📄 GMvLuaGlobalVarFunc.md](http://218.76.30.1:30067/doc/692/)

全局变量模块用于在全局变量块中存储和读取数据，支持多种数据类型。

> 全部 117 个函数的完整参考见 [📄 GMvLuaGlobalVarFunc.md](GMvLuaGlobalVarFunc.md)

### 核心函数一览

| 分类 | Lua 方法 | 说明 |
|------|----------|------|
| **全局控制** | `SetSaveGlobalData(bool)`, `GetSaveGlobalData()`, `SaveGlobalData()` | 全局数据保存 |
| **变量检查** | `IsExistGlobal(block, var)`, `IsValidGlobal(block, var)` | 检查变量是否存在/有效 |
| **基础读取** | `ReadGlobal(block, var, CMvVariant)` → `bool` | 通用读取（第三个参数是输出容器，CMvVariant 输出容器，非错误码） |
| **基础写入** | `WriteGlobal(block, var, val)`, `WriteGlobalString(block, var, str)` | 通用写入 |
| **初始化** | `WriteInitGlobal(block, var, val)`, `WriteInitGlobalString(block, var, str)` | 写入默认值（程序启动时） |
| **按索引** | `ReadGlobalByIndex`, `WriteGlobalByIndex`, `WriteGlobalStringByIndex`, `WriteInitGlobalByIndex` | 按区块索引/变量索引操作 |

### 类型化读取（共20 种类型 × 按名称 + 按索引 = 40 个函数）

```lua
-- 按名称读取（变量不存在返回 nil）
LuaGlobalVar:ReadGlobalBool(block, var)          -- 布尔
LuaGlobalVar:ReadGlobalLong(block, var)          -- 整数
LuaGlobalVar:ReadGlobalReal(block, var)          -- 浮点
LuaGlobalVar:ReadGlobalString(block, var)        -- 字符串
LuaGlobalVar:ReadGlobalRealPoint(block, var)     -- 点坐标
LuaGlobalVar:ReadGlobalPosture(block, var)       -- 姿态
LuaGlobalVar:ReadGlobalLine(block, var)          -- 直线
LuaGlobalVar:ReadGlobalRange(block, var)         -- 范围
LuaGlobalVar:ReadGlobalRect(block, var)          -- 矩形
LuaGlobalVar:ReadGlobalRotatedRect(block, var)   -- 旋转矩形
LuaGlobalVar:ReadGlobalCircle(block, var)        --圆

-- 数组版本
LuaGlobalVar:ReadGlobalBoolArray(block, var)
LuaGlobalVar:ReadGlobalLongArray(block, var)
LuaGlobalVar:ReadGlobalRealArray(block, var)
LuaGlobalVar:ReadGlobalRealPointArray(block, var)
LuaGlobalVar:ReadGlobalPostureArray(block, var)
LuaGlobalVar:ReadGlobalLineArray(block, var)
LuaGlobalVar:ReadGlobalRectArray(block, var)
LuaGlobalVar:ReadGlobalRotatedRectArray(block, var)
LuaGlobalVar:ReadGlobalCircleArray(block, var)

-- ByIndex 版本（完整列表）
LuaGlobalVar:ReadGlobalBoolByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalLongByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalRealByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalStringByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalRealPointByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalPostureByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalLineByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalRangeByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalRectByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalRotatedRectByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalCircleByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalBoolArrayByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalLongArrayByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalRealArrayByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalRealPointArrayByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalPostureArrayByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalLineArrayByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalRectArrayByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalRotatedRectArrayByIndex(blockIdx, varIdx)
LuaGlobalVar:ReadGlobalCircleArrayByIndex(blockIdx, varIdx)
```

### 类型化写入

```lua
-- 按名称写入（基础）
LuaGlobalVar:WriteGlobal(block, var, val)
LuaGlobalVar:WriteGlobalString(block, var, str)
LuaGlobalVar:WriteInitGlobal(block, var, val)
LuaGlobalVar:WriteInitGlobalString(block, var, str)

-- 按名称写入（类型化）
LuaGlobalVar:WriteGlobalBool(block, var, val)
LuaGlobalVar:WriteGlobalLong(block, var, val)
LuaGlobalVar:WriteGlobalReal(block, var, val)
LuaGlobalVar:WriteGlobalRealPoint(block, var, pt)
LuaGlobalVar:WriteGlobalPosture(block, var, pose)
LuaGlobalVar:WriteGlobalLine(block, var, line)
LuaGlobalVar:WriteGlobalRange(block, var, range)
LuaGlobalVar:WriteGlobalRect(block, var, rect)
LuaGlobalVar:WriteGlobalRotatedRect(block, var, rrect)
LuaGlobalVar:WriteGlobalCircle(block, var, circle)
LuaGlobalVar:WriteGlobalBoolArray(block, var, val)
LuaGlobalVar:WriteGlobalLongArray(block, var, val)
LuaGlobalVar:WriteGlobalRealArray(block, var, val)
LuaGlobalVar:WriteGlobalRealPointArray(block, var, val)
LuaGlobalVar:WriteGlobalPostureArray(block, var, val)
LuaGlobalVar:WriteGlobalLineArray(block, var, val)
LuaGlobalVar:WriteGlobalRectArray(block, var, val)
LuaGlobalVar:WriteGlobalRotatedRectArray(block, var, val)
LuaGlobalVar:WriteGlobalCircleArray(block, var, val)

-- 按索引写入
LuaGlobalVar:WriteGlobalBoolByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalLongByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalRealByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalRealPointByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalPostureByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalLineByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalRangeByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalRectByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalRotatedRectByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalCircleByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalBoolArrayByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalLongArrayByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalRealArrayByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalRealPointArrayByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalPostureArrayByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalLineArrayByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalRectArrayByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalRotatedRectArrayByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteGlobalCircleArrayByIndex(blockIdx, varIdx, val)

-- 按名称初始化（WriteInitGlobal）
LuaGlobalVar:WriteInitGlobalBool(block, var, val)
LuaGlobalVar:WriteInitGlobalLong(block, var, val)
LuaGlobalVar:WriteInitGlobalReal(block, var, val)
LuaGlobalVar:WriteInitGlobalRealPoint(block, var, val)
LuaGlobalVar:WriteInitGlobalPosture(block, var, val)
LuaGlobalVar:WriteInitGlobalLine(block, var, val)
LuaGlobalVar:WriteInitGlobalRange(block, var, val)
LuaGlobalVar:WriteInitGlobalRect(block, var, val)
LuaGlobalVar:WriteInitGlobalRotatedRect(block, var, val)
LuaGlobalVar:WriteInitGlobalCircle(block, var, val)
LuaGlobalVar:WriteInitGlobalBoolArray(block, var, val)
LuaGlobalVar:WriteInitGlobalLongArray(block, var, val)
LuaGlobalVar:WriteInitGlobalRealArray(block, var, val)
LuaGlobalVar:WriteInitGlobalRealPointArray(block, var, val)
LuaGlobalVar:WriteInitGlobalPostureArray(block, var, val)
LuaGlobalVar:WriteInitGlobalLineArray(block, var, val)
LuaGlobalVar:WriteInitGlobalRectArray(block, var, val)
LuaGlobalVar:WriteInitGlobalRotatedRectArray(block, var, val)

-- 按索引初始化（WriteInitGlobalByIndex）
LuaGlobalVar:WriteInitGlobalBoolByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteInitGlobalLongByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteInitGlobalRealByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteInitGlobalRealPointByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteInitGlobalPostureByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteInitGlobalLineByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteInitGlobalRangeByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteInitGlobalRotatedRectByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteInitGlobalCircleByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteInitGlobalBoolArrayByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteInitGlobalLongArrayByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteInitGlobalRealArrayByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteInitGlobalRealPointArrayByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteInitGlobalPostureArrayByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteInitGlobalLineArrayByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteInitGlobalRectArrayByIndex(blockIdx, varIdx, val)
LuaGlobalVar:WriteInitGlobalRotatedRectArrayByIndex(blockIdx, varIdx, val)
```

### 使用示例

```lua
-- 标准 ReadGlobal 用法（带错误处理）
local var = CMvVariant()
local ok = LuaGlobalVar:ReadGlobal("块1", "变量1", var)
if ok then
    LuaLog:Debug(var:get())
else
    LuaLog:Debug("变量不存在，使用默认值 -10")
end

-- 类型化函数（推荐）
local count = LuaGlobalVar:ReadGlobalLong("系统参数", "当前个数")
if count == nil then count = -10 end

-- 各类数据写入
LuaGlobalVar:WriteGlobalRealPoint("Positions", "PickPos", {x=100, y=200})
LuaGlobalVar:WriteGlobalCircle("Vision", "Detected", {cx=500, cy=600, r=50})
```

> **注意**：`ReadGlobal` 的第三个参数是 `CMvVariant` 输出容器，**不是错误码**。错误码是 bool 返回值。

---

## 2. 数组操作 (LuaArray)

> **详细文档**：[📄 GMvLuaArrayFunc.md](GMvLuaArrayFunc.md)

数组/列表操作函数集合。

### 2.1 基础数组方法

| Lua 方法 | 说明 | 示例 |
|----------|------|------|
| `Create()` | 创建新数组| `local arr = LuaArray.Create()` |
| `Copy(array)` | 复制数组 | `local newArr = arr:Copy()` |
| `CopyTo(destArray)` | 复制到目标数组| `arr:CopyTo(destArray)` |
| `Fill(value)` | 用值填充数组| `arr:Fill(0)` |
| `Reset()` | 重置数组 | `arr:Reset()` |
| `Resize(newSize)` | 调整数组大小 | `arr:Resize(10)` |
| `ToString()` | 转换为字符串 | `local str = arr:ToString()` |
| `Mid(index, length)` | 截取子数组| `arr:Mid(0, 5)` |
| `Length()` | 获取数组长度 | `local len = arr:Length()` |
| `Type()` | 获取元素类型 | `local t = arr:Type()` |
| `Get(index)` | 获取元素 | `local v = arr:Get(0)` |
| `Set(index, value)` | 设置元素 | `arr:Set(0, value)` |
| `Remove(index)` | 移除元素 | `arr:Remove(0)` |
| `RemoveFirst()` | 移除第一个元素| `arr:RemoveFirst()` |
| `RemoveLast()` | 移除最后一个元素| `arr:RemoveLast()` |
| `Clear()` | 清空数组 | `arr:Clear()` |
| `Insert(index, value)` | 插入元素 | `arr:Insert(0, val)` |
| `PushBack(value)` | 尾部添加 | `arr:PushBack(val)` |
| `PushFront(value)` | 头部添加 | `arr:PushFront(val)` |
| `Append(array)` | 追加数组 | `arr:Append(otherArr)` |

---

## 3. 相机控制 (LuaCamera)

> **详细文档**：[📄 GMvLuaCameraFunc.md](GMvLuaCameraFunc.md)

相机采集和参数控制。

### 3.1 相机状态与参数

| Lua 方法 | 说明 | 参数 | 返回值 |
|----------|------|------|--------|
| `GetCameraCount()` | 获取相机数量 |圆| `int` |
| `GetCameraState(cameraIndex)` | 获取相机状态 | 相机索引 | `int` |
| `GetCameraExpourse(cameraIndex)` | 获取曝光值 | 相机索引 | `float` |
| `GetCameraGain(cameraIndex)` | 获取增益值 | 相机索引 | `float` |
| `GetCameraTriggerMode(cameraIndex)` | 获取触发模式 | 相机索引 | `int` |
| `GetInputState(cameraIndex, inputIndex)` | 获取输入状态 | 相机索引, 输入索引 | `int` |
| `GetOutputState(cameraIndex, outputIndex)` | 获取输出状态 | 相机索引, 输出索引 | `int` |

### 3.2 相机参数设置

| Lua 方法 | 说明 |
|----------|------|
| `SetCameraExpourse(cameraIndex, val)` | 设置曝光值 |
| `SetCameraGain(cameraIndex, val)` | 设置增益值 |
| `SetCameraTriggerMode(cameraIndex, val)` | 设置触发模式 |
| `SetOutputState(cameraIndex, outputIndex, val)` | 设置输出状态 |

### 3.3 图像采集

| Lua 方法 | 说明 | 返回值 |
|----------|------|--------|
| `GetCameraImage(cameraIndex)` | 获取相机图像 | `cyImage` |
| `GetCameraImageByParams(cameraIndex, expourse, gain)` | 带参数采集图像| `cyImage` |

### 3.4 图像显示

| Lua 方法 | 说明 |
|----------|------|
| `DisplayImage(image, name)` | 显示图像 |
| `DisplayMat(mat, name)` | 显示Mat图像 |
| `DestroyAllWindows()` | 关闭所有显示窗口 |

### 3.5 使用示例

```lua
-- 获取相机数量
local count = LuaCamera:GetCameraCount()

-- 设置相机参数并采集
LuaCamera:SetCameraExpourse(0, 5000)  -- 曝光 5000
LuaCamera:SetCameraGain(0, 10)       -- 增益 10

-- 采集图像
local image = LuaCamera:GetCameraImage(0)

-- 带参数采集
local img = LuaCamera:GetCameraImageByParams(0, 5000, 10)

-- 显示图像
LuaCamera:DisplayImage(image, "Camera0")

-- 清理
LuaCamera:DestroyAllWindows()
```

---

## 4. 通讯控制 (LuaCommu)

> **详细文档**：[📄 GMvLuaCommuFunc.md](GMvLuaCommuFunc.md)

串口/网口通讯控制。

### 4.1 通讯状态与开关

| Lua 方法 | 说明 | 参数 | 返回值 |
|----------|------|------|--------|
| `GetCommuState(commuIndex)` | 获取通讯状态 | 通讯索引 | `int` |
| `OpenCommu(commuIndex)` | 打开通讯 | 通讯索引 | `int` |
| `CloseCommu(commuIndex)` | 关闭通讯 | 通讯索引 | `int` |

### 4.2 IO 控制

| Lua 方法 | 说明 |
|----------|------|
| `SetOutputState(commuIndex, outputIndex, val)` | 设置输出 |
| `SetOutputStateDelayTime(commuIndex, outputIndex, val, timeMs)` | 延时设置输出 |
| `GetInputState(commuIndex, inputIndex)` | 获取输入 |
| `GetOutputState(commuIndex, outputIndex)` | 获取输出 |
| `WaitInputState(commuIndex, inputIndex, state, waitMs)` | 等待输入状态 |
| `WaitOutputState(commuIndex, outputIndex, state, waitMs)` | 等待输出状态 |

### 4.3 多点 IO 操作

```lua
-- 获取多个输入状态
local states = LuaCommu:GetMultiInputState(0, {0, 1, 2})

-- 获取多个输出状态
local states = LuaCommu:GetMultiOutputState(0, {0, 1, 2})

-- 等待多个输入状态
local result = LuaCommu:WaitMultiInputState(0, {0, 1}, {1, 1}, 5000)

-- 等待多个输出状态
local result = LuaCommu:WaitMultiOutputState(0, {0, 1}, {1, 1}, 5000)
```

### 4.4 数据读写

**字符串读写：**
```lua
-- 发送字符串
LuaCommu:WriteString(0, "Hello")

-- 发送字节数
LuaCommu:WriteByteArray(0, byteArray)

-- 读取字符串
local str = LuaCommu:ReadString(0)

-- 读取字节数组
local bytes = LuaCommu:ReadByteArray(0)
```

**寄存器读写：**
```lua
-- 写寄存器
LuaCommu:WriteRegisterBool(commuIndex, regIndex, regType, val)
LuaCommu:WriteRegisterShort(commuIndex, regIndex, val)
LuaCommu:WriteRegisterLong(commuIndex, regIndex, val)
LuaCommu:WriteRegisterReal(commuIndex, regIndex, val)
LuaCommu:WriteRegisterByteArray(commuIndex, regIndex, byteArray)

-- 读寄存器
local val = LuaCommu:ReadRegisterShort(commuIndex, regIndex, failVal)
local val = LuaCommu:ReadRegisterLong(commuIndex, regIndex, failVal)
local val = LuaCommu:ReadRegisterReal(commuIndex, regIndex, failVal)
local bytes = LuaCommu:ReadRegisterByteArray(commuIndex, address, length)
```

### 4.5 数据块操作

```lua
-- 写数据块
LuaCommu:WriteDataBlockByteArray(commuIndex, byteArray)

-- 读数据块
local bytes = LuaCommu:ReadDataBlockByteArray(commuIndex)
```

### 4.6 字节数组转换

| Lua 方法 | 说明 |
|----------|------|
| `byteArray_short(bytes, orderCode, failVal)` | 字节数组转Short |
| `byteArray_int(bytes, orderCode, failVal)` | 字节数组转Int |
| `byteArray_float(bytes, orderCode, failVal)` | 字节数组转Float |
| `short_bytearray(val, orderCode)` | Short转字节数组 |
| `int_bytearray(val, orderCode)` | Int转字节数组 |
| `float_bytearray(val, orderCode)` | Float转字节数组 |
| `midBytearray(bytes, start, length)` | 截取字节数组 |

---

## 5. 数据库 (LuaDataBase)

> **详细文档**：[📄 GMvLuaDataBaseFunc.md](GMvLuaDataBaseFunc.md)

SQLite 数据库操作。

### 5.1 表操作

```lua
-- 创建表
LuaDataBase:EnqueueCreateTable("myTable", "id INTEGER PRIMARY KEY, name TEXT")

-- 删除表
LuaDataBase:EnqueueDropTable("myTable")
```

### 5.2 数据操作

```lua
-- 插入数据
LuaDataBase:EnqueueInsert("myTable", "name, age", "'John', 25")

-- 更新数据
LuaDataBase:EnqueueUpdate("myTable", "age", "30", "name", "'John'")

-- 删除数据
LuaDataBase:EnqueueDelete("myTable", "name", "'John'")
```

### 5.3 查询操作

```lua
-- 执行SQL查询
local result = LuaDataBase:Query("SELECT * FROM myTable WHERE age > ?", "[20]")
local result = LuaDataBase:QueryLimit("SELECT * FROM myTable", 10)

-- 查询返回结果示例
-- result = {{id=1, name="John"}, {id=2, name="Jane"}, ...}
```

---

## 6. IO卡控制 (LuaIOCard)

> **详细文档**：[📄 GMvLuaIOCardFunc.md](GMvLuaIOCardFunc.md)

IO 卡输入输出控制。

### 6.1 状态与IO操作

| Lua 方法 | 说明 | 参数 | 返回值 |
|----------|------|------|--------|
| `GetIOCardState(ioCardIndex)` | 获取IO卡状态 | IO卡索引 | `int` |
| `SetOutputState(ioCardIndex, outputIndex, val)` | 设置输出 | IO卡索引, 输出索引,圆| `int` |
| `SetOutputStateDelayTime(ioCardIndex, outputIndex, val, timeMs)` | 延时输出 | 同上+延时ms | `int` |
| `GetInputState(ioCardIndex, inputIndex)` | 获取输入 | IO卡索引, 输入索引 | `int` |
| `GetOutputState(ioCardIndex, outputIndex)` | 获取输出 | IO卡索引, 输出索引 | `int` |
| `WaitInputState(ioCardIndex, inputIndex, state, waitMs)` | 等待输入 | 同上+等待超时ms | `int` |
| `WaitOutputState(ioCardIndex, outputIndex, state, waitMs)` | 等待输出 | 同上+等待超时ms | `int` |

### 6.2 多点操作

```lua
-- 获取多个输入
local states = LuaIOCard:GetMultiInputState(0, {0, 1, 2, 3})

-- 获取多个输出
local states = LuaIOCard:GetMultiOutputState(0, {0, 1, 2, 3})

-- 等待多个输入
local result = LuaIOCard:WaitMultiInputState(0, {0, 1}, {1, 1}, 5000)

-- 等待多个输出
local result = LuaIOCard:WaitMultiOutputState(0, {0, 1}, {1, 1}, 5000)
```

### 6.3 使用示例

```lua
-- 打开气缸
LuaIOCard:SetOutputState(0, 0, 1)

-- 延时关闭
LuaIOCard:SetOutputStateDelayTime(0, 0, 0, 500)

-- 等待传感器信号（最多等 5 秒）
local result = LuaIOCard:WaitInputState(0, 0, 1, 5000)
if result == 0 then
    LuaLog:Debug("传感器触发)
else
    LuaLog:Debug("等待超时")
end
```

---

## 7. 光源控制 (LuaLight)

> **详细文档**：[📄 GMvLuaLightFunc.md](GMvLuaLightFunc.md)

光源/打光灯控制。

### 7.1 基础控制

| Lua 方法 | 说明 | 参数 | 返回值 |
|----------|------|------|--------|
| `GetLightState(lightIndex)` | 获取光源状态 | 光源索引 | `int` |
| `SetChannelVal(lightIndex, channelIndex, val)` | 设置通道值 | 光源索引, 通道索引,圆0-255) | `int` |
| `GetChannelVal(lightIndex, channelIndex)` | 获取通道值 | 同上 | `int` |
| `OpenChannel(lightIndex, channelIndex)` | 打开通道 | 同上 | `int` |
| `CloseChannel(lightIndex, channelIndex)` | 关闭通道 | 同上 | `int` |

### 7.2 IO 控制

```lua
-- 设置输出
LuaLight:SetOutputState(lightIndex, outputIndex, val)

-- 延时设置输出
LuaLight:SetOutputStateDelayTime(lightIndex, outputIndex, val, timeMs)

-- 获取IO状态
local inputState = LuaLight:GetInputState(lightIndex, inputIndex)
local outputState = LuaLight:GetOutputState(lightIndex, outputIndex)
```

### 7.3 等待操作

```lua
-- 等待输入状态
local result = LuaLight:WaitInputState(lightIndex, inputIndex, state, waitMs)

-- 等待输出状态
local result = LuaLight:WaitOutputState(lightIndex, outputIndex, state, waitMs)

-- 多点等待
local states = LuaLight:GetMultiInputState(lightIndex, {0, 1, 2})
local states = LuaLight:GetMultiOutputState(lightIndex, {0, 1, 2})
local result = LuaLight:WaitMultiInputState(lightIndex, {0, 1}, {1, 1}, 5000)
local result = LuaLight:WaitMultiOutputState(lightIndex, {0, 1}, {1, 1}, 5000)
```

### 7.4 使用示例

```lua
-- 设置光源亮度（0-255）
LuaLight:SetChannelVal(0, 0, 200)  -- 通道0亮度200
LuaLight:SetChannelVal(0, 1, 150)  -- 通道1亮度150
LuaLight:SetChannelVal(0, 2, 0)    -- 通道2关闭

-- 打开/关闭光源
LuaLight:OpenChannel(0, 0)
LuaLight:CloseChannel(0, 0)

-- 频闪控制：先开灯 -> 采图 -> 关灯
LuaLight:SetChannelVal(0, 0, 255)
LuaLight:OpenChannel(0, 0)
local img = LuaCamera:GetCameraImage(0)
LuaLight:CloseChannel(0, 0)
```

---

## 8. 日志输出 (LuaLog)

> **详细文档**：[📄 GMvLuaLogFunc.md](GMvLuaLogFunc.md)

日志和信息显示。

### 8.1 日志函数

| Lua 方法 | 说明 |
|----------|------|
| `Debug(info)` | 输出调试信息 |
| `WriteLog(info)` | 写入日志文件 |
| `ShowMessage(info)` | 显示消息弹窗 |

### 8.2 使用示例

```lua
LuaLog:Debug("开始执行流程)
LuaLog:WriteLog("工位1完成，耗时: 500ms")
LuaLog:ShowMessage("操作完成，请检查结果)
```

---

## 9. 运动控制 (LuaMotion)

> **详细文档**：[📄 GMvLuaMotionFunc.md](GMvLuaMotionFunc.md)

运动控制卡轴运动控制。

### 9.1 运动卡状态

| Lua 方法 | 说明 | 返回值 |
|----------|------|--------|
| `GetMotionState(motionIndex)` | 获取运动卡状态| `int` |

### 9.2 轴使能与参数

```lua
-- 使能控制
LuaMotion:SetAxisOutputEnable(motionIndex, axisIndex, val)  -- 设置使能
local state = LuaMotion:GetAxisOutputEnable(motionIndex, axisIndex)  -- 获取使能

-- 速度参数
LuaMotion:SetAxisSpeed(motionIndex, axisIndex, speedVal)
local speed = LuaMotion:GetAxisSpeed(motionIndex, axisIndex)

-- 加速度
LuaMotion:SetAxisAccel(motionIndex, axisIndex, accelVal)
local accel = LuaMotion:GetAxisAccel(motionIndex, axisIndex)

-- 减速度
LuaMotion:SetAxisDecel(motionIndex, axisIndex, decelVal)
local decel = LuaMotion:GetAxisDecel(motionIndex, axisIndex)
```

### 9.3 基础运动

| Lua 方法 | 说明 |
|----------|------|
| `AxisHomeState(motionIndex, axisIndex)` | 回零状态 |
| `AxisState(motionIndex, axisIndex)` | 报警状态 |
| `AxisRunState(motionIndex, axisIndex)` | 运行状态 |
| `AxisLoction(motionIndex, axisIndex)` | 获取当前位置 |
| `AxisLoctionClear(motionIndex, axisIndex)` | 清零当前位置 |
| `AxisEncoderLoction(motionIndex, axisIndex)` | 获取编码器位置 |
| `AxisEncoderLoctionClear(motionIndex, axisIndex)` | 清零编码器位置 |

### 9.4 运动指令

| Lua 方法 | 说明 | 参数 |
|----------|------|------|
| `AxisMoveStop(motionIndex, axisIndex)` | 立即停止 | 轴索引 |
| `AxisMoveStart(motionIndex, axisIndex, direction)` | 连续运动 | 方向(1正向/-1负向) |
| `AxisMoveDistance(motionIndex, axisIndex, distance)` | 运动指定距离 | 距离（浮点数） |
| `AxisMovePosition(motionIndex, axisIndex, position)` | 运动到绝对位置 | 目标位置 |
| `AxisMoveToHome(motionIndex, axisIndex)` | 回原点 |圆|
| `WaiterAxisStop(motionIndex, axisIndex, maxTime)` | 等待轴停止 | 最大等待时间ms |

### 9.5 IO 控制

```lua
-- 输出
LuaMotion:SetOutputState(motionIndex, outputIndex, val)
LuaMotion:SetOutputStateDelayTime(motionIndex, outputIndex, val, timeMs)
LuaMotion:SetMultiOutputState(motionIndex, startIndex, {val1, val2, ...})

-- 输入
local input = LuaMotion:GetInputState(motionIndex, inputIndex)
local output = LuaMotion:GetOutputState(motionIndex, outputIndex)

-- 等待
LuaMotion:WaitInputState(motionIndex, inputIndex, state, waitMs)
LuaMotion:WaitOutputState(motionIndex, outputIndex, state, waitMs)

-- 多点
local inputs = LuaMotion:GetMultiInputState(motionIndex, {0, 1, 2})
local outputs = LuaMotion:GetMultiOutputState(motionIndex, {0, 1, 2})
```

### 9.6 多轴联动

```lua
-- 检查所有轴是否停止
local result = LuaMotion:isStopAllAxis({0, 0}, {0, 1})  -- 卡片0,轴1

-- 停止所有轴
LuaMotion:stopAllAxis({0, 0}, {0, 1})

-- 多轴运动到绝对位置
LuaMotion:movePostionAllAxis({0, 0}, {0, 1}, {100.0, 50.0})

-- 多轴回原点
LuaMotion:moveToHomeAllAxis({0, 0}, {0, 1})

-- 阻塞式多轴运动
LuaMotion:MulAxisMovePositionFunc({0, 0}, {0, 1}, {100.0, 50.0}, 5000)
LuaMotion:MulAxisMoveToHomeFunc({0, 0}, {0, 1}, 5000)

-- 多轴相对运动
LuaMotion:MulAxisMoveDistanceFunc(0, {0, 1}, {10.0, -5.0})
```

### 9.7 使用示例

```lua
-- 初始化轴参数
LuaMotion:SetAxisSpeed(0, 0, 100)     -- 速度100
LuaMotion:SetAxisAccel(0, 0, 1000)   -- 加速度1000
LuaMotion:SetAxisDecel(0, 0, 1000)   -- 减速度1000

-- 使能轴
LuaMotion:SetAxisOutputEnable(0, 0, 1)

-- 回原点
LuaMotion:AxisMoveToHome(0, 0)
LuaMotion:WaiterAxisStop(0, 0, 30000)

-- 运动到位
LuaMotion:AxisMovePosition(0, 0, 100.0)
LuaMotion:WaiterAxisStop(0, 0, 10000)

-- 获取位置
local pos = LuaMotion:AxisLoction(0, 0)

-- 相对移动
LuaMotion:AxisMoveDistance(0, 0, 50.0)

-- 停止
LuaMotion:AxisMoveStop(0, 0)
```

---

## 10. 字符串处理 (LuaString)

> **详细文档**：[📄 GMvLuaStringFunc.md](GMvLuaStringFunc.md)

字符串操作工具函数。

### 10.1 基础查询

| Lua 方法 | 说明 | 示例 |
|----------|------|------|
| `Length(str)` | 获取长度 | `Length("hello")`圆5 |
| `Contains(str, sub)` | 是否包含子串 | `Contains("hello", "ell")`圆true |
| `IndexOf(str, sub)` | 首次出现位置 | `IndexOf("hello", "ll")`圆3 |
| `LastIndexOf(str, sub)` | 最后出现位置 | `LastIndexOf("hello", "l")`圆4 |

### 10.2 截取操作

| Lua 方法 | 说明 | 示例 |
|----------|------|------|
| `Mid(str, index)` | 从index到结尾 | `Mid("hello", 2)`圆"llo" |
| `MidLenght(str, index, len)` | 从index截取len长度 | `MidLenght("hello", 2, 2)`圆"ll" |

### 10.3 分割与合并

```lua
-- 分割（返回CMvVariant数组）
local arr = LuaString:Split("a,b,c", ",")  -- {"a", "b", "c"}

-- 合并
local str = LuaString:Join(arr, "-")  -- "a-b-c"
```

### 10.4 替换操作

| Lua 方法 | 说明 | 示例 |
|----------|------|------|
| `Replace(str, before, after)` | 替换文本 | `Replace("hello", "l", "L")`圆"heLLo" |
| `Remove(str, removeStr)` | 移除文本 | `Remove("hello", "l")`圆"heo" |
| `RemoveHeadTail(str, head, tail)` | 移除首尾 | `RemoveHeadTail("[abc]", "[", "]")`圆"abc" |

### 10.5 前缀后缀检查

| Lua 方法 | 说明 | 示例 |
|----------|------|------|
| `StartWith(str, prefix)` | 是否以prefix开头 | `StartWith("hello", "he")`圆true |
| `EndWith(str, suffix)` | 是否以suffix结尾 | `EndWith("hello", "lo")`圆true |

### 10.6 大小写与空格

| Lua 方法 | 说明 | 示例 |
|----------|------|------|
| `ToUpper(str)` | 转大写 | `ToUpper("hello")`圆"HELLO" |
| `ToLower(str)` | 转小写 | `ToLower("HELLO")`圆"hello" |
| `Trimmed(str)` | 移除所有空格 | `Trimmed(" h e l l o ")`圆"hello" |

### 10.7 插入操作

| Lua 方法 | 说明 | 示例 |
|----------|------|------|
| `Insert(str, index, insertStr)` | 插入文本 | `Insert("hello", 2, "X")`圆"heXllo" |
| `Append(str, addStr)` | 追加到尾部 | `Append("hello", "!")`圆"hello!" |
| `Prepend(str, addStr)` | 追加到头部 | `Prepend("hello", "!")`圆"!hello" |

### 10.8 科学计数法转换

```lua
-- 科学计数法字符串转普通数字字符串
local str = LuaString:ScientificConverter("1.23e+05")  -- "123000"
```

### 10.9 类型转换

**字符串转数值：**
```lua
local boolVal = LuaString:ToBool("true", false)
local longVal = LuaString:ToLong("123", 0)
local realVal = LuaString:ToReal("3.14", 0.0)
local bytes = LuaString:ToByteArray("abc", ",")
```

**数值转字符串：**
```lua
local str = LuaString:FromBool(true)           -- "true"
local str = LuaString:FromLong(123)             -- "123"
local str = LuaString:FromReal(3.14)           -- "3.14"
local str = LuaString:FromByteArray(bytes, ",")
```

---

## 11. 系统函数 (LuaSystem)

> **详细文档**：[📄 GMvLuaSystemFunc.md](GMvLuaSystemFunc.md)

系统时间和流程控制。

### 11.1 时间获取

| Lua 方法 | 说明 | 返回值 |
|----------|------|--------|
| `GetYear()` | 获取年份 | 2026 |
| `GetMonth()` | 获取月份 | 1-12 |
| `GetDay()` | 获取日期 | 1-31 |
| `GetDayOfYear()` | 获取年内第几天 | 1-366 |
| `GetWeek()` | 获取星期几 | 1-7 |
| `GetWeekOfYear()` | 获取年内第几天 | 1-53 |
| `GetHour()` | 获取小时 | 0-23 |
| `GetMinute()` | 获取分钟 | 0-59 |
| `GetSecond()` | 获取秒 | 0-59 |
| `GetMillisecond()` | 获取毫秒 | 0-999 |
| `GetTimeStamp()` | 获取时间戳 | int64 |
| `GetDate()` | 获取日期字符串| "2026-04-30" |
| `GetTime()` | 获取时间字符串| "09:30:45" |
| `GetDatetime()` | 获取日期时间字符串| "2026-04-30 09:30:45" |

### 11.2 时间使用示例

```lua
-- 获取当前时间戳用于计时
local startTime = LuaSystem:GetTimeStamp()

-- 执行某些操作...

local endTime = LuaSystem:GetTimeStamp()
local elapsed = endTime - startTime
LuaLog:Debug(string.format("耗时: %d ms", elapsed))

-- 格式化时间
local date = LuaSystem:GetDate()      -- "2026-04-30"
local time = LuaSystem:GetTime()        -- "09:30:45"
local dt = LuaSystem:GetDatetime()     -- "2026-04-30 09:30:45"

-- 拼接日志文件名
local logName = string.format("log_%s.txt", LuaSystem:GetDate())
```

### 11.3 延时与暂停

| Lua 方法 | 说明 | 返回值 |
|----------|------|--------|
| `WaitMs(milliseconds)` | 延时（阻塞） | `bool` |
| `IsPauseRunning()` | 是否暂停 | `bool` |
| `SetPauseRunning(val)` | 设置暂停状态 |圆|

```lua
-- 延时1秒
LuaSystem:WaitMs(1000)

-- 延时500毫秒
LuaSystem:WaitMs(500)
```

### 11.4 流程触发（按索引）

```lua
-- 触发指定类型的流程
LuaSystem:TriggerLineByIndex(projectType, lineIndex)

-- 检查流程是否运行中
local running = LuaSystem:IsLineRunningByIndex(projectType, lineIndex)
```

### 11.5 流程触发（按触发ID）

```lua
-- 触发
LuaSystem:TriggerLineByTriggerId(triggerId)

-- 检查运行状态
local running = LuaSystem:IsLineRunningByTriggerId(triggerId)
```

### 11.6 流程触发（按名称）

```lua
-- 触发
LuaSystem:TriggerLineByName(projectType, lineName)

-- 检查运行状态
local running = LuaSystem:IsLineRunningByName(projectType, lineName)
```

### 11.7 多流程等待

```lua
-- 按索引等待多个流程完成
-- 格式：0,0;0,1;0,2" 表示卡片0,,1,2
local result = LuaSystem:WaitMultiLineFinishedByIndex("0,0;0,1", 100, 5000)

-- 按触发ID等待
local result = LuaSystem:WaitMultiLineFinishedByTriggerId("1;2;3", 100, 5000)

-- 按名称等待（分号分隔）
local result = LuaSystem:WaitMultiLineFinishedByName("Line1;Line2;Line3", 100, 5000)
```

### 11.8 全局流程等待

```lua
-- 只有在整体软件中才会等待
local result = LuaSystem:WaitMultiGlobalLineFinishedByIndex("0,0;0,1", 100, 5000)
local result = LuaSystem:WaitMultiGlobalLineFinishedByTriggerId("1;2", 100, 5000)
local result = LuaSystem:WaitMultiGlobalLineFinishedByName("Global1;Global2", 100, 5000)
```

### 11.9 流程触发并等待

```lua
-- 触发不等待
local result = LuaSystem:TriggerLineByTriggerIdNoWait("1;2;3")
-- 返回：0成功, 1格式错误, 2跳过, -1未找到,-2类型错误, -3运行中

-- 触发等待任一完成
local result = LuaSystem:TriggerLineByTriggerIdWaitOnce("1;2;3", 5000)
-- 额外返回： -4超时

-- 触发等待全部完成
local result = LuaSystem:TriggerLineByTriggerIdWaitAll("1;2;3", 5000)

-- 按名称版本
local result = LuaSystem:TriggerLineByNameNoWait("Type1,Line1;Type2,Line2")
local result = LuaSystem:TriggerLineByNameWaitOnce("Line1;Line2", 5000)
local result = LuaSystem:TriggerLineByNameWaitAll("Line1;Line2", 5000)
```

### 11.10 停止流程

```lua
-- 停止不等待
local result = LuaSystem:StopLineByNameNoWait("Line1;Line2")

-- 停止等待一个完成
local result = LuaSystem:StopLineByNameWaitOnce("Line1;Line2", 5000)

-- 停止等待全部完成
local result = LuaSystem:StopLineByNameWaitAll("Line1;Line2", 5000)

-- 按类型停止所有流程
-- proType: 0普通流程, 1全局流程, -1所有流程
LuaSystem:StopAllLine(0)
```

### 11.11 使用示例

```lua
-- 获取当前项目名称
local projName = LuaSystem:GetCurrentProjName()

-- 流程控制示例
local result = LuaSystem:TriggerLineByTriggerIdWaitOnce("10;11", 10000)
if result == 0 then
    LuaLog:Debug("流程执行成功")
elseif result == -4 then
    LuaLog:Debug("等待超时")
end

-- 停止所有普通流程,
LuaSystem:StopAllLine(0)
```

---

## 12. 文件操作 (LuaFile)

> **详细文档**：[📄 GMvLuaFileFunc.md](GMvLuaFileFunc.md)

文件操作模块提供了文件系统管理（创建/删除目录、删除文件）、文本文件读写、CSV 文件读写以及图像文件的读取和保存功能。

### 12.1 文件/目录检查

| Lua 方法 | 说明 | 参数 | 返回值 |
|----------|------|------|--------|
| `ExistFile(filePath)` | 检查文件是否存在 | `filePath`: 文件路径 | `bool` |
| `ExistDirct(dirctPath)` | 检查目录是否存在 | `dirctPath`: 目录路径 | `bool` |

### 12.2 目录操作

| Lua 方法 | 说明 | 参数 | 返回值 |
|----------|------|------|--------|
| `NewDirct(dirctPath)` | 创建新目录 | `dirctPath`: 目录路径 | `bool` |
| `DelDirct(dirctPath)` | 删除目录 | `dirctPath`: 目录路径 | `bool` |

### 12.3 文件操作

| Lua 方法 | 说明 | 参数 | 返回值 |
|----------|------|------|--------|
| `DelFile(filePath)` | 删除文件 | `filePath`: 文件路径 | `bool` |

### 12.4 文本文件操作

| Lua 方法 | 说明 | 参数 | 返回值 |
|----------|------|------|--------|
| `NewTxt(filePath, txtString)` | 新建文本文件并写入内容 | `filePath`: 文件路径, `txtString`: 文本内容 | `bool` |
| `AppendTxt(filePath, txtString)` | 追加内容到文本文件 | `filePath`: 文件路径, `txtString`: 追加内容 | `bool` |
| `ReadTxt(filePath)` | 读取文本文件内容 | `filePath`: 文件路径 | `QString` |

### 12.5 CSV 文件操作

| Lua 方法 | 说明 | 参数 | 返回值 |
|----------|------|------|--------|
| `NewCSV(filePath, csvHead)` | 新建 CSV 文件并写入表头 | `filePath`: 文件路径, `csvHead`: 表头字符串| `bool` |
| `AppendLineCSV(filePath, csvLine)` | 追加一行到 CSV 文件 | `filePath`: 文件路径, `csvLine`: 行内容 | `bool` |
| `ReadCSV(filePath)` | 读取 CSV 文件所有行 | `filePath`: 文件路径 | `QStringList` |

### 12.6 图像文件操作

| Lua 方法 | 说明 | 参数 | 返回值 |
|----------|------|------|--------|
| `ReadImage(filePath)` | 从文件读取图像 | `filePath`: 图像文件路径 | `cyImage` |
| `SaveImage(image, filePath)` | 保存图像到文件 | `image`: cyImage 图像对象, `filePath`: 保存路径 | `bool` |

### 12.7 使用示例

```lua
-- 文件/目录管理
if not LuaFile:ExistDirct("D:/data/images") then
    LuaFile:NewDirct("D:/data/images")
end
if LuaFile:ExistFile("D:/data/config.txt") then
    local content = LuaFile:ReadTxt("D:/data/config.txt")
    LuaLog:Debug(content)
end
LuaFile:DelFile("D:/data/temp.txt")

-- 文本文件
LuaFile:NewTxt("D:/data/result.txt", "检测结果：OK")
LuaFile:AppendTxt("D:/data/result.txt", "时间：2026-05-07")

-- CSV 文件
LuaFile:NewCSV("D:/data/result.csv", "序号,结果,X坐标,Y坐标")
for i = 1, 10 do
    local line = string.format("%d,%s,%.2f,%.2f", i, "OK", 100.5, 200.3)
    LuaFile:AppendLineCSV("D:/data/result.csv", line)
end
local lines = LuaFile:ReadCSV("D:/data/result.csv")
for _, line in ipairs(lines) do
    LuaLog:Debug(line)
end

-- 图像读写（配合 LuaCamera）
local img = LuaCamera:GetCameraImage(0)
if img then
    LuaFile:SaveImage(img, "D:/data/images/cap_001.bmp")
end
local loaded = LuaFile:ReadImage("D:/data/template.bmp")
if loaded then
    LuaCamera:DisplayImage(loaded, "模板")
end
```

### 12.8 注意事项
- 文件路径建议使用正斜杠 `/`，避免转义问题
- `SaveImage` 支持的保存格式取决于底层图像库（通常支持 bmp、png、jpg 等）
- `ReadImage` 返回 `cyImage` 对象，可用于 `DisplayImage` 显示或作为视觉算法输入
- 文件操作失败时返回 `false`，建议检查返回值以确认操作成功

---

## 13. ZMotion XPLC系列 (ZMotion)

> **详细文档**：[📄 GMvZMotionFunc.md](GMvZMotionFunc.md)

正运动XplcPLC 控制器

### 13.1 连接状态

| Lua 方法 | 说明 | 返回状态|
|----------|------|--------|
| `ConnectState(mIndex)` | 获取连接状态| `int` (0断开, 1连接) |

### 13.2 紧急制动

| Lua 方法 | 说明 |
|----------|------|
| `Emergency(mIndex)` | 紧急停止 |
| `Rapidstop(mIndex, val)` | 快速停止所有轴 |

### 13.3 轴参数设置

```lua
-- 轴类 
ZMotion:SetAtype(mIndex, aIndex, val)      -- 设置轴类型
local atype = ZMotion:GetAtype(mIndex, aIndex)  -- 获取

-- 轴使
ZMotion:SetAxisEnable(mIndex, aIndex, val) -- 设置使能
local enable = ZMotion:GetAxisEnable(mIndex, aIndex) -- 获取

-- 脉冲当量
ZMotion:SetUnits(mIndex, aIndex, 100.0)     -- 100脉冲/单位
local units = ZMotion:GetUnits(mIndex, aIndex)

-- 速度/加速度/减速度
ZMotion:SetSpeed(mIndex, aIndex, 200.0)    -- 速度
ZMotion:SetAccel(mIndex, aIndex, 2000.0)   -- 加速度
ZMotion:SetDecel(mIndex, aIndex, 2000.0)   -- 减速度
ZMotion:SetSramp(mIndex, aIndex, 100.0)    -- S曲线时间
ZMotion:SetLspeed(mIndex, aIndex, 10.0)     -- 起始速度

-- 批量设置
ZMotion:setSpeedVals(mIndex, aIndex, speed, acc, dec)

-- 获取参数
local speed = ZMotion:GetSpeed(mIndex, aIndex)
local accel = ZMotion:GetAccel(mIndex, aIndex)
local decel = ZMotion:GetDecel(mIndex, aIndex)
local sramp = ZMotion:GetSramp(mIndex, aIndex)
local lspeed = ZMotion:GetLspeed(mIndex, aIndex)
```

### 13.4 限位与信号设置

```lua
-- 软限位
ZMotion:SetFsLimit(mIndex, aIndex, 1000.0)  -- 正向限位
ZMotion:SetRsLimit(mIndex, aIndex, -1000.0)  -- 负向限位
local fs = ZMotion:GetFsLimit(mIndex, aIndex)
local rs = ZMotion:GetRsLimit(mIndex, aIndex)

-- 输入信号
ZMotion:SetDatumIn(mIndex, aIndex, bit, validState)  -- 原点
ZMotion:SetFwdIn(mIndex, aIndex, bit, validState)    -- 正限位
ZMotion:SetRevIn(mIndex, aIndex, bit, validState)    -- 负限位
ZMotion:SetAlmIn(mIndex, aIndex, bit, validState)    -- 报警

local datum = ZMotion:GetDatumIn(mIndex, aIndex)
local fwd = ZMotion:GetFwdIn(mIndex, aIndex)
local rev = ZMotion:GetRevIn(mIndex, aIndex)
local alm = ZMotion:GetAlmIn(mIndex, aIndex)

-- 回零参数
ZMotion:SetCreep(mIndex, aIndex, 20.0)      -- 爬行速度
ZMotion:SetHomeWait(mIndex, aIndex, 50)   -- 等待时间
local creep = ZMotion:GetCreep(mIndex, aIndex)
local wait = ZMotion:GetHomeWait(mIndex, aIndex)
```

### 13.5 轴状态

| Lua 方法 | 说明 | 返回 值|
|----------|------|--------|
| `AxisHomeState(mIndex, axis)` | 回零状态| `int` |
| `AxisMoveState(mIndex, axis)` | 运动状状态| `int` |
| `AxisState(mIndex, axis)` | 轴状态| `int` |

### 13.6 运动指令

| Lua 方法 | 说明 | 参数 |
|----------|------|------|
| `AxisStop(mIndex, aIndex)` | 轴停止| 轴索引|
| `AxisVMove(mIndex, axis, direction)` | 连续运动 | 方向(1/-1) |
| `AxisMove(mIndex, axis, distance)` | 相对运动 | 距离 |
| `AxisMoveAbs(mIndex, axis, position)` | 绝对运动 | 目标位置 |
| `AxisMoveHome(mIndex, aIndex, mode)` | 回原运动| 回零模式 |

### 13.7 位置获取/设置

```lua
-- 指令位置
local pos = ZMotion:GetDpos(mIndex, aIndex)  -- 获取
ZMotion:SetDpos(mIndex, aIndex, 0.0)         -- 设置

-- 编码器位置
local pos = ZMotion:GetMpos(mIndex, aIndex)  -- 获取
ZMotion:SetMpos(mIndex, aIndex, 0.0)         -- 设置
```

### 13.8 输入输出

```lua
-- 单点IO
ZMotion:SetOut(mIndex, address, val)   -- 输出
local outVal = ZMotion:GetOut(mIndex, address)
local inVal = ZMotion:GetIn(mIndex, address)

-- 多点IO
ZMotion:SetOuts(mIndex, startAddr, {val1, val2, ...})
local outs = ZMotion:GetOuts(mIndex, address, length)
local ins = ZMotion:GetIns(mIndex, address, length)
```

### 13.9 PLC命令

```lua
-- 发送命令字符串
local response = ZMotion:SendCommand(mIndex, "BASE(0,1,2)")
```

### 13.10 任务控制

```lua
-- 任务状态
local state = ZMotion:GetTaskState(mIndex, taskIndex)

-- 停止任务
ZMotion:StopTask(mIndex, taskIndex)

-- 启动任务字符串
ZMotion:StartTaskString(mIndex, taskIndex, "PRINT 'hello'")

-- 调用任务并等待返
local result = ZMotion:CallTaskString(mIndex, taskIndex, timeout, "var", "BASE(0)")
local floatVal = ZMotion:CallFloatTaskString(mIndex, taskIndex, timeout, "retVar", "F(V0)")
local strVal = ZMotion:CallStringTaskString(mIndex, taskIndex, timeout, "retVar", 10, "STR(V0)")
```

### 13.11 变量寄存器

```lua
-- VR寄存器(float)
ZMotion:SetVR(mIndex, vrIndex, val)
local val = ZMotion:GetVR(mIndex, vrIndex)
ZMotion:SetMulVR(mIndex, vrIndex, {v1, v2, ...})
local vals = ZMotion:GetMulVR(mIndex, vrIndex, count)

-- 位变量
ZMotion:SetBit(mIndex, modIndex, val)
local bit = ZMotion:GetBit(mIndex, modIndex)

-- USHORT寄存器
ZMotion:SetUShortMod(mIndex, vrIndex, val)
local val = ZMotion:GetUShortMod(mIndex, vrIndex)
ZMotion:SetMulUShortMod(mIndex, vrIndex, {v1, v2, ...})
local vals = ZMotion:GetMulUShortMod(mIndex, vrIndex, count)

-- INT寄存器
ZMotion:SetIntMod(mIndex, vrIndex, val)
local val = ZMotion:GetIntMod(mIndex, vrIndex)
ZMotion:SetMulIntMod(mIndex, vrIndex, {v1, v2, ...})
local vals = ZMotion:GetMulIntMod(mIndex, vrIndex, count)

-- FLOAT寄存器
ZMotion:SetFloatMod(mIndex, vrIndex, val)
local val = ZMotion:GetFloatMod(mIndex, vrIndex)
ZMotion:SetMulFloatMod(mIndex, vrIndex, {v1, v2, ...})
local vals = ZMotion:GetMulFloatMod(mIndex, vrIndex, count)

-- 字符串变量
ZMotion:SetStringMod(mIndex, modIndex, length, "value")
local str = ZMotion:GetStringMod(mIndex, modIndex, length)

-- 用户变量
ZMotion:SetUserVar(mIndex, "varName", val)
local val = ZMotion:GetUserVar(mIndex, "varName")
ZMotion:SetUserVarString(mIndex, "varName", length, "value")
local str = ZMotion:GetUserVarString(mIndex, "varName", length)

-- FLASH存储
ZMotion:SetFlash(mIndex, flashId, {v1, v2, ...})
local vals = ZMotion:GetFlash(mIndex, flashId, count)
```

### 13.12 使用示例

```lua
-- 连接检查
local connected = ZMotion:ConnectState(0)
if connected ~= 1 then
    LuaLog:Debug("PLC未连接)
    return
end

-- 轴参数初始化
ZMotion:SetAxisEnable(0, 0, 1)  -- 使能轴
ZMotion:SetUnits(0, 0, 100)    -- 100脉冲/单位
ZMotion:SetSpeed(0, 0, 200)     -- 速度200
ZMotion:SetAccel(0, 0, 2000)   -- 加速度2000
ZMotion:SetDecel(0, 0, 2000)   -- 减速度2000

-- 回原点
ZMotion:AxisMoveHome(0, 0, 0)

-- 运动到100位置
ZMotion:AxisMoveAbs(0, 0, 100.0)

-- 读取当前位置
local pos = ZMotion:GetDpos(0, 0)

-- IO操作
ZMotion:SetOut(0, 0, 1)  -- 输出0置1
local in0 = ZMotion:GetIn(0, 0)  -- 读取输入0

-- VR寄存器用于参数存储
ZMotion:SetVR(0, 0, 100.5)
local speed = ZMotion:GetVR(0, 0)
```

---

## 附录：通用约定

### 索引说明
- 所有设备索引从 `0` 开始
- 轴索引、IO索引同理

### 返回值约定
| 返回值 | 含义 |
|--------|------|
| 0 | 成功 |
| 1 | 参数错误 |
| -1 | 未找到/未连接|
| -2 | 类型错误 |
| -3 | 资源忙/运行中|
| -4 | 超时 |
| 其他 | 具体错误码 |

### 阻塞函数说明
- 所有带 `Func` 后缀的函数为阻塞函数
- `Wait...` 系列函数会阻塞等待条件满足或超时

### 等待超时单位
- `WaitMs` 参数单位：毫秒 (ms)
- 其他等待函数参数若无特殊说明，默认单位为毫秒

---