FranklinWH-Toolbox/docs/fault-record/protocol-specification.md

故障录波 MQTT 协议详细描述

状态：待补全的协议描述，2026-10-12；2026-10-14 按 FaultFilter_MQTT协议文档 更正业务层字段；2026-10-16 补充 607～610 文件上传与下载地址（第 8A 节）。本文按现有信息逐字段描述 377～380，供补充和确认使用；不是已经完成设备验证的最终规范。

业务层（dataArea 内的 cmd/data、设备回复的 result/list）以 FaultFilter 协议文档为准；外层（cmdType、snno、crc、topic 等）不在该文档范围内，仍按本文记录。原始证据与样本时间线见 protocol-observations.md。功能目标见 requirements.md，架构讨论见 technical-design.md。本文中的字段类型不等于完整的必填性、值域或失败行为约束。

1. 信息来源与阅读规则

标记	来源与适用范围
样本记录	观察文档整理的 CSV 通讯记录，仅覆盖cmd=0/2、aGate 和成功结果；2026-09-29 附件未入库，2026-10-14 附件为 CloudLog_2026-10-14_104644.csv（含 607～610）
已验证代码	用户此前确认可信的现有参数设置请求结构；代码入口为service/repositories/mqtt/fwh_mqtt/fwh_mqtt_fault_record.go
FaultFilter 文档	FaultFilter_MQTT协议文档：设备侧故障录波服务的 {cmd, data} 业务协议；业务字段以其为准，经 377～380 外层转发后的表现仍需实测
现有实现	仓库当前行为，不能单独证明设备协议要求
用户确认	本轮讨论确认的协议行为或服务端约定
旧描述	先前协议说明；与 FaultFilter 文档冲突时以后者为准，其余未被样本或用户确认覆盖的部分仍待验证
待补充	缺少资料、语义不清或证据存在冲突

本文 JSON 均为结构示意，不是完整原始抓包。占位字符串没有协议值域含义，hexData 占位内容不能发送给设备；不为示意报文编造 crc/len。

业务层映射：FaultFilter 文档的请求为 {cmd, data:{list}}，与 377.dataArea 一致；其回复为 {cmd, data:{result, list, filename}}，而样本 379.dataArea 中 result/list/filename 直接位于 dataArea 顶层，没有 data 包裹。推断网关转发时展开了 data，379 承载的即 FaultFilter 回复；该映射在 cmd=1/3 和错误场景下尚未实测。FaultFilter 文档中的 topic（aws/faultrecord / faultfilter/faultrecord）是该服务自身的收发主题，与云端 fwh/s2c|c2s/mng/{SN} 的关系待确认，不能互相替代。

2. 协议角色、方向与传输

存在两套方向不同的请求应答：

请求	请求方	应答	应答方	用途
377	本工具	378	设备	发起故障录波操作并获得指令应答
379	设备	380	FWH 平台	上传数据或处理结果并获得上传应答；本工具只监听
607	FWH 平台	608	设备	平台通知设备上传录波文件；本工具只监听（见 8A）
609	设备	610	FWH 平台	设备报告文件上传结果；本工具只监听

378 与 379 不是同一种响应。现有样本在 377/378 后出现 379/380，但尚未确认每次请求是否必然产生上传、上传条数以及严格顺序。两套协议分别关联；379/380 的关联不能反向证明某次 379 属于某次 377。FaultFilter 文档规定请求与回复通过 cmd 关联、设备同一时刻只处理一条业务命令（见第 4.1 节），可作为 377→379 业务关联的依据，但外层是否保证一请求一上传仍待实测。

消息	MQTT topic	来源／状态
377	fwh/s2c/mng/{gatewaySN}	现有实现；所有设备和失败场景是否适用待确认
378	fwh/c2s/mng/{gatewaySN}	现有实现的等待 topic；原 CSV 未包含 topic
379	待补充	不能假定与378 相同
380	待补充	不能假定与377 相同；样本中由 FWH 平台发出
607／610	fwh/s2c/debug/{gatewaySN}	FWH 平台发给设备，本工具只监听（用户确认，2026-10-19）
608／609	fwh/c2s/debug/{gatewaySN}	设备发给 FWH 平台（用户确认，2026-10-19）

测试服与生产服使用不同的 broker、证书和平台域名，同一操作的 MQTT 与 HTTP 下载必须属于同一环境，见 technical-design.md。

现有通用客户端订阅 QoS 为 1，故障录波发布使用 QoS 0、retained=false。这些是实现配置，设备要求的 QoS、会话和离线投递规则待补充。FaultFilter 文档中的 QoS 2 针对其自身 topic，不直接适用于云端外层。

3. 公共报文外层

四种消息的样本记录均包含以下外层字段。dataArea 是 JSON 对象，不是 JSON 字符串。

字段	JSON 类型	含义／现有行为	来源与待补充内容
cmdType	整数	消息类型，分别为377/378/379/380	样本记录、已验证代码
equipNo	字符串	现有377 填目标网关 SN	样本中均为同一网关；真正子设备场景及全部应答取值待确认
type	整数	外层设备类型；现有发送填0，代码注释为网关 IBG	样本为0；其他值待补充。不同于业务层字符串 list[].type
timeStamp	整数	现有发送使用 Unix 秒time.Now().Unix()	接收端单位、生成时点和校时规则待确认
snno	整数	消息序号；关联规则见第 4 节	取值范围、回绕及设备重发是否保留序号待补充
len	整数	现有发送为序列化后dataArea 的字节长度	接收规则与失败校验行为待确认
crc	字符串	现有发送为dataArea 序列化字节的 CRC32 IEEE，8 位大写十六进制	接收规则与校验失败行为待确认
dataArea	对象	命令业务内容，详见第 5～8 节	业务字段见 FaultFilter 文档；外层失败报文的形态待补充

现有发送计算方式：先以 Go json.Marshal(dataArea) 得到字节 B，再取 len(B) 和 CRC32_IEEE(B)。发送外层中的 dataArea 仍为对象。协议尚未明确 JSON 字段顺序、空白、Unicode 转义和数值格式对接收端 CRC 校验的影响，不能直接规定“反序列化后重新序列化”就是正确的校验方式。FaultFilter 文档说明业务 JSON 字段顺序不固定、接收方应按字段名解析。

外层字段完整必填规则、最大报文长度、未知字段处理及空值规则均待补充。

4. 序号、关联和当前服务端约定

4.1 377/378

• 用户确认：设备端没有严格按请求 snno 应答，请求方和应答方各自维护序号，不能用它关联 377/378。
• 用户确认：服务端发送 377 可使用固定 snno=123 或随机数；现有代码使用 123。
• 用户确认：当前采用串行发送并等待对应类型应答的方向；串行范围及释放时点尚待细化。
• FaultFilter 文档：设备同一时刻只处理一条业务命令。处理期间收到非「退出(cmd=4)」命令时直接回复错误 busy，不中断当前处理；cmd=4 用于结束当前处理。判定顺序为先校验 cmd、再判忙、再校验 data。该 busy 回复经外层体现为 378 还是 379 待实测。
• 服务端暂定：响应等待超时为 15 秒。在当前讨论中针对 377/378 梳理；计时起点尚待确认，不是设备承诺的最长响应时间，也不作为 379 的超时。
• 待设计：建议核对 topic、equipNo、cmdType=378、dataArea.cmd，而非只匹配 cmdType；此过滤方案尚未落地。
• 待补充：迟到或重复 378、其他发送方请求产生的 378 如何处理；相同网关和 cmd 的消息没有唯一关联凭据。

4.2 379/380

• 用户确认：380 由服务端实现，可以使用 snno 关联 379/380。
• 待细化：是否通过 380.snno=379.snno 实现关联，还是另有规则；尚未确认，本文不将回显写为既定要求。
• 证据冲突：旧样本记录的 379/380 序号不同（14→7536、26→7559）。保留其历史事实，不将它解释为新服务端必须继续采用的行为；新关联方式需补充设备接受条件和验证结果。
• 待补充：应答 topic、应答期限、重发规则、应答成功的语义及重复上传处理。

5. 377：服务端操作请求

5.1 公共业务结构

字段路径（相对dataArea）	类型	含义	来源／约束
cmd	整数	0 获取实时数据；1 设置参数；2 获取记录；3 查询参数；4 退出；90/99 连通性测试	FaultFilter 文档；样本覆盖0/2，已验证代码覆盖 1；3/4/90/99 经外层转发待实测
data	对象	请求内容	cmd=4/90/99 为空对象{}
data.list	对象数组	按设备类型分组	最小／最大数量待补充
data.list[].type	字符串	目标设备类型：pe 或 aGate	字典见第 9 节
data.list[].info	对象数组	该类型下的目标设备和操作项	批量限制待补充
data.list[].info[].sn	字符串	目标设备 SN；pe 必填并用于寻址（最多 15 台），aGate 可填但不用于寻址	FaultFilter 文档；pe 的 SN 无法匹配时整条命令回复 pe sn not find

5.2 cmd=0：获取实时数据

附加字段 data.list[].info[].codeList 为整数数组，每个元素为数据项编号。设备对每个 code 串行读取子设备，汇总后在回复的 hexList 中返回。

code	含义	hexData 结构（FaultFilter 文档）
1	故障总体信息	5.1.1，变长
2	设备故障录波功能基本信息	5.1.1，固定 16 字节
3	故障录波总目录	5.1.1，1 字节条数 + N × 14 字节目录项

cmd=0 只支持 code=1～3（用户确认，2026-10-14）。单一故障信息（4）和单一故障波形数据（5）属于具体记录，必须用 cmd=2 按记录序号导出（见 5.4）。样本请求 [3] 即查询录波总目录，目录项中的位置索引 index 是 cmd=2 的请求取值。重复值及空数组的行为未定义。

dataArea 结构示意：

{
  "cmd": 0,
  "data": {
    "list": [
      { "type": "aGate", "info": [{ "sn": "<目标设备SN>", "codeList": [3] }] }
    ]
  }
}

5.3 cmd=1：设置参数

附加字段路径（相对dataArea）	类型	含义
data.list[].info[].paraList	对象数组	待执行的功能项列表
data.list[].info[].paraList[].id	整数	命令控制符（功能码），不是数据参数编号；取值 1～7，见下表
data.list[].info[].paraList[].setVal	字符串	该功能码的输入参数，十六进制字符串（每 2 字符 1 字节）；无输入参数的功能码可为空字符串

id	功能	setVal 字节结构
1	清除设备故障波形	无
2	采样通道配置	通道数(1B) + n × 通道含义(2B，大端)
3	手动触发故障录波	无
4	设备对时	年(2B，大端) 月 日 时 分 秒，共 7 字节
5	设置采样频率	2 字节，Hz，大端
6	配置可配采样通道	索引号(1B) + 数据类型(1B，高半字节=设置方式，低半字节=地址类型) + 数据(4B)
7	故障录波功能状态控制	1 字节：0=关闭，1=使能

完整定义见 FaultFilter 文档 5.4.1。

dataArea 结构示意，值取自现有辅助函数，不代表通用默认配置：

{
  "cmd": 1,
  "data": {
    "list": [
      {
        "type": "pe",
        "info": [
          {
            "sn": "<目标子设备SN>",
            "paraList": [
              { "id": 6, "setVal": "010100015984" },
              { "id": 6, "setVal": "020100015981" }
            ]
          }
        ]
      }
    ]
  }
}

两项 id=6 均为「配置可配采样通道」，由 setVal 首字节的通道索引区分：01 01 00015984 表示通道 1、默认方式、Uint16、地址 0x00015984；02 01 00015981 表示通道 2、地址 0x00015981。因此 id 不能作为条目唯一键；回复 setResultList 是否按请求顺序逐项对应待实测。前端目前只校验十六进制字符，未按功能码校验字节长度。HTTP DTO 使用 val，MQTT 使用 setVal，两者不可混淆。

5.4 cmd=2：获取记录

附加字段 data.list[].info[].index 为整数数组，字段名为单数 index，值为数组。每个元素是记录序号，即 cmd=0, code=3 目录中各记录的位置索引（从 1 开始，不超过 code=1 的「最大可存储故障记录总数」）。旧描述的范围 1～16 未在 FaultFilter 文档中出现，以目录实际返回为准。样本请求 [9]。

设备对每个记录序号分别读取「故障数据」(code=4) 与「波形数据」(code=5)，并保存为设备本地文件（见 7.4）。每次 cmd=2 开始前，设备会删除保存根目录下的全部历史记录文件。

{
  "cmd": 2,
  "data": {
    "list": [
      { "type": "aGate", "info": [{ "sn": "<目标设备SN>", "index": [9] }] }
    ]
  }
}

5.5 cmd=3：查询参数

FaultFilter 文档定义，无样本，经 377 转发待实测。附加字段 data.list[].info[].idList 为整数数组，元素为第 5.3 节的功能码，不带输入参数。

{
  "cmd": 3,
  "data": {
    "list": [
      { "type": "pe", "info": [{ "sn": "<目标子设备SN>", "idList": [2, 5, 7] }] }
    ]
  }
}

5.6 cmd=4／cmd=90／cmd=99

• cmd=4 退出：data 为 {}，结束设备当前处理，不产生业务数据回复。
• cmd=90／cmd=99 连通性测试：data 为 {}，设备分别回复 result="ok"／"test fail"。

以上均来自 FaultFilter 文档，经外层转发的表现待实测。

6. 378：设备操作应答

字段路径（相对dataArea）	类型	含义／状态
cmd	整数	样本为0/2；现有代码按 0/1/2 定义。是否始终等于请求命令待确认
result	整数	样本成功为0；旧描述失败为 -1；完整错误值域待补充

{ "cmd": 0, "result": 0 }

378 属于外层应答，FaultFilter 文档未定义（其回复 result 为字符串，对应 379）。样本与现有代码没有显示这里包含逐设备、逐参数或文件字节。result=0 表示收到、接受、排队还是执行完成，尚未确认；不能仅凭它断言数据已取得、文件可下载或参数已生效。

待补充的应答行为：一条请求对应一条还是多条应答；格式错误、设备忙和不支持命令时 378 是否仍为 0；重复及迟到应答规则；字段缺失规则；收到应答后能否立即发送下一条请求（FaultFilter 层忙时会回复 busy）。

7. 379：设备数据／处理结果上传请求

7.1 公共业务字段

字段路径（相对dataArea）	类型	含义／状态
cmd	整数	回显请求命令码；样本为0/2
result	字符串	整体结果："ok" 全部子项成功，"error" 至少一个子项失败；错误回复时为错误说明
list	对象数组	上传设备列表，位于dataArea.list，不是 dataArea.data.list
list[].type	字符串	设备类型：pe 或 aGate
list[].info	对象数组	各设备结果
list[].info[].sn	字符串	设备 SN；样本类型为字符串，不是数组

错误回复：命令无法进入业务处理时，FaultFilter 回复只含 result，没有 list：

result	原因
json unpack err	消息体不是合法 JSON
cmd unpack err	缺少 cmd（此时回复 cmd 为 0）
data unpack err	缺少 data
busy	设备正忙，收到非退出命令
pe sn not find	pe 的 SN 无法匹配
cmd no define	不支持的命令码

子项结果 resultOne（所有 hexList[]／indexInfo[]／idInfo[]／setResultList[] 子项通用）：

取值	含义
ok	成功，对应数据有效
cancomerr:suberrcode=<hex>	子设备负响应错误码（NRC），见 FaultFilter 文档 10.6
cancomerr:time out	与子设备通信超时
cancomerr:index=<hex>	设备内部通信错误判定码，见 FaultFilter 文档 10.5
emserr:can p null	未取到目标子设备
emserr:can data null	子设备返回数据为空
emserr:set cmd err	下发命令失败
emserr:other	其他错误

resultOne 不为 ok 时，对应 hexData／idData 可能为空或无效。错误回复经外层后是否仍以 379 上传待实测。

7.2 cmd=0：实时数据上传

附加字段路径	类型	含义
list[].info[].hexList	对象数组	各数据项结果
list[].info[].hexList[].code	整数	回显请求的code；样本3 为故障录波总目录
list[].info[].hexList[].resultOne	字符串	子项结果，见 7.1
list[].info[].hexList[].hexData	字符串	子设备原始字节的十六进制字符串；结构按 code 见第 5.2 节

{
  "cmd": 0,
  "result": "ok",
  "list": [
    {
      "type": "aGate",
      "info": [{ "sn": "<目标设备SN>", "hexList": [{ "code": 3, "resultOne": "ok", "hexData": "<原始十六进制数据>" }] }]
    }
  ]
}

code=3 目录项固定 14 字节：位置索引(1) + 发生时间(7，年份大端) + 参数列表版本(4) + 事件触发源(2)。2026-10-14 样本的 hexData 共 211 字节 = 1 + 15 × 14，15 条记录均按此结构解析出合理的时间与触发源（0x1001／0x1002），结构已验证；解析结果见 protocol-observations.md。

7.3 cmd=1：参数设置结果上传

无样本，结构来自 FaultFilter 文档。旧描述的 resultList[{id, result}] 有误，正确字段为 setResultList：

附加字段路径	类型	含义
list[].info[].setResultList	对象数组	各功能项执行结果
list[].info[].setResultList[].id	整数	回显请求 paraList[].id（功能码）
list[].info[].setResultList[].resultOne	字符串	子项结果，见 7.1；为字符串，不是数组

{
  "cmd": 1,
  "result": "ok",
  "list": [
    {
      "type": "pe",
      "info": [{ "sn": "<目标子设备SN>", "setResultList": [{ "id": 6, "resultOne": "ok" }, { "id": 6, "resultOne": "ok" }] }]
    }
  ]
}

重复功能码（如两项 id=6）的结果是否严格按请求顺序返回，待实测。

7.4 cmd=2：记录处理结果上传

附加字段路径	类型	含义
filename	字符串	本次导出批次的时间戳目录名，格式YYYY-MM-DD_HH_MM_SS；样本为 2026-09-29_14_18_29
list[].info[].indexInfo	对象数组	各记录项结果
list[].info[].indexInfo[].index	整数	记录数据类型码：4=故障数据，5=波形数据；不是请求的记录序号
list[].info[].indexInfo[].resultOne	字符串	子项结果，见 7.1；不是数组

{
  "cmd": 2,
  "result": "ok",
  "filename": "2026-09-29_14_18_29",
  "list": [
    {
      "type": "aGate",
      "info": [{ "sn": "<目标设备SN>", "indexInfo": [{ "index": 4, "resultOne": "ok" }, { "index": 5, "resultOne": "ok" }] }]
    }
  ]
}

请求的每个记录序号在回复中展开为 4、5 两项，回复不回传记录序号本身。因此样本请求 [9] 后上传 4/5 是正常对应，并非索引转换。请求多个记录序号时，回复中会出现多组 4/5，无法仅凭回复区分属于哪个记录序号，只能依赖请求顺序（待实测）。

上传不含文件字节或下载地址。文件保存在设备本地：

/home/root/ExportFile/faultFilterRecode/<filename>/<sn>/index_<记录序号>/failuredata
/home/root/ExportFile/faultFilterRecode/<filename>/<sn>/index_<记录序号>/waveformdata

文件内容为原始字节的大写十六进制 ASCII 文本，无文件头；仅成功项落盘。内部结构见 FaultFilter 文档 5.2.2／5.2.3。文件由 FWH 平台通过 607～610 触发上传到 hes-upload，见第 8A 节。

7.5 cmd=3：参数查询结果上传

无样本，结构来自 FaultFilter 文档。

附加字段路径	类型	含义
list[].info[].idInfo	对象数组	各功能项查询结果
list[].info[].idInfo[].id	整数	回显请求的功能码
list[].info[].idInfo[].idData	字符串	当前配置／状态的十六进制字符串，结构参照第 5.3 节对应功能码
list[].info[].idInfo[].resultOne	字符串	子项结果，见 7.1

8. 380：服务端上传应答

字段路径（相对dataArea）	类型	含义／状态
cmd	整数	样本为0/2；是否必须与 379.cmd 一致待明确
result	整数	样本为0；旧描述失败为 -1

{ "cmd": 0, "result": 0 }

380 属于外层，FaultFilter 文档未定义。关联方向已由用户确认可使用 snno，具体赋值规则见第 4.2 节。result=0 是接收成功、校验通过还是保存成功尚待确认。业务项失败时能否仍回复上传接收成功，以及失败应答是否触发设备重发，也待补充。

设计决策（2026-10-16）：样本中的 380 由 FWH 平台回复，本工具不回复 380，只监听，避免设备收到重复应答。cmd=0/1/3 的 380 是否同样由平台回复待实测。

8A. 607～610：录波文件上传

来源：2026-10-14 样本记录（两轮 cmd=2，结构一致）。这一组消息由 FWH 平台在收到 379(cmd=2) 后自动发起，本工具只监听（用户确认，2026-10-16）。

cmdType	日志名称	方向	dataArea 样本
607	故障录波召唤下行数据	平台 → 设备	{"faultRecordID":5226,"fileName":"2026-10-14_05_46_20","url":"http://test.franklinwh.com/hes-upload/v1/file/upload","logTime":"2026-10-14"}
608	故障录波召唤应答上行数据	设备 → 平台	{"result":0,"filename":"2026-10-14_05_46_20","result":5226}
609	故障录波文件上传结果	设备 → 平台	{"result":0,"fileName":"2026-10-14_05_46_20.tar.bz2"}
610	故障录波文件上传结果应答	平台 → 设备	{"result":1}

字段说明：

字段	消息	类型	含义／状态
faultRecordID	607	整数	FWH 平台的召唤记录 ID；可与 DataDownload 使用的平台记录互查
fileName	607	字符串	等于 379.filename，无扩展名
url	607	字符串	设备 HTTP 上传地址；样本为测试服 http:// 地址，不用于推导下载地址
logTime	607	字符串	日期 YYYY-MM-DD，用途待确认
filename	608	字符串	回显 607.fileName；注意键名小写
result	608	整数	应答结果，样本为 0
id	608	整数	平台召唤记录 ID，等于 607.faultRecordID。旧版本设备把字段名误写为 result，同一对象出现两个 result，第二个即 id（用户确认，2026-10-16）；后续版本修复，旧版本仍需兼容：解析前将第二个 result 键改名为 id，新旧格式按同一结构解析。10-19 测试服的 608 为 {"result":0,"filename":…}，既无重复 result 也无 id，此时平台记录 ID 只取自 607；608 与 607 到达顺序不固定
result	609	整数	样本 0，推测为上传成功；失败值待补充
fileName	609	字符串	上传文件名。不同固件不一致：10-14 样本为 <批次>.tar.bz2，10-19 测试服 EamonAux 为 <批次>（不带后缀）。实际下载文件都带 .tar.bz2，下载前统一补齐后缀
result	610	整数	样本 1；与 378/380 的 0=成功 约定不同，不能统一按 0 判定成功

时序（样本）：379 与 607/608 在同一秒内，380 晚约 1 秒，609/610 在 607 后约 11～12 秒。

下载地址（用户确认，2026-10-16）：

https://<环境域名>/hes-upload/v1/file/download/logger/<equipNo>/<609.fileName>

测试服 <环境域名> 为 test.franklinwh.com，生产服为 FWH_ENERGY 配置的域名。下载不需要 token（用户确认，2026-10-16）。文件保留期限待确认。

压缩包（2026-10-14 样本验证）：扩展名为 .tar.bz2，实际是 gzip 压缩的 tar，解压须按文件头（1f 8b 为 gzip，42 5a 68 为 bzip2）判断。内部结构为：

<filename>/<sn>/index_<记录序号>/failuredata
<filename>/<sn>/index_<记录序号>/waveformdata

文件解析规则（以 FaultFilter 文档 5.2.2／5.2.3 为基础，按样本补充，详见 protocol-observations.md）：

项目	规则	依据
failuredata 长度字段	等于整个文件字节数（含填充），不能当有效数据长度用；按结构逐项解析	样本 512 字节，结构在第 308 字节结束
failuredata 末尾	0xFF 填充，解析到可配采样通道组结束即停止	样本
版本字符串	取第一个 NUL 之前的内容。aGate 的 INV／FPGA 两段为填充，填充方式不限定，不解析，只跳过 64 字节	用户确认（2026-10-16）；样本填充为 01 02 … 40
波形通道数 n	= failuredata 的“采样通道总数”，已包含可配采样通道	样本 16 通道，文件长度恰好整除
波形点数 m	= 基本信息“采样点总数”；故障时刻在第“故障前采样点数”点	样本 1536 点，第 1024 点故障字跳变
波形排列	采样点优先（同一点的 n 个通道连续）	样本验证
采样值	每点每通道 2 字节、大端；按 int16 解释（文档写 Uint16）	样本正弦通道按有符号解释才连续
float32 可配通道	在波形中同样只占 2 字节，换算方式待确认	样本

9. 设备类型与数据字典

位置／来源	已出现的值	说明
FaultFilter 文档	pe、aGate	业务层仅定义这两种；pe 按 SN 寻址（最多 15 台），aGate 系统内唯一
用户确认（2026-10-20）	pe、aGate、mppt、apbox、dif	377 type 全集：mppt=aPower-MPPT（与 aPower 同 SN）、apbox=aHub（aPbox2.0）、dif=Digital Interface（前端暂未开放）
377/379.list[].type 样本	aGate	cmd=0/2
377.list[].type 已验证代码	pe、aGate	参数设置
377.list[].type 旧描述	pe、agate、mppt、apbox	FaultFilter 文档未定义agate（小写）、mppt、apbox，不应使用
379.list[].type 旧描述	aGate、aPower	FaultFilter 文档未定义aPower，回复类型与请求一致为 pe／aGate
HTTP／页面类型	pe、agate	现有设置代码将 HTTPagate 转成 MQTT aGate；MQTT 层必须使用 aGate

已由 FaultFilter 文档补齐的字典：code 含义及 hexData 结构（5.2）、功能码及 setVal 结构（5.3）、indexInfo[].index 类型码（7.4）、resultOne 及错误字符串（7.1）、事件触发源与子设备错误码（见该文档第 10 节）。通道含义参数代码（F14）见产品级《参数代码表》，未随该文档提供。

仍缺失：外层 378/380.result 值域、支持的设备型号与固件版本。

10. 待补充清单

以下编号用于逐项讨论；“待补充”不是已经确定的限制。优先补齐 A 类，再继续分析上传协议。

编号	待补充信息	当前已知／缺口	可补充的材料
A01	378.result 的精确定义	只知道样本为0，成功阶段未知	协议说明、设备处理流程或对照实测
A02	378 应答条数和批量语义	未知是否一请求一应答；批量子项结果已知在379 中按 resultOne 表达	多子设备／多参数请求及完整应答
A03	378 字段与错误值域	业务层错误字符串已知（7.1），其在外层的体现方式未知	非法输入、忙、不支持等场景的完整报文
A04	连续请求的设备行为	FaultFilter 层串行处理、忙时回复busy；busy 经外层如何体现未知	处理中发送下一条请求的结果
A05	迟到、重复和重发应答	无唯一关联标识，15 秒不保证设备停止回复	延迟／断线场景的完整时间线和最大时限说明
A06	topic 与发送方隔离	当前实现有mng/{SN}；FaultFilter 自身 topic 与云端 topic 的关系未知	双向 topic、其他平台发送时的消息可见性
A07	外层字段和 CRC 规则	发送代码有算法，接收及错误规则未知	原始 JSON 字节、校验规范、失败样本
A08	377 输入约束	pe 最多 15 台；其余批量上限未知	数量限制和输入校验说明
A09	15 秒超时的计时口径	服务端暂定值，起点与超时后策略未确定	服务端决策；设备延迟证据供参考
B01	cmd=3／cmd=4 外层支持	FaultFilter 文档定义了 cmd=3（查询参数）和 cmd=4（退出），旧描述、现有代码和实报只有 0/1/2。用户判断可能支持（2026-10-16），待实测。不支持时参数读取、复读和设备侧取消不可用	cmd=3、cmd=4 实测报文
B02	code/hexData 解释	已明确（5.2）；code=3 已用 2026-10-14 样本验证（7.2），code=1/2 待样本	code=1/2 原始十六进制样本
B03	参数 ID／值／重复 ID	id 为功能码，setVal 结构及重复 id=6 的区分方式已明确（5.3）	重复功能码结果顺序的实测
B04	文件传输链路	已明确：平台经 607～610 触发设备 HTTP 上传 tar.bz2，按规律下载（8A）；平台是否对本工具直连发出的 377 同样自动上传待实测	本工具直连 cmd=2 的完整时间线
B05	379 产生条件和批次	是否依赖成功378、是否主动／拆分上传未知	操作到全部上传的时间线
B06	379(cmd=1) 结构	已明确为setResultList[{id, resultOne}]（7.3）	成功、部分失败实测报文
B07	379/380 topic 与关联	服务端可用snno，具体规则和旧样本不一致	明确赋值规则及设备接受新应答的实测
B08	上传应答语义和可靠性	成功判据、应答时限、重发和断线恢复未知；本工具不回复 380，此项影响降低	设备上传处理规范及异常时间线
B09	607～610 topic 与订阅权限	已明确：607/610 在 fwh/s2c/debug/{SN}，608/609 在 fwh/c2s/debug/{SN}；测试服实测 s2c 方向可订阅（收到 380）	生产服订阅实测
B10	609/610 值域	608 第二个 result 已确认为误写的 id，已兼容（8A）。仍待确认：609 失败值；610.result=1 含义。待用户统一找人确认	设备方或平台方说明、上传失败样本
B11	下载认证与压缩包结构	已明确：不需要 token；实为 gzip tar；结构见 8A。保留期限和生产服是否一致待确认	生产服下载一个真实文件
B12	float32 可配通道的 16 位表示	样本第 13、14 通道类型为 float32，波形中每点仅 2 字节，值在 -248～249；换算方式未知。待用户统一找设备方确认	设备方说明
B13	failuredata 中 aGate 的 INV／FPGA 版本字段	已明确（用户确认，2026-10-16）：aGate 中这两段是填充，填充方式不限定，解析时跳过	—
B14	采样值有无符号	文档写 Uint16，样本正弦通道按 int16 解释才连续；暂按 int16 处理	设备方确认
B15	F14 物理量与换算系数	决策（2026-10-16）：解析器先只显示原始值和通道含义代码，是否按《参数代码表》换算后续再定	《参数代码表》

补充时建议记录：编号、确认结论、适用设备／固件、证据来源、原始请求／响应和 topic。先保留历史样本，再更新字段或规则，避免将实现选择写成设备协议事实。