|
|
@@ -0,0 +1,928 @@
|
|
|
+# 故障滤波（FaultFilter）MQTT 接口协议
|
|
|
+
|
|
|
+本协议用于云端 / 上位机与故障滤波设备之间通过 MQTT 进行的数据采集、记录导出与参数读写交互。本文档面向对接方开发者，仅描述通信主题、消息流程与字段定义。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 1. 通信主题（Topic）
|
|
|
+
|
|
|
+| 主题 | 方向 | QoS | 说明 |
|
|
|
+| --------------------------- | ------------------------ | --- | -------------------------- |
|
|
|
+| `aws/faultrecord` | 对端 → 设备（下行命令） | 2 | 下发采集 / 记录 / 参数命令 |
|
|
|
+| `faultfilter/faultrecord` | 设备 → 对端（上行回复） | 2 | 对下行命令的处理结果回复 |
|
|
|
+
|
|
|
+交互模型为「请求 / 应答」：对端在 `aws/faultrecord` 发布一条命令，设备处理后在 `faultfilter/faultrecord` 发布一条对应的回复。请求与回复通过 `cmd` 字段关联，回复的 `cmd` 与请求保持一致。
|
|
|
+
|
|
|
+> 消息体均为 UTF-8 编码的 JSON 字符串。字段顺序不固定，接收方应按字段名解析。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 2. 消息总体结构
|
|
|
+
|
|
|
+所有下行命令与上行回复的顶层结构一致：
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "cmd": <命令码>,
|
|
|
+ "data": { ... }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+| 字段 | 类型 | 必填 | 说明 |
|
|
|
+| -------- | ---- | ---- | ----------------------------------------- |
|
|
|
+| `cmd` | 整数 | 是 | 命令码，标识本次交互的业务类型，见第 3 节 |
|
|
|
+| `data` | 对象 | 是 | 命令数据体，内容随 `cmd` 不同而不同 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 3. 命令码（cmd）
|
|
|
+
|
|
|
+| 命令码 | 名称 | 方向 | 说明 |
|
|
|
+| ------ | ------------ | ----------- | ---------------------------------- |
|
|
|
+| 0 | 获取实时数据 | 请求 / 回复 | 读取设备实时数据 |
|
|
|
+| 1 | 设置参数 | 请求 / 回复 | 写入设备参数 |
|
|
|
+| 2 | 获取记录数据 | 请求 / 回复 | 导出故障录波 / 波形记录 |
|
|
|
+| 3 | 查询参数 | 请求 / 回复 | 读取设备参数 |
|
|
|
+| 4 | 退出 | 请求 | 通知设备结束当前处理 |
|
|
|
+| 90 | 测试成功 | 请求 | 连通性测试，设备回复 `ok` |
|
|
|
+| 99 | 测试失败 | 请求 | 连通性测试，设备回复 `test fail` |
|
|
|
+
|
|
|
+> 处理约束：
|
|
|
+>
|
|
|
+> - 命令码按 8 位无符号整数处理，有效范围 0–255。
|
|
|
+> - 设备同一时刻只处理一条业务命令。收到命令后的判定顺序为：先校验 `cmd` 字段 → 再判忙碌 → 再校验 `data` 字段。
|
|
|
+> - 当设备处于忙碌状态时收到非「退出(4)」命令，直接返回错误 `busy`（此时不中断正在进行的处理）；其余在校验阶段失败的命令，回复错误后会结束当前处理流程。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 4. 设备分组与寻址
|
|
|
+
|
|
|
+命令数据体中的设备通过「类型 + 序列号」寻址，统一组织为 `list → info` 两级结构。
|
|
|
+
|
|
|
+### 4.1 设备类型（type）
|
|
|
+
|
|
|
+| type | 含义 | 寻址方式 |
|
|
|
+| --------- | --------------- | ------------------------------------ |
|
|
|
+| `pe` | PE 功率单元 | 通过 `sn` 序列号定位（最多 15 台） |
|
|
|
+| `aGate` | 网关 / 从控单元 | 系统内唯一，固定寻址 |
|
|
|
+
|
|
|
+### 4.2 分组结构
|
|
|
+
|
|
|
+```json
|
|
|
+"data": {
|
|
|
+ "list": [
|
|
|
+ {
|
|
|
+ "type": "pe",
|
|
|
+ "info": [
|
|
|
+ { "sn": "<设备序列号>", ... }
|
|
|
+ ]
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "type": "aGate",
|
|
|
+ "info": [
|
|
|
+ { "sn": "<设备序列号>", ... }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+| 字段 | 类型 | 层级 | 说明 |
|
|
|
+| --------------- | ------ | ---- | --------------------------------------------------- |
|
|
|
+| `list` | 数组 | data | 设备分组列表，按 `type` 分组 |
|
|
|
+| `list[].type` | 字符串 | list | 设备类型：`pe` 或 `aGate` |
|
|
|
+| `list[].info` | 数组 | list | 该类型下的具体设备项 |
|
|
|
+| `info[].sn` | 字符串 | info | 设备序列号。`pe` 必填；`aGate` 可填但不用于寻址 |
|
|
|
+
|
|
|
+> 若 `pe` 的 `sn` 在设备侧无法匹配，整条命令返回错误 `pe sn not find`（见第 6 节）。
|
|
|
+
|
|
|
+### 4.3 回复中的整体结果（result）
|
|
|
+
|
|
|
+每条回复的 `data.result` 表示本次命令的整体处理结果：
|
|
|
+
|
|
|
+| 取值 | 含义 |
|
|
|
+| --------- | ------------------------ |
|
|
|
+| `ok` | 全部子项处理成功 |
|
|
|
+| `error` | 存在至少一个子项处理失败 |
|
|
|
+
|
|
|
+子项级别的结果由各自的 `resultOne` 字段描述。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 5. 各命令详细定义
|
|
|
+
|
|
|
+### 5.1 获取实时数据（cmd = 0）
|
|
|
+
|
|
|
+#### 请求
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "cmd": 0,
|
|
|
+ "data": {
|
|
|
+ "list": [
|
|
|
+ {
|
|
|
+ "type": "aGate",
|
|
|
+ "info": [
|
|
|
+ {
|
|
|
+ "sn": "10060010A01X26310190",
|
|
|
+ "codeList": [3]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+> 示例取自 2026-09-29 实报：查询 aGate 的故障录波总目录。
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+| ------------------- | -------- | -------------------------------------- |
|
|
|
+| `info[].codeList` | 整数数组 | 需要读取的数据项命令码集合，取值见下表 |
|
|
|
+
|
|
|
+`codeList` / `code` 取值定义：
|
|
|
+
|
|
|
+| code | 含义 |
|
|
|
+| ---- | ------------------------ |
|
|
|
+| 1 | 故障总体信息 |
|
|
|
+| 2 | 设备故障录波功能基本信息 |
|
|
|
+| 3 | 故障录波总目录 |
|
|
|
+
|
|
|
+> 数组中的多个 `code` 由设备按子设备串行逐个读取（每个 `code` 对应一次独立的子设备读取事务），全部完成后在回复的 `hexList` 中汇总返回。
|
|
|
+> 说明：`hexData` 回传的是子设备原始字节的十六进制字符串，各 code 的字节结构见 5.1.1。
|
|
|
+>
|
|
|
+> **cmd=0 不能用于查询 code=4（单一故障信息）和 code=5（单一故障波形数据）。** 这两类数据属于某条具体记录，须通过获取记录数据（cmd=2，见 5.2）按记录序号导出：先用 cmd=0 + code=3 查询总目录，再以目录项的位置索引作为 cmd=2 的 `index`。
|
|
|
+
|
|
|
+#### 5.1.1 各 code 返回数据（hexData）的字节格式
|
|
|
+
|
|
|
+`hexData` 回传的是子设备返回的原始字节的十六进制字符串。`code=1/2/3` 的字节结构如下（多字节字段按紧凑排列、无填充），已由子设备方资料确认。
|
|
|
+
|
|
|
+**时间字段结构（固定 7 字节）**：
|
|
|
+
|
|
|
+| 字节 | 字段 | 类型 | 说明 |
|
|
|
+| ---- | ---- | -------------------------- | -------------------------------- |
|
|
|
+| 1~2 | year | Uint16（大端，高字节在前） | 年，如 `07 E6` = 0x07E6 = 2022 |
|
|
|
+| 3 | mon | Uint8 | 月 |
|
|
|
+| 4 | day | Uint8 | 日 |
|
|
|
+| 5 | hour | Uint8 | 时 |
|
|
|
+| 6 | min | Uint8 | 分 |
|
|
|
+| 7 | sec | Uint8 | 秒 |
|
|
|
+
|
|
|
+> 示例：`07 E6 01 01 01 01 01` 表示 2022-01-01 1:1:1。
|
|
|
+
|
|
|
+**code=1 故障总体信息**：
|
|
|
+
|
|
|
+| 顺序 | 字段 | 字节数 | 含义 |
|
|
|
+| ---- | ---------------------- | ------ | --------------------------------------- |
|
|
|
+| 1 | 最大可存储故障记录总数 | 1 | — |
|
|
|
+| 2 | 当前故障记录总数 | 1 | — |
|
|
|
+| 3 | 最早故障发生时间 | 7 | 时间字段结构见本节上方 |
|
|
|
+| 4 | 最新故障发生时间 | 7 | 时间字段结构见本节上方 |
|
|
|
+| 5 | 快照通道总数 | 1 | 记为 a |
|
|
|
+| 6 | 已使用快照通道个数 | 1 | — |
|
|
|
+| 7 | 各快照通道含义 | 2 × a | 每通道 2 字节含义编号（见第 10 节 F14） |
|
|
|
+| 8 | 采样通道总数 | 1 | 记为 b |
|
|
|
+| 9 | 已使用采样通道个数 | 1 | — |
|
|
|
+| 10 | 各采样通道含义 | 2 × b | 每通道 2 字节含义编号（见第 10 节 F14） |
|
|
|
+| 11 | 最大可配快照通道总数 | 1 | 记为 c |
|
|
|
+| 12 | 已配置可配快照通道个数 | 1 | — |
|
|
|
+| 13 | 各可配快照通道 | 6 × c | 每项 = 类型(2B) + 地址(4B) |
|
|
|
+| 14 | 最大可配采样通道总数 | 1 | 记为 d |
|
|
|
+| 15 | 已配置可配采样通道个数 | 1 | — |
|
|
|
+| 16 | 各可配采样通道 | 6 × d | 每项 = 类型(2B) + 地址(4B) |
|
|
|
+
|
|
|
+> 关于 code=1 中的编号含义：
|
|
|
+>
|
|
|
+> - 「各快照通道含义」/「各采样通道含义」中每个 2 字节值为通道含义参数代码，用于标识该通道对应的物理量（故障字 / 控制字 / 状态量，如温度、SOC、母线电流等），具体编号与物理量的对应关系由产品的参数代码表定义（见第 10 节 F14）。
|
|
|
+> - 「各可配快照通道」/「各可配采样通道」中每项的类型(2B) 与 地址(4B) 用于标识可配通道所记录的变量，取值含义同属产品定义（见第 10 节 F14）。
|
|
|
+>
|
|
|
+> 与 code=4 的关系（可相互参考）：code=1 从「快照通道」起的后半部分，与 code=4（见 5.2.2）的通道部分结构基本一致，均按「快照通道组 → 采样通道组 → 可配快照通道组 → 可配采样通道组」组织，每组均为「总数 + 已用/已配数 + 逐通道数据」。两者的通道含义编号（F14）与可配通道类型/地址共用同一套定义。**唯一区别**：code=1 的快照通道逐项**只有含义(2B)**；code=4 的快照通道逐项是**含义(2B) + 数值(2B)**（code=4 需记录故障发生时刻的瞬时值，code=1 仅描述通道配置）。
|
|
|
+
|
|
|
+**code=2 设备故障录波功能基本信息**（固定 16 字节）：
|
|
|
+
|
|
|
+| 偏移 | 字段 | 字节数 | 含义 |
|
|
|
+| ---- | ---------------------- | ------ | ---- |
|
|
|
+| 0 | CAN 通讯协议版本号 | 1 | — |
|
|
|
+| 1 | 故障数据存储格式版本号 | 1 | — |
|
|
|
+| 2 | 参数列表版本号 | 4 | — |
|
|
|
+| 6 | 最大支持采样频率 | 2 | — |
|
|
|
+| 8 | 采样频率 | 2 | — |
|
|
|
+| 10 | 采样点总数 | 2 | — |
|
|
|
+| 12 | 故障前采样点个数 | 2 | — |
|
|
|
+| 14 | 故障后采样点个数 | 2 | — |
|
|
|
+
|
|
|
+**code=3 故障录波总目录**：
|
|
|
+
|
|
|
+| 顺序 | 字段 | 字节数 | 含义 |
|
|
|
+| ---- | -------------------- | ------- | ---------------------- |
|
|
|
+| 1 | 总目录中故障记录条数 | 1 | 记为 N |
|
|
|
+| 2 | 记录项列表 | N × 14 | N 条记录，每条结构见下 |
|
|
|
+
|
|
|
+单条记录（固定 **14 字节**）：
|
|
|
+
|
|
|
+| 顺序 | 字段 | 字节数 | 含义 |
|
|
|
+| ---- | -------------- | ------ | -------------------------------- |
|
|
|
+| 1 | 位置索引 | 1 | — |
|
|
|
+| 2 | 故障发生时间 | 7 | 时间字段结构见本节上方，年份大端 |
|
|
|
+| 3 | 参数列表版本号 | 4 | — |
|
|
|
+| 4 | 事件触发源 | 2 | 代码表见第 10 节 F15 |
|
|
|
+
|
|
|
+> 单条长度 = 1 + 7 + 4 + 2 = **14 字节**（时间按 7 字节）。
|
|
|
+
|
|
|
+**code=4 单一故障信息 / code=5 单一故障波形数据**：
|
|
|
+不能通过 cmd=0 查询，由 cmd=2 按记录导出并保存为文件。文件内容的字节结构见 5.2.2（`failuredata`，code=4）与 5.2.3（`waveformdata`，code=5），解析导出文件时使用。
|
|
|
+
|
|
|
+#### 回复
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "cmd": 0,
|
|
|
+ "data": {
|
|
|
+ "result": "ok",
|
|
|
+ "list": [
|
|
|
+ {
|
|
|
+ "type": "aGate",
|
|
|
+ "info": [
|
|
|
+ {
|
|
|
+ "sn": "10060010A01X26310190",
|
|
|
+ "hexList": [
|
|
|
+ {
|
|
|
+ "code": 3,
|
|
|
+ "hexData": "<故障录波总目录原始数据>",
|
|
|
+ "resultOne": "ok"
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+> 示例取自 2026-09-29 实报（对上述请求的回复）。该次 `hexData` 原文未存档，此处以占位符表示，结构见 5.1.1 code=3。2026-10-14 实报的 `hexData` 原文见 `CloudLog_2026-10-14_104644.csv`，已按 5.1.1 验证。
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+| ----------------------- | ------ | ------------------------------------------ |
|
|
|
+| `info[].hexList` | 数组 | 本设备各数据项的读取结果 |
|
|
|
+| `hexList[].code` | 整数 | 数据项命令码，对应请求 `codeList` 中的值 |
|
|
|
+| `hexList[].hexData` | 字符串 | 读取到的原始数据，十六进制字符串形式 |
|
|
|
+| `hexList[].resultOne` | 字符串 | 该数据项的处理结果 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 5.2 获取记录数据（cmd = 2）
|
|
|
+
|
|
|
+用于导出故障录波 / 波形记录文件。
|
|
|
+
|
|
|
+#### 请求
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "cmd": 2,
|
|
|
+ "data": {
|
|
|
+ "list": [
|
|
|
+ {
|
|
|
+ "type": "aGate",
|
|
|
+ "info": [
|
|
|
+ {
|
|
|
+ "sn": "10060010A01X26310190",
|
|
|
+ "index": [9]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+> 示例取自 2026-09-29 实报：导出目录中位置索引为 9 的记录。
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+| ---------------- | -------- | ---------------------- |
|
|
|
+| `info[].index` | 整数数组 | 需要导出的记录索引集合 |
|
|
|
+
|
|
|
+#### 回复
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "cmd": 2,
|
|
|
+ "data": {
|
|
|
+ "result": "ok",
|
|
|
+ "list": [
|
|
|
+ {
|
|
|
+ "type": "aGate",
|
|
|
+ "info": [
|
|
|
+ {
|
|
|
+ "sn": "10060010A01X26310190",
|
|
|
+ "indexInfo": [
|
|
|
+ {
|
|
|
+ "index": 4,
|
|
|
+ "resultOne": "ok"
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "index": 5,
|
|
|
+ "resultOne": "ok"
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ],
|
|
|
+ "filename": "2026-09-29_14_18_29"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+> 示例取自 2026-09-29 实报（对上述请求的回复）：记录序号 9 展开为 `4`（故障数据）与 `5`（波形数据）两项。
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+| ------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
|
|
|
+| `info[].indexInfo` | 数组 | 本设备各记录项的处理结果 |
|
|
|
+| `indexInfo[].index` | 整数 | 记录数据类型码（非请求的记录序号）：`4`=故障数据，`5`=波形数据。请求的每个记录序号在回复中会展开为这两类各一项 |
|
|
|
+| `indexInfo[].resultOne` | 字符串 | 该记录项的处理结果 |
|
|
|
+| `data.filename` | 字符串 | 本次导出记录对应的时间戳目录名，格式 `YYYY-MM-DD_HH_MM_SS` |
|
|
|
+
|
|
|
+> 实现细节：
|
|
|
+>
|
|
|
+> - 对请求中的每个记录序号，设备向子设备分别请求「故障数据」和「波形数据」两类，因此回复的 `indexInfo` 中每个记录序号对应两项，`index` 字段分别为 `4`（故障数据）与 `5`（波形数据）。回复项中**不直接回传请求的记录序号数值**。
|
|
|
+
|
|
|
+#### 5.2.1 记录文件保存格式（code=4 / code=5 的落盘内容）
|
|
|
+
|
|
|
+获取记录（cmd=2）读取的是 `code=4`（单一故障信息 / 故障数据）与 `code=5`（单一故障波形数据），这两类数据设备不解析其内部结构，而是直接保存为文件。保存规则如下：
|
|
|
+
|
|
|
+**保存根目录**：`/home/root/ExportFile/faultFilterRecode/`
|
|
|
+
|
|
|
+**完整文件路径**：
|
|
|
+
|
|
|
+```
|
|
|
+/home/root/ExportFile/faultFilterRecode/<filename>/<sn>/index_<记录序号>/<类型文件名>
|
|
|
+```
|
|
|
+
|
|
|
+| 路径段 | 来源 | 说明 |
|
|
|
+| -------------------- | ----------------------------- | -------------------------------------------------------------------------- |
|
|
|
+| `<filename>` | 本次导出批次时间戳 | 与回复 `data.filename` 相同，格式 `YYYY-MM-DD_HH_MM_SS` |
|
|
|
+| `<sn>` | 设备序列号 | 该记录所属子设备的 SN |
|
|
|
+| `index_<记录序号>` | 请求 `index[]` 中的记录序号 | 记录序号在此目录名中体现（**不**在 `indexInfo[].index` 字段中） |
|
|
|
+| `<类型文件名>` | 数据类型 | `failuredata`（故障数据，code=4）或 `waveformdata`（波形数据，code=5） |
|
|
|
+
|
|
|
+示例：按上述实报（记录序号 9，SN `10060010A01X26310190`，批次时间 `2026-09-29_14_18_29`），按本节规则应生成两个文件（路径为按规则推导，未在设备上核对）：
|
|
|
+
|
|
|
+```
|
|
|
+/home/root/ExportFile/faultFilterRecode/2026-09-29_14_18_29/10060010A01X26310190/index_9/failuredata
|
|
|
+/home/root/ExportFile/faultFilterRecode/2026-09-29_14_18_29/10060010A01X26310190/index_9/waveformdata
|
|
|
+```
|
|
|
+
|
|
|
+**文件内容**：子设备返回的原始字节，经「每字节转 2 位大写十六进制字符」转换后的 **ASCII 文本字符串**（例如字节 `0x0A 0x1B` 存为文本 `0A1B`）。文件以覆盖方式写入。
|
|
|
+
|
|
|
+> 补充说明：
|
|
|
+>
|
|
|
+> - 文件为纯十六进制文本，不含文件头。
|
|
|
+> - 每次获取记录（cmd=2）开始前，设备会先清空保存根目录下的**全部**历史记录文件，再保存本次结果。
|
|
|
+> - 仅当该记录项处理成功时才落盘；失败项不生成文件，仅在 `indexInfo` 中以 `resultOne` 反映错误。
|
|
|
+
|
|
|
+#### 5.2.2 `failuredata` 文件内容格式（code=4 单一故障信息）
|
|
|
+
|
|
|
+文件内为十六进制文本，还原成字节后按下表顺序解析（紧凑排列，多字节字段除另有说明外按示例中的大端顺序）。
|
|
|
+
|
|
|
+| 字节数 | 字段 | 数据类型 | 备注 |
|
|
|
+| ------ | ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
|
+| 2 | 单一故障信息数据长度 | Uint16 | 后续数据的长度 |
|
|
|
+| 16 | 故障录波功能基本信息 | — | 结构同 code=2「基本信息」，共 16 字节（见 5.1.1） |
|
|
|
+| 1 | 位置索引号 | Uint8 | 从 1 开始，最大不超过「最大可存储故障记录总数」 |
|
|
|
+| 7 | 故障发生时间 | Uint8[7] | 例：`07 E6 01 01 01 01 01` 表示 2022-01-01 1:1:1 |
|
|
|
+| 2 | 事件触发源 | Uint16 | 采用事件触发源代码表示，触发源在应用层配置 |
|
|
|
+| 64 | 故障发生时 DCDC 软件版本号 | char[64] | aGate 中表示从 DSP 软件版本号。例：`PE_DCDC:V10R03B32D00` 或 `EMS_SL:V10R03B32D00` |
|
|
|
+| 64 | 故障发生时 INV 软件版本号 | char[64] | aGate 中留空。例：`PE_INV:V10R03B32D07` |
|
|
|
+| 64 | 故障发生时 FPGA 软件版本号 | char[64] | aGate 中留空。例：`PE_FPGA:V255R03B32D00` |
|
|
|
+| 1 | 快照通道总数 | Uint8 | 设计最大 32 通道；无论是否使用都上传该参数及后续快照参数 |
|
|
|
+| 1 | 已使用的快照通道个数 | Uint8 | ≤ 快照通道总数 |
|
|
|
+| 2 | 第 1 个快照通道含义 | Uint16 | 通道含义参数代码，标识该通道对应的物理量（故障字 / 控制字 / 状态量，如温度、SOC 等）；「采样通道」与「快照通道」共用同一套参数代码（见第 10 节 F14） |
|
|
|
+| 2 | 第 1 个快照通道数值 | Uint16 | 取参数代码对应变量的数值，如母线电流 |
|
|
|
+| … | …（第 2 … n 个快照通道的含义 + 数值，各 2+2 字节） | Uint16 | n = 快照通道总数；每通道按「含义(2B) + 数值(2B)」重复 |
|
|
|
+| 2 | 第 n 个快照通道含义 | Uint16 | 同上 |
|
|
|
+| 2 | 第 n 个快照通道数值 | Uint16 | 同上 |
|
|
|
+| 1 | 采样通道总数 | Uint8 | — |
|
|
|
+| 1 | 已使用的采样通道个数 | Uint8 | ≤ 采样通道总数 |
|
|
|
+| 2 | 第 1 个采样通道含义 | Uint16 | 含义同快照通道含义 |
|
|
|
+| … | …（第 2 … m 个采样通道含义，各 2 字节） | Uint16 | m = 采样通道总数；每通道仅「含义(2B)」 |
|
|
|
+| 2 | 第 m 个采样通道含义 | Uint16 | 同上 |
|
|
|
+| 1 | 最大可配快照通道总数 | Uint8 | — |
|
|
|
+| 1 | 已配置的可配快照通道个数 | Uint8 | ≤ 最大可配快照通道总数 |
|
|
|
+| 2 | 第 1 个可配快照通道所记录变量的类型 | Uint16 | 采用约定类型代码（同 5.4.1 的 id=6 功能）；「可配采样通道」与「可配快照通道」共用同一套类型代码：`0h`=Empty；`1h`=Uint16；`2h`=int16；`3h`=float32；`4h`=Uint32_HWord；`5h`=Uint32_LWord；`6h`=Uint32；其他=无效 |
|
|
|
+| 4 | 当前第 1 个可配采样通道所记录变量的地址 | Uint32 | 与程序版本相关。例：`00 31 11 94` 表示地址 0x311194 |
|
|
|
+| … | …（第 2 … x 个：类型(2B) + 地址(4B)） | — | x = 最大可配快照通道总数；每项按「类型(2B) + 地址(4B)」重复 |
|
|
|
+| 2 | 第 x 个可配快照通道所记录变量的类型 | Uint16 | 同上 |
|
|
|
+| 4 | 当前第 x 个可配采样通道所记录变量的地址 | Uint32 | 同上 |
|
|
|
+| 1 | 最大可配采样通道总数 | Uint8 | — |
|
|
|
+| 1 | 已配置的可配采样通道个数 | Uint8 | ≤ 最大可配采样通道总数 |
|
|
|
+| 2 | 第 1 个可配采样通道所记录变量的类型 | Uint16 | 类型代码同可配快照通道 |
|
|
|
+| 4 | 当前第 1 个可配采样通道所记录变量的地址 | Uint32 | 与程序版本相关，同可配快照通道 |
|
|
|
+| … | …（第 2 … y 个：类型(2B) + 地址(4B)） | — | y = 最大可配采样通道总数；每项按「类型(2B) + 地址(4B)」重复 |
|
|
|
+| 2 | 第 y 个可配采样通道所记录变量的类型 | Uint16 | 同上 |
|
|
|
+| 4 | 当前第 y 个可配采样通道所记录变量的地址 | Uint32 | 同上 |
|
|
|
+
|
|
|
+> 注：上表「16 字节 故障录波功能基本信息」与 code=2 的基本信息结构一致（见 5.1.1，共 16 字节），两处相符。
|
|
|
+> 通道含义参数代码（快照 / 采样通道含义编号）的取值定义见第 10 节 F14；事件触发源代码表见 10.4（第 10 节 F15）。
|
|
|
+>
|
|
|
+> 与 code=1 的关系（可相互参考）：本表从「快照通道总数」起的后半部分，与 code=1（见 5.1.1）的通道部分结构基本一致（快照 / 采样 / 可配快照 / 可配采样四组，每组「总数 + 已用/已配数 + 逐通道数据」），通道「含义」编号（F14）与可配通道 type/addr 共用同一套定义。**唯一区别**：此处 code=4 的快照通道逐项为**含义(2B) + 数值(2B)**（含故障时刻瞬时值），而 code=1 的快照通道逐项**只有含义(2B)**。
|
|
|
+
|
|
|
+#### 5.2.3 `waveformdata` 文件内容格式（code=5 单一故障波形数据）
|
|
|
+
|
|
|
+文件内为十六进制文本，还原成字节后为连续的 Uint16 采样点序列。排列方式为**按采样点外层、波形通道内层**：先排所有波形在第 1 个采样点的值，再排所有波形在第 2 个采样点的值，依此类推。
|
|
|
+
|
|
|
+| 字节数 | 字段 | 数据类型 | 备注 |
|
|
|
+| ------ | ------------------------------------- | -------- | ------------------------ |
|
|
|
+| 2 | 第 1 个波形 第 1 个点的数值 | Uint16 | — |
|
|
|
+| 2 | 第 2 个波形 第 1 个点的数值 | Uint16 | — |
|
|
|
+| … | …（第 1 个采样点，第 1 … n 个波形） | Uint16 | n = 波形通道数 |
|
|
|
+| 2 | 第 n 个波形 第 1 个点的数值 | Uint16 | — |
|
|
|
+| 2 | 第 1 个波形 第 2 个点的数值 | Uint16 | 第 2 个采样点开始 |
|
|
|
+| … | …（第 2 个采样点，第 1 … n 个波形） | Uint16 | — |
|
|
|
+| 2 | 第 n 个波形 第 2 个点的数值 | Uint16 | — |
|
|
|
+| … | …（依次到第 m 个采样点） | Uint16 | m = 每个波形的采样点总数 |
|
|
|
+| 2 | 第 n 个波形 第 m 个点的数值 | Uint16 | 最后一个点 |
|
|
|
+
|
|
|
+> 说明：
|
|
|
+>
|
|
|
+> - 存储顺序为「采样点优先」：第 k 个采样点处所有 n 个波形的值连续排列，再进入第 k+1 个采样点。
|
|
|
+> - 波形通道数 n、采样点总数 m 等由 code=1 / code=2 中的通道配置与采样点参数决定（如 code=2 的「采样点总数 / 故障前采样点 / 故障后采样点」）。
|
|
|
+> - 每个波形各采样点代表哪个物理量，对应 code=4 中的「采样通道含义」编号。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 5.3 查询参数（cmd = 3）
|
|
|
+
|
|
|
+> 与 cmd=1 相同，`id` 是**命令控制符（功能码）**（定义见 5.4.1）。查询时只提供功能码、不带输入参数；返回的 `idData` 为该功能码对应的当前配置 / 状态，其数据结构可参照 5.4.1 中该功能码的参数结构。
|
|
|
+
|
|
|
+#### 请求
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "cmd": 3,
|
|
|
+ "data": {
|
|
|
+ "list": [
|
|
|
+ {
|
|
|
+ "type": "pe",
|
|
|
+ "info": [
|
|
|
+ {
|
|
|
+ "sn": "10050015A00X25070634",
|
|
|
+ "idList": [5]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+> 暂无 cmd=3 实报，本例为按协议构造的示意：查询 PE 当前采样频率。
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+| ----------------- | -------- | ------------------------------------------------ |
|
|
|
+| `info[].idList` | 整数数组 | 需要查询的命令控制符（功能码）集合，取值见 5.4.1 |
|
|
|
+
|
|
|
+#### 回复
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "cmd": 3,
|
|
|
+ "data": {
|
|
|
+ "result": "ok",
|
|
|
+ "list": [
|
|
|
+ {
|
|
|
+ "type": "pe",
|
|
|
+ "info": [
|
|
|
+ {
|
|
|
+ "sn": "10050015A00X25070634",
|
|
|
+ "idInfo": [
|
|
|
+ {
|
|
|
+ "id": 5,
|
|
|
+ "idData": "1194",
|
|
|
+ "resultOne": "ok"
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+> 构造示意：`idData = "1194"` 表示 4500 Hz，数值为假设值，非实测。
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+| ---------------------- | ------ | --------------------------------------------------------------------- |
|
|
|
+| `info[].idInfo` | 数组 | 本设备各功能项的查询结果 |
|
|
|
+| `idInfo[].id` | 整数 | 命令控制符（功能码），对应请求 `idList` 中的值 |
|
|
|
+| `idInfo[].idData` | 字符串 | 读取到的该功能码对应配置 / 状态值，十六进制字符串形式；结构参照 5.4.1 |
|
|
|
+| `idInfo[].resultOne` | 字符串 | 该功能项的处理结果 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 5.4 设置参数（cmd = 1）
|
|
|
+
|
|
|
+> `id` 并非「某个数据参数的编号」，而是**命令控制符（功能码）**：每个 `id` 代表一种对子设备的操作，`setVal` 是该操作的「函数输入参数」，其内容结构随 `id` 不同而不同。功能码及其输入参数结构见 5.4.1。
|
|
|
+
|
|
|
+#### 请求
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "cmd": 1,
|
|
|
+ "data": {
|
|
|
+ "list": [
|
|
|
+ {
|
|
|
+ "type": "pe",
|
|
|
+ "info": [
|
|
|
+ {
|
|
|
+ "sn": "10050015A00X25070634",
|
|
|
+ "paraList": [
|
|
|
+ { "id": 6, "setVal": "010100015984" },
|
|
|
+ { "id": 6, "setVal": "020100015981" },
|
|
|
+ { "id": 6, "setVal": "030100015983" },
|
|
|
+ { "id": 6, "setVal": "04030003FD34" }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+> 示例取自已验证代码 `ChargeChannel`（`service/repositories/mqtt/fwh_mqtt/fwh_mqtt_fault_record.go`）：一次配置 4 个可配采样通道，同一功能码 `id=6` 重复出现，由 `setVal` 首字节的通道索引区分。按 5.4.1 解析：
|
|
|
+>
|
|
|
+> | setVal | 索引号 | 数据类型 | 数据 |
|
|
|
+> | ------------------ | ------ | ----------------- | --------------- |
|
|
|
+> | `01 01 00015984` | 1 | 默认方式，Uint16 | 地址 0x00015984 |
|
|
|
+> | `02 01 00015981` | 2 | 默认方式，Uint16 | 地址 0x00015981 |
|
|
|
+> | `03 01 00015983` | 3 | 默认方式，Uint16 | 地址 0x00015983 |
|
|
|
+> | `04 03 0003FD34` | 4 | 默认方式，float32 | 地址 0x0003FD34 |
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+| --------------------- | ------ | ------------------------------------------------------------ |
|
|
|
+| `info[].paraList` | 数组 | 需要执行的功能项列表 |
|
|
|
+| `paraList[].id` | 整数 | 命令控制符（功能码），取值见 5.4.1 |
|
|
|
+| `paraList[].setVal` | 字符串 | 该功能码的输入参数（结构见 5.4.1）；无输入参数的功能码可为空 |
|
|
|
+
|
|
|
+#### 回复
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "cmd": 1,
|
|
|
+ "data": {
|
|
|
+ "result": "ok",
|
|
|
+ "list": [
|
|
|
+ {
|
|
|
+ "type": "pe",
|
|
|
+ "info": [
|
|
|
+ {
|
|
|
+ "sn": "10050015A00X25070634",
|
|
|
+ "setResultList": [
|
|
|
+ { "id": 6, "resultOne": "ok" },
|
|
|
+ { "id": 6, "resultOne": "ok" },
|
|
|
+ { "id": 6, "resultOne": "ok" },
|
|
|
+ { "id": 6, "resultOne": "ok" }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+> 暂无 cmd=1 回复实报，本例为按协议构造的示意。重复功能码的结果是否严格按请求顺序逐项返回，待实测确认。
|
|
|
+
|
|
|
+| 字段 | 类型 | 说明 |
|
|
|
+| ----------------------------- | ------ | ------------------------------------------------ |
|
|
|
+| `info[].setResultList` | 数组 | 本设备各功能项的执行结果 |
|
|
|
+| `setResultList[].id` | 整数 | 命令控制符（功能码），对应请求 `paraList[].id` |
|
|
|
+| `setResultList[].resultOne` | 字符串 | 该功能项的执行结果 |
|
|
|
+
|
|
|
+#### 5.4.1 命令控制符（id / 功能码）定义
|
|
|
+
|
|
|
+`id` 为命令控制符（功能码），指明对设备执行的操作。设置（cmd=1）时 `setVal` 为该功能码的输入参数；查询（cmd=3）时无输入参数，查询返回的数据结构可参照对应功能码的参数结构。
|
|
|
+
|
|
|
+| id | 功能 | 设置时的输入参数（setVal）结构 |
|
|
|
+| -- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
|
+| 1 | 清除设备故障波形 | 无输入参数 |
|
|
|
+| 2 | 采样通道配置功能 | 「最大可配置的采样通道总数」(1 字节) + 「第 1 个采样通道含义」(2 字节, 大端) + … + 「第 n 个采样通道含义」(2 字节, 大端)。通道含义编号见第 10 节 F14 |
|
|
|
+| 3 | 手动触发故障录波 | 无输入参数 |
|
|
|
+| 4 | 设备对时 | 7 字节，按「年(2 字节) 月 日 时 分 秒」顺序。例：`07 E6 01 01 01 01 01` 表示 2022-01-01 1:1:1（年为大端） |
|
|
|
+| 5 | 设置故障录波采样频率 | 2 字节，单位 Hz。例：`11 94` 表示 4500 Hz（大端） |
|
|
|
+| 6 | 配置可配采样通道功能 | 「可配采样通道的索引号」(1 字节) + 「数据类型」(1 字节) + 「数据」(4 字节)，见下方说明 |
|
|
|
+| 7 | 故障波形功能状态控制 | 「控制字节」(1 字节)：`0h`=关闭故障录波；`1h`=使能故障录波；其他=无效 |
|
|
|
+
|
|
|
+**id=6「配置可配采样通道功能」的参数结构**：
|
|
|
+
|
|
|
+- 索引号（1 字节）：被配置的可配采样通道索引。
|
|
|
+- 数据类型（1 字节），拆为高半字节 ByteH 与低半字节 ByteL：
|
|
|
+ - ByteH = 设置方式：`0h`=默认方式（需携带采样通道地址类型与地址信息）；`1h`=代码方式（需携带采样通道参数代码）；其他=无效。
|
|
|
+ - ByteL = 采样通道地址类型（仅默认方式 ByteH=0h 时有效）：`0h`=Empty；`1h`=Uint16；`2h`=int16；`3h`=float32；`4h`=Uint32_HWord；`5h`=Uint32_LWord；`6h`=Uint32；其他=无效。
|
|
|
+- 数据（4 字节），按设置方式解析：
|
|
|
+ - ByteH=0h（默认方式）：4 字节表示要设置的地址。例：`00 31 11 94` 表示地址 0x311194。
|
|
|
+ - ByteH=1h（代码方式）：前 2 字节表示采样通道代码（参数代码见 F14），后 2 字节无效。例：`12 34 xx xx` 表示采样通道代码 0x1234。
|
|
|
+
|
|
|
+**`setVal` 的编码方式**：`setVal` 为**十六进制字符串**，每 2 个字符表示 1 个字节。例如 `setVal = "010100015984"` 表示字节序列 `0x01 0x01 0x00 0x01 0x59 0x84`。各功能码输入参数的字节内容按上表 / 上文结构填写后，整体以十六进制字符串形式放入 `setVal`。
|
|
|
+
|
|
|
+> 对时（id=4）示例：7 字节 `07 E6 01 01 01 01 01` → `setVal = "07E60101010101"`（14 个十六进制字符）。采样频率（id=5）设 4500Hz 示例：2 字节 `11 94` → `setVal = "1194"`。
|
|
|
+
|
|
|
+> 备注（设备端实现）：`setVal` 的十六进制字符串由设备端负责转换为字节后发往子设备。此转换属设备端实现细节，待后续联调测试确认，不影响本协议对接。
|
|
|
+
|
|
|
+> 查询（cmd=3）：请求 `idList` 中填功能码，无输入参数；返回的 `idData` 为对应功能码的当前配置 / 状态，其数据结构**参照上表中该功能码的参数结构**（例如查 id=2 返回采样通道配置、查 id=5 返回当前采样频率等）。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 5.5 退出（cmd = 4）
|
|
|
+
|
|
|
+通知设备结束当前处理流程。
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "cmd": 4,
|
|
|
+ "data": {}
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+该命令不产生业务数据回复。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+### 5.6 连通性测试（cmd = 90 / 99）
|
|
|
+
|
|
|
+用于链路连通性验证。
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "cmd": 90,
|
|
|
+ "data": {}
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+设备回复（错误回复结构，见第 6 节）：
|
|
|
+
|
|
|
+- `cmd = 90` → `data.result = "ok"`
|
|
|
+- `cmd = 99` → `data.result = "test fail"`
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 6. 错误回复
|
|
|
+
|
|
|
+当命令无法正常进入业务处理（如格式错误、字段缺失、设备忙、序列号无效等）时，设备返回简化的错误回复：
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "cmd": <命令码>,
|
|
|
+ "data": {
|
|
|
+ "result": "<错误说明>"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+| `data.result` | 触发原因 |
|
|
|
+| ------------------- | ---------------------------- |
|
|
|
+| `json unpack err` | 消息体不是合法 JSON |
|
|
|
+| `cmd unpack err` | 缺少 `cmd` 字段 |
|
|
|
+| `data unpack err` | 缺少 `data` 字段 |
|
|
|
+| `busy` | 设备正忙，收到非「退出」命令 |
|
|
|
+| `pe sn not find` | `pe` 设备序列号无法匹配 |
|
|
|
+| `cmd no define` | 不支持的命令码 |
|
|
|
+| `ok` | 测试命令（cmd=90）的成功回复 |
|
|
|
+| `test fail` | 测试命令（cmd=99）的回复 |
|
|
|
+
|
|
|
+> 当 `cmd` 字段无法解析时，错误回复中的 `cmd` 取值为 0。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 7. 字段速查
|
|
|
+
|
|
|
+| 字段 | 出现位置 | 类型 | 含义 |
|
|
|
+| ---------------------- | ------------------- | -------- | ---------------------------------------------------------- |
|
|
|
+| `cmd` | 顶层 | 整数 | 命令码 |
|
|
|
+| `data` | 顶层 | 对象 | 数据体 |
|
|
|
+| `data.result` | 回复 | 字符串 | 整体结果：`ok` / `error`（或错误说明） |
|
|
|
+| `data.filename` | 获取记录回复 | 字符串 | 导出文件标识 |
|
|
|
+| `list` | data | 数组 | 设备分组列表 |
|
|
|
+| `type` | list | 字符串 | 设备类型：`pe` / `aGate` |
|
|
|
+| `info` | list | 数组 | 设备项列表 |
|
|
|
+| `sn` | info | 字符串 | 设备序列号 |
|
|
|
+| `codeList` | info（请求，cmd=0） | 整数数组 | 数据项命令码列表 |
|
|
|
+| `index` | info（请求，cmd=2） | 整数数组 | 记录索引列表 |
|
|
|
+| `idList` | info（请求，cmd=3） | 整数数组 | 命令控制符（功能码）列表 |
|
|
|
+| `paraList` | info（请求，cmd=1） | 数组 | 功能项列表 |
|
|
|
+| `paraList[].id` | paraList | 整数 | 命令控制符（功能码） |
|
|
|
+| `paraList[].setVal` | paraList | 字符串 | 功能码的输入参数（十六进制字符串） |
|
|
|
+| `hexList` | info（回复，cmd=0） | 数组 | 实时数据结果列表 |
|
|
|
+| `hexList[].code` | hexList | 整数 | 数据项命令码 |
|
|
|
+| `hexList[].hexData` | hexList | 字符串 | 数据值（十六进制字符串） |
|
|
|
+| `indexInfo` | info（回复，cmd=2） | 数组 | 记录结果列表 |
|
|
|
+| `indexInfo[].index` | indexInfo | 整数 | 记录数据类型码：4=故障数据，5=波形数据（非请求的记录序号） |
|
|
|
+| `idInfo` | info（回复，cmd=3） | 数组 | 功能码查询结果列表 |
|
|
|
+| `idInfo[].id` | idInfo | 整数 | 命令控制符（功能码） |
|
|
|
+| `idInfo[].idData` | idInfo | 字符串 | 功能码对应的配置 / 状态值（十六进制字符串） |
|
|
|
+| `setResultList` | info（回复，cmd=1） | 数组 | 功能项执行结果列表 |
|
|
|
+| `setResultList[].id` | setResultList | 整数 | 命令控制符（功能码） |
|
|
|
+| `resultOne` | 各回复子项 | 字符串 | 子项处理结果 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 8. 编号字段速览（code / index / id）
|
|
|
+
|
|
|
+本协议中有三类编号字段，分别用于不同命令。下面汇总其含义与取值出处。
|
|
|
+
|
|
|
+### 8.1 `code`（获取实时数据，cmd=0）
|
|
|
+
|
|
|
+- 表示要读取的实时数据类别，取值 1~3，定义见 5.1。code=4/5 不能通过 cmd=0 查询，须用 cmd=2 按记录导出。
|
|
|
+- 读取结果以十六进制字符串放入回复的 `hexData`；各 code 的 `hexData` 字节结构见 5.1.1。
|
|
|
+
|
|
|
+### 8.2 `index`（获取记录，cmd=2）
|
|
|
+
|
|
|
+- 表示要导出的记录序号，取值来源于 code=3「故障录波总目录」中各记录的位置索引（见 5.1.1）。
|
|
|
+- 每条记录包含故障数据（failuredata）与波形数据（waveformdata）两类，分别保存为文件（见 5.2.1）。
|
|
|
+
|
|
|
+### 8.3 `id`（设置 / 查询，cmd=1 / cmd=3）
|
|
|
+
|
|
|
+- 为**命令控制符（功能码）**，表示对设备执行的一种操作，而非某个数据参数的编号。
|
|
|
+- 功能码取值、设置时的输入参数 `setVal` 结构、查询返回的数据结构，均见 5.4.1。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 9. 子项处理结果（resultOne）取值
|
|
|
+
|
|
|
+读取 / 设置的每个子项（`hexList[]`、`indexInfo[]`、`idInfo[]`、`setResultList[]`）都带一个 `resultOne` 字符串，表示该子项的处理结果。取值如下：
|
|
|
+
|
|
|
+| `resultOne` 取值 | 含义 |
|
|
|
+| ------------------------------ | -------------------------------------------------------------------------------- |
|
|
|
+| `ok` | 该子项处理成功；对应的 `hexData` / `idData` 有效 |
|
|
|
+| `cancomerr:suberrcode=<hex>` | 与子设备通信时，子设备返回了错误码；`<hex>` 为子设备返回的错误代码（十六进制） |
|
|
|
+| `cancomerr:time out` | 与子设备通信超时 |
|
|
|
+| `cancomerr:index=<hex>` | 其他通信类错误；`<hex>` 为设备内部的错误判定码（十六进制） |
|
|
|
+| `emserr:can p null` | 未取到目标子设备（子设备不可达 / 不存在） |
|
|
|
+| `emserr:can data null` | 子设备返回数据为空 |
|
|
|
+| `emserr:set cmd err` | 下发命令失败 |
|
|
|
+| `emserr:other` | 其他错误 |
|
|
|
+
|
|
|
+> 当 `resultOne` 不为 `ok` 时，对应子项的 `hexData` / `idData` 可能为空或无效。
|
|
|
+> 其中 `cancomerr:suberrcode=<hex>` 里的 `<hex>` 为子设备错误码（F12，代码表见 10.6）；`cancomerr:index=<hex>` 里的 `<hex>` 为设备内部判定码（F13，数值表见 10.5）。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 10. 编号 / 代码字段汇总与消歧
|
|
|
+
|
|
|
+本节汇总协议中各类编号 / 代码字段的含义与取值出处，并对同名字段做消歧。各字段的取值表或来源均已在本文档内给出或指明。
|
|
|
+
|
|
|
+> 为避免混淆：`code`、`id`、`index`、`resultOne` 等名字在「请求 / 回复」「不同命令」里重复出现，但含义不同。下表用**完整 JSON 路径**（从消息根对象 `{}` 开始，`data.list[].info[]` 为设备项层级）加上**命令号与方向**唯一标识每个字段，请以路径为准，不要只看字段末名。
|
|
|
+
|
|
|
+### 10.1 编号字段清单（按完整 JSON 路径定位）
|
|
|
+
|
|
|
+**状态总览**：
|
|
|
+
|
|
|
+| 字段 | 含义与取值出处 |
|
|
|
+| --------------- | ----------------------------------------------------------------------- |
|
|
|
+| F1、F2 | 实时数据类别 `code`，取值 1~3，见 5.1 |
|
|
|
+| F3 | 各 code 的 `hexData` 字节结构，见 5.1.1 |
|
|
|
+| F4 | 记录序号，取值即 code=3 目录中各记录的 `index`（见 5.1.1） |
|
|
|
+| F5、F6、F8、F10 | 命令控制符（功能码），见 5.4.1 |
|
|
|
+| F7 | 查询返回值 `idData`，结构参照 5.4.1 对应功能码 |
|
|
|
+| F9 | 设置输入参数 `setVal`，十六进制字符串，结构见 5.4.1 |
|
|
|
+| F11 | 记录文件保存格式与字节结构，见 5.2.1~5.2.3 |
|
|
|
+| F12 | 下级设备错误码表，见 10.6 |
|
|
|
+| F13 | 设备内部通信错误判定码，见 10.5 |
|
|
|
+| F14 | 通道含义参数代码（Uint16 编号 → 物理量），对照表为产品级《参数代码表》 |
|
|
|
+| F15 | 事件触发源代码表，见 10.4 |
|
|
|
+
|
|
|
+> 下表为完整清单，列出每个字段的完整 JSON 路径、含义与取值出处。
|
|
|
+
|
|
|
+| 编号 | 完整 JSON 路径 | 命令 / 方向 | 类型 | 含义 | 取值出处 |
|
|
|
+| ---- | ----------------------------------------------------------------------------------------------- | --------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
|
|
|
+| F1 | `data.list[].info[].codeList[]` | cmd=0 请求 | 整数数组 | 实时数据类别编号：1-故障总体信息；2-设备故障录波功能基本信息；3-故障录波总目录（4/5 不能用于 cmd=0） | 5.1 |
|
|
|
+| F2 | `data.list[].info[].hexList[].code` | cmd=0 回复 | 整数 | 回显请求 F1 的编号 | 5.1 |
|
|
|
+| F3 | `data.list[].info[].hexList[].hexData` | cmd=0 回复 | 字符串(hex) | 各 code 返回数据的原始字节（十六进制字符串） | 字节结构：5.1.1；内含编号见 F14 / F15 |
|
|
|
+| F4 | `data.list[].info[].index[]` | cmd=2 请求 | 整数数组 | 记录序号，取值即 code=3 目录中各记录的位置索引 `index`（从 1 开始）。对端应先用 cmd=0 + code=3 查目录，再以目录中列出的 `index` 作为本字段取值 | 5.1.1（code=3） |
|
|
|
+| F5 | `data.list[].info[].idList[]` | cmd=3 请求 | 整数数组 | 命令控制符（功能码） | 5.4.1 |
|
|
|
+| F6 | `data.list[].info[].idInfo[].id` | cmd=3 回复 | 整数 | 回显请求 F5 的功能码 | 5.4.1 |
|
|
|
+| F7 | `data.list[].info[].idInfo[].idData` | cmd=3 回复 | 字符串(hex) | 查询返回的功能码对应配置 / 状态字节（如 id=2 返回采样通道配置、id=5 返回采样频率） | 5.4.1（对应功能码结构） |
|
|
|
+| F8 | `data.list[].info[].paraList[].id` | cmd=1 请求 | 整数 | 命令控制符（功能码） | 5.4.1 |
|
|
|
+| F9 | `data.list[].info[].paraList[].setVal` | cmd=1 请求 | 字符串(hex) | 功能码输入参数，十六进制字符串（每 2 字符 = 1 字节，如 `"010100015984"` = `01 01 00 01 59 84`） | 5.4.1 |
|
|
|
+| F10 | `data.list[].info[].setResultList[].id` | cmd=1 回复 | 整数 | 回显请求 F8 的功能码 | 5.4.1 |
|
|
|
+| F11 | 设备侧导出的记录文件（`failuredata`/`waveformdata`）内容 | cmd=2（非 MQTT 字段） | 文本文件 | 导出记录的落盘文件 | 保存规则 5.2.1；字节结构 5.2.2 / 5.2.3 |
|
|
|
+| F12 | `resultOne` = `cancomerr:suberrcode=<hex>` 中的 `<hex>` | 回复子项 | 整数(hex) | 子设备返回的错误码 | 10.6 |
|
|
|
+| F13 | `resultOne` = `cancomerr:index=<hex>` 中的 `<hex>` | 回复子项 | 整数(hex) | 设备内部的通信错误判定码 | 10.5 |
|
|
|
+| F14 | 通道含义编号（参数代码），见 code=1 的 `hexData`（5.1.1）、code=4 的 `failuredata`（5.2.2） | cmd=0 / cmd=2 | 整数编号(Uint16) | 快照 / 采样通道的含义编号（快照与采样共用同一套参数代码），标识通道对应的物理量；code=1 的可配通道「类型 / 地址」标识可配通道所记录的变量 | 产品级《参数代码表》（编号 → 物理量） |
|
|
|
+| F15 | 事件触发源代码，见 code=3（5.1.1）、code=4（5.2.2）的「事件触发源」字段 | cmd=0 | 整数(Uint16) | 事件触发源 | 10.4（表外代码为未定义） |
|
|
|
+
|
|
|
+### 10.2 同名字段消歧（重点）
|
|
|
+
|
|
|
+以下几组字段末名相同但不是同一个东西，按路径区分：
|
|
|
+
|
|
|
+| 末名 | 不同含义的字段 | 区别 |
|
|
|
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
|
+| `index` | ① `data.list[].info[].index[]`（cmd=2 **请求**，F4）② `data.list[].info[].indexInfo[].index`（cmd=2 **回复**） | ① 是请求的**记录序号**，取值来源于 code=3 目录（见 5.1.1）。② 是**记录数据类型码**（固定 4=故障数据 / 5=波形数据，见 5.2）。两者含义不同，均已明确。 |
|
|
|
+| `code` | `data.list[].info[].hexList[].code`（cmd=0 回复，F2） | 仅此一处；它回显请求 `codeList`（F1）的元素。 |
|
|
|
+| `id` | `idList[]`(F5) / `idInfo[].id`(F6) / `paraList[].id`(F8) / `setResultList[].id`(F10) | 四处均为**同一套命令控制符（功能码）**，分布在不同命令 / 方向；取值见 5.4.1。 |
|
|
|
+| `result` vs `resultOne` | `data.result`（整条命令结果）`...resultOne`（单个子项结果） | `data.result` 取值 `ok`/`error`（见 4.3）；`resultOne` 取值见第 9 节；其中内嵌的 `<hex>` 代码表见 10.5（F13）/ 10.6（F12）。 |
|
|
|
+
|
|
|
+> 注意 F13：`cancomerr:index=<hex>` 里的 `index` 与记录序号、记录类型码都**无关**，它是设备内部的通信错误判定码，与子设备无关。其数值表见 10.5。
|
|
|
+
|
|
|
+### 10.3 各编号 / 代码表的取值出处汇总
|
|
|
+
|
|
|
+本协议所涉编号 / 代码字段的取值表或来源均已在本文档内给出或指明：
|
|
|
+
|
|
|
+| 字段 | 取值出处 |
|
|
|
+| -------------------------------------------------------------------- | ------------------------------------------ |
|
|
|
+| 实时数据类别 `code`（cmd=0） | 5.1 |
|
|
|
+| `hexData` 字节结构（code=1/2/3） | 5.1.1 |
|
|
|
+| 记录文件字节结构（code=4 `failuredata` / code=5 `waveformdata`） | 5.2.2 / 5.2.3 |
|
|
|
+| 记录序号 `index`（cmd=2） | 来源于 code=3 目录（5.1.1） |
|
|
|
+| 命令控制符 `id` 及输入参数 `setVal`、查询返回结构（cmd=1/3） | 5.4.1 |
|
|
|
+| 通道含义参数代码（F14） | 产品级《参数代码表》（编号 → 物理量对照） |
|
|
|
+| 事件触发源代码（F15） | 10.4 |
|
|
|
+| 设备内部通信错误判定码（F13） | 10.5 |
|
|
|
+| 子设备错误码（F12） | 10.6 |
|
|
|
+
|
|
|
+### 10.4 事件触发源代码表（F15）
|
|
|
+
|
|
|
+以下为「事件触发源」字段（`triggerSource`，Uint16）的取值定义。该字段出现在 code=3（故障录波总目录，见 5.1.1）与 code=4（单一故障信息，见 5.2.2）中。
|
|
|
+
|
|
|
+| 代码 | 含义 |
|
|
|
+| ---------- | ------------------------ |
|
|
|
+| `0xFF0` | 手动触发 _Fix |
|
|
|
+| `0xFF1` | 模拟故障触发 _Auto |
|
|
|
+| `0x1000` | SL_DSP 预留触发源 16_1 |
|
|
|
+| `0x1001` | 并网发生状态切换故障 |
|
|
|
+| `0x1002` | 离网发生 aPower 离运问题 |
|
|
|
+| `0x1003` | 油机发生状态切换故障 |
|
|
|
+| `0x5000` | PE_INV 预留触发源 16_1 |
|
|
|
+| `0x5001` | 运行态下逆变故障 |
|
|
|
+| `0xD000` | MPPT 预留触发源 16_1 |
|
|
|
+| `0xD001` | 运行态下 MPPT 故障 |
|
|
|
+| `0xD800` | APBOX2.0 预留触发源 16_1 |
|
|
|
+| `0xD801` | 运行态下 APBOX2.0 故障 |
|
|
|
+| `0xE000` | DIF 预留触发源 16_1 |
|
|
|
+| `0xE001` | 并网发生状态切换故障 |
|
|
|
+| `0xE002` | 离网发生 aPower 离运问题 |
|
|
|
+
|
|
|
+> 上表以外的代码为未定义，待后续补充。
|
|
|
+
|
|
|
+### 10.5 内部通信错误判定码（F13）
|
|
|
+
|
|
|
+`resultOne` 为 `cancomerr:index=<hex>` 时，`<hex>` 是**设备内部**在与子设备通信过程中判定的错误类型码（以十六进制输出）。此表为设备自身定义，与子设备无关。
|
|
|
+
|
|
|
+说明：这些码对应与子设备通信在不同阶段（数据读取、记录传输、参数读写）的异常，供排查参考。
|
|
|
+
|
|
|
+| `<hex>` | 含义 |
|
|
|
+| --------- | --------------------------------------------------- |
|
|
|
+| `3` | 下发命令与子设备回复的命令不一致 |
|
|
|
+| `4` | 数据读取阶段：子设备回复错误 |
|
|
|
+| `5` | 数据读取阶段：回复的数据类别不符 |
|
|
|
+| `6` | 记录传输阶段：起始报文接收错误 |
|
|
|
+| `7` | 记录传输阶段：后续数据未接收完成 |
|
|
|
+| `8` | 记录传输阶段：数据块不连续 |
|
|
|
+| `9` | 记录传输阶段：数据块内序号不连续 |
|
|
|
+| `a` | 记录传输阶段：收到多余的后续数据 |
|
|
|
+| `b` | 记录传输阶段：首包数据过短 |
|
|
|
+| `c` | 记录传输结束阶段：后续数据未接收完成 |
|
|
|
+| `d` | 数据读取阶段：接收超时 |
|
|
|
+| `e` | 记录传输阶段：接收超时 |
|
|
|
+| `f` | 记录传输结束阶段：接收超时 |
|
|
|
+| `10` | 其他命令：接收超时 |
|
|
|
+| `11` | 记录传输阶段：后续数据接收超时 |
|
|
|
+| `12` | 参数读写阶段：读 / 写类型不一致（如请求读却回复写） |
|
|
|
+| `13` | 参数读写阶段：回复的功能码不一致 |
|
|
|
+| `14` | 参数读写阶段：回复数据过短 |
|
|
|
+| `15` | 参数读写阶段：接收超时 |
|
|
|
+| `16` | 参数读写阶段：后续数据未接收完成 |
|
|
|
+
|
|
|
+> 说明：
|
|
|
+>
|
|
|
+> - 另有「子设备回复错误」与「通用超时」两种情况，分别以 `cancomerr:suberrcode=<hex>`（F12）与 `cancomerr:time out` 形式返回，**不会**出现在 `cancomerr:index=` 中。故本表取值集中在 `0x3`~`0x16`。
|
|
|
+> - 这些是「设备侧判定」的通信错误；而 F12（`suberrcode`）是「子设备回复」的错误码，二者来源不同，不要混淆。
|
|
|
+
|
|
|
+### 10.6 子设备错误码表（F12 / suberrcode）
|
|
|
+
|
|
|
+`resultOne` 为 `cancomerr:suberrcode=<hex>` 时，`<hex>` 是**子设备**返回的错误码（否定响应码），以十六进制输出。取值定义如下。
|
|
|
+
|
|
|
+| 代码 | 名称 | 说明 |
|
|
|
+| -------- | ---------------------------------------- | ------------------------------------------ |
|
|
|
+| `0x10` | GeneralReject | 诊断服务被服务器(ECU)拒绝 |
|
|
|
+| `0x11` | serviceNotSupported | ECU 不支持该诊断请求 |
|
|
|
+| `0x12` | subFunctionNotSupported | ECU 不支持该诊断请求子功能 |
|
|
|
+| `0x13` | incorrectMessageLengthOrInvalidFormat | 请求报文长度或格式错误 |
|
|
|
+| `0x14` | ResponseTooLong | 诊断响应数据长度超出服务器所支持的最大长度 |
|
|
|
+| `0x22` | conditionsNotCorrect | 条件错误 |
|
|
|
+| `0x23` | commTimeoutError | 自定义，通信超时 |
|
|
|
+| `0x31` | requestOutOfRange | 请求超过范围 |
|
|
|
+| `0x33` | securityAccessDenied | 安全访问拒绝该请求 |
|
|
|
+| `0x35` | invalidKey | 反馈密钥错误 |
|
|
|
+| `0x36` | exceedNumberOfAttempts | 安全访问尝试次数超限 |
|
|
|
+| `0x37` | requiredTimeDelayNotExpired | 安全访问延时未到期 |
|
|
|
+| `0x70` | UploadDownloadNotAccepted | 上传或下载数据失败 |
|
|
|
+| `0x71` | TransferDataSuspended | 由于故障导致数据传输操作被中断 |
|
|
|
+| `0x72` | GeneralProgrammingFailure | 擦除或写入 Flash 出现错误 |
|
|
|
+| `0x73` | WrongBlockSequenceCounter | 数据包序列编号错误 |
|
|
|
+| `0x78` | requestCorrectlyReceived-ResponsePending | ECU 正忙，无法及时响应该请求 |
|
|
|
+| `0x7F` | serviceNotSupportedInActiveSession | ECU 不支持当前诊断模式下进行该 SID 请求 |
|
|
|
+
|
|
|
+> 说明：此表为子设备（PE / aGate）定义的错误码，由子设备在负响应中返回、经设备原样透传到 `suberrcode`。请勿与 F13（10.5，设备内部判定码）混淆：F12 是「子设备回复的错误」，F13 是「本设备判定的错误」。
|
Jerry Liang