edit

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


本文档向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过滤(确保路由器没有禁止设备入网)