# 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
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
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|和校验（包长度\.\.\.校验和前一个字节）|