产品通用协议
所有产品共用本页的报文、系统命令和结果码。字节流使用 AF FA + LEN；CAN / CAN FD 使用 ISO-TP。点击命令查看字段。
CMD 分段
| 范围 | 归属 | 用法 |
|---|---|---|
0x00 | 保留 | 不得作为 CMD 使用 |
0x01–0x0F | 通用系统命令 | Boot 与 App 必须实现已分配的四条命令 |
0x10–0x1F | 通用业务命令 | 序列号和硬件版本等，产品按需实现 |
0x20–0x2F | IAP 升级命令 | 支持升级的型号按统一载荷实现 |
0x30–0x4F | 通用预留 | 当前不得使用 |
0x50–0xEF | 产品业务命令 | 各产品独立定义 |
0xF0–0xFF | 工厂与调试命令 | 不作为公开接口 |
命令报文与接口分帧
| 字段 | 长度 |
|---|---|
SEQ | 1字节 |
CMD | 1字节 |
PAYLOAD | 0 至 1024 字节 |
CRC16 | 2字节 |
原始报文为 SEQ + CMD + PAYLOAD + CRC16（4–1028 字节）。CRC 使用 CRC-16/CCITT-FALSE：poly=0x1021、init=0xFFFF、不反射、xorout=0，覆盖 SEQ、CMD、PAYLOAD；CRC 低字节先发。多字节数值使用小端。
UART / RS485、BLE 透传和 Wi‑Fi TCP 等字节流线路发送 AF FA + LEN(2字节小端) + 原始报文。LEN 是原始报文长度，不含外层 4 字节；接收方按帧头和长度收齐后校验 CRC。PAYLOAD 无需转义；错误帧丢弃，断链后丢弃半帧。CAN / CAN FD 使用 ISO-TP 传原始报文，不添加字节流外层头。RS485 多设备共线的地址与收发规则尚未统一定义。
例如空载荷 Get Info：SEQ=01、CMD=01、CRC16=3E1F，原始报文为 01 01 1F 3E，字节流帧为 AF FA 04 00 01 01 1F 3E。
主机请求使用 SEQ=1..255；响应回显 SEQ 和 CMD，SEQ=0 留给设备主动事件。每条逻辑链路一次只保留一笔未完成请求；超时重发必须保持完整请求原始帧不变。响应 PAYLOAD 首字节是 Result。收到 ACCEPTED 后继续等待同一请求的最终响应。Get Info.MaxPayload 是当前模式的载荷上限，包含响应的 Result 字节。
通用结果码
| 值 | 名称 | 含义 |
|---|---|---|
| 0x00 | OK | 最终成功 |
| 0x01 | ACCEPTED | 异步命令已接收，后续还会返回最终结果 |
| 0x02 | BUSY | 设备忙 |
| 0x03 | BAD_COMMAND | 不支持 CMD |
| 0x04 | BAD_PAYLOAD | 长度或内容错误 |
| 0x05 | BAD_STATE | 当前状态不允许 |
| 0x06 | BAD_SEQUENCE | SEQ 冲突或重复请求不一致 |
| 0x07 | VERIFY_FAILED | 校验失败 |
| 0x08 | IO_ERROR | Flash、外设或链路错误 |
| 0x09 | TIMEOUT | 操作超时 |
| 0x0A | INTERNAL_ERROR | 内部错误 |
除命令另有规定外，非 OK 的最终响应和 ACCEPTED 中间响应都只带一个 Result 字节。
系统命令 · 0x01–0x0F
0x01 Get Info 获取设备信息
请求 PAYLOAD
空
成功响应 PAYLOAD · 19字节
Result(1字节) + ProtocolVersion(1字节) + TargetID(4字节) + HWVersion(2字节) + Mode(1字节) + BootVersion(4字节) + AppVersion(4字节) + MaxPayload(2字节)
ProtocolVersion=1；Mode=0 引导程序，1 应用程序。目标ID 用于固件兼容校验；MaxPayload 包含响应结果字节，范围为 19 至 1024 字节。
0x02 Get UID 获取设备 UID
请求 PAYLOAD
空
成功响应 PAYLOAD · 13字节
Result(1字节) + UID(12字节)
UID 是固定的 12 字节原始数据，不是十六进制文本；引导程序与应用程序返回同一个 UID。
0x03 Reboot 重启设备
请求 PAYLOAD
空
成功响应 PAYLOAD · 1字节
Result(1字节)
先完整发送 OK 响应，再复位；OTA 正在进行时返回 BAD_STATE。
0x04 Enter Boot 进入引导程序
请求 PAYLOAD
空
成功响应 PAYLOAD · 1字节
Result(1字节)
应用程序写入引导程序保持标志，发完 OK 响应后复位进入 Boot；引导程序收到时返回 BAD_STATE。
通用业务命令 · 0x10–0x1F
以下命令由产品按需注册；Boot 与 App 均必须实现上方四条系统命令。未实现的通用业务命令返回 BAD_COMMAND。
0x10 Product SN Read 读取产品序列号
请求 PAYLOAD
空
成功响应 PAYLOAD · 3+N 字节
Result(1字节) + Provisioned(1字节) + SNLength(1字节) + SN(N字节)
未写入时 已写入标志=0、N=0；已写入时 已写入标志=1、N=1..32。SN 只允许 ASCII 大写字母、数字和连字符。
0x11 Product SN Write 写入产品序列号
请求 PAYLOAD · 1+N 字节
SNLength(1字节) + SN(N字节)
成功响应 PAYLOAD · 2+N 字节
Result(1字节) + SNLength(1字节) + SN(N字节)
N=1..32；仅首次写入且具备工厂状态或物理授权。持久化并回读通过后才回复 OK。
0x12 HW Version Read 读取硬件版本
请求 PAYLOAD
空
成功响应 PAYLOAD · 4字节
Result(1字节) + Provisioned(1字节) + HWVersion(2字节)
未写入时 已写入标志=0、硬件版本=0；写入后与“获取设备信息”返回的硬件版本一致。
0x13 HW Version Write 写入硬件版本
请求 PAYLOAD · 2字节
HWVersion(2字节)
成功响应 PAYLOAD · 3字节
Result(1字节) + HWVersion(2字节)
硬件版本不得为 0；默认只允许首次写入且需工厂状态或物理授权。已写入不同值时拒绝。
IAP 升级命令 · 0x20–0x2F
支持升级的型号通过 BEGIN → WRITE → VERIFY → COMMIT 处理完整 IAP2 镜像文件；明文与加密 IAP2 使用同一组命令，设备按自身策略验证镜像。BEGIN、WRITE、VERIFY、COMMIT、ABORT 可能先回 ACCEPTED，再回相同 SEQ 和 CMD 的最终结果。等待最终响应后再发下一条命令。
| CMD | 命令 | 请求 PAYLOAD | 最终成功响应 PAYLOAD |
|---|---|---|---|
0x20 | BEGIN 开始升级 | ImageSize(4字节)，完整 IAP2 文件总长度，含镜像头 | Result(1字节) |
0x21 | WRITE 写入数据 | Offset(4字节) + Data(N字节)，从文件偏移 0 顺序发送；N≥1，4+N≤MaxPayload | Result(1字节) |
0x22 | VERIFY 验证镜像 | 空 | Result(1字节) |
0x23 | COMMIT 提交镜像 | 空 | Result(1字节) |
0x24 | ABORT 中止升级 | 空 | Result(1字节) |
0x25 | STATUS 查询升级状态 | 空 | Result(1字节) + State(1字节) + ImageSize(4字节) + Received(4字节) |
STATUS.State：0 空闲、1 接收中、2 已验证、3 失败、4 已提交；STATUS 直接回最终结果。ImageSize 和 Received 均按字节计，包含镜像头。提交响应丢失时先重发原请求；设备重启后用运行版本确认镜像是否生效。中止后新的升级从 BEGIN、偏移 0 开始。
已出厂设备的协议格式按型号与固件版本确认。
产品通用协议 v1 · 报文与命令。镜像头和授权数据格式由对应产品规定。