跳到主要内容

过程数据

读 I，写 Q。对齐 SDK IoStatus 的质量字节也在同一份快照里。

区字段方向可写
IinputHex控制器 → 本设备否
QoutputHex本设备 → 控制器是

GET /api/io​

GET /api/io HTTP/1.1
Host: 127.0.0.1:18840
{
  "inputHex": "0000",
  "outputHex": "0100",
  "inputLength": 32,
  "outputLength": 20,
  "inputIopsHex": "80",
  "outputIopsHex": "80",
  "inputValid": true,
  "outputValid": true,
  "outputSyncedToDriver": true,
  "formatVersion": 2,
  "timestamp": "2026-09-16T10:24:31.4829173+08:00"
}
字段说明
inputValid本世代收到过控制器发来的 I 区数据
outputValidQ 区写过 且 已送到控制器可取的位置。只写过但还没送出 = false
outputSyncedToDriverQ 区当前内容是否已送出。false = 写入还停在服务侧、控制器拿不到
formatVersion契约版本，当前 2。多出来的字段跳过就行

outputHex 在掉线窗口内也会跟着写（写入被暂存），所以别只看字节：这份快照有没有用，由 outputValid / outputSyncedToDriver 说了算。

IOPS 0x80 = GOOD，0x00 = BAD。掉线如实全 BAD。

POST /api/io​

写 Q。data 是十六进制，从 offset 起覆盖。没覆盖的字节不动。没连上也能写，连上后自动发出去。

POST /api/io HTTP/1.1
Host: 127.0.0.1:18840
Content-Type: application/json

{"offset": 0, "data": "0100"}

响应如实区分「已送出」与「只是排上了」：

字段说明
ok写入是否已送到控制器可取的位置（与 delivered 同值）
delivered同上，直读用，不必理解 ok 的组合语义
queued写入已留在服务侧，链路恢复后随周期帧自动下发，不需要重发。恒 true
connected / state这次写入时刻的链路与运行态
reasonCode没送出的原因码（稳定字符串，送出时为空）
waitReason / message没送出的人读说明（送出时为空）
errorCode服务当前错误码，0 = 无。掉线本身不是错误码，判失败看 reasonCode
offset / length实际写入的起始偏移与字节数

送出（HTTP 200）：

{
  "ok": true,
  "delivered": true,
  "queued": true,
  "connected": true,
  "state": "DataExchange",
  "reasonCode": "",
  "waitReason": "",
  "message": "",
  "errorCode": 0,
  "offset": 0,
  "length": 2,
  "timestamp": "2026-09-16T10:24:31.4829173+08:00"
}

掉线窗口（HTTP 仍 200，只有 ok 如实为 false）：

{
  "ok": false,
  "delivered": false,
  "queued": true,
  "connected": false,
  "state": "Initialized",
  "reasonCode": "PnS.Io.NotDelivered.LinkDown",
  "waitReason": "尝试连接",
  "message": "输出区写入未到达过程映像: 尝试连接。已暂存服务过程映像 (offset 0, 2 字节), 控制器链路恢复后随周期帧下发",
  "errorCode": 0,
  "offset": 0,
  "length": 2,
  "timestamp": "2026-09-16T10:24:31.4829173+08:00"
}
reasonCode含义
PnS.Io.NotDelivered.LinkDown掉线 / 链路未建立，数据不往控制器走
PnS.Io.NotDelivered.DataPlaneStopped数据面未运行（未启动 / 已停）
PnS.Io.NotDelivered.NotFlushed数据面在跑，只是这次写入还没等到送出回执

非 200 只有两种：请求不合法 = 400，服务内部异常 = 500。

情况HTTP
offset 缺失 / 负数，data 非十六进制或奇数长度，非法 JSON400
offset + 写入长度超出输出区400
服务内部错误（响应带 errorCode）500