wuchuyuan
7b7583668b
P1 业务： - 管理：0x16 出厂复位（清配对+时区）、0x18 模组重启、0x1A 通知 MCU 重启（预留） - 对时：网关 DEVICEINFO 下发 Unix 秒+时区，写入 RTC；MCU 0x1C/0x1D 读当前时间 - 版本：UART 0x40 拉 MCU 信息，SOC 0x41 上报网关；网关 ACK 等待 2s，最多 3 次 RTC： - 新增 usr_periph，打开板级 "rtc"；开发板无 32K 用 LRC，量产模组再改 CLK_SEL_32K - 对时补偿 +1s；时区存 VM；出厂复位清除时区；硬件走时，软件只刷新 UTC 缓存 链路与 0x14： - VM paired_flag 仍表示已绑定；CONFIGURED 改为绑定+已连接+CCC，否则保持 RECONNECTING - 0x07/0x41 等 notify 未就绪不发送、不占重试，避免 MCU 过早上报
336 lines
10 KiB
Markdown
336 lines
10 KiB
Markdown
# SOC方案接入通信协议文档
|
||
|
||
# 修订记录
|
||
|
||
|文档版本|协议版本|日期|编写人|修订类型|修订内容|
|
||
|---|---|---|---|---|---|
|
||
|V1\.0\.0|V1\.0|2026\-07\-08|麦田|新建|首次发布SOC方案接入协议通讯文档|
|
||
|
||
---
|
||
|
||
# 协议说明
|
||
|
||
- 数据采用**大端模式**（Big Endian）传输。
|
||
|
||
- 数据帧格式： **包头 \+ 包长度 \+ 命令 \+ 序列号 \+ 数据 \+ 校验和**。
|
||
|
||
- 包头固定为 `0x55AA`。
|
||
|
||
- 包长度表示 **命令开始至校验和结束** 的数据长度。
|
||
|
||
- 命令字（Command）用于区分不同功能。
|
||
|
||
- 序列号（Seq）由请求方递增生成，ACK需原样返回，用于匹配请求与响应。
|
||
|
||
- 默认所有命令采用 **一问一答机制**，发送方发送命令后，接收方必须返回对应 ACK。
|
||
|
||
- ACK 数据包包含 Result 字段，用于返回执行结果。
|
||
|
||
- 超时未收到 ACK 时，发送方可进行重试，最大重试次数建议为 3 次。
|
||
|
||
- 数据点标志（Bitmap）由 DP 配置文档自动生成，一个 Bit 对应一个 DP。
|
||
|
||
- 数据点值按照 Bitmap 中 Bit 置位顺序依次排列。
|
||
|
||
- 读取命令通过 Bitmap 指定需要读取的 DP，Bitmap 全 1 表示读取全部 DP。
|
||
|
||
- BLE 模组主要负责数据透传、蓝牙连接及状态管理，业务数据由 MCU 处理。
|
||
|
||
- 校验方式：累加和校验（Sum Check），计算范围为 **包长度字段至校验和前一个字节**。
|
||
|
||
## Result 定义：
|
||
|
||
|值|含义|
|
||
|---|---|
|
||
|0x00|成功|
|
||
|0x01|参数错误|
|
||
|0x02|设备忙|
|
||
|0x03|不支持该操作|
|
||
|0x04|校验错误|
|
||
|0x05|执行失败|
|
||
|
||
### OTA 专用错误码
|
||
|
||
|值|含义|
|
||
|---|---|
|
||
|0x20|无需升级（版本一致）|
|
||
|0x21|OTA 版本低于当前版本|
|
||
|0x22|Flash 空间不足|
|
||
|0x23|OTA 状态错误|
|
||
|0x24|OTA文件检验失败|
|
||
|0x25|升级失败|
|
||
|
||
# 基本通讯协议
|
||
|
||
## 设备上报版本信息
|
||
|
||
> 设备绑定上网关之后，主动上报固件版本到服务器，此命令通过网关的应答格式判断是否发送成功。。
|
||
>
|
||
>
|
||
|
||
### 设备 =\> 网关
|
||
|
||
|序号|字段名称|字节长度|内容说明|
|
||
|---|---|---|---|
|
||
|1|包头|2|0x55AA|
|
||
|2|包长度|2|len\(命令\.\.\.校验和\)|
|
||
|3|命令|1|0x41|
|
||
|4|序列号|1|与请求的序列号一致|
|
||
|5|Result|1|执行结果（见 Result 定义）|
|
||
|6|BLE Version|3|固件版本号，格式：主版本号\(1Byte\)\+次版本号\(1Byte\)\+修订版本号\(1Byte\)，显示格式为：`Vx.x.x`|
|
||
|7|MCU Version|3|固件版本号，格式：主版本号\(1Byte\)\+次版本号\(1Byte\)\+修订版本号\(1Byte\)，显示格式为：`Vx.x.x`，如MCU不存在则填0|
|
||
|8|Hardware Version|3|硬件版本号，格式：硬件主版本号\(1Byte\)\+硬件次版本号\(1Byte\)\+硬件修订版本号\(1Byte\)，显示格式：`Vx.x.x`|
|
||
|9|校验和|1|和校验（包长度\.\.\.校验和前一个字节）|
|
||
|
||
#### Version版本格式说明
|
||
|
||
|字节|字段名称|内容说明|
|
||
|---|---|---|
|
||
|Byte0|主版本号|产品架构、通信协议等重大变化时递增|
|
||
|Byte1|次版本号|新增功能或功能优化时递增|
|
||
|Byte2|修订版本号|Bug修复、参数调整、性能优化时递增|
|
||
|
||
#### 示例
|
||
|
||
|MCU Version|版本号|
|
||
|---|---|
|
||
|0x01 0x02 0x05|V1\.2\.5|
|
||
|0x05 0x02 0x21|V5\.2\.33|
|
||
|
||
### 网关 =\> 设备
|
||
|
||
通过网关的应答格式判断是否发送成功
|
||
|
||
## APP控制设备
|
||
|
||
### APP =\> 设备
|
||
|
||
|序号|字段名称|字节长度|内容说明|
|
||
|---|---|---|---|
|
||
|1|包头|2|0x55AA|
|
||
|2|包长度|2|len\(命令\.\.\.校验和\)|
|
||
|3|命令|1|0x03（下发控制）|
|
||
|4|序列号|1|APP递增生成，ACK原样回传|
|
||
|5|数据点标志|x（\(DP数量\+7\)/8）|一个字节可代表8个数据点|
|
||
|6|数据点值|x|数据值|
|
||
|7|校验和|1|和校验（包长度\.\.\.校验和前一个字节）|
|
||
|
||
### 设备 =\> APP
|
||
|
||
|序号|字段名称|字节长度|内容说明|
|
||
|---|---|---|---|
|
||
|1|包头|2|0x55AA|
|
||
|2|包长度|2|len\(命令\.\.\.校验和\)|
|
||
|3|命令|1|0x04（应答下发控制）|
|
||
|4|序列号|1|与请求的序列号一致|
|
||
|5|Result|1|执行结果（见 Result 定义）|
|
||
|6|校验和|1|和校验（包长度\.\.\.校验和前一个字节）|
|
||
|
||
---
|
||
|
||
## APP读取设备
|
||
|
||
### APP =\> 设备
|
||
|
||
|序号|字段名称|字节长度|内容说明|
|
||
|---|---|---|---|
|
||
|1|包头|2|0x55AA|
|
||
|2|包长度|2|len\(命令\.\.\.校验和\)|
|
||
|3|命令|1|0x05（下发读取）|
|
||
|4|序列号|1|APP递增生成，ACK原样回传|
|
||
|5|数据点标志|x（\(DP数量\+7\)/8）|指定需要读取的 DP，Bitmap 全 1 表示读取全部 DP|
|
||
|6|校验和|1|和校验（包长度\.\.\.校验和前一个字节）|
|
||
|
||
### 设备=\> APP
|
||
|
||
|序号|字段名称|字节长度|内容说明|
|
||
|---|---|---|---|
|
||
|1|包头|2|0x55AA|
|
||
|2|包长度|2|len\(命令\.\.\.校验和\)|
|
||
|3|命令|1|0x06（应答读取）|
|
||
|4|序列号|1|与请求的序列号一致|
|
||
|5|数据点标志|x（\(DP数量\+7\)/8）|返回的数据点标志|
|
||
|6|数据点值|x|数据值|
|
||
|7|校验和|1|和校验（包长度\.\.\.校验和前一个字节）|
|
||
|
||
---
|
||
|
||
## 设备主动上报数据
|
||
|
||
此命令直接上报到服务器，通过网关的应答格式判断是否发送成功。
|
||
|
||
### 设备 =\> APP/IPC
|
||
|
||
|序号|字段名称|字节长度|内容说明|
|
||
|---|---|---|---|
|
||
|1|包头|2|0x55AA|
|
||
|2|包长度|2|len\(命令\.\.\.校验和\)|
|
||
|3|命令|1|0x07（主动上报）|
|
||
|4|序列号|1|设备递增生成|
|
||
|5|数据点标志|x（\(DP数量\+7\)/8）|一个字节可代表8个数据点|
|
||
|6|数据点值|x|数据值|
|
||
|7|校验和|1|和校验（包长度\.\.\.校验和前一个字节）|
|
||
|
||
### APP/IPC =\> 设备
|
||
|
||
通过网关的应答格式判断是否发送成功
|
||
|
||
---
|
||
|
||
# 扩展通讯协议
|
||
|
||
## APP向设备推送OTA升级
|
||
|
||
> **功能说明：**
|
||
APP 将与设备升级相关的信息发送给设备，设备根据这些信息判断是否允许OTA升级，并返回升级准备结果。
|
||
|
||
### APP =\> 设备
|
||
|
||
|序号|字段名称|字节长度|内容说明|
|
||
|---|---|---|---|
|
||
|1|包头|2|固定 `0x55AA`|
|
||
|2|包长度|2|len\(命令\.\.\.校验和\)|
|
||
|3|命令|1|0x30|
|
||
|4|序列号|1|数据包序列号|
|
||
|5|固件类型（Type）|1|0x01：MCU<br>0x02：BLE|
|
||
|6|固件版本（Firmware Version）|3|OTA 固件版本号|
|
||
|7|固件长度（Payload Length）|4|OTA Bin 数据长度|
|
||
|8|固件 CRC32（Payload CRC32）|4|OTA Bin 数据 CRC32 校验值|
|
||
|9|校验和|1|和校验（包长度\.\.\.校验和前一个字节）|
|
||
|
||
### 设备 =\> APP
|
||
|
||
|序号|字段名称|字节长度|内容说明|
|
||
|---|---|---|---|
|
||
|1|包头|2|固定 `0x55AA`|
|
||
|2|包长度|2|`len(命令...校验和)`|
|
||
|3|命令|1|0x31|
|
||
|4|序列号|1|与请求保持一致|
|
||
|5|Result|1|执行结果（见 Result OTA 专用错误码定义）|
|
||
|6|Max Data Length|2|设备 单次允许接收的最大 Payload 长度（Byte）|
|
||
|7|校验和|1|和校验（包长度\.\.\.校验和前一个字节）|
|
||
|
||
---
|
||
|
||
## APP向设备推送OTA数据
|
||
|
||
> **功能说明：**
|
||
APP 根据 设备 返回的 **Max Data Length** 对 OTA Bin 进行分片，并按顺序发送给设备。
|
||
设备 每接收一包数据后立即返回应答，APP 收到成功应答后继续发送下一包。
|
||
|
||
### APP =\> 设备
|
||
|
||
|序号|字段名称|字节长度|内容说明|
|
||
|---|---|---|---|
|
||
|1|包头|2|固定 `0x55AA`|
|
||
|2|包长度|2|`len(命令...校验和)`|
|
||
|3|命令|1|0x32|
|
||
|4|序列号|1|数据包序列号|
|
||
|5|分片序号|2|当前数据包的分片序号，分片序号从1开始计算|
|
||
|6|总分片数|2||
|
||
|7|Payload Data|x|OTA Bin 数据，长度 ≤ Max Data Length|
|
||
|8|校验和|1|和校验（包长度\.\.\.校验和前一个字节）|
|
||
|
||
### 设备 =\> APP
|
||
|
||
> **功能说明：**
|
||
设备 成功接收并处理当前 OTA 数据包后返回 Result。
|
||
APP收到成功应答后继续发送下一包 OTA 数据；若返回失败，则停止本次 OTA 升级。
|
||
|
||
|序号|字段名称|字节长度|内容说明|
|
||
|---|---|---|---|
|
||
|1|包头|2|固定 `0x55AA`|
|
||
|2|包长度|2|`len(命令...校验和)`|
|
||
|3|命令|1|0x33|
|
||
|4|序列号|1|与请求保持一致|
|
||
|5|Result|1|执行结果（见 Result 定义）|
|
||
|6|校验和|1|和校验（包长度\.\.\.校验和前一个字节）|
|
||
|
||
## 设备通知APP模组OTA升级完成
|
||
|
||
> **功能说明：
|
||
** 设备完成OTA升级后，主动通知APP当前升级结果及固件版本信息。
|
||
|
||
### 设备 =\> APP
|
||
|
||
|序号|字段名称|字节长度|内容说明|
|
||
|---|---|---|---|
|
||
|1|包头|2|固定 `0x55AA`|
|
||
|2|包长度|2|`len(命令...校验和)`|
|
||
|3|命令|1|0x34|
|
||
|4|序列号|1|数据包序列号|
|
||
|5|类型（Type）|1|0x01：MCU<br>0x02：BLE|
|
||
|6|OTA Result|1|OTA结果|
|
||
|7|Firmware Version|3|当前固件版本|
|
||
|8|校验和|1|和校验（包长度\.\.\.校验和前一个字节）|
|
||
|
||
### APP =\> 设备
|
||
|
||
|序号|字段名称|字节长度|内容说明|
|
||
|---|---|---|---|
|
||
|1|包头|2|固定 `0x55AA`|
|
||
|2|包长度|2|`len(命令...校验和)`|
|
||
|3|命令|1|0x35|
|
||
|4|序列号|1|与请求保持一致|
|
||
|5|Result|1|执行结果（见 Result 定义）|
|
||
|6|校验和|1|和校验（包长度\.\.\.校验和前一个字节）|
|
||
|
||
---
|
||
|
||
## APP向设备通知OTA停止
|
||
|
||
> **功能说明：**
|
||
APP 主动通知设备终止当前 OTA 升级流程。设备收到后立即停止 OTA 数据接收，释放 OTA 相关资源，并返回处理结果。
|
||
|
||
### APP =\> 设备
|
||
|
||
|序号|字段名称|字节长度|内容说明|
|
||
|---|---|---|---|
|
||
|1|包头|2|固定 `0x55AA`|
|
||
|2|包长度|2|`len(命令...校验和)`|
|
||
|3|命令|1|0x36|
|
||
|4|序列号|1|数据包序列号|
|
||
|5|校验和|1|和校验（包长度\.\.\.校验和前一个字节）|
|
||
|
||
### 设备 =\> APP
|
||
|
||
|序号|字段名称|字节长度|内容说明|
|
||
|---|---|---|---|
|
||
|1|包头|2|固定 `0x55AA`|
|
||
|2|包长度|2|`len(命令...校验和)`|
|
||
|3|命令|1|0x37|
|
||
|4|序列号|1|与请求保持一致|
|
||
|5|Result|1|执行结果（见 Result 定义）|
|
||
|6|校验和|1|和校验（包长度\.\.\.校验和前一个字节）|
|
||
|
||
---
|
||
|
||
## 设备向APP通知OTA停止
|
||
|
||
> **功能说明：**
|
||
设备在 OTA 过程中因内部异常无法继续升级时，主动通知 APP 停止当前 OTA。APP 收到通知后立即停止发送 OTA 数据，并返回应答。
|
||
|
||
### 设备 =\> APP
|
||
|
||
|序号|字段名称|字节长度|内容说明|
|
||
|---|---|---|---|
|
||
|1|包头|2|固定 `0x55AA`|
|
||
|2|包长度|2|`len(命令...校验和)`|
|
||
|3|命令|1|0x38|
|
||
|4|序列号|1|数据包序列号|
|
||
|5|校验和|1|和校验（包长度\.\.\.校验和前一个字节）|
|
||
|
||
### APP =\> 设备
|
||
|
||
|序号|字段名称|字节长度|内容说明|
|
||
|---|---|---|---|
|
||
|1|包头|2|固定 `0x55AA`|
|
||
|2|包长度|2|`len(命令...校验和)`|
|
||
|3|命令|1|0x39|
|
||
|4|序列号|1|与通知保持一致|
|
||
|5|Result|1|`0x00`：已收到并停止 OTA|
|
||
|6|校验和|1|和校验（包长度\.\.\.校验和前一个字节）|
|
||
|
||
|
||
|