Wi-Fi 串口协议（HomeKit）

本文适用于用户对接同时具有连接涂鸦 IoT 和苹果 HomeKit 生态的能力的 Wi-Fi 模组。用户使用 MCU 的串口，根据此协议，实现与涂鸦模组的串口通信，组成同时具有涂鸦生态和苹果 HomeKit 生态的设备。

串口通信约束

• 波特率：9600
• 数据位：8
• 奇偶校验：无
• 停止位：1
• 数据流控：无
• MCU：用户控制板控制芯片，与涂鸦模组通过串口对接。

帧格式说明

字段	字节数	说明
帧头	2	固定为0x55aa
版本	1	升级扩展用
命令字	1	具体帧类型
数据长度	2	大端
数据	N	实体数据
校验和	1	从帧头开始按字节求和得出的结果对256求余

• 所有大于1个字节的数据均采用大端模式传输。

• 一般情况下，采用同命令字一发一收同步机制，即一方发出命令，另一方应答，若发送方超时未收到正确的响应包，则超时传输，如下图所示：

  

  说明：具体通信方式以 协议详述 章节中为准。

• 模组控制命令下发及MCU状态上报则采用异步模式，假设模组控制命令下发“命令字”为x，MCU状态上报“命令字”为y，如下所示：

  • 模组控制命令下发：

    

  • MCU 状态上报：

    

状态数据单元

datapoint 命令/状态数据单元如下所示：

数据段	字节数	说明
dpid	1	datapoint 序号
type	1	对应开放平台上某 datapoint 具体的数据类型，详细信息见如下type字段说明
len	2	长度对应 value 的字节数，详细信息见如下type字段说明
value	1/2/4/N	hex 表示，大于 1 字节采用大端传输

type字段解释：

type	类型	对应长度len（字节）	说明
0x00	raw	N	对应于 raw 型 datapoint（模组透传）
0x01	bool	1	范围：0x00/0x01
0x02	value	4	对应 int 类型，大端表示
0x03	string	N	对应于具体字符串
0x04	enum	1	枚举类型，范围 0-255
0x05	bitmap	1/2/4	长度大于 1 字节时，大端表示

• datapoint 命令/状态数据单元除”raw”类型外，其他类型均属于“obj”型 datapoint
• “状态数据”可含多个 datapoint“命令数据单元”

协议详述

心跳检测

• Wi-Fi模组上电后，以15s的间隔定期发送心跳，若在超时时间（3s）内，未收到MCU的回应，则认为MCU离线。

• MCU侧也可依据此心跳定期检测模组是否正常工作，若模组无心跳下发，则MCU可通过模组提供的硬件复位引脚复位Wi-Fi模组。

模组发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x00
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：55 aa 00 00 00 00 ff

MCU返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x00
数据长度	2	0x0001
数据	1	0x00：MCU重启后第一次心跳返回值，仅发送一次，用于模组判断工作过程中MCU是否重启 0x01：除MCU重启后第一次返回0外，其余均返回此值
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：55 aa 03 00 00 01 00 03（MCU第一次返回）

55 aa 03 00 00 01 01 04（除第一次外，正常返回）

查询产品信息

产品信息由product ID、MCU软件版本构成：

• product ID：对应 涂鸦开发者平台 的PID(产品标识)，由涂鸦开发者平台生成，用于云端记录产品相关信息
• MCU软件版本号格式定义：采用点分十进制形式，”x.x.x”（0<=x<=99），x为十进制数

如果使用HomeKit能力，模组在发完此命令并收到回复之后，将发送HomeKit服务配置命令。但如果是MCU OTA导致的重启，则不再发送HomeKit服务配置，将直接发送查询MCU和设定模组的工作模式。

模组发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x01
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：55 aa 00 01 00 00 00

MCU返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x01
数据长度	2	N
数据	N	{“p”:”AIp08kLIftb8x***”,“v”:”1.0.0”,”pt”:19}
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：{“p”:”AIp08kLIftb8x***”,“v”:”1.0.0”,”pt”:19}

产品信息字段说明:

• p 表示产品ID为AIp08kLIftb8x***,也就是用户在涂鸦IOT平台创建的产品ID。(必选)

• v 表示MCU版本为1.0.0,MCU的版本号格式需要按照x.x.x的格式定义。(必选)

• pt表示HomeKit产品品类（详细信息见附录1）(必选)

查询MCU和设定模组的工作模式

• 模组工作模式主要针对如何指示Wi-Fi的工作状态以及如何重置Wi-Fi而言，主要分两种情况：

  • MCU与模组配合处理，即模组通过串口通知MCU Wi-Fi当前的工作状态，由MCU提供显示支持；MCU检测出Wi-Fi的重置需求，通过串口通知模组重置Wi-Fi。
  • 模组自处理：Wi-Fi模组的工作状态通过Wi-Fi的GPIO引脚驱动LED状态显示；Wi-Fi重置通过检测GPIO输入需求处理。

• 模组自处理Wi-Fi重置方法为：Wi-Fi检测GPIO入口低电平持续5s以上触发Wi-Fi 重置。指示灯与按钮所使用的GPIO管脚由以下命令配置。

• 部分模组跨组IO设置,需要在设置组IO脚基础上加32，PB20设置序号为20+32

• 模组自处理LED显示状态列表

• 模组自处理硬件IO有效电平:

  按键低电平有效、LED灯低电平有效

涂鸦网络状态：

设备联网状态	描述	状态值
状态1	处于配网状态	间隔250ms亮灭
状态2	模组已配置但未未连上路由器	常灭
状态3	连上路由器但未连上云端	常灭
状态4	连接到云端	常亮

HomeKit网络状态：

设备联网状态	描述	状态值
状态1	待绑定或绑定中	间隔250ms亮灭
状态2	未连接	常灭
状态3	已连接	常亮
状态4（特殊）	HomeKit配件提示，用于提示设备连接（用完即弃，不可改变之前的网络状态）	闪烁3次

模组发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x02
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：0x55aa 00 02 0000 01

MCU返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x02
数据长度	2	0x0000/0x0003 0x0000：指示模组工作为“MCU与模组配合处理”模式，MCU需实现上述“说明”中提及的功能。 0x0003：指示模组工作为“模组自处理”模式。
数据	0/3	数据长度为3： 第一字节为涂鸦的Wi-Fi状态指示GPIO序号； 第二字节为HomeKit的Wi-Fi状态指示GPIO序号； 第三字节为Wi-Fi重置按键GPIO序号
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：0x55aa 03 02 0000 04（MCU与模组配合处理）

0x55aa 03 02 0003 0c 0d 0e 2e（模组自处理，涂鸦指示灯0x0c：GPIO12，HomeKit指示灯0x0d：GPIO13，复位按钮0x0e：GPIO14）

报告设备联网状态

涂鸦联网状态：

设备联网状态	描述	状态值
状态1	处于配网状态	0x00
状态2	模组已配置但未连上路由器	0x01
状态3	连上路由器但未连上云端	0x02
状态4	连接到云端	0x03

HomeKit联网状态：

设备联网状态	描述	状态值
状态1	待绑定或绑定中	0x00
状态2	未连接	0x01
状态3	已连接	0x02
状态4（特殊）	HomeKit配件提示，用于提示设备连接（用完即弃，不可改变之前的网络状态）	0x03

• 特别注意：状态4是一个特殊的状态通知，不可作为网络状态使用。模组发送状态4，表示用户发送了配件识别，需要设备5s内有所反馈，例如网络指示灯闪烁3次（闪烁完之后，需要恢复到之前的网络状态），或蜂鸣器响3声。在模组自处理模式时，采用HomeKit网络指示灯闪烁3次来提供配件识别。
• 当模组检测到MCU重启或MCU断线再上线的过程，则主动下发Wi-Fi状态至MCU。
• 当模组的Wi-Fi状态发生变化，则主动下发Wi-Fi状态至MCU。
• 网络状态标志用来区分Wi-Fi网络状态来自涂鸦配网还是HomeKit配网。
• 如设置模组工作模式为“模组自处理”，则MCU无需实现该协议。

模组发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x03
数据长度	2	0x0002
数据	1	网络状态标志： 0x00：涂鸦配网Wi-Fi网络状态 0x01：HomeKit配网Wi-Fi网络状态
	1	若是涂鸦网络状态值： 0x00:状态1 0x01:状态2 0x02:状态3 0x03:状态4 若是HomeKit网络状态值： 0x00:状态1 0x01:状态2 0x02:状态3 0x03:状态4（特殊）
校验和	1	从帧头开始按字节求和得出的结果对256求余

MCU返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x03
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

重置Wi-Fi

• HomeKit设备有两种账号体系并且互不干涉，使用涂鸦智能 App配网后的设备可以再被同一局域网下的ios手机进行hap绑定，也可以先使用ios手机进行hap绑定，然后在同一局域网下使用涂鸦智能 App 配网。但使用涂鸦智能 App 配网时，只能使用蓝牙配网。

• 关于绑定与重置的说明：

  • 配对hap，手机移除hap，设备仍处于连接局域网状态，可以直接进行hap绑定，不经过配网过程。

  • 配对hap，再绑定涂鸦智能 App ，可以共同控制，移除涂鸦智能 App ，重启，仍然保留原来的hap配对状态，可以重新绑定涂鸦智能 App。

  • 配对hap，再绑定涂鸦智能 App ，可以共同控制，再移除hap，不重启，仍然保留原来的涂鸦智能 App 配对状态，可以重新绑定hap。

  • 配对andriod 涂鸦智能 App ，涂鸦智能 App 移除，设备直接进入配网状态。

  • 配对andriod 涂鸦智能 App ，再用另一台ios手机绑定，涂鸦智能 App 移除，ios手机仍能正常控制设备。

• 模组自处理Wi-Fi重置方法为：Wi-Fi检测GPIO入口低电平持续5s以上触发Wi-Fi 重置。如设置模组工作模式为“模组自处理”，则MCU无需实现该协议。

MCU发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x04
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：55 aa 03 04 00 00 06

模组返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x04
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：55 aa 00 04 00 00 03

命令下发

• “命令下发”可含多个datapoint“状态数据单元”

• “命令下发”为异步处理协议，对应于MCU的datapoint“状态上报”

模组发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x06
数据长度	2	取决于“命令数据单元”类型以及个数
数据	N	“状态数据单元”组
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：系统开关对应3号DP,使用bool型变量，开机数值为1

55 aa 00 06 00 05 03 01 00 01 01 10

状态上报

• datapoint状态数据单元说明详见“状态数据单元”。

• “状态上报”为异步处理协议，“状态上报”触发机制有三类：

  • MCU收到“命令下发处理帧时，正确执行相应datapoint命令，再通过“状态上报”帧将变化后的datapoint状态发送至模组；
  • MCU主动检测到datapoint有变化，将变化后的datapoint状态发送至模组；
  • MCU收到状态查询帧时，将所有的datapoint状态发送至模组。

• “状态上报”可含多个datapoint“状态数据单元”。

MCU发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x07
数据长度	2	取决于“状态数据单元”类型以及个数
数据	N	“状态数据单元”组
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：湿度对应5号DP,使用value型变量，湿度为30%

55 aa 03 07 00 08 05 02 00 04 00 00 00 1e 3a

“多个状态数据单元”上报样例：

DP 点 109 bool 型变量，数值为 1

DP 点 102 string 型变量，“201804121507”（具体传输对应 ASCII 值）

55 aa 03 07 00 15 6d 01 00 01 01 66 03 00 0c 32 30 31 38 30 34 31 32 31 35 30 37 62

状态查询

• “状态查询”为异步处理协议，主要用于模组查询MCU所有的“obj”类型的datapoint状态，当MCU收到此帧时，通过状态上报帧上报datapoint状态。

• 当MCU收到此帧时，需要将涂鸦智能 App 状态和HomeKit状态都上报。否则会导致状态显示不一致和其他问题。

• “状态查询”发送时机主要有两种：

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

模组发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x08
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：55 aa 00 08 00 00 07

MCU升级服务

• 何时升级由客户在涂鸦开发者平台自己的产品页面配置相关升级选项触发，模组仅作为支持MCU升级的数据传输通道，也不对数据内容做任何解析。

• 目前涂鸦平台的MCU升级支持下面四种升级方式的配置：

  • App提醒升级：这个升级方式用户每次进入设备控制面板都会收到升级提醒的弹窗，是否确认升级由用户自己在App确认
  • App静默升级：这个升级方式App不会有任何提醒弹窗，模组上电后一分钟内会去自动去检测升级发现有高版本的升级包会自动开始拉取相关升级包，第一次上电后模组会间隔24小时去云端检测一次是否有升级包配置。
  • App强制升级:
    这个升级方式App端会有升级提醒弹窗，如果用户不确认升级用户就没法正常使用这个产品的控制面板。
  • App检测升级:这个升级方式App端不会有任何升级提醒的弹窗，必须要用户在App端自己去点击相关固件版本检测，如果有高版本的固件配置才会显示升级提示信息。

• MCU升级相关流程图：
  Wi-Fi模组发送完所有的升级包，重新发送01命令字（查询产品信息），MCU需要在一分钟回复产品信息中的MCU软件版本号（升级后的版本号），版本号需要和在涂鸦后台配置升级的版本号保持一致。

升级启动（升级包大小通知）

升级启动方式含自动及手动升级。当处于自动升级时，模组检测云端MCU有更新版本固件，则自动启动与MCU升级包交互流程；当处于手动升级时，通过App确定，模组才启动与MCU升级包交互流程

模组发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0a
数据长度	2	0x0004
数据	4	固件包字节数，unsigned int，大端
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：55 aa 00 0a 00 04 00 00 68 00 75

表示固件包长度26624，即26KB。

MCU返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x0a
数据长度	2	0x0001
数据	1	升级包分包传输大小： 0x00：默认256byte（兼容旧固件） 0x01：512byte 0x02：1024byte
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：55 aa 03 0a 00 01 00 0d

升级包传输

• 升级包传输数据格式：包偏移 + 包数据。

• MCU若收到该帧数据长度为4字节，并且包偏移 >= 固件大小，则包传输结束。

模组发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0b
数据长度	2	0x0004+数据包长度
数据	N	前四字节，固定为包偏移，后面为数据包内容
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：

若要升级的文件大小530Byte，(最后一包数据可不回复)

1. 第一包数据，包偏移为0x00000000，数据包长度为256
   55 aa 00 0b 01 04 00000000 xx…xx XX
2. 第二包数据，包偏移为0x00000100，数据包长度为256
   55 aa 00 0b 01 04 00000100 xx…xx XX
3. 倒数第2包数据，包偏移为0x00000200，数据包长度为18
   55 aa 00 0b 00 16 00000200 xx…xx XX
4. 最后一包，包偏移为0x00000212，数据包长度为0
   55 aa 00 0b 00 04 00000212 xx...xx XX

MCU返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x0b
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：55 aa 03 0b 00 00 0d

获取系统时间(格林时间)

说明:

• 格林时间不带有时区和夏令时的因素，是一个国际标准的时间基准。

• 当模组连接上网络后，本地的时间戳校准完成才会返回成功，并携带有效的时间数据。

MCU发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x0c
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：55 aa 03 0c 00 00 0e

模组返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0c
数据长度	2	0x0007
数据	7	数据长度为7字节: Data[0]为是否获取时间成功标志，为0表示失败，为1表示成功 Data[1]为年份, 0x00表示2000年 Data[2]为月份，从1开始到12结束 Data[3]为日期，从1开始到31结束 Data[4]为时钟，从0开始到23结束 Data[5]为分钟，从0开始到59结束 Data[6]为秒钟，从0开始到59结束
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：格林时间2016年4月19日5时6分7秒

55 aa 00 0c 00 07 01 10 04 13 05 06 07 4c

获取本地时间

说明:

• 本地时间是在格林时间的基础上加上当地(设备激活所在地)时区和夏令时的时间。

• 当模组连接上网络后，本地的时间戳校准完成才会返回成功，并携带有效的时间数据。

MCU发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x1c
数据长度	2	0x0000
数据	xxxx	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

模组返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x1c
数据长度	2	0x0008
数据	Data	数据长度为8字节: Data[0]为是否获取时间成功标志，为0表示失败，为1表示成功 Data[1]为年份, 0x00表示2000年 Data[2]为月份，从1开始到12结束 Data[3]为日期，从1开始到31结束 Data[4]为时钟，从0开始到23结束 Data[5]为分钟，从0开始到59结束 Data[6]为秒钟，从0开始到59结束 Data[7]为星期，从1开始到7结束，1代表星期一
校验和	1	从帧头开始按字节求和得出的结果对256求余

• 如设备在国内激活使用，则当地时间为北京时间(东8区)。
  例：北京时间2016年4月19日5时6分7秒
  55 aa 00 1c 00 08 01 10 04 13 05 06 07 02 5f

• 如果设备在国外激活使用，则当地时间为设备所处时区时间。

Wi-Fi功能性测试（扫描指定路由）

• 模组内部目前扫描指定的SSID：tuya_mdev_test，返回扫描结果和信号强度百分比。

• 这里为了最大程度防止不良品这里建议客户将路由于设备距离控制在5米左右，信号强度大于等于60%为合格，这里可以根据自己产线和工厂环境的情况自行调整。

MCU发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x0e
数据长度	2	0x0000
数据	Data	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

模组返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0e
数据长度	2	0x0002
数据	2	数据长度为2字节： Data[0]: 0x00失败, 0x01成功; 当Data[0]为0x01，即成功时，Data[1]表示信号强度 (0-100, 0信号最差，100信号最强) 当Data[0]为0x00，即失败时， Data[1]为0x00表示未扫描到指定的SSID，Data[1]为0x01表示模组未烧录授权key
校验和	1	从帧头开始按字节求和得出的结果对256求余

获取模组内存

说明：获取 Wi-Fi模组剩余内存。

MCU发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x0f
数据长度	2	0x0000
数据	Data	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

模组返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0f
数据长度	2	0x0004
数据	4	数据长度为4字节,大端格式： 如0x00 0x00 0x28 0x00代表剩余10240字节内存
校验和	1	从帧头开始按字节求和得出的结果对256求余

获取当前Wi-Fi信号强度（可选）

MCU发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x24
数据长度	2	0
数据	N	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

模组返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x24
数据长度	2	0x0001
数据	Data	0x00：表示失败 小于0：表示信号强度，如(-60db)
校验和	1	从帧头开始按字节求和得出的结果对256求余

通知Wi-Fi模组关闭心跳（可选）

MCU发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x25
数据长度	2	0
数据	N	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

模组返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x25
数据长度	2	0
数据	N	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

说明：对于需要休眠降低功耗的MCU模组，可在休眠前发送该指令关闭Wi-Fi模组心跳，方便进入休眠状态。该指令请勿在设备刚上电时发送，Wi-Fi模组上电后需要和MCU建立心跳连接。

获取当前Wi-Fi联网状态

MCU发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x2B
数据长度	2	0x0000
数据	Data	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

模组返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x2B
数据长度	2	0x0001
数据	1	与报告设备联网状态保持一致
校验和	1	从帧头开始按字节求和得出的结果对256求余

获取模组MAC

MCU发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x2d
数据长度	2	0x0000
数据	Data	无
校验和	1	从帧头开始按字节求和得出的结果对256求余

模组返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x2d
数据长度	2	0x0007
数据	Data	data[0]: 获取MAC地址是是否成功的标志： 0x00表示成功，表示后面6字节的MAC地址有效 0x01表示获取MAC失败，表示后面6字节的MAC无效 data[1]~data[6]:当获取MAC地址标志位data[0]表示成功则表示模组有效的MAC地址
校验和	1	从帧头开始按字节求和得出的结果对256求余

模组拓展服务

获取Wi-Fi模组相关数据信息

• 针对有些产品需求，需要知道Wi-Fi模组的一些运行数据情况，都统一使用这个字段用于获取。

• MCU可根据自己所需要的数据发送对应功能编码来获取。当MCU需要多种数据时请按照对应编码，依次顺序排列发送给Wi-Fi模组；

• 若MCU需要获取当前所有支持的数据，使用0xff编码即可。

注意：

• 此字段数据格式为json字符串的形式，data数据长度不一定。
• Mcu发送命令的数据长度至少有2个字节，即子命令+1字节data 编码，若长度不对则返回失败。
• 数据编码是一一对应关系，请勿使用错误，且不可使用预留编码。
• 模组返回数据字段说明表：模组运行信息字段说明表

MCU发送:

字段	长度	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x34
数据长度	2	0x01+0x01+…N
数据	1	子命令0x07
	Data（1）	0x01 –预留 0x02 -国家码 0x03 -模组SN ……… 0xFF -获取所有当前已经支持的数据内容（此编码只在第一字节有效，且优先级最高，解析到此编码时即推送所有信息）
	Data（2）	0x01 –预留 0x02 -国家码 0x03 -模组SN ………
	Data(N)	0x01 –预留 0x02 -国家码 0x03 -模组SN ………
校验和	1	从帧头开始按字节求和得出的 结果对 256 求余

示例： 55 AA 03 34 00 02 07 02 41

模组返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x34
数据长度	2	0x02+N
数据	1	0x07(子命令)
	1	执行结果： 0x00：成功 0x01：失败 （当执行失败后，无后续data内容）
	{ “cc” :xx, “sn” :”xxx” }	cc：国家码（可选） sn：模组SN（可选）
校验和	1	从帧头开始按字节求和得出的 结果对 256 求余

HomeKit能力

说明：此部分命令为HomeKit设备需要用到的命令。

初始化交互流程：

注意：从模组发送心跳到MCU回复模组工作模式，时间不要超过3s。

HomeKit状态数据单元

数据段	字节数	说明
服务序号	1	进行服务配置时，发送的服务序号
特性字符串标识长度	1	特性字符串标识长度
特性字符串标识	n	特性字符串标识（详细信息见附录3）
type	1	数据类型，通过如下type字段说明
len	2	长度对应value的字节数
value	1/2/4/N	hex表示，大于1字节采用大端传输

type字段解释：

类型	表示值	长度（字节）	说明
bool	0x00	1	value范围：0x00/0x01
uint	0x01	4	无符号整形（uint8, uint16, uint32），大端表示
int	0x02	4	有符号整形，大端表示
64bit uint	0x03	8	64位无符号整形（uint64），大端表示
float	0x04	4	浮点型数据，前两个字节表示整数部分，后两个字节表示小数部分，大端表示
string	0x05	N	字符串类型数据
raw	0x06	N	透传型数据

HomeKit服务配置查询

• 模组发送此命令作为HomeKit相关配置开始标志。MCU收到此命令之后开始按照流程图的提示发送HomeKit所需的服务和特性配置信息。

• MCU在发送完所有HomeKit配置信息之后，再回复此命令的返回。

模组发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x36
数据长度	2	0x0001
数据	1	0x01(子命令)
校验和	1	从帧头开始按字节求和得出的结果对256求余

MCU返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x36
数据长度	2	0x0001
数据	1	0x01(子命令)
校验和	1	从帧头开始按字节求和得出的结果对256求余

HomeKit服务配置

• 此命令需要在查询产品信息之后，查询模组工作方式之前进行交互。

• 同一个设备可以配置多个相同的服务，为避免混淆，使用服务序号来对每个服务进行区分和管理。如果有相同的服务，使用服务序号就可以区分。如果没有相同的服务，为了格式统一，也使用服务序号来管理不同服务。

• 对于有多个服务的品类，服务之间会有链接关系，需要注意有主服务和其他服务的区分。主服务请放在服务配置的第一个服务，其他服务放在之后。

• 服务序号在HomeKit命令下发和上报时使用。

• 每个服务都会包含一些特性（附录3），模组会自动添加必选特性。可选特性需要MCU发送可选特性配置帧来添加。

MCU发送：

字段		字节数	说明
帧头		2	0x55aa
版本		1	0x03
命令字		1	0x36
数据长度		2	0x0001+2N+M1+M2+…+Mn
数据		1	0x02(子命令)
	第1个服务	1	服务序号。建议从0开始，每增加一个服务，序号加1.
			1
		M1	服务字符串标识（详细信息见附录2）
	第2个服务	1	服务序号
		1	服务字符串标识长度
		M2	服务字符串标识（详细信息见附录2）
	-	-	-
	第N个服务	1	服务序号
		1	服务字符串标识长度
		Mn	服务字符串标识（详细信息见附录2）
校验和		1	从帧头开始按字节求和得出的结果对256求余

模组返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x36
数据长度	2	0x0002+N 或 0x0002
数据	1	0x02(子命令)
	1	数据处理结果： 0x00：成功。之后的服务配置结果数据有效。 0x01：失败。不再发送服务配置结果数据。
	N	第1个服务配置结果： 0x00：成功 0x01：失败
		第2个服务配置结果
		-
		第N个服务配置结果
校验和	1	从帧头开始按字节求和得出的结果对256求余

HomeKit命令下发

HomeKit命令/状态数据单元说明详见“HomeKit命令/状态数据单元”

模组发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x36
数据长度	2	0x0001+N
数据	1	0x03(子命令)
	N	“HomeKit命令/状态数据单元”组
校验和	1	从帧头开始按字节求和得出的结果对256求余

HomeKit状态上报

• HomeKit命令/状态数据单元说明详见“HomeKit命令/状态数据单元”

• 2“状态上报”为异步处理协议，“状态上报”触发机制有三类：

  • MCU收到HomeKit命令下发帧时，正确执行相应HomeKit命令，然后将变化后的HomeKit状态发送至模组；
  • MCU主动检测到HomeKit有变化，主动将变化后的HomeKit状态发送至模组；
  • MCU收到状态查询帧时，将所有的HomeKit状态发送至模组。

• “状态上报”可含多个“HomeKit命令/状态数据单元”

MCU发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x36
数据长度	2	0x0001+N
数据	1	0x04(子命令)
	N	“HomeKit命令/状态数据单元”组
校验和	1	从帧头开始按字节求和得出的结果对256求余

HomeKit可选特性配置（可选）

• 每种HomeKit服务一般都有必选特性和可选特性。必选特性模组会默认添加，可选特性需要用此命令添加。

• MCU发送服务配置帧，然后会收到模组回复，如果服务配置成功，可以接着发此命令配置可选特性。

• 如果MCU不发此命令，则模组注册服务只包含必选特性。

• 此命令需要在MCU发送服务配置查询回复帧之前发。

MCU发送：

字段		字节数	说明
帧头		2	0x55aa
版本		1	0x03
命令字		1	0x36
数据长度		2	0x0001+2N+M1+M2+…+Mn
数据		1	0x05(子命令)
		1	服务序号。与服务配置对应
	第1个可选特性	1	可选特性字符串标识长度
		M1	可选特性字符串标识（见附录3）
	第2个可选特性	1	可选特性字符串标识长度
		M2	可选特性字符串标识（见附录3）
	-	-	-
	第N个可选特性	1	可选特性字符串标识长度
		Mn	可选特性字符串标识（见附录3）
校验和		1	从帧头开始按字节求和得出的结果对256求余

模组返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x36
数据长度	2	0x0002+N 或 0x0002
数据	1	0x05(子命令)
	1	数据处理结果： 0x00：成功。之后的可选特性配置结果数据有效。 0x01：失败。不再发送可选特性配置结果数据。
	N	第1个可选特性配置结果： 0x00：成功 0x01：失败
		第2个可选特性配置结果
		-
		第N个可选特性配置结果
校验和	1	从帧头开始按字节求和得出的结果对256求余

HomeKit特性有效值配置（可选）

说明：

• 有些特性的取值在某些产品中没有使用，可以使用此命令配置有效值。

• 例如：当前空气净化器状态特性，默认的枚举值有0：关；1：空闲；2：工作中，三个取值，如果设备不需要使用1：空闲，需要MCU发送此命令将有效值配置成0：关；2：工作中。

• 此命令需在配置完相应服务和特性之后，MCU回复36-01命令之前进行发送。

• 如果MCU不发此命令，则模组注册特性时将按照默认配置。

• 此命令的有效值配置目前只支持uint8数据类型的特性。

注意：

如果某个特性存在未使用的取值，并且没有配置有效值，可能会导致苹果认证测试不通过。

MCU发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x36
数据长度	2	0x0001+N
数据	1	0x06(子命令)
	{ “service_serial”:xx, “char_str”:“xx”, “val_type”:xx, “valid_val”:[xx,xx,xx] }	service_serial：字段值表示要配置的特性所属的服务的服务序号。 char_str：字段值表示要配置的特性的字符串标识。 val_type:字段值表示要配置的特性的取值类型 0：表示修改有效值。常用于当前空气净化器状态、空气质量这类特性。 1：表示修改取值范围，常用于转速、PM2.5浓度这类特性。 其他：预留 valid_value：字段值为数组形式。 当val_type为0时，数组的元素则为有效值列表，元素个数取决于有效值个数； 当val_type为1时，数组的元素则为新取值范围的最小值和最大值，元素个数为2个，第1个元素为最小值，第2个元素为最大值；
校验和	1	从帧头开始按字节求和得出的结果对256求余

例：空气净化器服务的服务序号是0，将当前空气净化器状态特性的有效值中的空闲（idle）去掉。

55 AA 03 36 00 44 06 7B 22 73 65 72 76 69 63 65 5F 73 65 72 69 61 6C 22 3A 30 2C 22 63 68 61 72 5F 73 74 72 22 3A 22 41 39 22 2C 22 76 61 6C 5F 74 79 70 65 22 3A 30 2C 22 76 61 6C 69 64 5F 76 61 6C 22 3A 5B 30 2C 32 5D 7D 96

模组返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x36
数据长度	2	0x0002
数据	1	0x06(子命令)
	1	数据处理结果： 0x00：成功。 0x01：失败。service_serial未找到。 0x02：失败。char_str未找到。 0x03：失败。val_type不支持。 0x04：失败。valid_val配置不合要求。 0x05：失败。参数错误。 0x06：失败。不在可配置阶段。 0x07：失败。模组数据处理失败。 其他：预留
校验和	1	从帧头开始按字节求和得出的结果对256求余

设备新功能设置通知命令

说明：

• 此命令在设备上电后，建议在0x02命令之前发送执行，用于相关功能设置通知；

• 此命令每次上电或者是模组启动之后均需要发送；

• 若无所需要的新增功能，此命令字不需要执行。

• 此命令会根据业务的拓展，功能字段也会扩充增加。

MCU 发送：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x03
命令字	1	0x37
数据长度	2	0x0001+N
数据	1	子命令：0x00
	{“mcu_ota”:xx}	mcu_ota ：MCU OTA执行方式设置; 0：MCU有程序暂存区 1：MCU无程序暂存区
校验和	1	从帧头开始按字节求和得出的结果对256求余

模组返回：

字段	字节数	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x37
数据长度	2	0x0002
数据	1	子命令：0x00
	1	Ret： 0x00：成功； 0x01：数据字段内容不合法； 0x02：设置执行失败；
校验和	1	从帧头开始按字节求和得出的结果对256求余

字段说明：

mcu_ota：设置选择mcuota执行方式。

• MCU 无程序暂存区的OTA

  此升级方式其实是将Wi-Fi模组充当MCU的升级程序暂存区，最大支持1.5M（1572864个字节）的OTA文件，升级时，Wi-Fi模组先将升级包从云端获取存储到Wi-Fi模组本地，待Wi-Fi模组正确拉取升级包完成后，Wi-Fi模组通过串口通知MCU开始升级。

• 在升级时请注意设备保持上电状态。若升级过程中发生断电等异常升级失败的情况，Wi-Fi模组会一直重试，直到升级成功。Wifi模组在每次的启动时均会判断升级状态，若是升级失败，会从0x0A命令字开始，重新触发升级，直到升级成功。

• MCU OTA升级OTA图 MCU OTA 升级流程示意图。

注意：

• 此命令在模组启动后发送，且每次模组的重新启动后均需要重新发送此命令。
• MCU的Bootload需要支持0x0A和0x0B命令。
• MCU OTA和Wi-Fi OTA不可同时触发。若触发了MCU OTA则必须等待MCU OTA成功后再触发Wi-Fi OTA，反之同理。

附录一：HomeKit产品品类列表

品类	数值
桥接器	2
风扇	3
车库门	4
照明	5
锁	6
插座	7
开关	8
恒温器	9
传感器	10
安全系统	11
电动门	12
窗户	13
窗帘	14
可编程开关	15
（预留）	16
摄像头	17
门铃	18
空气净化器	19
加热器	20
空调	21
加湿器	22
除湿机	23
洒水器	28
水龙头	29
淋浴系统	30

附录二：HomeKit服务列表

服务	服务字符串标识
附件信息	“3E”
协议信息	“A2”
车库门开关	“41”
照明	“43”
锁管理	“44”
锁定机构	“45”
开关	“49”
插座	“47”
恒温器	“4A”
空气质量传感器	“8D”
安全系统	“7E”
一氧化碳传感器	“7F”
接触传感器	“80”
门	“81”
湿度传感器	“82”
泄漏传感器	“83”
光敏感器	“84”
运动传感器	“85”
占用感应器	“86”
烟雾传感器	“87”
无状态可编程开关	“89”
温度传感器	“8A”
窗户	“8B”
窗帘	“8C”
电池服务	“96”
二氧化碳传感器	“97”
电扇	“B7”
板条	“B9”
过滤器的维护	“BA”
空气净化器	“BB”
加热器冷却器	“BC”
加湿器除湿机	“BD”
服务标签	“CC”
浇灌系统	“CF”
阀	“D0”
水龙头	“D7”

附录三：HomeKit特性点

特性英文描述	字符串标识	中文描述
administrator_only_access	“1”	管理员只访问
brightness	“8”	亮度
cooling_threshold_temperature	“D”	冷却温度阈值
current_door_state	“E”	当前门状态
current_heating_cooling_state	“F”	当前加热冷却状态
current_relative_humidity	“10”	当前的相对湿度
current_temperature	“11”	当前温度
firmware_revision	“52”	固件版本
hardware_revision	“53”	硬件版本
heating_threshold_temperature	“12”	加热温度阈值
hue	“13”	色彩
identify	“14”	识别
lock_control_point	“19”	锁控制点
lock_current_state	“1D”	锁定当前状态
lock_last_known_action	“1C”	锁定最后已知动作
lock_management_auto_security_timeout	“1A”	锁管理自动安全超时
lock_target_state	“1E”	锁定目标状态
logs	“1F”	日志
manufacturer	“20”	制造商
model	“21”	模型
motion_detected	“22”	运动检测
name	“23”	名称
obstruction_detected	“24”	障碍物检测
on	“25”	开/关
outlet_in_use	“26”	插座使用中
rOTAtion_direction	“28”	转动方向
rotation_speed	“29”	转速
saturation	“2F”	色饱和度
serial_number	“30”	序号
target_door_state	“32”	目标门状态
target_heating_cooling_state	“33”	目标加热冷却状态
target_relative_humidity	“34”	目标相对湿度
target_temperature	“35”	目标温度
temperature_display_units	“36”	温度显示单位
version	“37”	VERSION
air_particulate_density	“64”	空气微粒密度
air_particulate_size	“65”	空气微粒大小
security_system_current_state	“66”	安全系统当前状态
security_system_target_state	“67”	安全系统目标状态
battery_level	“68”	电池电量
carbon_monoxide_detected	“69”	一氧化碳检测
contact_sensor_state	“6A”	接触传感器状态
current_ambient_light_level	“6B”	当前环境光照等级
current_horizontal_tilt_angle	“6C”	当前水平倾斜角度
current_position	“6D”	当前位置
current_vertical_tilt_angle	“6E”	当前垂直倾斜角度
hold_position	“6F”	保持位置
leak_detected	“70”	泄漏检测
occupancy_detected	“71”	占用检测
position_state	“72”	位置状态
programmable_switch_event	“73”	可编程开关事件
status_active	“75”	工作状态活跃
smoke_detected	“76”	烟雾检测
status_fault	“77”	状态故障
status_jammed	“78”	状态阻塞
status_low_battery	“79”	低电量状态
status_tampered	“7A”	状态被篡改
target_horizontal_tilt_angle	“7B”	目标水平倾斜角
target_position	“7C”	目标位置
target_vertical_tilt_angle	“7D”	目标垂直倾角
status_security_system_alarm_type	“8E”	状态安全系统报警类型
charging_state	“8F”	充电状态
carbon_monoxide_level	“90”	一氧化碳水平
carbon_monoxide_peak_level	“91”	一氧化碳峰值水平
carbon_dioxide_detected	“92”	二氧化碳检测
carbon_dioxide_level	“93”	二氧化碳水平
carbon_dioxide_peak_level	“94”	二氧化碳峰值水平
air_quality	“95”	空气质量
accessory_flags	“A6”	附件标记
lock_physical_controls	“A7”	锁定物理控制
current_air_purifier_state	“A9”	空气净化器当前状态
current_slat_state	“AA”	当前板条状态
slat_type	“C0”	板条类型
filter_life_level	“AB”	过滤器使用寿命
filter_change_indication	“AC”	过滤器更换指示
reset_filter_indication	“AD”	重置过滤器指示
target_air_purifier_state	“A8”	目标空气净化器状态
target_fan_state	“BF”	目标风扇状态
current_fan_state	“AF”	当前风扇状态
active	“B0”	活动状态
swing_mode	“B6”	摇摆模式
current_tilt_angle	“C1”	当前倾斜角度
target_tilt_angle	“C2”	目标倾斜角度
ozone_density	“C3”	臭氧浓度
nitrogen_dioxide_density	“C4”	二氧化氮密度
sulphur_dioxide_density	“C5”	二氧化硫浓度
pm_2_5_density	“C6”	PM2.5浓度
pm_10_density	“C7”	PM10浓度
voc_density	“C8”	VOC密度
service_label_index	“CB”	服务标签索引
service_label_namespace	“CD”	服务标签名称空间
color_temperature	“CE”	色温
current_heater_cooler_state	“B1”	加热器冷却器状态
target_heater_cooler_state	“B2”	目标加热器冷却器状态
current_humidifier_dehumidifier_state	“B3”	当前加湿器除湿器状态
target_humidifier_dehumidifier_state	“B4”	目标加湿器除湿器状态
water_level	“B5”	水位
relative_humidity_dehumidifier_threshold	“C9”	相对湿度除湿器阈值
relative_humidity_humidifier_threshold	“CA”	相对湿度加湿器阈值
program_mode	“D1”	程序模式
in_use	“D2”	在使用中
set_duration	“D3”	设置时间
remaining_duration	“D4”	剩余时间
valve_type	“D5”	阀门类型
is_configured	“D6”	已配置
product_data	“220”	产品数据

附录四：模组运行信息字段

名称	说明	支持选项	读	写
cc	国家码	0：表示CN，包含区域：中国，韩国，新加坡，澳大利亚，日本（1-13），其他； 1：表示US，包含区域为：美国，中国台湾，加拿大； 2：表示JP，包含区域为：日本（1-14） 3：表示EU，包含区域为：欧洲	支持	不支持

附录五：MCU 无程序暂存区OTA升级流程示意图

更新说明

说明	修订日期	备注
创建文档	20200915	首次创建
修订文档	20201118	增加获取Wi-Fi模组相关数据信息中的国家码读取
修订文档	20201221	1. 增加洒水器、水龙头、淋浴系统，三个品类 2. 修改服务配置描述
修订文档	20210107	1. 新增设备新功能设置通知命令。 2. 支持MCU单备份OTA
修订文档	20210204	1. homekit网络状态兼容设备提示通知 2. 增加homekit特性有效值配置命令
修订文档	20210415	增加获取Wi-Fi模组相关数据信息中的模组SN读取命令