氦氪HEKR模块串口透传协议¶

关键词¶

模块(MODULE)：由氦氪提供的Wi-Fi通信模块，简称模块或Wi-Fi模块
设备(DEVICE)：指设备等厂商的设备,例如热水器
帧间隔时间：MCU串口连续发送数据帧给模块时两帧之间的间隔时间
模块启动时间：Wi-Fi模块上电至正常连接到云端的时间

1. 基本帧格式¶

帧头 (1B)：帧起始标识，指定为H或十六进制0x48；
帧长 (1B)：整帧内容（包括帧头、帧长、校验码等）的字节个数，取值：[0x06,0xFE]；
帧类型 (1B)：识别该帧类型，取值见“附录-帧类型列表”；
帧序号 (1B)：取值[0x00,0xFF]，循环累加，标识顺序，返回帧中填入相同值；
有效数据 (nB)：实际通信内容。根据不同业务分别说明；
校验码 (1B)：整帧内容（包括帧头、帧长等）的数据和，超过0XFF取低8位（1B）。

帧类型表¶

| 码值 | 含义 | 传输方向 | 应答方与应答帧格式 | 备注 | |:------------- |:---------- |:----------------- |:-----| | 0x01 | 设备上报帧 | 设备——>模块-->APP | 模块、原帧返回 | | | 0x02 | 模块下发帧 | APP-->模块——>设备 | 设备、原帧返回 | | | 0xFE | 模块操作帧 | 设备——>模块 | 模块、取决于帧命令 | | | 0xFF | 错误帧 | 模块<——>设备 | 无 | |

注：为简化交互流程，本文档中的描述弱化云端节点，将模块<——>云端<——>APP改述为模块<——>APP。

2. 设备上报帧¶

此类帧应用于设备数据主动上报给APP，供APP端实时监控设备状态。

2.1 设备上报流程¶

1.设备定时（如1分钟）或在自身状态发生变化时向Wi-Fi模块主动发起上报。
2.设备主动上报频率（即帧间隔时间）不能低于200ms，否则可能造成丢帧。

模块应答¶

模块接收到设备上报帧后会对帧格式校验，校验无误返回原帧作为应答，否则应答错误帧。错误类型请参考附1. 错误码表

3. 模块下发帧¶

此类帧应用于APP主动发送控制设备的指令，数据帧是经由模块下发至设备MCU。

3.1 模块下发流程¶

设备应答¶

模块将来自APP的数据帧下发后会等待设备MCU返回应答帧，超时时间为3s；MCU须在超时时间内进行应答，原帧返回即可。

设备进行应答后若设备状态发生改变，还需发送一帧设备上报帧,上报设备当前状态。参考2.1 设备主动上报流程。

3.2 下发帧协议示例¶

产品协议由厂商设备自定义的通信业务协议，由下发帧和上报帧构成。
在下发帧协议中，基本原则是尽可能在一帧中表达所有业务，基本格式为【命令+所有对应属性】，相关命令则调用相对应属性。
为了精简文档，本小节仅说明基本帧格式中有效数据部分，其他帧头等部分参考基本帧格式。以智能照明灯为例进行定义说明。

智能照明¶

有效数据格式及取值表¶

示例帧¶

打开灯具

序号：#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发送控制指令导致的状态改变），务必需要通过主动上报帧上报当前所有状态！主动上报帧格式及内容可登录console平台查询。

4. 模块操作帧¶

本小节定义模块操作相关部分内容，例如Wi-Fi模块状态查询、重启Wi-Fi模块等。对应基本帧格式中有效数据部分。帧类型为0xFE。

模块操作命令发送帧有效数据格式为命令+保留，命令码值取值如下：

操作成功模块返回命令码+0x00；失败则按错误帧类型返回。

4.1 模块查询命令¶

模块状态查询帧¶

模块状态查询应答帧¶

模块状态查询示例帧¶

    设备发送：48 07 FE 01 01 00 4F
    模块应答：48 0B FE 01 01 01 01 01 05 00 5B
    含义：模块工作在STA模式、连接路由器正常、连接云端正常、路由信号最强

另外，当模块状态改变，会主动发送状态帧到设备，格式与查询状态返回格式一致。

模块版本查询帧¶

模块版本查询应答帧¶

模块版本查询示例帧¶

    设备发送：48 07 FE 01 10 00 5E
    模块应答：48 0B FE 01 10 04 01 0F 01 01 78
    含义：模块版本号为4.1.15.1，且固件运行在A区。

对于8266来说，固件运行区分为A和B，#10来表示；而对于其他硬件平台，则不区分，#10为00

4.2 模块厂测模式设置命令¶

厂测模式设置帧¶

厂测模式设置示例帧¶

    设备发送：48 07 FE 01 20 00 6E
    模块应答：48 07 FE 01 20 00 6E
    含义：模块启用厂测模式

4.3 ProdKey操作命令¶

ProdKey是产品唯一标识码，由开发者在氦氪console平台上添加产品时自动生成，字符串度为32Byte.

ProdKey用于区分不同产品型号，通常由厂测软件写入模块。也可由设备MCU通过串口指令来设置，以MCU设置的优先。

4.3.1 ProdKey设置¶

产品秘钥ProdKey设置帧¶

产品秘钥ProdKey设置过程示例¶

1.登录氦氪console平台并且点击进入“产品管理”界面。如果产品管理列表中已有氦氪项目部为您创建的产品，可点击对应产品图标右上角的“查看产品信息”，在基本信息栏中查看产品秘钥（ProdKey）。

2.获取的ProdKey为32Byte的字符串，例如：0136a66c12754ee82fff8804b7faa53c

3.根据产品秘钥ProdKey设置帧格式将获取的ProdKey字符串转换为对应的ProdKey设置帧。转换后的示例帧如下：

    设备发送：48 16 FE 01 21 01 36 A6 6C 12 75 4E E8 2F FF 88 04 B7 FA A5 3C D0
    模块应答：48 16 FE 01 21 01 36 A6 6C 12 75 4E E8 2F FF 88 04 B7 FA A5 3C D0

4.如果产品管理列表中暂时没有产品，可直接使用上述示例帧进行产品秘钥设置进入体验页面。

4.3.2 ProdKey查询¶

考虑到ProdKey的安全性，模块不支持直接查询，而是带ProdKey查询、模块返回是否匹配，所以开发者只能使用已知的PK去查询与模块中的ProdKey是否匹配。具体格式如下：

    设备发送：48 16 FE 01 11 01 F7 51 A4 E9 ED B7 09 69 08 20 D5 4A 54 64 D5 2E
    模块应答：48 07 FE 01 11 01 60
    含义：模块应答帧中#6字节0x01表示匹配正确，如果是0x00则表示匹配失败。

4.4 NTP下发¶

NTP时间下发帧¶

    示例：48 0D FE 01 40 75 01 1B 12 04 10 01 4C
    说明：year值是从1900年起算，mon值是0表示一月。当前时间为2017-02-27 18:04:10 周一。
    注：周日表示为00。

NTP下发帧是由模块下发给MCU，为提供MCU时钟校准服务。
模块启动后云端登陆成功下发一次NTP，之后每隔一小时下发一次。

5. 错误帧¶

错误帧格式¶

设备发送给模块的帧包括0x01设备上报帧和0xFE模块操作帧，如果模块应答错误帧，则说明发送帧有问题，如帧校验错误、操作帧中的帧命令不支持等。

附1. 错误码表¶

错误码	含义	备注
0x01	操作错误(失败)	无
0x02	校验码错误	无
0x03	数据范围错误	无
0x04	命令不支持	无
0x05	上报帧数据与后台协议数据不一致	无

附2. 透传性能参数表¶

对应氦氪 V1.1 Wi-Fi模块 4.x版本固件（ESP8266）

参数项	取值	备注
模块启动时间	正常情况下小于5s	Wi-Fi模块上电至正常连接到云端的时间
HekrConfig超时时间	5分钟	Wi-Fi模块一键配置模式超时时间

修改时间：2016/11/3 16:24:13