SoftPLC Socket 通信协议

适用于 rtl-25.01，核对日期：2026-09-10。以当前控制器命令分发、SoftPLC SDK 和示教器调用代码为准；每个命令独立列出功能、JSON、字段含义和响应命令。

通用说明

• 本文描述 Socket 帧中的 SoftPLC JSON 负载，外层 Socket 帧格式沿用通用协议。
• JSON 使用 UTF-8。JSON 语法错误时不产生对应 PLC 回复。
• 除 var_page 从 1 开始外，section、rung、变量和坐标索引均从 0 开始。
• robot 是兼容字段。当前控制器只有一个 SoftPLC 实例，PLC handler 不读取该字段。
• 梯形图固定 12 列，默认 8 行；当前控制器支持扩展至 1000 行。每个 rung 的实际行数由 nbr_lines_used 给出，x=0..11，y=0..nbr_lines_used-1。客户端应通过 0x7434 获取行列容量，不再按固定 8 行解析。
• 编辑成功后工程保存到 ./plc/default.clprj。保存失败可能发生在内存修改之后，收到失败响应时应重新查询相关模型。
• 开机自启配置单独保存到 ./plc/runtime.json，默认关闭；工程文件导入/导出不包含该配置。
• 下文部分示例用空数组或空对象省略模型内容，例如 elements: []、changed_models.rungs: []；完整响应以字段表定义为准。

命令索引

命令字	名称	类型
0x7400	PLC 启动请求	请求
0x7401	PLC 停止请求	请求
0x7402	PLC 状态查询	请求
0x7403	PLC 状态响应	响应
0x7404	PLC 工程概要查询	请求
0x7405	PLC 工程概要响应	响应
0x7406	PLC section 数据查询	请求
0x7407	PLC section 数据响应	响应
0x7411	PLC rung 数据查询	请求
0x7412	PLC rung 数据响应	响应
0x7413	PLC 插入 rung / 行	请求
0x7414	PLC 插入 rung / 行响应	响应
0x7415	PLC 删除 rung / 行	请求
0x7416	PLC 删除 rung / 行响应	响应
0x7420	PLC 元素更新	请求
0x7422	PLC 元素更新响应	响应
0x7423	IEC Timer 更新	请求
0x7424	IEC Timer 更新响应	响应
0x7425	Counter 更新	请求
0x7426	Counter 更新响应	响应
0x7427	CTU 更新	请求
0x7428	CTU 更新响应	响应
0x7429	CTD 更新	请求
0x742A	CTD 更新响应	响应
0x742B	MOVE 更新	请求
0x742C	MOVE 更新响应	响应
0x742D	元素属性更新	请求
0x742E	元素属性更新响应	响应
0x7430	PLC 变量写入	请求
0x7431	PLC 变量读取	请求
0x7432	PLC 变量值响应	响应
0x7433	PLC 通用参数查询	请求
0x7434	PLC 通用参数响应	响应
0x7435	PLC 重置	请求
0x7436	PLC 重置响应	响应
0x7437	PLC 工程导出准备	请求
0x7438	PLC 工程导出准备响应	响应
0x7439	PLC 工程导入准备	请求
0x743A	PLC 工程导入准备响应	响应
0x743B	PLC 工程导入应用	请求
0x743C	PLC 工程导入应用响应	响应
0x743D	PLC 开机自启查询	请求
0x743E	PLC 开机自启设置	请求
0x743F	PLC 开机自启响应	响应

0x7410（PLC_UPDATE_RUNG_INFO_INQUIRE）和 0x7421（PLC_ELEMENT_INQUIRE）目前只在头文件中定义，未接入控制器命令分发，不属于可用请求。

0x7400 PLC 启动请求

功能： 启动 SoftPLC。处理完成后用 0x7403 返回当前状态。

{"robot": 1}

字段	类型	必填	含义
robot	int	否	兼容字段，当前控制器忽略。

0x7401 PLC 停止请求

功能： 停止 SoftPLC，随后执行 PLC reset。处理完成后用 0x7403 返回当前状态。

{"robot": 1}

字段	类型	必填	含义
robot	int	否	兼容字段，当前控制器忽略。

0x7402 PLC 状态查询

功能： 查询 SoftPLC 当前运行状态。用 0x7403 响应。

{"robot": 1}

字段	类型	必填	含义
robot	int	否	兼容字段，当前控制器忽略。

0x7403 PLC 状态响应

功能： 响应 0x7400、0x7401 或 0x7402。

{"state": 2}

字段	类型	含义
state	int	PLC 当前状态。

state 值	含义
0	正在加载
1	已停止
2	正在运行
3	运行冻结
4	单周期运行

该响应没有 ok 和 error。启动或停止失败时会关闭 SoftPLC 运行时，调用方根据最终 state 判断结果。未初始化时 state=-3（PLC_API_ERR_NOT_INITIALIZED），不能将所有返回值都按 0 到 4 的状态枚举处理；其他响应中的 state 也遵循这一规则。

0x7404 PLC 工程概要查询

功能： 查询 section 数量、rung 数量和工程修改状态。用 0x7405 响应。

{"robot": 1}

字段	类型	必填	含义
robot	int	否	兼容字段，当前控制器忽略。

0x7405 PLC 工程概要响应

{
  "section_count": 1,
  "rung_count": 3,
  "current_section_index": 0,
  "dirty_flag": 0
}

字段	类型	含义
section_count	int	当前已使用的 section 数量。
rung_count	int	工程中的 rung 总数量。
current_section_index	int	当前 section 的 0 基索引。
dirty_flag	int	0 表示无未保存修改，1 表示有未保存修改。

读取概要失败时控制器不发送本响应。

0x7406 PLC Section 数据查询

功能： 查询一个 section。控制器按 rung 拆分，每个 rung 单独发送一帧 0x7407。

{
  "robot": 1,
  "section_no": 0,
  "rung_format": "compact-v1"
}

字段	类型	必填	含义
robot	int	否	兼容字段，当前控制器忽略。
section_no	int	否	section 的 0 基索引，缺省为 0。
rung_format	string	否	值为 compact-v1 时，0x7407 中 rung 元素使用紧凑数组；否则使用普通对象。

section 无效或 section 没有 rung 时不发送 0x7407。

0x7407 PLC Section 数据响应

功能： 返回 section 基本信息、一个 rung 和该 rung 引用的功能块。一个 section 通常连续收到多帧。

{
  "section_index": 0,
  "section_no": 0,
  "used": 1,
  "name": "main",
  "language": 0,
  "sub_routine_number": -1,
  "first_rung": 0,
  "last_rung": 2,
  "sequential_page": 0,
  "rung_format": "compact-v1",
  "rung": {
    "index": 0,
    "data": {
      "rung_index": 0,
      "used": 1,
      "prev_rung": -1,
      "next_rung": 1,
      "nbr_lines_used": 8,
      "label": "",
      "comment": "",
      "elements": []
    }
  },
  "models": {
    "counters": [],
    "timers_iec": [],
    "ctus": [],
    "ctds": [],
    "moves": []
  }
}

字段	类型	含义
section_index	int	section 的 0 基索引。
section_no	int	与 section_index 相同，用于协议兼容。
used	int	0 未使用，1 已使用。
name	string	section 名称。
language	int	0 ladder，1 sequential。
sub_routine_number	int	子程序编号；-1 表示主程序 section。
first_rung	int	section 第一个 rung 索引。
last_rung	int	section 最后一个 rung 索引。
sequential_page	int	sequential 页号；ladder 通常为 0。
rung_format	string	仅请求 compact-v1 时存在。
rung.index	int	本帧携带的 rung 索引。
rung.data	object	本帧的 rung 数据。
models.counters	array	本 rung 引用的 Counter 模型。
models.timers_iec	array	本 rung 引用的 IEC Timer 模型。
models.ctus	array	本 rung 引用的 CTU 模型。
models.ctds	array	本 rung 引用的 CTD 模型。
models.moves	array	本 rung 引用的 MOVE 模型。

rung.data 字段：

字段	类型	含义
rung_index	int	rung 索引。
used	int	0 未使用，1 已使用。
prev_rung	int	前一个 rung；-1 表示没有。
next_rung	int	后一个 rung；-1 表示没有。
nbr_lines_used	int	本 rung 的逻辑行数，包含空行；普通和 compact-v1 格式都只返回这些行。
label	string	rung 标签。
comment	string	rung 注释。
elements	array	elements[y][x]，共 nbr_lines_used 行，每行 12 列。

普通元素对象字段：

字段	类型	含义
type	int	元素类型。
connected_with_top	int	是否与上方元素连接。
var_type	int	变量类型。
var_num	int	变量 0 基编号。
indexed_var_type	int	索引变量类型；-1 表示未使用。
indexed_var_num	int	索引变量编号。
dynamic_input	int	运行时输入状态。
dynamic_state	int	运行时元素状态。
dynamic_var_bak	int	运行时变量备份值。
dynamic_output	int	运行时输出状态。
dynamic_var_setted	int	运行时变量是否已设置。
rung_index/x/y	int	元素所在 rung 和坐标。

compact-v1 元素为 [type,connected_with_top,var_type,var_num,indexed_var_type,indexed_var_num,runtime_bits]。runtime_bits 的 bit0 到 bit4 依次表示 dynamic_input、dynamic_state、dynamic_var_bak、dynamic_output、dynamic_var_setted。

0x7411 PLC Rung 数据查询

功能： 查询单个 rung、批量完整模型或批量运行态。用 0x7412 响应。

单个查询：

{"rung_no": 0}

批量查询：

{"robot": 1, "rung_nos": [0, 1, 2]}

字段	类型	必填	含义
robot	int	否	兼容字段，控制器忽略。
rung_no	int	单个查询时必填	要查询的 rung 索引。
rung_nos	array<int>	批量查询时必填	rung 索引数组。存在该数组时走批量路径。
rung_format	string	否	当前命令忽略该字段；完整模型使用普通格式，运行态使用下面的专用结构。
runtime_only	int	否	仅批量查询有效。缺省 0 返回完整模型；非 0 只返回运行态。
request_id	JSON 值	否	仅批量运行态查询原样回传，可用于匹配请求；其他查询路径不回传。

运行态查询：

{"robot": 1, "rung_nos": [0, 1], "runtime_only": 1, "request_id": 12}

rung_nos 是数组时优先于 rung_no，包括空数组；没有该数组时走单 rung 路径，忽略 runtime_only 和 request_id。

0x7412 PLC Rung 数据响应

单个查询响应是一个普通 rung：

{
  "rung_index": 0,
  "used": 1,
  "prev_rung": -1,
  "next_rung": 1,
  "nbr_lines_used": 8,
  "label": "",
  "comment": "",
  "elements": []
}

字段	类型	含义
rung_index	int	rung 索引。
used	int	0 未使用，1 已使用。
prev_rung	int	前一个 rung；-1 表示没有。
next_rung	int	后一个 rung；-1 表示没有。
nbr_lines_used	int	本 rung 的逻辑行数，包含空行。
label	string	rung 标签。
comment	string	rung 注释。
elements	array	nbr_lines_used x 12 普通元素对象数组。字段含义与 0x7407 相同。

单个 rung 无效时响应为 JSON null。

批量查询响应：

{
  "ok": 1,
  "rungs": [],
  "models": {
    "counters": [],
    "timers_iec": [],
    "ctus": [],
    "ctds": [],
    "moves": []
  }
}

字段	类型	含义
ok	int	当前批量路径固定为 1。
rungs	array	查询成功的普通 rung 对象。无效 rung 被跳过。
models.*	array	所有成功 rung 引用的功能块模型。

批量运行态响应（runtime_only != 0）：

{
  "ok": 1,
  "runtime_only": 1,
  "request_id": 12,
  "rungs": [
    {
      "rung_no": 0,
      "nbr_lines_used": 8,
      "states": [
        0,0,0,0,0,0,0,0,0,0,0,0,
        0,0,0,0,0,0,0,0,0,0,0,0,
        0,0,0,0,0,0,0,0,0,0,0,0,
        0,0,0,0,0,0,0,0,0,0,0,0,
        0,0,0,0,0,0,0,0,0,0,0,0,
        0,0,0,0,0,0,0,0,0,0,0,0,
        0,0,0,0,0,0,0,0,0,0,0,0,
        0,0,0,0,0,0,0,0,0,0,0,0
      ],
      "runtime_values": [
        {"x": 0, "y": 0, "value": 0},
        {"x": 2, "y": 0, "current": 0, "preset": 10}
      ]
    }
  ]
}

字段	类型	含义
ok	int	固定为 1；无效 rung 跳过，不代表每个请求的 rung 都有效。
runtime_only	int	固定为 1。
request_id	JSON 值	仅请求包含该字段时存在，原样回传。
rungs[].rung_no	int	rung 索引；注意这里使用 rung_no，不是完整模型中的 rung_index。
rungs[].nbr_lines_used	int	本 rung 实际返回的逻辑行数。
rungs[].states	array<int>	一维数组，按行排列，长度为 nbr_lines_used * 12，坐标 (x,y) 对应 states[y * 12 + x]。
rungs[].runtime_values	array<object>	可读取的元素数值；没有数值时整个字段省略。
runtime_values[].x/y	int	数值所属元素在 rung 内的坐标。
runtime_values[].value	int	触点或线圈绑定的变量值，已解析索引变量偏移。
runtime_values[].current/preset	int	Counter、IEC Timer、CTU、CTD 的当前值和预置值。
runtime_values[].input/output	int	MOVE 的输入值和输出值。

states 每项的 bit0 到 bit4 与 compact-v1 的 runtime_bits 相同。数值字段按元素类型和读取结果提供，可能只存在其中一部分，不能把缺失字段当作 0；本接口数值按 int 读取，GD 的小数部分不会保留。

运行态响应不含 elements、标签、注释及 models，应叠加到已获取的完整模型上。空请求数组或全部 rung 无效时返回 rungs: []。当前示教器用此路径轮询可见 rung。

0x7413 PLC 插入 Rung / 行请求

功能： 未传 row_no 时，在 anchor rung 后插入新 rung；传入 row_no 时，在指定 rung 的该行之后插入一行。两种路径都用 0x7414 响应。

插入整个 rung：

{"robot": 1, "rung_no": 0, "rung_format": "compact-v1"}

字段	类型	必填	含义
robot	int	否	兼容字段，控制器忽略。
rung_no	int	是	整个 rung 路径为 anchor 索引；行路径为要修改的 rung 索引。
rung_format	string	否	插入整个 rung 时，仅 compact-v1 响应包含变更模型；插入行时始终返回变更模型，该字段只控制 rung 编码格式。
row_no	int	否	存在时切换为行插入，表示插入位置之前的 0 基行号，范围为 0..nbr_lines_used-1。

在 rung 0 的第 0 行之后插入一行：

{"robot": 1, "rung_no": 0, "row_no": 0, "rung_format": "compact-v1"}

新行为空行，后续行下移，nbr_lines_used 加 1。已达最大行数、行号越界、插入位置跨越多行功能块或竖向连接时失败。

0x7414 PLC 插入 Rung / 行响应

未传 row_no 时：

{
  "action": "insert",
  "anchor_rung_no": 0,
  "section_no": 0,
  "ok": 1,
  "inserted_rung_no": 1,
  "rung_format": "compact-v1",
  "changed_models": {"section": {}, "rungs": []}
}

字段	类型	含义
action	string	固定为 insert。
anchor_rung_no	int	请求中的 anchor rung。
section_no	int	所属 section 索引；找不到时为 -1。
ok	int	1 成功，0 失败。
inserted_rung_no	int	新 rung 索引，仅成功时存在。
rung_format	string	仅 compact-v1 请求成功时存在。
changed_models.section	object	仅 compact-v1 请求成功且找到 section 时返回变更后的 section。
changed_models.rungs	array	仅 compact-v1 请求成功时返回 anchor、新 rung 和可能的后继 rung。
error	string	失败原因，仅失败时存在。

传入 row_no 时：

{
  "action": "insert_row",
  "rung_no": 0,
  "row_no": 1,
  "section_no": 0,
  "ok": 1,
  "rung_format": "compact-v1",
  "changed_models": {"section": {}, "rungs": []}
}

字段	类型	含义
action	string	固定为 insert_row。
rung_no	int	请求中的 rung 索引；行路径不返回 anchor_rung_no、inserted_rung_no。
row_no	int	新行索引，即请求的 row_no + 1；失败响应也按此规则回填。
section_no	int	所属 section 索引，找不到为 -1。
ok	int	1 成功，0 失败。
rung_format	string	仅 compact-v1 请求成功时存在。
changed_models.section	object	成功且找到 section 时返回的 section 元数据。
changed_models.rungs	array	成功时返回修改后的当前 rung；未请求 compact-v1 时使用普通格式。
error	string	仅失败时存在。

0x7415 PLC 删除 Rung / 行请求

功能： 未传 row_no 时删除整个 rung；传入 row_no 时删除 rung 内的一行。用 0x7416 响应。

删除整个 rung：

{"robot": 1, "rung_no": 1, "rung_format": "compact-v1"}

字段	类型	必填	含义
robot	int	否	兼容字段，控制器忽略。
rung_no	int	是	整个 rung 路径为要删除的 rung；行路径为要修改的 rung 索引。
rung_format	string	否	删除整个 rung 时，仅 compact-v1 响应包含变更模型；删除行时始终返回变更模型，该字段只控制 rung 编码格式。
row_no	int	否	存在时切换为行删除，表示要删除的 0 基行号，范围为 0..nbr_lines_used-1。

删除 rung 0 的第 1 行：

{"robot": 1, "rung_no": 0, "row_no": 1, "rung_format": "compact-v1"}

后续行上移，nbr_lines_used 减 1。当前行数不得减到 8 以下；行号越界、目标行占用多行功能块或与上下行有竖向连接时失败。目标行不必为空，允许删除该行中的普通触点、线圈或水平连接。

0x7416 PLC 删除 Rung / 行响应

未传 row_no 时：

{
  "action": "delete",
  "section_no": 0,
  "deleted_rung_no": 1,
  "ok": 1,
  "rung_format": "compact-v1",
  "changed_models": {"section": {}, "rungs": []}
}

字段	类型	含义
action	string	固定为 delete。
section_no	int	删除前所属 section。
deleted_rung_no	int	被删除的 rung。
ok	int	1 成功，0 失败。
rung_format	string	仅 compact-v1 请求成功时存在。
changed_models.section	object	仅 compact-v1 请求成功且找到 section 时返回。
changed_models.rungs	array	仅 compact-v1 请求成功且有相邻 rung 时返回变更后的前驱和后继 rung。
error	string	失败原因。

传入 row_no 时：

{
  "action": "delete_row",
  "rung_no": 0,
  "row_no": 1,
  "section_no": 0,
  "ok": 1,
  "rung_format": "compact-v1",
  "changed_models": {"section": {}, "rungs": []}
}

action 固定为 delete_row，row_no 为请求中要删除的行号，rung_no 为所在 rung；不返回 deleted_rung_no。其余字段及存在条件与 insert_row 响应相同，成功时返回修改后的当前 rung。

0x7420 PLC 元素更新请求

功能： 插入、替换或删除单个元素，也支持批量更新。用 0x7422 响应。

单元素：

{
  "robot": 1,
  "section_no": 0,
  "rung_format": "compact-v1",
  "rung_no": 0,
  "x": 0,
  "y": 0,
  "element": {
    "type": 1,
    "var_type": 400,
    "var_num": 0,
    "indexed_var_type": -1,
    "indexed_var_num": 0
  }
}

批量：

{
  "robot": 1,
  "rung_format": "compact-v1",
  "elements": [
    {"rung_no": 0, "x": 0, "y": 0, "element": {"type": 0}},
    {"rung_no": 0, "x": 1, "y": 0, "element": {"type": 0}}
  ]
}

字段	类型	必填	含义
robot	int	否	兼容字段，控制器忽略。
section_no	int	否	兼容字段，当前定位实际使用 rung_no/x/y。
rung_format	string	否	compact-v1 时 changed_models.rungs 使用紧凑格式。
rung_no	int	单元素时必填	rung 索引。
x/y	int	单元素时必填	元素坐标。
element	object	单元素时必填	新元素数据；type=0 表示删除。
elements	array	批量时必填	多个包含 rung_no/x/y/element 的项目。

element 字段：

字段	类型	含义
type	int	元素类型；0 free，1 常开输入，2 常闭输入，3 上升沿，4 下降沿，9 水平连接，10 旧 Timer，11 Monostable，12 Counter，13 IEC Timer，14 Register，20 比较，50 到 53 输出，54 jump，55 call，60 operate，300 CTU，301 CTD，302 MOVE。编辑动作还支持 100 竖向连接、102 长连接、107 取反。
var_type	int	PLC 变量类型，常用 400 到 407。
var_num	int	变量 0 基编号或功能块实例编号。
indexed_var_type	int	索引变量类型，-1 表示不使用。
indexed_var_num	int	索引变量编号。

普通触点（1、2）可绑定 X/Y/M/T/C/GB/GI/GD；边沿触点（3、4）及线圈（50 到 53）当前属性校验仅接受 X/Y/GB，索引变量也按相同范围校验。X 仍是只读变量，线圈写出应使用 Y 或 GB。输出元素须放在末列，多格功能块受占用和边界约束。

type=100 设置与上方的竖向连接（要求 y>0）；type=102 从当前空格向右补水平连接，遇非空格或输出列前停止；type=107 切换触点/线圈的对应类型（1/2、3/4、50/51、52/53）。这些值是编辑动作，不作为响应中的持久元素类型。

功能块插入时由控制器分配实例编号，不能依靠本请求的 var_num 指定新功能块实例；应重新读取 rung/功能块模型，再用对应的模型更新命令设置参数。connected_with_top 和运行态字段不从本请求的 element 对象读取。

批量处理不是事务，首次失败后停止；已成功项目会尝试保存。响应 ok=0 也可能包含已成功项目的 changed_models。单项内部先改元素类型、再设置属性，属性校验失败时前一步可能已经生效；失败后应重新查询对应 rung。

0x7422 PLC 元素更新响应

{
  "action": "update_elements",
  "section_no": 0,
  "rung_no": 0,
  "x": 0,
  "y": 0,
  "processed_count": 2,
  "requested_count": 2,
  "ok": 1,
  "rung_format": "compact-v1",
  "changed_models": {"rungs": []}
}

字段	类型	含义
action	string	单元素为 insert_element，批量为 update_elements。
section_no	int	第一个处理元素所属 section；找不到时为 -1。
rung_no	int	第一个处理元素的 rung。
x/y	int	第一个处理元素坐标。
processed_count	int	成功处理的元素数量。
requested_count	int	批量请求总数，仅批量时存在。
ok	int	1 全部成功，0 发生失败。
rung_format	string	请求 compact-v1 且有 changed rung 时存在。
changed_models.rungs	array	已发生变化的 rung。
error	string	失败原因。

0x7423 IEC Timer 更新请求

{
  "robot": 1,
  "timer_index": 0,
  "timer_iec": {
    "preset": {"type": 0, "num": 10},
    "value": {"type": 403, "num": 0},
    "base": 1000,
    "timer_mode": 0,
    "display_format": ""
  }
}

字段	类型	必填	含义
robot	int	否	兼容字段，控制器忽略。
timer_index	int	是	IEC Timer 实例索引。
timer_iec.preset	object	是	预置值引用。type=0 时 num 是常量。
timer_iec.value	object	是	当前值变量引用。
timer_iec.base	int	是	时间基值，只接受 100、1000、60000 毫秒；省略时解析为 0，校验失败。
timer_iec.timer_mode	int	否	0 TON，1 TOF，2 TP。
timer_iec.display_format	string	否	ClassicLadder 显示格式。

请求中的运行态字段会被忽略。

IEC Timer、Counter、CTU、CTD 的 preset/value 均为 {"type": ..., "num": ...} 引用：type=0 时 num 为非负整数常量，其他情况为变量编号。当前可引用 X/Y/M/T/C/GI/GD，不接受 GB；MOVE 的 in/out 额外允许 GB。旧引用类型 1、2 分别兼容为 GI（406）、GD（407），响应使用规范化类型。变量编号须在对应容量范围内。

这些模型更新请求不是局部合并，未提供的引用或运行态字段通常按 0 解析；Timer 的 base 尤其必须显式传入。Counter、CTU、CTD 和 MOVE 会读取并写入请求中的运行态字段；Timer 更新则清零输入、备份输入、输出、启动标记和时间基累积值，并向当前值引用写入 0。

0x7424 IEC Timer 更新响应

{
  "action": "update_timer_iec",
  "timer_index": 0,
  "ok": 1,
  "timer_iec": {}
}

字段	类型	含义
action	string	固定为 update_timer_iec。
timer_index	int	Timer 索引。
ok	int	1 成功，0 失败。
timer_iec	object	成功时的完整模型。
error	string	失败原因。

timer_iec 包含 timer_index,preset,value,base,timer_mode,display_format,input,input_bak,output,timer_started,value_to_reach_one_base_unit。input/output 等字段是运行态。

0x7425 Counter 更新请求

{
  "robot": 1,
  "counter_index": 0,
  "counter": {
    "preset": {"type": 0, "num": 10},
    "value": {"type": 404, "num": 0},
    "value_bak": 0,
    "input_reset": 0,
    "input_preset": 0,
    "input_count_up": 0,
    "input_count_up_bak": 0,
    "input_count_down": 0,
    "input_count_down_bak": 0,
    "output_done": 0,
    "output_empty": 0,
    "output_full": 0
  }
}

字段	类型	含义
robot	int	兼容字段，控制器忽略。
counter_index	int	Counter 实例索引。
counter.preset	object	预置值引用。
counter.value	object	当前值引用。
value_bak	int	上一次值。
input_reset	int	reset 输入状态。
input_preset	int	preset 输入状态。
input_count_up/input_count_up_bak	int	加计数当前/备份输入。
input_count_down/input_count_down_bak	int	减计数当前/备份输入。
output_done	int	完成输出。
output_empty	int	空输出。
output_full	int	满输出。

0x7426 Counter 更新响应

{"action":"update_counter","counter_index":0,"ok":1,"counter":{}}

字段	类型	含义
action	string	固定为 update_counter。
counter_index	int	Counter 索引。
ok	int	1 成功，0 失败。
counter	object	成功时的完整 Counter，字段同 0x7425，并额外带 counter_index。
error	string	失败原因。

0x7427 CTU 更新请求

{
  "robot": 1,
  "ctu_index": 0,
  "ctu": {
    "preset": {"type":0,"num":10},
    "value": {"type":404,"num":0},
    "input_reset": 0,
    "input_count_up": 0,
    "input_count_up_bak": 0,
    "output_done": 0
  }
}

字段	类型	含义
robot	int	兼容字段，控制器忽略。
ctu_index	int	CTU 实例索引。
ctu.preset	object	预置值引用。
ctu.value	object	当前值引用。
input_reset	int	reset 输入。
input_count_up	int	加计数输入。
input_count_up_bak	int	上一次加计数输入。
output_done	int	完成输出。

0x7428 CTU 更新响应

{"action":"update_ctu","ctu_index":0,"ok":1,"ctu":{}}

字段	类型	含义
action	string	固定为 update_ctu。
ctu_index	int	CTU 索引。
ok	int	1 成功，0 失败。
ctu	object	成功时完整 CTU，字段同 0x7427，额外带 ctu_index。
error	string	失败原因。

0x7429 CTD 更新请求

{
  "robot": 1,
  "ctd_index": 0,
  "ctd": {
    "preset": {"type":0,"num":10},
    "value": {"type":404,"num":0},
    "input_load": 0,
    "input_count_down": 0,
    "input_count_down_bak": 0,
    "output_done": 0
  }
}

字段	类型	含义
robot	int	兼容字段，控制器忽略。
ctd_index	int	CTD 实例索引。
ctd.preset	object	预置值引用。
ctd.value	object	当前值引用。
input_load	int	load 输入；兼容字段名 input_reset。
input_count_down	int	减计数输入。
input_count_down_bak	int	上一次减计数输入。
output_done	int	完成输出。

0x742A CTD 更新响应

{"action":"update_ctd","ctd_index":0,"ok":1,"ctd":{}}

字段	类型	含义
action	string	固定为 update_ctd。
ctd_index	int	CTD 索引。
ok	int	1 成功，0 失败。
ctd	object	成功时完整 CTD，字段同 0x7429，额外带 ctd_index。
error	string	失败原因。

0x742B MOVE 更新请求

{
  "robot": 1,
  "move_index": 0,
  "move": {
    "in": {"type":0,"num":10},
    "out": {"type":406,"num":0},
    "out_bak": 0,
    "en": 0,
    "en_bak": 0,
    "eno": 0
  }
}

字段	类型	含义
robot	int	兼容字段，控制器忽略。
move_index	int	MOVE 实例索引。
move.in	object	输入值引用。
move.out	object	输出值引用。
out_bak	int	上一次输出值。
en	int	使能输入。
en_bak	int	上一次使能输入。
eno	int	使能输出。

0x742C MOVE 更新响应

{"action":"update_move","move_index":0,"ok":1,"move":{}}

字段	类型	含义
action	string	固定为 update_move。
move_index	int	MOVE 索引。
ok	int	1 成功，0 失败。
move	object	成功时完整 MOVE，字段同 0x742B，额外带 move_index。
error	string	失败原因。

0x742D PLC 元素属性更新请求

功能： 不改变元素类型，仅修改变量引用属性。

{
  "robot": 1,
  "section_no": 0,
  "rung_format": "compact-v1",
  "rung_no": 0,
  "x": 0,
  "y": 0,
  "element": {
    "type": 1,
    "var_type": 402,
    "var_num": 0,
    "indexed_var_type": -1,
    "indexed_var_num": 0
  }
}

字段	类型	含义
robot	int	兼容字段，控制器忽略。
section_no	int	兼容字段，控制器实际按 rung 定位。
rung_format	string	compact-v1 时响应 rung 使用紧凑格式。
rung_no	int	rung 索引。
x/y	int	元素坐标。
element.type	int	必须与当前位置可编辑元素的类型相同。
element.var_type	int	新变量类型。
element.var_num	int	新变量编号。
element.indexed_var_type	int	索引变量类型，-1 表示不使用。
element.indexed_var_num	int	索引变量编号。

触点/线圈的变量及索引变量范围与 0x7420 相同；功能块、jump/call 和表达式元素仅更新 var_num。若坐标落在多格功能块的占位格上，控制器会解析到可编辑主格；响应 x/y 仍回填请求坐标，客户端应应用返回的完整 rung。

0x742E PLC 元素属性更新响应

{
  "action": "update_element_properties",
  "section_no": 0,
  "rung_no": 0,
  "x": 0,
  "y": 0,
  "ok": 1,
  "rung_format": "compact-v1",
  "changed_models": {"rungs":[]}
}

字段	类型	含义
action	string	固定为 update_element_properties。
section_no	int	元素所属 section。
rung_no/x/y	int	被修改元素的位置。
ok	int	1 成功，0 失败。
rung_format	string	请求 compact-v1 且成功时存在。
changed_models.rungs	array	修改后的 rung。
error	string	失败原因。类型不匹配时为 element type mismatch for property update。

0x7430 PLC 变量写入请求

功能： 按页写入 10 个 PLC 变量。用 0x7432 返回结果。

{
  "var_type": 402,
  "var_page": 1,
  "value": [1,0,0,0,0,0,0,0,0,0]
}

字段	类型	必填	含义
var_type	int	是	400 X、401 Y、402 M、403 T、404 C、405 GB、406 GI、407 GD。
var_page	int	是	1 基页码，每页 10 个变量。
value	array<int>	是	10 个写入值。最后一页越界位置被忽略并在响应中返回 0。

X 是只读变量。写 X 仍会收到 0x7432，其中 ok=0,error="read_only"，value 全为 0。无效类型、页码小于 1 或底层变量写入失败时不发送该响应。超出变量总数的整页返回 10 个 0，ok=1；成功响应的 value 是请求值回显，不是写后回读值。

0x7431 PLC 变量读取请求

{"var_type": 402, "var_page": 1}

字段	类型	必填	含义
var_type	int	是	400 X、401 Y、402 M、403 T、404 C、405 GB、406 GI、407 GD。
var_page	int	是	1 基页码，每页 10 个变量。

无效类型、页码小于 1 或底层变量读取失败时不发送 0x7432。超出变量总数的整页返回 10 个 -1，ok=1。

0x7432 PLC 变量值响应

功能： 响应 0x7430 或 0x7431。

{
  "var_type": 402,
  "var_page": 1,
  "ok": 1,
  "value": [0,0,0,0,0,0,0,0,0,0]
}

字段	类型	含义
var_type	int	请求的变量类型。
var_page	int	请求的 1 基页码。
ok	int	1 成功，0 失败。
value	array<int>	10 个变量值。读取最后一页时，越界位置为 -1；写入响应越界位置为 0。
error	string	失败原因；当前明确值包括 read_only。

变量数量：X 16、Y 16、M 999、T 99、C 99、GB/GI/GD 各 999。GD 在该接口中按 int 传输，小数会丢失。

0x7433 PLC 通用参数查询

{"robot": 1}

字段	类型	必填	含义
robot	int	否	兼容字段，控制器忽略。

用 0x7434 响应。

0x7434 PLC 通用参数响应

{
  "nbr_rungs": 0,
  "nbr_bits": 0,
  "nbr_words": 0,
  "nbr_counters": 0,
  "nbr_ctus": 0,
  "nbr_ctds": 0,
  "nbr_moves": 0,
  "nbr_timers_iec": 0,
  "nbr_registers": 0,
  "register_list_size": 0,
  "nbr_phys_inputs": 0,
  "nbr_phys_outputs": 0,
  "nbr_arithm_expr": 0,
  "nbr_sections": 0,
  "nbr_symbols": 0,
  "nbr_phys_words_inputs": 0,
  "nbr_phys_words_outputs": 0,
  "period_millis_task_logic": 0,
  "period_millis_task_scan_inputs": 0,
  "real_inputs_outputs_only_on_target": 0,
  "automatically_adjust_summer_winter_time": 0,
  "rung_width": 12,
  "rung_height_default": 8,
  "rung_height_max": 1000
}

字段	类型	含义
nbr_rungs	int	rung 容量。
nbr_bits	int	ClassicLadder 内部 bit 数量。
nbr_words	int	ClassicLadder 内部 word 数量。
nbr_counters	int	Counter 数量。
nbr_ctus	int	CTU 数量。
nbr_ctds	int	CTD 数量。
nbr_moves	int	MOVE 数量。
nbr_timers_iec	int	IEC Timer 数量。
nbr_registers	int	Register 数量。
register_list_size	int	Register 数据列表容量。
nbr_phys_inputs	int	物理 bit 输入数量。
nbr_phys_outputs	int	物理 bit 输出数量。
nbr_arithm_expr	int	算术表达式数量。
nbr_sections	int	section 容量。
nbr_symbols	int	符号表容量。
nbr_phys_words_inputs	int	物理 word 输入数量。
nbr_phys_words_outputs	int	物理 word 输出数量。
period_millis_task_logic	int	PLC 逻辑任务周期，单位 ms。
period_millis_task_scan_inputs	int	输入扫描任务周期，单位 ms。
real_inputs_outputs_only_on_target	int	是否只在目标设备使用真实 IO。
automatically_adjust_summer_winter_time	int	是否自动调整夏令时和冬令时。
rung_width	int	每个 rung 的列数，当前为 12。
rung_height_default	int	默认行数及行删除下限，当前为 8。
rung_height_max	int	每个 rung 的最大行数，当前控制器为 1000。

示例中其他容量和周期的 0 是占位值，实际值以控制器返回为准。

当前 SoftPLC 页面在初始化和成功导入后会发送本查询，响应信号由通信层转发；页面暂未连接消费这些字段的槽函数。协议接入方仍应读取新增的行列容量字段。

0x7435 PLC 重置请求

功能： 调用 ClassicLadder reset。用 0x7436 响应。

{"robot": 1}

字段	类型	必填	含义
robot	int	否	兼容字段，控制器忽略。

reset 会重置 ClassicLadder 运行数据，并恢复原先的运行状态；它不是停止命令，运行中调用后可能继续运行。需要保持停止时使用 0x7401 并确认状态。

当前 reset 没有调用 PlcVariableSystem::resetRuntime()，因此不能保证扩展变量 M/T/C 全部清零。

0x7436 PLC 重置响应

{"ok": 1, "state": 1}

字段	类型	含义
ok	int	1 重置成功，0 重置失败。
state	int	重置后的 PLC 状态，含义同 0x7403；运行中重置不保证变为 1，未初始化可返回 -3。
error	string	失败原因，仅失败时存在。

0x7437 PLC 工程导出准备请求

功能： 将当前内存工程保存为可下载的 default.clprj 快照，用 0x7438 返回下载信息。调用前必须确认 PLC 为停止状态（state=1）；未停止时先用 0x7401 停止并等待状态响应。

{"robot": 1}

字段	类型	必填	含义
robot	int	否	兼容字段，控制器忽略。

该命令只准备工程文件，不在 PLC JSON 响应中传输文件内容。

0x7438 PLC 工程导出准备响应

{
  "ok": 1,
  "state": 1,
  "remote_path": "./plc/transfer/default.clprj",
  "file_name": "default.clprj",
  "size": 4096,
  "md5": "0123456789abcdef0123456789abcdef"
}

字段	类型	含义
ok	int	1 准备成功，0 失败。
state	int	当前 PLC 状态。
remote_path	string	成功时的控制器下载路径，当前固定为 ./plc/transfer/default.clprj。
file_name	string	成功时的建议文件名，固定为 default.clprj。
size	uint	成功时的文件字节数，范围为 1 到 16777216（16 MiB）。
md5	string	成功时文件的 32 位小写十六进制 MD5。
code	string	失败时的错误分类：plc_running、prepare_failed 或 export_failed。
error	string	仅失败时存在，错误说明。

示例中的 size、md5 仅为格式示意；下载完成后应校验文件实际大小和 MD5。每次导出准备都会重新生成该路径的快照。

0x7439 PLC 工程导入准备请求

功能： 在 PLC 停止时准备上传路径，用 0x743A 响应。当前仅支持 .clprj 工程，文件大小不得超过 16 MiB。

{"robot": 1, "extension": "clprj", "size": 4096}

字段	类型	必填	含义
robot	int	否	兼容字段，控制器忽略。
extension	string	是	必须为小写 clprj，不带点。
size	uint	是	待上传文件的实际字节数，范围为 1 到 16777216。

准备成功会删除原暂存文件并登记新的待导入路径。此时尚未替换当前工程。

0x743A PLC 工程导入准备响应

{
  "ok": 1,
  "state": 1,
  "remote_path": "./plc/transfer/import.clprj",
  "max_size": 16777216
}

字段	类型	含义
ok	int	1 准备成功，0 失败。
state	int	当前 PLC 状态。
remote_path	string	成功时的上传路径，当前固定为 ./plc/transfer/import.clprj。
max_size	uint	成功时返回最大文件字节数，当前为 16777216。
code	string	失败时的错误分类：plc_running、invalid_file 或 prepare_failed。
error	string	仅失败时存在，错误说明。

收到成功响应后，通过通用文件传输通道上传到 remote_path；上传完成后再发送 0x743B。

0x743B PLC 工程导入应用请求

功能： 校验已上传工程，备份当前工程，加载新工程并保存到 ./plc/default.clprj，重新加载后执行 reset。用 0x743C 响应。调用时仍须为停止状态。

{
  "robot": 1,
  "size": 4096,
  "md5": "0123456789abcdef0123456789abcdef"
}

字段	类型	必填	含义
robot	int	否	兼容字段，控制器忽略。
size	uint	是	已上传文件的实际字节数，必须与暂存文件一致且在 1 到 16777216 之间。
md5	string	是	已上传文件的 32 位小写十六进制 MD5；控制器按字符串精确比较。

请求不接受自选应用路径，始终使用最近一次成功准备的暂存路径。size、md5 必须由实际文件计算，不能照抄示例。

每次应用尝试都会消费待导入状态；校验失败、导入失败或调用时 PLC 已不在停止状态，均需重新执行准备、上传、应用流程。导入过程失败会尝试恢复原工程；不能仅凭文件上传成功判断工程已生效。

0x743C PLC 工程导入应用响应

{
  "ok": 1,
  "state": 1,
  "project_summary": {
    "section_count": 1,
    "rung_count": 3,
    "current_section_index": 0,
    "dirty_flag": 0
  }
}

字段	类型	含义
ok	int	1 已应用成功，0 失败。
state	int	应用或错误处理后的 PLC 状态。成功后保持停止，不自动启动。
project_summary	object	成功且能读取概要时存在，字段与 0x7405 相同。
code	string	仅失败时存在，取值见下表。
error	string	仅失败时存在，错误说明。

工程导入/导出错误分类：

code	适用响应	含义
plc_running	0x7438/0x743A/0x743C	当前状态不是 STOP（1），包括运行、冻结、加载或未初始化等状态。
prepare_failed	0x7438/0x743A	无法创建工程传输目录。
export_failed	0x7438	快照保存失败，或导出文件不存在、为空、超过大小限制。
invalid_file	0x743A	扩展名或声明的文件大小不合法。
not_prepared	0x743C	没有待应用的导入准备记录。
validation_failed	0x743C	暂存文件无效、大小不匹配或 MD5 不匹配。
backup_failed	0x743C	无法备份当前工程，尚未加载新工程。
import_failed	0x743C	导入失败，已恢复原工程。
rollback_failed	0x743C	导入及原工程恢复均失败，需检查控制器上的工程状态。

失败响应示例：

{
  "ok": 0,
  "code": "validation_failed",
  "error": "SoftPLC project validation failed",
  "state": 1
}

工程文件传输顺序

工程二进制数据复用通用文件传输通道，PLC 命令只负责准备和应用：

1. 导出：停止 PLC 并确认 state=1，发送 0x7437，收到成功的 0x7438 后，用 0x1074（REQUEST_DOWNLOAD_FILE）请求下载；等待通用文件传输完成，再核对大小和 MD5。
2. 导入：停止 PLC 并确认 state=1，发送 0x7439，收到成功的 0x743A 后，用 0x1072（REQUEST_UPLOAD_FILE）请求上传；等待上传完成，再发送 0x743B。收到成功的 0x743C 后，重新查询工程概要、section 和通用参数。

通用下载请求 0x1074：

{"name": "./plc/transfer/default.clprj"}

通用上传请求 0x1072：

{"name": "./plc/transfer/import.clprj", "size": 4096}

这里的 name 应原样使用 PLC 准备响应中的 remote_path；通用请求分别通过 0x1075、0x1073 响应，后续数据帧和完成确认沿用通用文件协议。上传路径不匹配或尚未准备时，0x1073 返回 answer="no", cause="invalid_project_transfer_path"；通道忙时返回 answer="busy"。

导入使用控制器级单个待导入路径，没有会话 ID 或并行任务队列。客户端应串行执行，避免多个客户端同时准备或覆盖暂存文件。工程文件不携带开机自启设置，成功导入后需启动时另发 0x7400。

0x743D PLC 开机自启查询请求

功能： 查询持久化的开机自启配置，用 0x743F 响应。该配置与当前 PLC 运行状态分别查询。

{"robot": 1}

字段	类型	必填	含义
robot	int	否	兼容字段，控制器忽略。

./plc/runtime.json 不存在或配置对象未包含 auto_start 时，正常返回关闭。文件损坏、内容无效或读取失败时返回 ok=0。

0x743E PLC 开机自启设置请求

功能： 持久化开机自启配置，用 0x743F 响应。只修改下次控制器启动时的行为，不立即启停 PLC，也不要求当前 PLC 停止。

{"robot": 1, "auto_start": true}

字段	类型	必填	含义
robot	int	否	兼容字段，控制器忽略。
auto_start	bool / int	是	true/false，兼容整数 1/0；其他值及缺失字段均无效。

控制器下次启动时，只有 SoftPLC 初始化和默认工程准备成功，且配置读取成功、auto_start=true，才调用启动。读取配置失败时按关闭处理。

0x743F PLC 开机自启响应

查询成功：

{"action": "query", "ok": 1, "auto_start": false}

设置成功：

{"action": "set", "ok": 1, "auto_start": true}

字段	类型	含义
action	string	查询为 query，设置为 set。
ok	int	1 成功，0 失败。
auto_start	bool	查询返回配置值，读取失败时为 false；设置请求合法时返回请求值，只有 ok=1 才表示持久化成功。非法设置请求不返回本字段。
error	string	仅失败时存在，取值见下表。

error	含义
Failed to read SoftPLC auto-start configuration	配置读取失败。
Invalid SoftPLC auto-start value	设置请求缺少字段或值不合法。
Failed to persist SoftPLC auto-start configuration	配置持久化失败。

该响应不含 state 或 code；当前运行状态仍用 0x7402/0x7403 查询。

核对依据

• 控制器命令字定义与命令分发。
• SoftPLC JSON 处理、模型序列化、工程传输及自启配置。
• 梯形图编辑约束、运行态数值和 reset与行列容量定义。
• 控制器启动流程。
• 示教器 SoftPLC 请求与响应处理。