协议解析

本文介绍 Wi-Fi 通用方案中的协议格式、基础协议中的指令和功能协议中的常用指令。

简介

本文为您介绍模组初始化过程中必须的指令及部分常用的扩展功能指令。其他部分的指令介绍参见串口通信协议。

• 基础协议：是模组本身的功能指令，和产品功能无关。
• 功能协议：是每个产品功能点数据收发指令。

说明：视频教程参见：Wi-Fi MCU 对接指南之协议解析

协议格式

MCU 和 Wi-Fi 模组通过串口交互。交互中的通信约定、数据帧格式和命令字索引表信息如下。

串口通信约定

参数	说明
波特率	取决于固件配置，支持波特率 9600 或 115200。
数据位	8 位
奇偶校验	无
停止位	1 位
数据流控	无

数据帧格式

字段	长度（字节）	说明
帧头	2	固定为 0x55aa
版本	1	协议的版本号
命令字	1	帧类型
数据长度	2	大端模式
数据	1~2	自定义数据
校验和	1	从帧头开始对字节进行求和，将得出的结果对 256 求余。

命令字索引表

命令字	说明
0x00	检测心跳
0x01	查询产品信息
0x02	查询模组工作模式
0x03	报告设备联网状态
0x04	重置 Wi-Fi
0x05	重置 Wi-Fi 并切换配网模式
0x06	下发 DP 命令
0x07	上报 DP 状态
0x08	查询状态
0x0a	启动 OTA 升级（可选）
0x0b	传输 OTA 升级包（可选）
0x1c	获取本地时间（可选）
0x0e	测试 Wi-Fi 功能

基础协议

基础协议是模组工作所必须的协议。

• 模组基本功能：命令字 0x00~0x08，包括检测心跳、查询产品信息和查询模组工作模式等。
• 模组拓展功能：命令字 0x0a~0x0e，包括 MCU OTA、获取本地时间和测试 Wi-Fi 功能等。

模组初始化

模组上电会不断发送心跳包， MCU 端回复心跳后，启动下图中的初始化流程。

波特率自适应

模组最新固件中添加了波特率检测自适应的功能，可自适应判断 9600/115200 波特率。因此，在初次初始化过程前，模组会经过波特率检测，收到部分乱码或初次启动时间延迟属于正常现象。

相关流程如下：

1. 模组读取 Flash 保存的波特率纪录数据。

2. 根据能否读取数据进入相关流程：

   • 若能读取数据：优先使用该组合，发3次握手包，每次隔 1秒左右。若没回复，则重新进入扫描模式。
   • 若不能读取数据：进入扫描模式，即在 9600 和 115200 中切换（300~400ms）每个组合发 2 次包。如果能收到指定的回复帧，则代表识别成功。随后使用该组合初始化串口并将组合参数保存至 Flash，同时保存并处理回复帧。

命令字说明

1. 心跳检测

   MCU 上电后发送心跳包，返回0x00或0x01命令字。

   • 0x00：上电后第一次的心跳包回复为 0x00，模组会自动进行初始化数据同步。
   • 0x01： 第二次及以后的心跳包回复为 0x01 ，判定设备是否离线或断网。

   类型	帧头	版本	命令字	数据长度	数据	校验和
   模块发送	0x55aa	0x00	0x00	0x0000	无	0xff
   MCU 返回	0x55aa	0x03	0x00	0x0001	第一次：0x00 其他：0x01	{校验和}

   示例：

   • 模组发送：55 aa 00 00 00 00 ff
   • MCU 返回：
     • 第一次：55 aa 03 00 00 01 00 03
     • 第二次及以后：55 aa 03 00 00 01 01 04

2. 查询产品信息

   收到心跳包回复后，模组会发送查询产品指令信息。MCU 返回 PID、版本、模式等信息。

   说明：{}:””等字符同样需要输入。

   类型	帧头	版本	命令字	数据长度	数据	校验和
   模块发送	0x55aa	0x00	0x01	0x0000	无	0x00
   MCU 返回	0x55aa	0x03	0x01	无数据长度限制。示例：0x002a	示例：{“p”:”RN2FVAgXG6W****”,“v”:”1.0.0”,”m”}。支持以下模式： 0：默认配网 1：低功耗 2：特殊配网	{校验和}

   示例：

   • 模组发送：55 aa 00 01 00 00 00
   • MCU 返回：55 aa 03 01 00 2a 7b 22 70 22 3a 22 52 4e 32 46 56 41 67 58 47 36 57 66 41 6b 74 55 22 2c 22 76 22 3a 22 31 2e 30 2e 30 22 2c 22 6d 22 3a 30 7d 0c

     说明： 将{“p”:”RN2FVAgXG6W****”,“v”:”1.0.0”,”m”}中的每一个字符（包括标点符号）转换成 ASCII 码，替换到数据的位置。

3. 设定模组工作方式

   收到产品信息后，模组会发送查询 MCU 设定模组工作方式的 0x02 命令字。模块工作模式主要针对如何指示 Wi-Fi 的工作状态以及如何重置 Wi-Fi ，主要分两种情况：

   • MCU 与模块配合处理模式

     • 配网状态显示方法：模块通过串口通知 MCU Wi-Fi 当前的工作状态，由 MCU 控制配网指示灯显示。
     • 上报数据：0

     

   • 模块自处理模式

     注意：模块自处理方式不需要进行初始化流程中的报告设备联网状态、重置 Wi-Fi 和重置 Wi-Fi 并切换配网模式这三个步骤。

     • 配网状态显示方法：通过 Wi-Fi 的 GPIO 引脚驱动 LED 状态进行显示。
     • 上报数据：指示灯 IO 口数据和按键 IO 口数据。
     • 重置方法：Wi-Fi 检测 GPIO 入口低电平持续 5 秒以上。指示灯与按钮所使用的 GPIO 管脚由以下命令配置。

     类型	帧头	版本	命令字	数据长度	数据	校验和
     模块发送	0x55aa	0x00	0x02	0x0000	无	0x01
     MCU 返回（MCU 和模块配合处理）	0x55aa	0x03	0x02	0x0000	无	{校验和}
     MCU 返回（模块自处理）	0x55aa	0x03	0x02	0x0002	首字节：Wi-Fi 状态指示GPIO 序号。 次字节：Wi-Fi 重置键 GPIO 序号。	{校验和}

     示例：

     • 模组发送：55 aa 00 02 00 00 01
     • MCU 返回：
       • MCU 与模组配合处理模式：55 aa 03 02 00 00 04。
       • 模组自处理模式：55 aa 03 02 00 02 05 00 0b，其中指示灯接 IO5，按键接 IO0。

4. 报告 Wi-Fi 状态

   说明：仅 MCU 与模块配合处理模式支持该功能。

   当模块检测到 MCU 重启或模块的 Wi-Fi 状态发生变化，会主动发送状态到 MCU。MCU 可以根据 03 命令字中的 Wi-Fi 状态控制指示灯的闪烁。03 版本协议中，Wi-Fi 共有 6 种状态。

   设备联网状态	描述	状态值	LED 显示
   状态 1	Smartconfig 配置状态	0x00	快闪，间隔 250ms
   状态 2	AP 配置状态	0x01	慢闪，间隔 1500ms
   状态 3	Wi-Fi 已配置但未连接路由器	0x02	熄灭
   状态 4	Wi-Fi 已配置且已连接路由器	0x03	常亮
   状态 5	已连接路由器和云端	0x04	常亮
   状态 6	Wi-Fi 设备处于低功耗模式	0x05	熄灭
   状态 7	Wi-Fi 设备处于 Smartconfig 和 AP 配置状态	0x06	快闪，间隔 250ms

   类型	帧头	版本	命令字	数据长度	数据	校验和
   模块发送	0x55aa	0x00	0x03	0x0001	支持以下状态值： 0x00：Smartconfig 配网模式。 0x01：AP 配网模式。 0x02：Wi-Fi 已配置但未连接路由器。 0x03：Wi-Fi 已配置且已连接路由器。 0x04：已连接路由器和云端。 0x05：Wi-Fi 设备处于低功耗模式 0x06：Wi-Fi 设备处于 Smartconfig 和 AP 配置状态	{校验和}
   MCU 返回	0x55aa	0x03	0x03	0x0000	无	0x05
   示例：

   • 模组发送：55 aa 00 03 00 01 01 {校验和}
   • MCU 返回：55 aa 03 03 00 00 05

5. 重置 Wi-Fi

   说明：仅 MCU 与模块配合处理模式支持该功能。

   配网指令，可以通过重置 Wi-Fi 使设备处于待配网状态。配网模式分两种：

   • Smartconfig 模式：即快闪模式，配网方式简单快捷。
   • AP 模式：即慢闪模式，配网稳定可靠。

   说明：建议两种模式同时开发，应对不同的需求。配网模式的触发机制可以自定义，通过指示灯快闪和慢闪进行区分。

   MCU 每发送一次 0x04 命令字，模组切换一次配网模式。第一次默认配置为 Smartconfig 模式，之后在 Smartconfig 与 AP 之间来回切换。

   

   类型	帧头	版本	命令字	数据长度	数据	校验和
   MCU 发送	0x55aa	0x00	0x04	0x0000	无	0x03
   模块返回	0x55aa	0x03	0x04	0x0000	无	0x06

   示例：

   • MCU 发送：55 aa 03 04 00 00 06
   • 模组返回：55 aa 00 04 00 00 03

6. 重置 Wi-Fi 并选择模式

   说明：仅 MCU 与模块配合处理模式支持该功能。

   重置 Wi-Fi 并选择配网模式，根据 MCU 发送的参数不同，可指定进入 Smart 或 AP 模式。此指令与 0x04 命令字作用相同，均可配网，但可指定进入某种配网模式。

   类型	帧头	版本	命令字	数据长度	数据	校验和
   MCU 发送（Smartconfig 模式）	0x55aa	0x03	0x05	0x0001	0x00	{校验和}
   MCU 发送（AP 模式）	0x55aa	0x03	0x05	0x0001	0x01	{校验和}
   模块返回	0x55aa	0x00	0x05	0x0000	无	0x04

   示例：

   • MCU 发送：
     • Smartconfig 模式：55 aa 03 05 00 01 00 08
     • AP 模式：55 aa 03 05 00 01 01 09
   • 模组返回：55 aa 00 05 00 00 04

7. 查询 MCU 工作状态

   08 命令字的作用是通过模块获取 MCU 所有 Datapoint 状态，并设置为 App 显示初值。MCU 收到08 命令字后，分条上报所有 DP 点数据。状态查询的发送情况主要有两种：

   • 模块首次上电，通过心跳与 MCU 建立连接后，查询发送。
   • 模块检测到 MCU 重启或发生了离线再上线的过程，查询发送。

   类型	帧头	版本	命令字	数据长度	数据	校验和
   模块发送	0x55aa	0x00	0x08	0x0000	无	{校验和}
   MCU 返回	0x55aa	0x03	0x07	无限制	上报所有 DP 点数据，作为显示的初始值	{校验和}

   示例：

   • 模组发送：55 aa 00 08 00 00 07
   • MCU 返回：
     • 55 aa 03 07 N \***\* {校验和}（DP1）
     • 55 aa 03 07 N \*\*** {校验和}（DP2）
     • … （DPN）

8. 产测指令

   主要用于产品量产时的 Wi-Fi 模组射频性能测试。建议等待上电初始化完成，5 秒以后调用产测指令。模组接收产测指令后，会自动扫描名称为 tuya_mdev_test 的 Wi-Fi 信号，返回扫描结果和信号强度百分比（范围为 0-100， 步进为 20）。

   类型	帧头	版本	命令字	数据长度	数据	校验和
   MCU 发送	0x55aa	0x03	0x0e	0x0000	无	{校验和}
   模块返回	0x55aa	0x00	0x0e	0x0002	第一个字节：测试是否成功 0x00：失败 0x01：成功 第二个字节：Wi-Fi 信号强度百分比	{校验和}

   示例：

   • MCU 发送：55 aa 03 0e 00 00 {校验和}
   • 模组返回：55 aa 00 0e 00 02 01 28 38 （产测成功，信号强度 40）

功能协议

模组下发数据命令字为 0x06，MCU 上报数据命令字为 0x07。
MCU 在收到数据下发指令后，根据收到的功能指令数据不同，进行相应的逻辑控制，并在 DP 状态改变时及时上报，更改 App 显示状态。（如果相同 DP 点的数据与上次上报数据相同，模组端会进行数据过滤。）

示例

PD ID	功能名称	数据传输类型	数据类型	备注
3	当前温度	只上报	value	数值范围：-20-50，间距：1，单位：℃
4	工作模式	可下发可上报	enum	枚举范围：smart,auto
21	故障告警	只上报	bitmap	标签： motor_fault
23	模式周程序	可下发可上报	raw	最大长度 128

• Value 型数据：4 字节，使用不满 4 字节的，前边补 0 即可。

  说明：例如当前温度，MCU 发送：55 aa 03 07 00 08 02 02 00 04 00 00 00 1e {校验和}（目标温度 30 度）。

• Bitmap 型数据：支持多故障同时上报。每一个 bit 位可代表一个警告，置 1 表示发生故障，置 0 表示无故障。可以为 1、2 或 4 字节，大于1 字节时为大端模式。

  说明：例如故障警告，MCU 发送：55 aa 03 07 00 06 0d 05 00 02 00 09 {校验和}（故障 bit0 和故障 bit3 发生故障）。

• String 型数据：字符串的含义与显示需与面板配套，自定义的可与面板沟通。

• Raw 类型数据：透传型数据，通常用于比较复杂的功能实现。不建议用户自行使用。