edit

氦氪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。
  1. NTP下发帧是由模块下发给MCU,为提供MCU时钟校准服务。
  2. 模块启动后云端登陆成功下发一次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