aiDgeController软PLC控制通讯协议文档

会周易的程序员2026-09-08 9:35

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

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

json 复制代码 
{"type":"cycle","cycle":100,"program":"/opt/cnetgate/bin/plc/main.bin"}

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

json 复制代码 
{"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运行时实现约定，协议层面仅区分启动/停止通道
相关推荐
把我格子衫拿来4 小时前
VTK 9.5 与 Qt 6 联合开发：从嵌入三维窗口到可维护的桌面架构
c++·python·qt·vtk·三维可视化
无忧.芙桃5 小时前
C++语言原理与实践(十六):多态机制讲解
开发语言·c++·多态
wuminyu7 小时前
JMM学习总结：深入理解happens-before关系
java·linux·c语言·jvm·c++
xxwl5857 小时前
区域赛分类题解
c++·笔记·学习·算法
青少儿编程课堂7 小时前
蓝桥杯+全国青少年信息素养大赛+电子学会PythonC/C++考级：最长公共子序列LCS解析
c++·python·算法·bfs·信息学竞赛
钱工的门窗技术笔记8 小时前
智能门窗的边界与前提：为什么“智能”不能替代本体性能
网络·物联网·智能家居
代钦塔拉9 小时前
【C++/Qt 进阶】设计模式系列(2)：工厂模式——从游戏角色到披萨店
c++·算法·设计模式
乐讯通物联网服务商10 小时前
仓库环境监测器配上物联网卡，环境数据如何实时上云
物联网·物联网卡·仓库环境监测器
把我格子衫拿来10 小时前
VTK 与 Qt 的 CMake 工程怎么组织？模块、工具链与二进制兼容排错
c++·qt·vtk·cmake·工程实践
灯澜忆梦11 小时前
【面向对象编程c++】| 指针与自定义数据类型
开发语言·c++·算法
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02「全语录+省流版」邵艾伦 × 孙宇晨：聊风口、聊个人IP、聊年轻人如何抓住 AI 时代的机会03GitHub 镜像站点04如何新建文件夹？ 电脑新建文件夹的4种方法05历年考研数学一、数学二、数学三真题试卷及答案PDF06几个好用的ip纯净度检测网站07蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接08Telegram APK 下载安装完整指南 — 2026年最新09苹果iPA游戏软件资源下载网站10Windows 10/11 如何退出微软账户并改用本地账户登录（含找不到选项的解决方法）