Skip to content

氦氪云一体化方案——对接文档

本文档向MCU工程师介绍氦氪Wi-Fi透传模块的基本概念、通信方式及开发方法，具体文档内容分布如下：

1.Wi-Fi模块硬件参数

请参考氦氪模块硬件说明文档，该文档中对以下硬件功能进行了说明：

1.模块硬件规格、引脚定义及电气参数
2.Wi-Fi天线布局注意事项
3.模块扩展注意事项

2.基础概念介绍

此部分文档用于说明Wi-Fi模块透传工作模式的基础概念，MCU工程师在开发前应熟悉此部分内容。

2.1 产品秘钥（prodKey）写入

产品秘钥prodKey是产品唯一标识码，关联了产品功能协议与产品描述信息，由开发者在氦氪产品后台上添加产品时自动生成，字符串长度为32Byte，查看方式如下图所示。 prodKey通常由设备MCU在通电启动后通过串口指令进行设置，且必须进行设置，详细设置指令请见3.2.3。

2.2 整机出厂测试

氦氪Wi-Fi模块提供了整机出厂测试的功能，用于整机出厂时测试模块的Wi-Fi连通性、串口通讯功能是否正常。

设备MCU可以有两种方式进入到整机出厂测试流程：

  1. 设备MCU通过Wi-Fi模块的初始化后主动发送的模块状态帧中#10位结果判断，如Wi-Fi模块在上电初始化的过程中扫描到存在SSID（路由器账号）为HEKR_PRODUCT_TEST的路由器，#10位结果为1则进入整机出厂测试流程，#10位结果为0，则说明模块Wi-Fi连通性不正常，详见3.7；
  2. 设备MCU定义进入整机出厂测试的物理操作方式以及测试结果的显示方式，在产线测试阶段由测试人员操作并判断测试结果。

设备MCU通过Wi-Fi模块整机出厂测试流程中模块状态返回帧#10位为1的结果，则应通过整机的特定响应动作（显示屏显示结果、指示灯显示、蜂鸣器提示、多次开关动作等）表示出厂测试通过，详细查询指令与注意事项请见3.7。 Wi-Fi固件4.1版本及以上扫描的SSID为HEKR_TEST_V4。

2.3 配网模式

设备MCU必须设计有允许用户使模块进入一键配网模式的物理操作方式，有如下两种方式：

  1. 通过拉低Wi-Fi模块的GPIO13（SCK）引脚5秒，可使模块进入一键配网模式；
  2. 通过设备的物理操作（例如长按设备按键5秒、设备组合键操作等），触发设备MCU向发送一键配网模式命令帧，使模块进入一键配网模式，详细设置指令请见3.2.2。

氦氪Wi-Fi模块提供了两种方式配网模式：HEKR-Config模式和兼容模式。

HEKR-Config模式(一键配网模式)

HEKR-Config模式就是手机App端发送包含Wi-Fi名称、Wi-Fi密码、Pincode的UDP广播包或者组播包，Wi-Fi模块接收到该UDP包后连接该Wi-Fi网络，并完成设备与账号的绑定。

兼容模式（AP模式）

HEKR-Config模式配网失败后可尝试使用兼容模式配网，Wi-Fi模块在HEKR-Config模式超过2分钟后将自动进入兼容模式，保证设备配网成功率。 兼容模式是在手机App直接连接Wi-Fi模块AP热点（SmartDevice－XXXX），用户在手机App上选择将连接的Wi-Fi、输入密码，手机App将Wi-Fi信息直接告知模块，使Wi-Fi模块可以连接此Wi-Fi网络并完成设备与账号的绑定。

2.4 模块指示灯状态

模块状态 指示灯状态 备注
HEKR-Config模式 一秒亮一秒灭 模块进入一键配网模式
兼容模式 两秒亮两秒灭 模块进入兼容配网模式
连接路由器状态 间隔100毫秒快闪 模块正在连接Wi-Fi路由器，即未连接上或断开Wi-Fi
连接云端状态 间隔1秒亮100毫秒 模块正在连接云端服务器，即未连接云端或断开网络
正常联网状态 间隔5秒亮100毫秒 模块正常联网工作

注：上表中的指示灯是指模块板载的红色 LED 灯，同时为支持用户扩展，将 GPIO14（SDA）作为 Wi-Fi 状态指示灯外接引脚，便于用户外接 LED，其电平状态与板载 LED 指示灯保持同步。 设备如果有显示屏可以显示Wi-Fi信号强度，可通过串口查询Wi-Fi模块状态帧来获取Wi-Fi状态、信号强度等数据进行显示。

2.5 串口透传模式介绍

通讯链路图

此文档只用于说明Device（设备）部分的通讯功能，即设备MCU与Wi-Fi模块之间的串口通讯功能。 Wi-Fi透传模块与Cloud（云端）、User（App）之间的通讯链路均已由氦氪实现，设备厂家不需要考虑此链路部分功能。

Device 包括氦氪Wi-Fi透传模块和设备MCU。 氦氪Wi-Fi透传模块实现与氦氪云端的连接与通讯功能；设备MCU实现产品自身功能。 两者之间通过氦氪自主定义的串口透传协议进行数据通讯，串口默认参数配置为：9600-8-N-1。

3.串口透传协议使用说明

串口透传协议完成文档: 链接地址

3.1 串口透传介绍

基本帧格式

  • 帧头 (1B)：帧起始标识，固定为0x48（十六进制）；
  • 帧长 (1B)：整帧内容（包括帧头、帧长、校验码等）的字节个数，取值：[0x06,0xFF]；
  • 帧类型 (1B)：识别该帧类型，取值见“帧类型表”；
  • 帧序号 (1B)：取值[0x00,0xFF]，循环累加，标识顺序，返回帧中填入相同值；
  • （4+n）有效数据 (nB)：可变内容，根据产品协议确定；
  • （5+n）校验码 (1B)：校验码之前所有字节的数据和，超过0XFF取低8位（1B）

注：设备MCU与模块是通过串口进行通信，串口默认参数配置为：9600-8-N-1。

常用帧类型表

码值 含义 传输方向 应答方与应答帧格式 应用
0x01 设备上报帧 设备-->模块-->云端-->APP 模块、原帧返回 设备状态上报至APP
0x02 模块下发帧 APP—>云端-->模块-->设备 设备、原帧返回 APP下发数据至设备
0xFE 模块操作帧 设备-->模块 模块、取决于帧命令 设备对模块控制操作
0xFF 错误帧 模块<-->设备 对发送帧校验错误时的返回

注：MCU有可能会接收到连续帧的情况，单片机工程师可以根据帧头和帧长对连续帧进行拆帧处理。
具体拆帧方法如下：

  1. 在一段数据中先找帧头0x48；
  2. 帧头后一个字节即为帧长，根据帧长截取相应长度的字节数，定为一帧；
  3. 接着继续找帧头，并根据帧长确定下一帧，以此类推，直到最后一个字节。

提示：一般连续帧出现在MCU发送进入一键配置模式帧后，MCU会连续接收到应答帧及因模块状态改变时主动发送的模块状态帧。

3.2 模块操作帧

注：MCU对Wi-Fi模块的常用操作指令如上图所示 此部分功能只涉及对模块的操作，不涉及与云端、App的通讯。

3.2.1模块状态查询

模块状态查询命令帧

模块应答帧（模块状态帧）

设备发送：48 07 FE 01 01 00 4F  
模块应答：48 0B FE 01 01 01 01 01 05 00 5B  
应答帧说明：模块工作在STA模式、连接路由器正常、连接云端正常、路由信号最强  
提示：可根据信号强度显示控制面板的Wi-Fi图标

四类模块常见状态：

  • 模块连网成功时：#6为01（正常工作模式）、#7为01（路由器连接正常）、#8为01（云端连接正常）
  • 模块进入一键配网模式时：#6为02（一键配网模式）
  • 模块未连接云端时：#6为01（正常工作模式）、#8不为01（云端连接异常）
  • 模块未连接路由器时：#6为01（正常工作模式）、#7不为01（路由器连接异常）

注：当模块状态改变，模块会主动发送模块状态帧到MCU，格式与模块状态帧格式一致。因此，MCU无需定时发送模块状态查询帧。

以下事件会造成模块状态改变，并主动发送模块状态帧：

  1. 模块进入一键配置模式
  2. 模块连接上路由器
  3. 模块登录上云端
  4. 模块与云端连接断开
  5. 模块断开路由器
  6. 模块初始化启动

3.2.2模块进入HEKR-Config模式操作

模块进入一键配网模式命令帧

模块应答帧（原帧应答）

设备发送：48 07 FE 01 03 00 51
模块应答：48 07 FE 01 03 00 51
应答帧说明：模块进入一键配网模式（原帧应答）。

注：模块进入一键配网模式后，会立马主动发送一条模块状态帧 48 0B FE 00 01 02 02 02 00 00 58

3.2.3模块设置产品秘钥操作

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
应答帧说明：模块prodKey写入成功（原帧应答）。

注：prodKey是产品唯一标识码，由开发者在氦氪Console平台上添加产品时自动生成，字符串长度为32Byte。需要将获取的prodKey字符串转换为对应的prodKey设置帧格式。如prodKey为“0136a66c12754ee82fff8804b7faa53c”，转换后的完整设置帧为：48 16 FE 01 21 01 36 A6 6C 12 75 4E E8 2F FF 88 04 B7 FA A5 3C D0 Wi-Fi模块原帧应答代表prodKey已写入成功。

3.3 NTP时间校准

NTP时间下发帧是由Wi-Fi模块下发给MCU，为MCU提供时钟校准服务。 模块启动且登录云端后将主动下发一次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。

注：Wi-Fi模块发送的NTP时间为东八区时间（北京时间）。 如果产品是出口使用在其他时区，则应在设备上增加时区偏移设置的功能，以满足用户调节设备显示当地时间。

3.4 错误帧

错误帧指的是模块在MCU的发送帧有误或执行不成功时进行错误应答的帧。单片机工程师可以根据应答的错误类型判别MCU的发送帧的错误。

示例：48 07 FF 01 02 00 51
说明：错误帧代表末位校验码错误。

注：数据范围错误仅对模块操作帧有效

3.5 产品功能协议

产品功能协议在氦氪产品后台的产品功能定义中编辑，编辑完成后点击下图“协议文档”链接可查看产品功能协议。

设备MCU主动上报帧：

上报帧使用规范

  • 上报帧格式：请参考Console产品协议中上报帧对应的示例帧。
  • 上报参数范围：需要在产品协议定义的取值范围内，比如产品协议中参数温度的取值范围为0~60℃，如果上报帧中温度值不在此范围内，则上报不成功，App将无法接收到该帧。
  • 模块应答：上报帧发送给模块后，模块会原帧返回作为应答（如果发送帧有误，则模块应答错误帧）。
  • App实时显示设备状态：App端支持间隔30S下发查询帧查看设备状态。温度数值等自身状态快速变化的无需主动上报。
  • 设备定时上报：主要用于历史统计等功能，请按照HEKR项目经理建议设置定时上报（最短间隔5分钟），不支持实时或间隔小于5分钟的定时上报，否则会影响页面操作及正常使用。
  • 帧间隔时间：必须大于200ms，否则模块接收处理时可能造成丢帧。帧间隔时间适用于所有帧类型。

Wi-Fi模块下发帧：

下发帧使用规范

  • 模块将来自App的数据帧下发后会等待设备MCU返回应答帧，超时时间为3s；MCU须在超时时间内进行原帧应答。
  • 如果下发帧出现错误，设备不应答即可，App上会自动提示响应超时，请重试。
  • MCU应答后，如有设备状态变化则还需上报一帧设备状态上报帧。

3.6 成品出厂测试

厂家操作流程包括成品出厂测试、prodKey写入模块及其他业务逻辑处理。厂家的MCU程序可以按照以下流程进行编程：

模块状态帧#10位为Wi-Fi连通性测试标志位

测试说明

  • 测试目的：厂家在装机嵌入模块时可能会经过高温炉、磕碰等外界因素对模块造成损坏，为了在装机后能发现这类问题，模块需要进行模块Wi-Fi连通性测试。

  • 设备MCU可以有两种方式进入到整机出厂测试流程：

    1. 设备MCU通过Wi-Fi模块的初始化后主动发送的模块状态帧中#10位结果判断，如Wi-Fi模块在上电初始化的过程中扫描到存在SSID（路由器账号）为HEKR_PRODUCT_TEST的路由器，#10位结果为1则进入整机出厂测试流程，#10位结果为0，则说明模块Wi-Fi连通性不正常；
    2. 设备MCU定义进入整机出厂测试的物理操作方式以及测试结果的显示方式，在产线测试阶段由测试人员操作并判断测试结果。

  • 整机出厂测试流程：

    1. 设备MCU发送模块状态查询帧。
    2. 设备MCU接收模块状态应答帧。
    3. 设备MCU解析模块状态应答帧。

测试结果

  1. 结果一：如果当前环境下存在此SSID并扫描到，此时模块状态应答帧保留位（即#10）为0x01，表示扫描到SSID为HEKR_PRODUCT_TEST的路由器，则说明模块Wi-Fi功能正常，可以用指示灯表示测试通过；
  2. 结果二：如果当前环境下存在此SSID但未扫描到，此时模块状态应答帧保留位（即#10）为0x00，表示未扫描到SSID为HEKR_PRODUCT_TEST的路由器，则说明模块Wi-Fi连通性不正常。
  3. 结果三：如果设备MCU未正确收到模块返回的状态帧，表示串口功能异常或模块未正常工作。


注意事项

  • 建议每台设备在出厂前都经过成品出厂测试流程，保证设备Wi-Fi通讯部分功能的良品率。
  • 设备MCU必须定义成品出厂测试的结果显示方式，用于测试人员快速判断测试结果，例如显示屏显示结果、指示灯显示、蜂鸣器提示、多次开关动作等方式。
  • 模块需要搜索特定名称的路由器信号来进行模块Wi-Fi连通性测试。因此需要将路由器的SSID配置为HEKR_PRODUCT_TEST，密码配置为任意值。
  • 正常使用环境下无需配置路由器，模块状态应答帧保留位（即#10）为0x00时不处理即可。
  • 模块初始化需要大约2s，设备上电2s后在接收到模块主动发送的模块状态帧后，再开始测试流程发送状态查询帧，只需发送一帧即可，无需定时发送，同样prodKey设置帧只需要发送一帧即可；如果模块返回错误帧，则说明写入失败，请检查prodKey设置帧格式是否正确。
  • 如厂家使用App进行整机绑定控制测试，则务必在测试完成后删除已绑定的测试设备。否则会因为安全机制导致用户无法绑定设备（设备绑定到一个账号下后需要解绑才能进行重新绑定）。
  • 建议厂家使用App完成真机测试后，出厂前让整机重新进入一键配置模式。

4 开发调试工具

氦氪产品后台 MCU SDK与用例下载 丛云App下载

5 FAQ

MCU发送串口通讯指令的两帧之间是否需要有时间间隔？

数据上报的基本时间约定：

  1. 任意2帧数据发送的间隔大于200ms；
  2. 设备主动上报时：当设备端数据发生变化时，可操作的功能（例如开/关）数据实时上报；而检测的数据（例如温湿度），上报时间大于等于300秒/次（通常约定300秒/次）；
  3. App查询，进入App的设备H5界面时，App下发查询指令（页面自动更新1次）设备自动反馈最新数据，停留在App的设备页面时，（页面每30秒更新1次），App下发查询指令设备自动反馈最新数据。

MCU应如何应答下发帧？

云端数据下发时：

  1. 数据为查询功能时，设备可以不进行原帧应答；
  2. 数据为设置功能时，设备必须进行原则帧应答；（多个操作终端上操作同一设备时）
  3. 设置（或查询）功能，设备先原帧应答（表示正常接收），设备再应答上报帧

产品秘钥（prodKey）应在何时写入？

发货模块默认为我们通用测试产品的PK，实际开发及使用，工程师根据需使用自身产品的PK

  1. Wi-Fi透传模式：提前在MCU程序中写入设备的PK（每款设备不同-后台对应Console）；
  2. 在厂测或者正常上电操作时，MCU一上电主动把PK写入Wi-Fi模块中；

如何判断模块的工作状态？

Wi-Fi模块指示灯说明：

  1. 亮 1s、灭 1s：进入一键配网模式
  2. 亮 2s、灭 2s：进入兼容配网模式
  3. 亮 0.1s、灭 0.1s：无法连接路由器
  4. 亮 0.1s、灭 5s：已经登录上服务器（正常状态）
  5. 亮 0.1s、灭 1s：无法登录上服务器

MCU时钟如何校准？

Wi-Fi模块在连接网络后将主动下发NTP时间（间隔1小时发送）

Wi-Fi模块的供电有何要求？

  1. 标准电压：3.3V（范围电压：3V ~ 3.6V）
  2. 电源支持：模块正常70mA（发射信号瞬间最大电流230mA）

Wi-Fi模块为何无法配上网络？

  1. Wi-Fi模块未进入配网：
    1. 检测Wi-Fi模块是否进入配网（亮灭各2S交替）
    2. 如果模块进入配网（通过按键操作入网，如入网无按键，短接Wi-Fi模块SCK接口到GND地，5S后进入配网状态-查看Wi-Fi模块指示灯）
  2. Wi-Fi网络问题：
    1. 连接了路由器5G网络（目前只支持2.4GHz)
    2. Wi-Fi账户密码错误，或者账户密码中有中文字符
    3. 网络信号差（查看是否正常上网，Wi-Fi信号弱）
    4. 办公网络加入Wi-Fi需要身份认证（比如进入页面认证）
    5. 路由设备满载（设备数量接入限制）
  3. 其它原因
    1. 设备未上电
    2. 手机未正常连接Wi-Fi（或者Wi-Fi连接上不可用）
    3. 配网过程，设备，手机，路由器距离太近，互相干扰
    4. 密码长度不超过32位
    5. 路由器加密方式为WPA2-PSK类型，认证类型为AES（或者皆为自动），另外模式频段不能为11n only
    6. 路由器开启MAC过滤（确保路由器没有禁止设备入网）