基础功能

更新时间：2021-12-10 02:38:38下载pdf

基础功能是指 MCU 对接 Wi-Fi 通用方案中，完成设备智能化必需的协议功能，包括模组初始化、配网操作和数据下发上报。

如果设备 MCU 硬件资源有限，不使用涂鸦提供的 MCU SDK 开发，您也可以选择自行对接Wi-Fi 通用串口协议。需要注意的是，您需要完成基础功能，设备才能正常工作。
本文展示的 功能协议示例 均由模组调试助手展示。推荐您使用涂鸦模组调试助手协助调试，可快速了解协议实现流程。

模组初始化

模组初始化是指模组接收到 MCU 发送的配置信息完成初始化配置的过程。

功能概述

模组在与 MCU 建立通信后，首先进行的便是初始化流程。只有先完成初始化流程，模组才可以响应 MCU 进行配网、数据处理及拓展功能的实现。该流程包括但不限于以下协议指令：

建立心跳连接
产品信息上报
模组工作方式配置
报告模组网络状态（若模组工作模式为与 MCU 配合处理）
状态同步查询

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

基础功能

波特率自适应

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

模组读取 Flash 保存的波特率纪录数据。
模组根据能否读取到波特率数据进入对应流程：
- 若读取到波特率数据：使用该波特率配置，连续间隔 1s 发送3次心跳包给 MCU。若 MCU 没回复，模组则重新进入扫描模式。
- 若读取不到波特率数据：模组进入扫描模式，即在 9600 和 115200 2 种波特率中切换（300~400ms）每个组合发 2 次心跳包。如果能收到指定的回复帧，则代表识别成功。随后模组将使用该配置初始化串口并将组合参数保存至 Flash。

使用场景

模组重启上电或者重置后会启动初始化流程，与 MCU 进行正确的指令交互完成初始化。有下面两种情况：

设备未进行配网：启动初始化流程后，完成产品信息及模组工作模式配置后，模组报告当前联网状态，进入配网状态等待用户配网操作。
设备已完成配网：启动初始化流程后，完成产品信息及模组工作模式配置后，模组重新连回原有网络，并将模组的联网状态报告给 MCU。同时，模组会查询设备状态，MCU 收到查询指令后应上报当前设备所有 DP 状态，用于配网成功后 App 同步设备状态。

指令列表

初始化流程涉及以下协议指令：

心跳检测指令：命令字 0x00
查询产品信息指令：命令字 0x01
设备新功能设置通知指令：命令字0x37(子命令0x00)
查询工作模式指令：命令字 0x02
报告设备联网状态指令：命令字 0x03
前置条件：模组工作模式为MCU与模组配合处理模式
查询设备状态指令：命令字 0x08
前置条件：若模组已完成配网

以下介绍各指令的详细信息。

心跳检测指令（`0x00`）

心跳指令的主要作用是检测 MCU，确保 MCU 处于正常工作状态，也是涂鸦 IoT 平台判定设备处于上线状态的重要依据。因此对于模组发送的心跳指令，MCU 需要及时响应。指令详细介绍，请参考 Wi-Fi通用串口协议-心跳检测。

Wi-Fi 模组在收到 MCU 心跳回复完成首次心跳交互后，以 15s 的间隔定期发送心跳，建议在收到心跳指令后，3s内回复模组。
超时清缓存：模组与 MCU 建立心跳连接后，若模组在连续两个心跳指令没有收到应答时，若此时模组端的串口缓存区有待发送数据，模组会先清空缓存数据不再发送，比如设备网络状态变化，模组原本要发送网络状态给到 MCU，但由于前两次心跳没有接收到 MCU 回复，模组会清空串口缓存区的网络状态数据不再发送，表现出的现象就是 MCU 端会丢失本次网络状态通知。
超时重启：模组与 MCU 建立心跳连接后，若模组在连续 90s 未收到MCU的心跳回复，即连续 6 个心跳没有应答时，模组会自动重启。若是已配网设备，重启后仍未建立连接，3分钟左右云端就会判定设备离线。

MCU 也可依据心跳定期检测模组是否正常工作。若多次发现模组无心跳下发，此时模组很可能出现了异常，则 MCU 可通过模组提供的硬件复位引脚复位 Wi-Fi 模组。

心跳检测是模组与设备建立连接通信的基础。协议对接过程中，建议先通过调试心跳指令测试串口信功能是否正常。如果对MCU功耗有要求需要断开心跳检测，可以参考关闭心跳指令 0x25。

查询产品信息指令（`0x01`）

收到心跳包回复后，模组会发送查询产品指令信息指令，MCU收到后需回复产品信息，包含 PID、MCU 版本、模式、可选字段配置等信息。指令详细介绍，请参考 Wi-Fi通用串口协议-查询产品信息。

若产品信息回复错误，模组会一直下发查询指令，此时需要检查上报产品信息的内容和格式是否正确。

指令示例

模组发送：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

字段	含义	字符	十六进制 ASCII 码
`p`	产品 ID（PID，Product ID）	`"p":"RN2FVAgXG6WfAktU"`	`22 70 22 3a 22 52 4e 32 46 56 41 67 58 47 36 57 66 41 6b 74 55 22`
`v`	MCU 版本	`"v":"1.0.0"`	`22 76 22 3a 22 31 2e 30 2e 30 22`
`m`	模组工作方式	`"m":0`	`22 6d 22 3a 30`

将{"p":"RN2FVAgXG6WfAktU","v":"1.0.0","m":0}中的每一个字符和标点符号转换成十六进制的 ASCII 码，替换到数据的位置，需要增加其他字段配置，按对应格式在回复数据中添加。

字段说明

字段	含义	配置内容	说明
`m`	模组工作模式	`0`：常配网工作模式。模组出厂上电后处于待配网状态，如果不对模组进行配网操作改变网络状态，模组会一直保持。 `1`：超时配网工作模式，又称安全模式。与常配网模式的差异是当模组处于配网状态三分钟后未被用户配走模组便退出配网状态，进入低功耗状态，需要重新收到重置命令才会重新进入配网模式。简称配网超时机制。 `2`：防误触工作模式。与超时配网模式相同的是防误触模式也具有配网超时机制。不同的是该模式还具有防误触功能，即模组配网成功后，如果本地重置（MCU 发送重置命令）进入配网状态，配网超时时间内未进行配网操作会自动恢复重置前的用户网络连接。本地重置后设备中途异常断电上电也会自动恢复重置前的用户网络连接。	常配网工作模式使用说明常配网模式下设备会保持待配网状态，但配网时由于各种环境因素失败后，模组的网络状态会卡在中间状态，不会自动回到配网状态，无法重新配网，此时只有外部重置配网，才能让设备重新进入配网状态。配网超时补充除了配网超时会退出配网状态，进入低功耗状态外，在配网状态`10s`后模组重启也会快速进入低功耗状态。这里提到的低功耗状态指的是配网低功耗，详细介绍见 Wi-Fi 低功耗方案防误触工作模式使用说明防误触工作模式下配网成功的设备如果本地移除进入配网，App 上不会移除设备图标，超时时间内没有被其他用户或者网络配走，会自动连回原来网络，避免 App 上出现设备突然消失有突然增加的现象。防误触工作模式下只有当设备被用户从 App 端移除设备便不会记录上次用户的网路连接并重连。该模式用于需要有本地防误重置的用户场景的需求。
`mt`	配网超时时间	设置安全模式和防误触模式的配网超时时间，没有上传这个字段默认超时时间3分钟，可以支持的设置时间范围：3分钟~10分钟。	如配置超时时间为5分钟，则需在回复中增加：`"mt":5`
`n`	模组的配网方式	没有该字段保持传统（两种配网方式互相切换）的模式: `0`： Wi-Fi 快连配网和热点联网共存配网模式。模组同时支持热点联网连接配网和EZ配网无需用户切换，对应的配网状态包见报告设备联网状态。 `1`：仅仅只有热点联网配网模式：这种模式下产品只能通过热点联网连接的方式进行设备配网。	配网方式介绍，请参考配网功能介绍
`ir`	红外功能	表明模组的红外功能并告知模组红外的收发脚使用哪些IO口，没有这个字段红外能力默认关闭。如在产品信息回复中增加：`"ir":"5.12"`，表示启动红外功能，并配置红外发送脚为IO5，红外接收脚为IO12。	如果工作模式中使用模组自处理模式，请勿与按键和Wi-Fi指示灯设置的IO口重复。部分模组跨组IO设置，需要在设置组IO脚基础上加32，PB20设置序号为20+32。红外发送脚需要用到PWM资源，接收需要使用IO中断，具体模组支持的IO口请参考模组资料。
`low`	低功耗模式	表明模组是否开启保持长连接的低功耗模式，没有该字段低功耗模式默认关闭。这个长连接的低功耗模式是指设备配网后稳定没有网络控制的情况下，在保持连接状态时通过降低射频功耗来实现的低功耗，这种状态下模组的平均功耗低于 15mA。通过这个字段可以打开模组这个能力。 `0`：关闭低功耗模式 `1`：打开模组低功耗模式	如产品信息回复中增加：`"low":1`，表明开启保持长连接的低功耗模式。双模模组打开这个功能后，模组只有蓝牙配网功能，蓝牙控制将会关闭。产品对于功耗没有要求的不需要关心这个字段。该字段开启的低功耗模式与串口协议中设备网络状态的低功耗状态不同，可以称为长连接低功耗，详细介绍，请参考 Wi-Fi 低功耗方案，配网成功后，如果一段时间不控制（具体时间和芯片有关），并且 IO 口没有输出（如果是照明固件，就需要关灯）模组会进入待机低功耗模式。此时功耗在 0.2W 之内。
`vt`	MCU 的固件类型	此字段表示MCU固件类型为设置的值，且此数据与开发者平台下的固件类型匹配。没有该字段默认MCU固件类型为9，此字段数据可选值为10—19。	字段内容一定要与开发者平台创建的固件类型数据匹配，否则会出现无法接收OTA信息或接收到错误的OTA升级信息，导致OTA升级异常。

设备新功能设置指令（`0x37`子命令`0x00`）

MCU 向模组发送产品信息后，模组会发送查询 MCU 设定工作方式的 0x02 命令字，此时 MCU 可通过设备新功能设置指令发送设备新功能设置到模组，包含 MCU OTA 执行方式、新功能使能、红外指示灯配置、和 MCU BUF 配置等信息。指令详细介绍，请参考 Wi-Fi通用串口协议-设备新功能设置。

若无所需要的新增功能设置，可不执行该指令。有需要设置新增功能时，MCU 需在每次上电或模组重启之后发送该指令到模组。

指令示例

模组发送：55 aa 00 01 00 00 00
MCU 返回：55 AA 03 37 00 27 00 7B 22 6D 63 75 5F 6F 74 61 22 3A 30 2C 22 61 62 76 22 3A 31 2C 22 69 72 22 3A 37 2C 22 62 75 66 22 3A 32 35 36 7D 42

字段	含义	字符	十六进制 ASCII 码
`mcu_ota`	设置 MCU 无程序暂存区 OTA 0x00：MCU 有程序暂存区 0x01：MCU 无程序暂存区暂时只有 HomeKit 通用对接支持这个功能	`"mcu_ota":0`	`22 6D 63 75 5F 6F 74 61 22 3A 30`
`abv`	功能使能字段，按位设置 Bit0：蓝牙状态通知（双模设备支持） 1：开启通知 0：关闭 Bit1：射频遥控器功能使能 1：开启功能 0：关闭功能 Bit2-bit7：0，预留，默认填充0	`"abv":1`	`22 61 62 76 22 3A 31`
`ir`	设置红外功能模组自处理工作状态指示 GPIO, GPIO 引脚编码规则同`0x02`命令字	`"ir":7`	`22 69 72 22 3A 37`
`buf`	设置 MCU 串口资源 BUF 可承受的最大数据量，最小为256字节	`"buf":256`	`22 62 75 66 22 3A 32 35 36`

此指令会根据业务的拓展，功能字段也会扩充增加。
该指令为新增指令，MCU SDK 暂未更新指令代码，但您可参照查询产品信息指令代码自行实现。

查询工作模式指令（`0x02`）

收到产品信息后，模组会发送查询 MCU 设定工作模式的 0x02 命令字，MCU 收到后需回复模组工作模式。指令详细介绍，请参考 Wi-Fi通用串口协议-配置工作模式。模组工作模式主要针对如何重置 Wi-Fi 以及如何指示 Wi-Fi 的工作状态，主要分两种情况：

MCU 与模组配合处理模式
- 重置方式：MCU 通过串口给模组发送重置配网指令，让模组进入配网状态。
- 网络状态显示方式：模组通过串口通知 MCU Wi-Fi 当前的网络状态，由 MCU 控制配网指示灯显示。
模组自处理模式
- 重置方式：Wi-Fi 检测重置按键 GPIO 入口低电平持续 5 秒以上。网络指示与重置按键所使用的 GPIO 管脚由以下命令配置。
- 网络状态显示方式：通过 Wi-Fi 的网络指示 GPIO 引脚驱动 LED 状态进行显示，显示效果请参考 Wi-Fi通用串口协议。

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

模组自处理方式不需要进行初始化流程中的报告设备联网状态、重置配网（重置 Wi-Fi 或重置 Wi-Fi 并选择配网模式）步骤，即模组不发送网络状态，重置配网只能通过外部拉低IO，发送配网指令无效。
每次重置操作后Wi-Fi模组的配网方式在热点配网与EZ配网之间切换，效果与0x04重置Wi-Fi指令类似

报告设备联网状态指令（`0x03`）

仅工作模式为 MCU 与模组配合处理的设备，支持该功能。

收到模组工作模式配置后，模组会将当前设备联网状态报告给 MCU。MCU 可以根据0x03命令字中的 Wi-Fi 状态控制指示灯的闪烁。指令详细介绍，请参考 Wi-Fi通用串口协议-报告设备联网状态。

当模组检测到 MCU 重启或模组的 Wi-Fi 网络状态发生变化，会主动发送状态到 MCU，MCU 接收到联网状态后，可以通过外接LED灯做联网状态指示，不同灯光展示效果表示不同的联网状态。建议设计的指示灯效果与自处理模式下的LED显示效果保持一致，如联网状态为状态1：指示灯间隔闪烁250ms。

查询设备状态指令（`0x08`）

指令详细介绍，请参考 Wi-Fi通用串口协议-模组查询设备状态。模组发送查询状态指令的时机有两个：

模组在已经完成配网后首次上电，或者配网成功过程中，初始化流程进行到模组工作模式配置。若模组工作模式配置成MCU与模组配合处理模式，则是在初始化流程进行到报告模组联网状态。此时，模组发送设备状态查询。
模组在已经完成配网的情况下，工作过程中检测到MCU重启或发生了离线再上线的过程。此时，模组发送设备状态查询。

MCU 收到后需通过状态上报指令 0x07 上报所有 DP 状态，用于 App 同步状态。

功能协议示例

心跳交互
产品信息回复
设备新功能设置通知
配置模组工作模式：
MCU与模组配合处理模式
报告模组联网状态
查询设备状态

MCU SDK示例

心跳包检测函数

心跳包检测函数heat_beat_check()定义在 MCU SDK 的system.c文件中，作用是回复模组发送的心跳包。应用步骤如下：

串口数据处理函数data_handle()接收到心跳指令。

MCU 调用heat_beat_check()回复。第一次回复的心跳包为 0x00，第二次及以后回复的心跳包为0x01。

/**
* @brief  数据帧处理
* @param[in] {offset} 数据起始位
* @return Null
*/
void data_handle(unsigned short offset)
{
	......
	case HEAT_BEAT_CMD:                                     //心跳检测指令
			heat_beat_check();                              //心跳回复函数
		break;
		......
}

/**
* @brief  心跳包检测
* @param  Null
* @return Null
*/
static void heat_beat_check(void)
{
	unsigned char length = 0;
	static unsigned char mcu_reset_state = FALSE;
	if(FALSE == mcu_reset_state) {
		length = set_wifi_uart_byte(length, FALSE);         //上电第一次心跳回复00
		mcu_reset_state = TRUE;
	}else {
		length = set_wifi_uart_byte(length, TRUE);          //上电第一次心跳回复01
	}
	wifi_uart_write_frame(HEAT_BEAT_CMD, MCU_TX_VER, length);
}

data_handle()为串口数据处理函数，作用是接收模组发送的协议指令数据，并做处理，wifi_uart_write_frame()为串口发送函数，作用是往模组串口发送指令数据。

产品信息回复函数

产品信息回复函数 product_info_update() 定义在 MCU SDK 的 system.c 文件中，作用是 MCU 返回产品信息。应用步骤如下：

串口数据处理函数 data_handle() 接收到查询产品信息指令。

调用 product_info_update() 上报产品信息。

PID、MCU 版本号、配置字段等信息都是通过打开或修改宏定义启动上报，从而配置相关功能。

#define PRODUCT_KEY "orxyzazpfw******"    //开发平台创建产品后生成的16位字符产品唯一标识
#define MCU_VER "1.0.0"         //用户的软件版本,用于MCU固件升级,MCU升级版本需修改
/*  模组工作方式选择,只能三选一,推荐使用防误触模式  */
//#define CONFIG_MODE     CONFIG_MODE_DEFAULT             //默认工作模式
//#define CONFIG_MODE     CONFIG_MODE_LOWPOWER            //安全模式 (低功耗配网方式)
#define CONFIG_MODE     CONFIG_MODE_SPECIAL             //防误触模式(特殊配网方式)

/*  设置低功耗配网方式和特殊配网方式的配网模式打开时间,该宏处于注释状态将按三分钟处理,可以支持的设置数据范围: 3~10 分钟  */
//#define CONFIG_MODE_DELAY_TIME    10         //配网模式打开时间 单位:分钟

/*  选择smart模式和热点配网模式,该宏都注释将保持smart模式和热点配网模式互相切换  */
//#define CONFIG_MODE_CHOOSE        0         //模组同时支持热点连接配网和EZ配网无需用户切换,对应的配网状态0x06
//#define CONFIG_MODE_CHOOSE        1         //仅只有热点配网模式

/*  启用模组的红外功能并告知模组红外的收发脚使用那些IO口，没有该字段红外能力默认关闭  */
//#define ENABLE_MODULE_IR_FUN                  //启用模组的红外功能
#ifdef ENABLE_MODULE_IR_FUN
#define MODULE_IR_PIN_TX      5       //红外发送脚
#define MODULE_IR_PIN_RX      12      //红外接收脚
#endif

/*  模组是否开启保持长连接的低功耗模式，没有该字段低功耗模式默认关闭  */
//#define LONG_CONN_LOWPOWER        0         //关闭低功耗模式
//#define LONG_CONN_LOWPOWER        1         //打开低功耗模式

void data_handle(unsigned short offset)
{
	......
	case PRODUCT_INFO_CMD:                                  //查询产品信息指令
			product_info_update();
		break;
		......
}

/**
* @brief  产品信息上传
* @param  Null
* @return Null
*/
static void product_info_update(void)
{
	unsigned char length = 0;
	unsigned char str[10] = {0};

	length = set_wifi_uart_buffer(length, "{\"p\":\"", my_strlen("{\"p\":\""));
	length = set_wifi_uart_buffer(length,(unsigned char *)PRODUCT_KEY,my_strlen((unsigned char *)PRODUCT_KEY));                 //往wifi_uart_buffer写入PID
	length = set_wifi_uart_buffer(length, "\",\"v\":\"", my_strlen("\",\"v\":\""));
	length = set_wifi_uart_buffer(length,(unsigned char *)MCU_VER,my_strlen((unsigned char *)MCU_VER));                     //往wifi_uart_buffer写入MCU版本
	length = set_wifi_uart_buffer(length, "\",\"m\":", my_strlen("\",\"m\":"));
	length = set_wifi_uart_buffer(length, (unsigned char *)CONFIG_MODE, my_strlen((unsigned char *)CONFIG_MODE));                 //往wifi_uart_buffer写入m字段
#ifdef CONFIG_MODE_DELAY_TIME
	sprintf((char *)str,",\"mt\":%d",CONFIG_MODE_DELAY_TIME);
	length = set_wifi_uart_buffer(length, str, my_strlen(str));                 //往wifi_uart_buffer写入mt字段
#endif
#ifdef CONFIG_MODE_CHOOSE
	sprintf((char *)str,",\"n\":%d",CONFIG_MODE_CHOOSE);
	length = set_wifi_uart_buffer(length, str, my_strlen(str));                 //往wifi_uart_buffer写入n字段
#endif
#ifdef ENABLE_MODULE_IR_FUN
	sprintf((char *)str,",\"ir\":\"%d.%d\"",MODULE_IR_PIN_TX,MODULE_IR_PIN_RX);
	length = set_wifi_uart_buffer(length, str, my_strlen(str));                 //往wifi_uart_buffer写入ir字段
#endif
#ifdef LONG_CONN_LOWPOWER
	sprintf((char *)str,",\"low\":%d",LONG_CONN_LOWPOWER);
	length = set_wifi_uart_buffer(length, str, my_strlen(str));                 //往wifi_uart_buffer写入low字段
#endif
	length = set_wifi_uart_buffer(length, "}", my_strlen("}"));
	wifi_uart_write_frame(PRODUCT_INFO_CMD, MCU_TX_VER, length);
}

查询工作模式函数

查询工作模式函数get_mcu_wifi_mode()定义在 SDK 的system.c文件中，作用是发送模组工作方式配置。应用步骤如下：

串口数据处理函数data_handle()接收到查询模组工作模式指令。

调用get_mcu_wifi_mode()回复上报。

通过屏蔽或打开WIFI_CONTROL_SELF_MODE的宏定义，可以配置模组工作方式为配合处理模式或模组自处理模式，如果是自处理模式，还需要配置重置按键和状态指示IO口。

//#define         WIFI_CONTROL_SELF_MODE                       //wifi自处理按键及LED指示灯;如为MCU外界按键/LED指示灯请关闭该宏
#ifdef          WIFI_CONTROL_SELF_MODE                      //模组自处理
#define     WF_STATE_KEY            14                    //wifi模组状态指示按键，请根据实际GPIO管脚设置
#define     WF_RESERT_KEY           0                     //wifi模组重置按键，请根据实际GPIO管脚设置
#endif

void data_handle(unsigned short offset)
{
	......
	case WORK_MODE_CMD:                                     //查询模组工作模式指令
			get_mcu_wifi_mode();
		break;
		......
}

/**
* @brief  mcu查询mcu和wifi的工作模式
* @param  Null
* @return Null
*/
static void get_mcu_wifi_mode(void)
{
	unsigned char length = 0;
#ifdef WIFI_CONTROL_SELF_MODE                                   //模组自处理模式，配置联网指示及重置配网引脚
	length = set_wifi_uart_byte(length, WF_STATE_KEY);
	length = set_wifi_uart_byte(length, WF_RESERT_KEY);
#else
	//No need to process data
#endif
	wifi_uart_write_frame(WORK_MODE_CMD, MCU_TX_VER, length);
}

查询 Wi-Fi 状态函数

查询 Wi-Fi 状态函数mcu_get_wifi_work_state()定义在 SDK 的mcu_api.c文件中，作用是 MCU 接收模组发送的网络状态。应用步骤如下：

模组工作模式选择 MCU 与模组配合处理时，串口数据处理函数data_handle()接收模组下发的网络状态赋值给变量wifi_work_state。

MCU 可自行调用mcu_get_wifi_work_state()接收并做其他处理，如根据联网状态做指示灯显示。

//#define         WIFI_CONTROL_SELF_MODE                       //wifi自处理按键及LED指示灯;如为MCU外界按键/LED   指示灯请关闭该宏
#ifdef          WIFI_CONTROL_SELF_MODE                      //模组自处理
#define     WF_STATE_KEY            14                    //wifi模组状态指示按键，请根据实际GPIO管脚设置
#define     WF_RESERT_KEY           0                     //wifi模组重置按键，请根据实际GPIO管脚设置
#endif

void data_handle(unsigned short offset)
{
	......
	#ifndef WIFI_CONTROL_SELF_MODE
		case WIFI_STATE_CMD:                                    //报告Wi-Fi工作状态指令
    		wifi_work_state = wifi_data_process_buf[offset + DATA_START];     //查询联网状态值
			wifi_uart_write_frame(WIFI_STATE_CMD, MCU_TX_VER, 0);
		......
}

/**
* @brief  MCU主动查询当前wifi工作状态
* @param  Null
* @return wifi work state
* -          SMART_CONFIG_STATE: smartconfig配置状态
* -          AP_STATE: 热点配置状态
* -          WIFI_NOT_CONNECTED: WIFI配置成功但未连上路由器
* -          WIFI_CONNECTED: WIFI配置成功且连上路由器
* -          WIFI_CONN_CLOUD: WIFI已经连接上云服务器
* -          WIFI_LOW_POWER: WIFI处于低功耗模式
* -          SMART_AND_AP_STATE: WIFI smartconfig&热点配网模式
* @note   如果为模组自处理模式,MCU无须调用该函数
*/
unsigned char mcu_get_wifi_work_state(void)     //MCU主动调用该函数查询当前wifi联网状状态值
{
	return wifi_work_state;
}

上报所有 DP 状态函数

上报所有DP状态函数all_data_update()定义在protocol.c文件中，作用是上报所有DP状态。应用步骤如下：

在串口数据处理函数data_handle()中，收到模组发来的设备状态查询;

MCU 需要调用all_data_update() 函数上报所有 DP 状态，用于面板同步设备状态。

all_data_update()内调用的分别是不同数据类型的 DP 上报函数，如mcu_dp_bool_update()函数就是上报bool型的数据，形参是上报的 DP ID 和 DP 数据。以此类推，mcu_dp_value_update()函数是数值型 DP 上报函数，mcu_dp_enum_update()是枚举型 DP 上报函数。

void data_handle(unsigned short offset)
{
	......
    case STATE_QUERY_CMD:                                   //状态查询指令
			all_data_update();
       	break;
    	......
}

/**
* @brief  系统所有dp点信息上传,实现APP和muc数据同步
* @param  Null
* @return Null
* @note   MCU需要实现该函数内数据上报功能
*/
void all_data_update(void)
{
	#error "请在此处理可下发可上报数据及只上报数据示例,处理完成后删除该行"
	/*
    //此代码为平台自动生成，请按照实际数据修改每个可下发可上报函数和只上报函数
    mcu_dp_bool_update(DPID_SWITCH,当前开关); //BOOL型数据上报;
    mcu_dp_value_update(DPID_PM25,当前PM2.5); //VALUE型数据上报;
    mcu_dp_enum_update(DPID_MODE,当前模式); //枚举型数据上报;
	   mcu_dp_value_update(DPID_FILTER_LIFE,当前滤芯寿命); //VALUE型数据上报;
	   mcu_dp_bool_update(DPID_ANION,当前负离子); //BOOL型数据上报;
    mcu_dp_value_update(DPID_COUNTDOWN_LEFT,当前倒计时剩余时间); //VALUE型数据上报;
 */
}

设备配网

设备配网功能是指通过 MCU 发送配网指令，或者拉低模组配网管脚使模组进入配网状态，并使用客户端 App（如 涂鸦智能）与设备交互完成配网操作连接到云端。本章节介绍如何让模组进入配网状态和模组的配网方式。

Wi-Fi 设备配网类型

热点配网：也称 AP 配网。自处理模式下对应的指示灯慢闪，所以又称慢闪配网模式。配网原理是设备先进入热点模式，客户端 App 连接设备热点后发送配网路由信息及配网标识码给模组，模组拿到后去连接配网路由，连接到云端，特点是配网可靠性强，操作较快连配网复杂。
快连配网：也称 EZ 配网，或快连配网。自处理模式下对应的指令灯快闪，又称快闪配网。配网原理是手机 App 广播配网路由信息及配网标识码，路由器转发，模组拿到后去连接配网路由，连接到云端，特点是配网操作简单，但受路由影响存在一定的失败概率。
蓝牙配网（Wi-Fi 蓝牙双模模组）：原理是模组蓝牙广播产品信息，客户端 App 收到后与设备去建立蓝牙连接，建立连接后将配网路由信息通过蓝牙发送给模组，模组拿到后去连接配网路由，连接到云端。蓝牙配网的特点是发现快，可靠性强，配网操作简单，Wi-Fi 蓝牙双模模组只要进入配网状态，蓝牙配网功能就默认处于开启状态。

不同配网类型的配置方式说明如下：

配网方式说明：通过产品信息里的n字段配置，可选择只有热点配网方式，或者热点与快连共存配网方式。
配网超时说明：只有模组工作模式选择超时配网模式或者防误触模式时，模组才存在配网超时时间，配网超时后模组进入配网低功耗状态，配网超时时间可通过产品信息里的 mt 字段配置。

设备只有进入配网状态，才能配合客户端 App 或者小程序进行配网操作。使用涂鸦智能 App 配网操作参考 App 使用指南。除此之外，使用涂鸦 IoT App SDK 开发方案还可能用到串口配网，更多详情请参考设备配网。

当需要对设备进行配网操作，需要先让模组进入待配网状态，才可以使用 App 进行配网绑定，Wi-Fi模组的配网状态有下列三种：

状态 1：Wi-Fi 快连配网配置状态
状态 2：热点联网配置状态
状态 7：Wi-Fi 快连配网和热点联网配置状态

网络状态介绍，请参考串口协议。

常见的使用场景根据模组工作方式有两种：

MCU 与模组配合处理模式：MCU 发送重置指令给到 Wi-Fi 模组，模组进入配网状态。一般的方式是在设备上做配网按键，需要配网时操作配网按键触发 MCU 发送重置指令给 Wi-Fi 模组，使模组进入配网状态。
模组自处理模式：Wi-Fi 检测重置按键 GPIO 入口低电平持续 5 秒以上，模组进入配网状态。

指令列表

配网流程涉及以下协议指令：

重置 Wi-Fi 指令：0x04
重置 Wi-Fi 并选择配网方式指令：0x05

仅 MCU 与模组配合处理模式支持下列协议指令。
这两个指令二选一即可，但建议选择0x04重置指令，两种配网方式同时开发，应对不同的需求。配网模式的触发机制可以自定义，通过指示灯快闪和慢闪进行区分。
只需 MCU 与模组成功完成一次重置指令（0x04或0x05）交互即可完成重置配网操作，不应同时发送0x04和0x05指令。

以下介绍各指令的详细信息。

重置 Wi-Fi 指令（`0x04`）

重置配网操作可以让设备重新进入配网状态。指令详细介绍，请参考 Wi-Fi通用串口协议。MCU 每发送一次 0x04 命令字，模组进入配网状态或切换一次配网方式。第一次默认配置为快连模式，之后在快连与热点之间来回切换。

基础功能

可通过配置产品信息回复中的 n 字段配合可选择的模组配网方式。

重置 Wi-Fi 并选择配置模式（`0x05`）

根据 MCU 发送的参数不同，可指定进入快连或热点配网模式。此指令与 0x04 指令作用相同，区别是可指定进入哪种配网模式。指令详细介绍，请参考 Wi-Fi通用串口协议。

基础功能

功能协议示例

推荐使用涂鸦模组调试助手协助调试，可快速了解模组初始化流程。以下协议示例，均由模组调试助手展示。

重置 Wi-Fi
重置 Wi-Fi 并选择配置模式

MCU SDK 示例

重置配网函数

重置配网函数 mcu_reset_wifi() 定义在 mcu_api.c 文件中，作用是发送重置配网指令到模组。应用步骤如下：

MCU 主动调用该函数，自定义在什么时刻启动配网。

在串口数据处理函数data_handle()中，若接收到模组回复重置指令将重置标志reset_wifi_flag置有效，通过mcu_get_reset_wifi_flag()函数返回reset_wifi_flag，判断重置 Wi-Fi 是否成功。

/**
* @brief  MCU主动重置wifi工作模式
* @param  Null
* @return Null
* @note   1:MCU主动调用,通过mcu_get_reset_wifi_flag()函数查询重置wifi是否成功
*         2:如果为模组自处理模式,MCU无须调用该函数
*/
void mcu_reset_wifi(void)
{
	   reset_wifi_flag = RESET_WIFI_ERROR;
    wifi_uart_write_frame(WIFI_RESET_CMD, MCU_TX_VER, 0);   //发送重置指令 0x04
}

void data_handle(unsigned short offset)
{
    ......
    case WIFI_RESET_CMD:                                    //重置wifi指令
 		   reset_wifi_flag = RESET_WIFI_SUCCESS;           //模组返回重置wifi成功
 	   break;
 	   ......
}

/**
* @brief  MCU查询复位wifi成功标志
* @param  Null
* @return 复位标志
* -           0(RESET_WIFI_ERROR):失败
* -           1(RESET_WIFI_SUCCESS):成功
* @note   1:MCU主动调用mcu_reset_wifi()后调用该函数查询复位状态
*         2:如果为模组自处理模式,MCU无须调用该函数
*/
unsigned char mcu_get_reset_wifi_flag(void)                //主动调用该函数可查询重置结果
{
	   return reset_wifi_flag;
}

重置并选择配置模式函数

重置 Wi-Fi 选择配置模式函数mcu_set_wifi_mode()定义在mcu_api.c文件中，作用是发送重置配网指令到模组，选择发送不同数据，可指定模组进入快连配网或热点配网模式。应用步骤如下：

MCU 主动调用该函数，自定义在什么时刻启动配网并选择配网模式。

在数据处理函数data_handle()中，若接收到模组回复重置指令将重置标志set_wifimode_flag置有效，通过mcu_get_wifimode_flag()函数返回set_wifimode_flag，判断重置 Wi-Fi 是否成功。

/**
* @brief  MCU设置wifi工作模式
* @param[in] {mode} 进入的模式
* @ref        0(SMART_CONFIG):进入smartconfig模式
* @ref        1(AP_CONFIG):进入热点配网模式
* @return Null
* @note   1:MCU主动调用
*         2:成功后,可判断set_wifi_config_state是否为TRUE;TRUE表示为设置wifi工作模式成功
*         3:如果为模组自处理模式,MCU无须调用该函数
*/
void mcu_set_wifi_mode(unsigned char mode)
{
    unsigned char length = 0;
    set_wifimode_flag = SET_WIFICONFIG_ERROR;
    length = set_wifi_uart_byte(length, mode);      //写入选择的配置模式（smartconfig/热点配网模式）
    wifi_uart_write_frame(WIFI_MODE_CMD, MCU_TX_VER, length); //发送重置配网并选择配置模式指令
}

void data_handle(unsigned short offset)
{
	   ......
    case WIFI_MODE_CMD:                   //重置配网并选择配置模式指令
 		   set_wifimode_flag = SET_WIFICONFIG_SUCCESS;  //重置wifi并配置模式返回成功
 	   break;
 	   ......
}

/**
* @brief  查询设置wifi状态成功标志
* @param  Null
* @return wifimode flag
* -           0(SET_WIFICONFIG_ERROR):失败
* -           1(SET_WIFICONFIG_SUCCESS):成功
* @note   1:MCU主动调用mcu_set_wifi_mode()后调用该函数查询复位状态
*         2:如果为模组自处理模式,MCU无须调用该函数
*/
unsigned char mcu_get_wifimode_flag(void)         //主动调用该函数可查询重置结果
{
   	   return set_wifimode_flag;
}

数据传输

数据传输功能概述

实现设备远程控制最直接相关的功能就是下发上报。模组下发控制指令，设备执行并上报自身状态。本章节介绍了协议中与数据传输相关的指令。

在涂鸦 IoT 平台修改 DP 后，您需要先将设备移除重新配网才能生效，否则上报调试过程可能报错。

上报处理说明

上报原则：除回复0x08查询状态指令需要上报所有 DP 状态外，其他时刻建议只有 DP 状态变化时才上报。
免过滤设置：使用0x07上报数据时，如果是同一 DP 的连续相同数据，模组端会对数据过滤，不进行上报。这种情况是为了避免重复的数据上报，如果是特殊应用场景需要连续上报相同数据，如绘制表格，有两种处理方案：
- 后台配置：联系您的涂鸦客户经理或者技术支持，针对 DP 做免过滤语法配置，设置后设备重新配网生效。
- 使用同步上报指令0x22：同步上报的数据，模组端不做过滤处理，参考上报拓展功能。

请避免频繁上报，即使是特殊功能需要，也不建议高频上报，会对模组及云端产生未知影响，可能造成设备离线或者数据丢失等问题，建议上报频率低于每秒 1 帧。

数据传输链路

智能化设备的数据传输链路分为下发和上报：

下发链路：面板的控制指令通过 App 发送到云端，云端下发给模组，模组通过串口协议指令发送给 MCU。
上报链路：MCU 通过串口协议指令把设备状态发送给模组，模组上报到云端，云端把设备状态给到 App。

上面介绍的数据传输链路是广域网控制，要求设备完成配网操作，连接到云端。除了广域网控制，设备与App之间还可以通过局域网和蓝牙实现短距离控制：

局域网控制：设备完成配网后，配网路由的广域网断开，设备与手机都处于配网路由下。此时 App 可以与设备通过局域网完成数据传输。
蓝牙控制：此控制功能仅适用于 Wi-Fi 蓝牙双模模组，在设备完成配网，同时断开广域网与局域网连接时，手机与设备处于蓝牙连接范围。此时 App 可以与设备通过蓝牙完成数据传输。

不同模组固件在断开广域网与局域网连接后，到建立蓝牙控制时需要的时间不等，一般在数秒到2分钟以内，测试时请注意观察。

指令列表

配网流程涉及以下协议指令：

下发指令：0x06
异步上报指令：0x07

以下介绍各指令的详细信息。

下发指令（`0x06`）

指令详细介绍，请参考 Wi-Fi通用串口协议。

设备与 App 建立连接的情况下，App 可以实现对设备的远程控制指令下发。模组把来自 App 的控制指令，用串口协议数据格式发送给 MCU。MCU 收到控制指令后需要执行下列操作：

调用 0x07 指令回复下发指令。如下发开关关闭指令：
- 模组发送：55 AA 00 06 00 05 01 01 00 01 00 0D
- MCU 回复：55 AA 03 07 00 05 01 01 00 01 00 11
  
  MCU需回复相同的DP控制数据
MCU 执行控制指令内容。如收到空净设备开关关闭指令，MCU 应执行关闭空净动作。

下发指令链路说明：设备已连上路由器且连接到云端，即联网状态值为 0x04。此时 App 的控制指令是走广域网下发，也可能是走局域网下发。若广域网断开，设备与手机处于同一局域网下，即联网状态值为0x03（ Wi-Fi已配置且连上路由器），此时 App 的控制指令是走局域网下发。

异步上报指令（`0x07`）

指令详细介绍，请参考 Wi-Fi通用串口协议。异步上报指令有三个应用场景：

回复 0x08 查询指令，需要使用 0x07 上报指令上报设备所有 DP 状态。
回复 0x06 下发指令，应用介绍见下发指令 0x06 介绍。
设备状态变化时，需主动调用 0x07 上报变化后的DP状态

使用注意事项：

数据长度说明：指DP数据的长度，不是指整帧数据长度。数据长度根据DP数据类型和DP数量确定，数据内容不满数据长度的，前边补充 0 即可。数据类型介绍参考串口协议-状态数据单元。
Enum 类型数据：枚举型数据，数据值范围为 0~255，需要注意不论枚举值是什么，上报的数据值都是从 0 开始计的数值，如枚举型 DP 工作模式work_type，枚举值: cold, warm, auto, air, dehumidify，对应的上报数值为0,1,2,3,4，即上报 dehumidify 时，需要上报的对应数值为 4；又比如枚举型 DP 百分比 level,枚举值：0,20,40,60,80,100，对应的上报值为 0,1,2,3,4,5，即上报 60 时，需要上报的对应数值为 3。另外需要注意的是如果修改 DP 数值，需要重新对应上报数值，如上述的 DP 工作模式 work_type，把auto删掉，枚举值变为：cold, warm, air, dehumidify，重新配网测试时，再上报dehumidify时，需要上报的对应数值变为 3。
Bitmap 类型数据：支持多故障同时上报。每一个 bit 位可代表一个警告，置 1 表示发生故障，置 0 表示无故障。可以为 1、2 或 4 字节，大于1 字节时为大端模式。如 MCU 发送：55 aa 03 07 00 06 0d 05 00 02 00 09 2C（同时上报故障 bit0 和故障 bit3 ）。如果需要配置告警推送及故障提示文案，可以参考推送设备消息。
String 类型数据：字符串的含义与显示需与面板配套，自定义的可与面板沟通。字符串信息需要转换成十六进制的 ASCII 码上报。如 MCU 发送：55 AA 03 07 00 08 6E 03 00 04 74 65 73 74 46（上报数据74 65 73 74对应字符test）。
Raw 类型数据：透传型数据，通常用于比较复杂的功能实现，不建议用户自行使用。需要注意的是，Raw 型数据是完全透传传输，但数据传输过程中会对 Raw 型数据进行 Base64 加解密操作。云端日志查询的 Raw 型数据，是经过 Base64 加密的，若需要调试查看，需自行解密校对数据。
- 上报过程中，模组对 Raw 型数据进行 Base64 加密，App 对 Raw 型数据进行 Base64 解密。
- 下发过程中，App 对 Raw 型数据进行 Base64 加密，模组对 Raw 型数据进行 Base64 解密。
组合上报：组合上报是指多个 DP 数据格式组合上报，减少数据帧交互，例如当前温度，模式放在同一帧上报，MCU 发送：55 aa 03 07 00 0d 03 02 00 04 00 00 00 19 04 04 00 01 00 {校验和}（当前温度25度，模式选择为smart）

功能协议示例

下发功能：红色框标出的控制指令下发，下发后需对应上报回复。
上报功能：上下图中绿色框标出的为上报指令，分别有回复下发指令上报、DP 状态变化主动上报、回复 08 查询上报。

MCU SDK 示例

下发数据处理函数

下发数据处理函数data_point_handle()定义在system.c文件中，作用是处理模组下发的 DP 控制指令。

应用步骤如下：

在串口接收数据处理函数data_handle()中，收到模组发来的 DP 控制指令。
调用data_point_handle()函数接收下发帧的数据单元，检测数据格式是否正确。

data_point_handle()函数调用 DP 下发处理函数dp_download_handle()进行处理，dp_download_handle()会针对dpid调用相应的处理函数执行控制指令，并把变化后的状态上报。

void data_handle(unsigned short offset)
{
    ......
    case DATA_QUERT_CMD:                                    //命令下发指令
 		   total_len = (wifi_data_process_buf[offset + LENGTH_HIGH] << 8) | wifi_data_process_buf[offset + LENGTH_LOW];
 		   for(i = 0;i < total_len; ) {
 			   dp_len = wifi_data_process_buf[offset + DATA_START + i + 2] * 0x100;
 			   dp_len += wifi_data_process_buf[offset + DATA_START + i + 3];
 			   //
 			   ret = data_point_handle((unsigned char *)wifi_data_process_buf + offset + DATA_START + i);                           //数据状态单元判断返回
 			   if(SUCCESS == ret) {
 				   //成功提示
 			   }else {
 				   //错误提示
 			   }
 			   i += (dp_len + 4);
 		   }
 	   break;
 	   ......
}

/**
* @brief  下发数据处理
* @param[in] {value} 下发数据源指针
* @return 返回数据处理结果
*/
static unsigned char data_point_handle(const unsigned char value[])
{
   unsigned char dp_id,index;
   unsigned char dp_type;
   unsigned char ret;
   unsigned short dp_len;

   dp_id = value[0];
   dp_type = value[1];
   dp_len = value[2] * 0x100;
   dp_len += value[3];

   index = get_dowmload_dpid_index(dp_id);
   if(dp_type != download_cmd[index].dp_type) {
	   //错误提示
	   return FALSE;
   }else {
	   ret = dp_download_handle(dp_id,value + 4,dp_len);          //数据状态单元处理返回
   }
   return ret;
}

异步上报函数

异步上报函数根据dp数据类型分为：mcu_dp_raw_update()、mcu_dp_bool_update()、mcu_dp_value_update()、mcu_dp_string_update()、mcu_dp_enum_update()、mcu_dp_fault_update()，这些函数定义在mcu_api.c文件中，作用是异步上报dp状态。如dp1数据类型是bool型，上报就调用mcu_dp_bool_update()。

/**
* @brief  bool型dp数据上传
* @param[in] {dpid} dpid号
* @param[in] {value} 当前dp值
* @return Null
* @note   Null
*/
unsigned char mcu_dp_bool_update(unsigned char dpid,unsigned char value)
{
    unsigned short send_len = 0;

    if(stop_update_flag == ENABLE)
    	   return SUCCESS;
    send_len = set_wifi_uart_byte(send_len,dpid);
    send_len = set_wifi_uart_byte(send_len,DP_TYPE_BOOL);
    //
    send_len = set_wifi_uart_byte(send_len,0);
    send_len = set_wifi_uart_byte(send_len,1);
    //
    if(value == FALSE) {
 	   send_len = set_wifi_uart_byte(send_len,FALSE);
    }else {
 	   send_len = set_wifi_uart_byte(send_len,1);
    }
    wifi_uart_write_frame(STATE_UPLOAD_CMD, MCU_TX_VER, send_len);   //启动上报
    return SUCCESS;
}

下一步

实现了 Wi-Fi 设备的 基础功能 后，您可以继续实现 拓展功能。

上一篇协议应用

下一篇拓展功能

基础功能

模组初始化

功能概述

指令列表

心跳检测指令（0x00）

查询产品信息指令（0x01）

设备新功能设置指令（0x37子命令0x00）

查询工作模式指令（0x02）

报告设备联网状态指令（0x03）

查询设备状态指令（0x08）

功能协议示例

MCU SDK示例

心跳包检测函数

产品信息回复函数

查询工作模式函数

查询 Wi-Fi 状态函数

上报所有 DP 状态函数

设备配网

Wi-Fi 设备配网类型

指令列表

重置 Wi-Fi 指令（0x04）

重置 Wi-Fi 并选择配置模式（0x05）

功能协议示例

MCU SDK 示例

重置配网函数

重置并选择配置模式函数

数据传输

数据传输功能概述

数据传输链路

指令列表

下发指令（0x06）

异步上报指令（0x07）

功能协议示例

MCU SDK 示例

下发数据处理函数

异步上报函数

下一步

心跳检测指令（`0x00`）

查询产品信息指令（`0x01`）

设备新功能设置指令（`0x37`子命令`0x00`）

查询工作模式指令（`0x02`）

报告设备联网状态指令（`0x03`）

查询设备状态指令（`0x08`）

重置 Wi-Fi 指令（`0x04`）

重置 Wi-Fi 并选择配置模式（`0x05`）

下发指令（`0x06`）

异步上报指令（`0x07`）