氦氪HEKR模块串口透传协议
v1.1.4 by zejun.zhao@hekr.me 2016/4/21 14:05:31
关键词
-
模块(MODULE)： 由氦氪提供的WiFi通信模块，简称模块或WiFi模块
-
设备(DEVICE)：指设备等厂商的设备,例如热水器
-
帧间隔时间：MCU串口连续发送数据帧时两帧之间的间隔时间
-
模块启动时间：Wi-Fi模块上电至正常连接到云端的时间
1.基本帧格式
-
帧头 (1B)：帧起始标识，指定为
H或十六进制0x48； -
帧长 (1B)：整帧内容（包括帧头、帧长、校验码等）的字节个数，取值：
[0x06,0xFE]； -
帧类型 (1B)：识别该帧类型，取值见“附录-帧类型列表”；
-
帧序号 (1B)：取值
[0x00,0xFF]，循环累加，标识顺序，返回帧中填入相同值； -
有效数据 (nB)：实际通信内容。根据不同业务分别说明；
-
校验码 (1B)：整帧内容（包括帧头、帧长等）的数据和，超过0XFF取低8位（1B）。
2.流程说明
本小节定义模块与设备之间通信流程及其对应的帧类型码（取值见附1），主要包括设备状态主动上报、模块数据下发、模块状态查询等流程。具体如下：
2.1设备主动上报流程
设备定时（如1分钟）或 在自身状态发生变化时向WiFi主动发起上报。
2.2模块数据下发流程
若设备状态发生改变，还需发送主动上报帧,参考
2.1 设备主动上报流程。
2.3默认应答方式
对于需要应答流程但未说明的应答帧内容的情况，采用默认应答方式。默认应答帧与接收帧保持一致。例如设备主动上报流程整中，Wi-Fi模块对设备的应答与设备上传的帧内容保持一致。
3.设备相关协议
- 设备协议是指WIFI模块与厂家设备之间通信的业务协议，包含具体的查询控制命令，控制命令下发帧类型为
0x02。
-
本协议基本原则是尽可能在一帧中表达所有业务，基本格式为【命令+所有对应属性】，相关命令则调用相对应属性。
-
为了精简文档，本小节仅说明基本帧格式中
有效数据部分，其他帧头等部分参考基本帧格式。以智能照明为例进行定义说明。
3.1智能照明
有效数据格式及取值表
示例帧
打开灯具
序号：#1 #2 #3 #4 #5 #6 #7 #8 #9#10#11#12#13 #14
发送：48 0E 02 01 02 01 00 00 00 00 00 00 00 5C
应答：48 0E 02 01 02 01 00 00 00 00 00 00 00 5C
关闭灯具
序号：#1 #2 #3 #4 #5 #6 #7 #8 #9#10#11#12#13 #14
发送：48 0E 02 01 02 02 00 00 00 00 00 00 00 5D
应答：48 0E 02 01 02 02 00 00 00 00 00 00 00 5D
注意：当设备状态发生改变（包括APP发送控制指令导致的状态改变），务必需要通过主动上报帧上报当前所有状态！帧类型为
0x01,命令为0x00。
4.模块相关协议
本小节定义模块操作相关部分内容，例如Wi-Fi模块状态查询、重启Wi-Fi模块等。对应基本帧格式中有效数据部分。帧类型为0xFE。
4.1模块操作命令
模块操作命令发送帧有效数据格式为命令+保留，命令码值取值如下：
操作成功模块返回命令码+0x00；失败则按错误帧类型返回。
4.2模块查询命令
模块状态查询帧
模块状态查询应答帧
模块状态查询示例帧
设备发送：48 07 FE 01 01 00 4F
模块应答：48 0B FE 01 01 01 01 01 05 00 5B
含义：模块工作在STA模式、连接路由器正常、连接云端正常、路由信号最强
另外，当模块状态改变，会主动发送状态帧到设备，格式与查询状态返回格式一致。
4.3设置命令
厂测模式设置帧
厂测模式设置示例帧
设备发送：48 07 FE 01 20 01 6F
模块应答：48 07 FE 01 20 01 6F
含义：模块启用厂测模式
5.错误应答
错误帧格式
附录
附1帧类型取值表
| 码值 | 含义 | 备注 |
|---|---|---|
| 0x01 | 设备数据主动上报帧 | 模块应答时帧类型与帧序号保持一致 |
| 0x02 | 模块数据下发帧 | 设备应答时帧类型与帧序号保持一致 |
| 0xFE | 模块操作相关帧 | 对Wi-Fi模块的操作，例如复位 |
| 0xFF | 错误帧 | 无 |
附2错误码取值表
| 码值 | 含义 | 备注 |
|---|---|---|
| 0x01 | 操作错误(失败) | 无 |
| 0x02 | 校验码错误 | 无 |
| 0x03 | 数据范围错误 | 无 |
| 0x04 | 命令不支持 | 无 |
附3命令字段特殊保留值
命令字段对应设备相关协议中#5字段
| 码值 | 含义 | 备注 |
|---|---|---|
| 0xC0 | 云端历史数据存储 | 无 |
| 0xC1 | 告警消息实时推送 | 通过该命令上报的消息，在APP关闭状态下仍可收到 |
附4透传性能参数表
对应氦氪V1.1Wi-Fi模块3.x版本固件（ESP8266）
| 参数项 | 取值 | 备注 |
|---|---|---|
| 帧间隔时间 | 取值建议大于100ms | MCU串口连续发送数据帧时两帧之间的间隔时间 |
| 模块启动时间 | 正常情况下小于5s | Wi-Fi模块上电至正常连接到云端的时间 |
| HekrConfig超时时间 | 5分钟 | Wi-Fi模块一键配网超时时间，超时后进入软AP模式 |