edit

单片机

氦氪云一体化客户对接文档-单片机

本文档只涉及模块硬件及MCU与模块之间的通信,具体流程如下

了解模块的硬件功能

请参考Hekr模块硬件使用说明及注意事项,该文档中对以下硬件功能进行了说明:

  1. 模块硬件规格、引脚定义及电气参数
  2. 通过gpio,控制模块进入一键配置模式
  3. 模块扩展注意事项

模块上Wi-Fi状态指示灯说明

  • 亮2s、灭2s:进入一键配置模式
  • 亮0.1s、灭5s:已经登录上服务器(正常工作状态)
  • 亮0.1s、灭1s:无法登录上服务器
  • 亮0.1s、灭0.5s:服务器域名解析失败(可能路由器外网不通)
  • 常亮:配网超时或Wi-Fi连接失败(配网时Wi-Fi密码错误、Wi-Fi网络状况不好)

注: 模块上电后,默认是进入一键配置模式(也叫HekrConfig模式),此时可以使用HEKR公版APP"丛云"给模块进行配网;
为支持用户扩展,将SDA(GPIO14)作为Wi-Fi状态指示引脚,便于用户外接LED,其电平状态与板载LED指示灯同步。

模块特殊说明

类型 时间 备注
模块初始化时间 2s 模块上电2s后模块才能处理串口48帧
模块登录上云端时间 一般情况下5s 模块上电到登录上云端的时间
模块HekrConfig超时时间 5min 超时后退出HekrConfig模式,指示灯常亮

通过串口操作模块

设备MCU与模块是通过串口进行通信,串口参数配置为:9600-8-N-1。
串口通信使用的是48帧协议,在示例操作之前,先对协议格式进行说明。

协议格式说明

帧格式

#1 帧头 (1B):帧起始标识,固定为`0x48`(十六进制); 
#2 帧长 (1B):整帧内容(包括帧头、帧长、校验码等)的字节个数,取值:`[0x06,0xFF]`; 
#3 帧类型 (1B):识别该帧类型,取值见“帧类型表”; 
#4 帧序号 (1B):取值`[0x00,0xFF]`,循环累加,标识顺序; 
#5 ~ #(4+n)有效数据 (nB):可变内容;  
#(5+n)校验码 (1B):校验码之前所有字节的数据和,超过0XFF取低8位(1B)

帧类型表

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

模块操作帧说明

在MCU与模块通信之前,单片机工程师可以在PC上使用串口调试助手对模块进行调试操作。
本文档仅对 0xFE模块操作帧进行说明,如模块状态查询、PK值写入、模块进入一键配置模式等等,并不涉及APP或云端与设备之间的通信。

  • 模块支持命令如下:

模块状态查询命令

模块状态查询帧

模块应答帧(模块状态帧)

设备发送: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、#7为02或07、#8为02

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

以下事件会造成模块状态改变:  
1.模块进入一键配置模式  
2.模块连接上路由器  
3.模块登录上云端  
4.模块与云端连接断开  
5.模块断开路由器  
6.模块退出一键配置模式

2.MCU有可能会接收到连续帧的情况,单片机工程师可以根据帧头和帧长对连续帧进行拆帧处理。

具体拆帧方法如下:  
1.在一段数据中先找帧头0x48;  
2.帧头后一个字节即为帧长,根据帧长截取相应长度的字节数,定为一帧;  
3.接着继续找帧头,并根据帧长确定下一帧,以此类推,直到最后一个字节。
提示:一般连续帧出现在MCU发送进入一键配置模式帧后,MCU会连续接收到应答帧及因模块状态改变时主动发送的模块状态帧。
模块进入一键配置模式命令

模块进入一键配置模式帧

模块应答帧

设备发送:48 07 FE 01 03 00 51
模块应答:48 07 FE 01 03 00 51
应答帧说明:模块进入一键配置模式。
prodKey设置命令

prodKey是产品唯一标识码,由开发者在氦氪console平台上添加产品时自动生成,字符串度为32Byte。prodKey通常由在厂测模式下通过服务器写入模块。也可由设备MCU通过串口指令来设置。

Tip

需要将获取的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

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查询命令

考虑到prodKey的安全性,模块不支持直接查询,而是带prodKey查询、模块返回是否匹配成功,所以单片机工程师只能使用已知的PK去查询与模块中的prodKey是否匹配。具体格式如下

模块prodKey查询帧

模块应答帧

设备发送:48 16 FE 01 11 01 36 A6 6C 12 75 4E E8 2F FF 88 04 B7 FA A5 3C C0  
模块应答:48 07 FE 01 11 01 60  
应答帧说明:匹配成功,模块中的prodKey为"0136a66c12754ee82fff8804b7faa53c"。

Tip

如果模块中无prodKey,模块会应答48 07 FF 01 01 50

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。

Note

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

错误帧

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

错误码 含义
0x01 模块操作错误(失败)
0x02 校验码错误
0x03 数据范围错误
0x04 命令不支持

Tip

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

厂家操作流程示例

厂家操作流程包括模块Wi-Fi连通性测试、prodKey写入模块及业务逻辑处理。厂家的MCU程序可以按照以下流程进行编程:

Tip

流程中所提及到的帧,请参考2.2模块操作帧说明 MCU示例代码下载

模块Wi-Fi连通性测试

测试目的:厂家在装机嵌入模块时可能会经过高温炉、磕碰等外界因素对模块造成损坏,为了在装机后能发现这类问题,模块需要进行模块Wi-Fi连通性测试。
测试步骤:模块在上电初始化过程中会扫描SSID(路由器账号)为HEKR _ TEST _ V4的路由器。
结果一:如果当前环境下存在此SSID并扫描到,此时模块状态应答帧保留位(即#10)为0x01,表示扫描到SSID为HEKR _ TEST _ V4的路由器,则说明模块Wi-Fi功能正常,可以用指示灯表示测试通过;
结果二:如果当前环境下存在此SSID但未扫描到,此时模块状态应答帧保留位(即#10)为0x00,表示未扫描到SSID为HEKR _ TEST _ V4的路由器,则说明模块Wi-Fi连通性不正常。
此过程称为模块Wi-Fi连通性测试。 说明:HEKR模块出厂前串口通讯、Wi-Fi联网等功能均已测试通过。

prodKey写入模块

prodKey设置帧可参考prodKey设置

配网步骤

  • 通过GPIO13(SCK)脚位低电平5秒后高电平或发送模块进入一键配置模式帧,使模块进入一键配置模式
  • 点击丛云APP主页右上角“+”号图标,按照提示步骤,输入当前手机连接的Wi-Fi,并保证设备和APP在同一个Wi-Fi网络中
  • 点击连接,等待设备与APP账户连接成功。如未成功,请参见问题收集与解决或联系HEKR项目经理。

注意事项

  • 模块需要连接特定名称的路由器信号来进行模块wifi连通性测试。因此需要将路由器的SSID配置为HEKR_TEST_V4,密码配置为任意值。
  • 正常使用环境下无需配置路由器,模块状态应答帧保留位(即#10)为0x00时不处理即可
  • 模块初始化需要大约2s,所以上电2s后再发送状态查询帧,只需发送一帧即可,无需定时发送,同样prodKey设置帧只需要发送一帧即可;如果模块返回错误帧,则说明写入失败,请检查prodKey设置帧格式是否正确。
  • 模块wifi连通性测试也可作为测试串口引脚是否有虚焊。
  • 如果需要跳过模块wifi连通性测试,则在上电2s后直接发送prodKey设置帧即可。但不建议这么操作。
  • 厂家使用APP完成整机测试后,务必在设备列表中删除已绑定的测试设备。否则会因为安全机制导致用户无法绑定设备(设备绑定到一个账号下后需要解绑才能进行重新绑定)。
  • 建议厂家使用APP完成真机测试后,出厂前让整机重新进入一键配置模式。