aiDgeController软PLC控制通讯协议文档

aiDgeController软PLC控制通讯协议文档

概述

本文档定义网关后端（aiDgeController，下称客户端 ）与网关主程序（下称服务端）之间，通过 UnixSocket 进行软PLC启停、调试模式启停及运行状态查询的命令联动协议。

• 客户端：网关后端进程，作为 UnixSocket 客户端主动连接网关主程序
• 服务端：网关主程序进程，作为 UnixSocket 服务端监听命令通道，接收命令并控制软PLC运行时
• 通道建立：服务端先创建并监听 UnixSocket；客户端连接后即可发送命令，每次命令采用"发送 → 等待应答"的同步方式

命令通道 UnixSocket 路径由网关后端配置文件 etc/config.xml 中 /IPCUnixSock/sockName 指定，未配置时默认使用 /tmp/aiDg_UnixSOCK。

协议特性

• 协议版本: 1
• 传输方式: UnixSocket (AF_UNIX, SOCK_STREAM)
• 序列化方式: 二进制包头 + JSON 数据体
• 字节序: 主机字节序（小端）

协议结构

1. 协议包头 (ProtocolHeader)

固定 12 字节，每个数据包必须包含包头（与网关通讯协议 GATEWAY_PROTOCOL.md 包头格式一致）：

偏移	长度	字段名	类型	说明
0	4	magic	uint32_t	魔数，固定值 0x4E474154（ASCII "NGAT"）
4	1	version	uint8_t	协议版本，当前为 1
5	1	cmdType	uint8_t	命令类型（见下文命令定义）
6	2	dataLength	uint16_t	数据体长度，0 ~ 65523
8	2	checksum	uint16_t	校验和
10	2	reserved	uint16_t	保留字节

2. 完整数据包格式

[ProtocolHeader (12B)] [Data (0~65523B)]

3. 校验和计算

1. 先将包头中的 checksum 字段置 0
2. 计算整个包（包头 + 数据体）所有字节的累加和
3. 取结果的低 16 位作为 checksum
4. 将结果填入包头 checksum 字段

命令定义

软PLC启停命令

值	名称	说明	方向	数据体
0x01	CMD_START_PLC	启动软PLC	客户端→服务端	JSON（运行参数）
0x02	CMD_STOP_PLC	停止软PLC	客户端→服务端	无
0x06	CMD_GET_PLC_STATUS	查询软PLC运行状态	客户端→服务端	无

软PLC调试模式启停命令

值	名称	说明	方向	数据体
0x08	CMD_START_PLC_DEBUG	调试模式启动软PLC	客户端→服务端	JSON（运行参数）
0x09	CMD_STOP_PLC_DEBUG	调试模式停止软PLC	客户端→服务端	无

应答命令

值	名称	说明	方向	数据体
0xFF	CMD_ACK	确认/应答	服务端→客户端	视命令而定

数据体格式

1. CMD_START_PLC / CMD_START_PLC_DEBUG 运行参数（JSON）

客户端启动软PLC时，将运行参数以 JSON 格式置于数据体中：

字段	类型	必填	说明
type	string	是	运行方式：cycle 周期扫描方式 / event 事件触发方式
cycle	int	条件	周期扫描周期，单位 ms；type 为 cycle 时必填且必须大于 0
program	string	否	PLC 程序文件绝对路径（网关后端上传目录 plc/ 下的文件）
debug	bool	否	调试模式标记；CMD_START_PLC_DEBUG 命令中固定为 true

示例（周期扫描方式启动）：

{"type":"cycle","cycle":100,"program":"/opt/cnetgate/bin/plc/main.bin"}

示例（事件触发方式调试启动）：

{"type":"event","program":"/opt/cnetgate/bin/plc/main.bin","debug":true}

2. CMD_ACK 应答数据体

CMD_START_PLC / CMD_STOP_PLC / CMD_START_PLC_DEBUG / CMD_STOP_PLC_DEBUG 应答：数据体为 1 字节执行状态（ResponseStatus）：

值	名称	说明
0x00	STATUS_SUCCESS	执行成功
0x01	STATUS_FAILED	执行失败
0x02	STATUS_UNKNOWN_CMD	未知命令
0x03	STATUS_INVALID_PARAM	无效参数
0x04	STATUS_TIMEOUT	超时

CMD_GET_PLC_STATUS 应答：数据体为 1 字节运行状态：

值	说明
0x01	运行中
0x00	已停止

交互流程

1. 启动软PLC（含调试模式启动）

网关后端(客户端)                          网关主程序(服务端)
      |                                        |
      |--- CMD_START_PLC + JSON运行参数 ----->|
      |                                        | 校验参数，加载PLC程序，
      |                                        | 按指定运行方式启动软PLC
      |<-- CMD_ACK + STATUS_SUCCESS(0x00) ----|
      |                                        |

调试模式启动使用 CMD_START_PLC_DEBUG（0x08），流程相同。

2. 停止软PLC（含调试模式停止）

网关后端(客户端)                          网关主程序(服务端)
      |                                        |
      |--- CMD_STOP_PLC --------------------->|
      |                                        | 停止软PLC运行
      |<-- CMD_ACK + STATUS_SUCCESS(0x00) ----|
      |                                        |

调试模式停止使用 CMD_STOP_PLC_DEBUG（0x09），流程相同。

3. 查询软PLC运行状态

网关后端(客户端)                          网关主程序(服务端)
      |                                        |
      |--- CMD_GET_PLC_STATUS --------------->|
      |                                        | 读取软PLC运行状态
      |<-- CMD_ACK + 运行状态(0x01/0x00) -----|
      |                                        |

数据包示例

以"周期扫描方式（100ms）启动软PLC"为例：

请求数据包 （CMD_START_PLC，JSON 数据体 {"type":"cycle","cycle":100} 共 30 字节）：

偏移 0x00: 54 41 47 4E  magic = 0x4E474154 ("NGAT"，小端存储)
偏移 0x04: 01           version = 1
偏移 0x05: 01           cmdType = 0x01 (CMD_START_PLC)
偏移 0x06: 1E 00        dataLength = 30
偏移 0x08: XX XX        checksum（按校验和算法计算）
偏移 0x0A: 00 00        reserved
偏移 0x0C: 7B 22 74 79 70 65 22 3A 22 63 79 63 6C 65 22 2C 22 63 79 63 6C
           65 22 3A 31 30 30 7D    数据体 {"type":"cycle","cycle":100}

应答数据包（CMD_ACK，1 字节状态 0x00）：

偏移 0x00: 54 41 47 4E  magic = 0x4E474154
偏移 0x04: 01           version = 1
偏移 0x05: FF           cmdType = 0xFF (CMD_ACK)
偏移 0x06: 01 00        dataLength = 1
偏移 0x08: XX XX        checksum
偏移 0x0A: 00 00        reserved
偏移 0x0C: 00           STATUS_SUCCESS

与网关后端 REST 接口的对应关系

REST 接口（api.md 16 软PLC）	协议命令
GET /api/v1/startPLC	CMD_START_PLC
GET /api/v1/stopPLC	CMD_STOP_PLC
PUT /api/v1/uploadPLC	无命令（仅保存文件到运行目录 plc/ 子目录）
POST /api/v1/setPLCRuntime	无命令（仅持久化配置，启动时随 CMD_START_PLC 下发）
GET /api/v1/PLCStatus	CMD_GET_PLC_STATUS

注意事项

1. 客户端每次命令等待应答超时时间为 3 秒，超时后判定命令失败
2. 服务端收到无法识别的 cmdType 时，应答 CMD_ACK + STATUS_UNKNOWN_CMD (0x02)
3. 服务端应校验 JSON 运行参数：type 必须为 cycle 或 event；type 为 cycle 时 cycle 必须大于 0，校验失败应答 CMD_ACK + STATUS_INVALID_PARAM (0x03)
4. PLC 程序文件由网关后端通过 PUT /api/v1/uploadPLC 上传至其运行目录 plc/ 子目录，program 字段为该文件的绝对路径，服务端直接读取该路径即可
5. 调试模式的具体行为（如单步运行、跳过输出等）由软PLC运行时实现约定，协议层面仅区分启动/停止通道