诊断

西门子工程师在 TIA 里先看设备诊断缓冲、模块诊断和通道状态。本接口同一套用法：

GET /api/status 看是否在交换、有没有致命报警。
GET /api/diag 看链路、周期、应用关系、事件簿。
GET /api/alarms 看本机汇聚报警。
需要上控制器时走 POST /api/diag（标准通道诊断）或 POST /api/alarm（过程报警）。

不要先去对过程数据字节。诊断不可用时如实 ok=false，不虚构计数器。

`GET /api/diag`

从站未启动或数据面未就绪时：

{
  "ok": false,
  "sharedMemoryMapped": false,
  "message": "驱动诊断不可用: 共享内存未映射 (从站未启动或驱动未就绪), 请检查服务日志获取详情",
  "errorCode": 0,
  "degraded": true,
  "degradedReason": "…",
  "driverServiceStatus": "…",
  "log": [],
  "timestamp": "…"
}

degraded=true 表示数据面未启动，服务仍在运行并后台退避重试。正常态 degraded=false。

可用时 ok=true，主要字段如下。

连接与周期

字段	说明
`ok`	诊断是否可用
`sharedMemoryMapped`	从站已启动且数据面就绪
`state`	`Stopped` / `Bound` / `Configured` / `Running` / `Safe` / `Faulted`
`linkUp`	网卡链路是否 Up
`connected`	周期数据是否正常（看门狗未超时）
`activeIocrCount`	已激活 IOCR 数
`iocrActive`	IOCR 激活位图（bit N = IOCR[N] 已激活）
`iocrHealthy`	IOCR 健康位图（bit N = IOCR[N] 周期健康）
`heartbeat`	心跳计数
`cycleCounter`	周期循环计数
`lastError`	最近错误码（0 = 无）
`inputAreaLength` / `outputAreaLength`	过程映像区长度（字节）

帧计数

字段	说明
`rxFrames` / `txFrames`	收 / 发总帧数
`rxRtFrames` / `txRtFrames`	收 / 发周期帧数
`droppedFrames`	被丢弃的帧数（缓冲满 / 非本设备）
`invalidFrames`	非法帧数（长度 / 校验 / FrameId）
`watchdogTrips`	看门狗超时次数
`lastRxTsc` / `lastTxTsc`	最近收 / 发帧时间戳
`loopbackFrames`	本机回环帧（已丢弃，不进状态机）

协议栈周期

字段	说明
`stackCycles`	周期计数（未启动为 0）
`stackFramesRx` / `stackFramesTx`	控制器→设备 / 设备→控制器帧计数
`stackMissedTicks`	错过节拍数（不追赶）
`stackMaxJitterUs`	最大抖动（µs）

stackMissedTicks / stackMaxJitterUs 是「周期循环是否跟上节拍」的第一指标。

应用关系

字段	说明
`arEpoch`	协商值代次。每次建立 / 中止递增；`0` = 从未建立
`arFrameIdCpm`	协商 CPM FrameId（控制器→设备）；`0` = 未协商
`arFrameIdPpm`	协商 PPM FrameId（设备→控制器）；`0` = 未协商
`arControllerMac`	控制器 MAC（`XX:XX:XX:XX:XX:XX`）；空 = 未协商
`arDataHoldFactor`	协商 data_hold_factor；`0` = 未协商 / 已清零
`arDataReady`	`1` = 已 application_ready 或收到数据；中止清 `0`

控制器报警摘要

负载本体不缓存，只保留最近一次定位信息。

字段	说明
`stackAlarmRxCount`	收到控制器报警总数
`stackAlarmTxAckOk`	本设备过程报警被控制器确认数
`stackAlarmTxAckFail`	过程报警确认失败数
`stackAlarmAckPending`	当前在途过程报警（0 / 1）
`stackAlarmMaintState`	当前维护请求状态
`stackAlarmLastArep`	最近控制器报警 AREP
`stackAlarmLastSlot` / `stackAlarmLastSubslot`	槽 / 子槽
`stackAlarmLastType` / `stackAlarmLastSeq`	类型 / 序列号
`stackAlarmLastUsi` / `stackAlarmLastLen`	负载 USI / 长度

事件簿 `logbook`

AR 事件环形，最多 20 条，新到旧。从未建立 AR → 空数组。

字段	说明
`event`	`1` 连接 / `2` 释放 / `3` 中止 / `4` 控制命令
`arep`	AR 序号
`arUuidHi` / `arUuidLo`	AR UUID 前 8 字节
`qpcUs`	时间戳（微秒）

驱动事件环 `log`

最多 32 条非零槽。读失败 → 空数组，不崩端点。

字段	说明
`eventCode`	事件码（十六进制文本，如 `"0x0006"`）
`arg0` / `arg1`	参数（十六进制文本）
`tsc`	时间戳

降级观测

字段	说明
`degraded`	是否降级
`degradedReason`	原因（非降级为空）
`driverServiceStatus`	最近观测到的驱动服务状态文本
`degradedSinceUtc` / `lastAttemptUtc`	进入降级 / 最近重试（UTC）
`nextRetrySeconds`	距下次重试秒数（非降级 = 0）

GET /api/diag HTTP/1.1
Host: 127.0.0.1

`POST /api/diag`

向控制器上送 / 更新 / 清除标准通道诊断（模块诊断）。插拔类诊断由栈在模块插拔时自动发，不要用本端点替代。过程报警走 POST /api/alarm。

{
  "action": "add",
  "slot": 1,
  "subslot": 1,
  "ch": 32768,
  "chBits": 0,
  "severity": 0,
  "chErrorType": 2832,
  "extChErrorType": 0,
  "extChAddValue": 0
}

字段	必填	说明
`action`	是	`add` / `update` / `remove`
`slot` / `subslot`	是	`0`–`65534`（`65535` 规范保留）
`ch`	是	`0`–`0x8000`。`0x8000`（32768）= 整子模块
`chErrorType`	是	通道错误类型（例 `0x0B10` = 2832）
`chBits`	仅 add	`0` / `1` / `2` / `4` / `8` / `16` / `32` / `64`。`0` = 未指定
`severity`	仅 add	`0` 故障 / `1` 需要维护 / `2` 要求维护 / `3` 合格化
`extChErrorType` / `extChAddValue`	否	扩展通道错误；缺省 `0`

成功：

{ "ok": true, "action": "add", "slot": 1, "subslot": 1, "timestamp": "…" }

失败（HTTP 400，errorCode = 栈返回码）：

`errorCode`	含义
空指针类	从站未启动
诊断拒绝类	目标项不存在（remove / update 未 add 过）或参数非法

越界 / 非法枚举在到达栈之前以 HTTP 400 拒绝。

GET /api/diag​

连接与周期​

帧计数​

协议栈周期​

应用关系​

控制器报警摘要​

事件簿 logbook​

驱动事件环 log​

降级观测​

POST /api/diag​