网关 Pro MCU 通用对接协议

涂鸦 Wi-Fi 串口协议是针对涂鸦 Wi-Fi 模组定制的串口协议，主要用于涂鸦 Wi-Fi 模组与其它 MCU 串口直连完成串口通信。

串口协议通信示意图如下。

串口通信要求

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

帧格式

字段	长度（字节）	说明
帧头	2	固定为 0x55aa
版本	1	MCU 软件版本号，升级扩展时使用
命令字	1	具体的命令字
数据长度	2	采用大端模式
数据	取决于具体数据	传输的数据
校验和	1	从帧头开始按字节求和，得出的结果对 256 求余。

基础协议

查询产品信息

产品信息由 PID（产品 ID）和 MCU 软件版本号构成。

• PID：对应涂鸦 IoT 平台的产品标识，由涂鸦 IoT 平台生成，用于云端记录产品相关信息。
• MCU 软件版本号：采用点分十进制形式，格式为：x.x.x，x 为十进制数并且 0<=x<=99。

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	支持以下两个版本： 0x00：不支持获取产品 PID 0x01：支持获取产品 PID
命令字	1	0x01
数据长度	2	0x0000
数据	0	无
校验和	1	从帧头开始按字节求和，然后将得出的结果对 256 求余

示例：0x55aa 00 01 0000 00

MCU 返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00 或 0x01
命令字	1	0x01
数据长度	2	N
数据	取决于具体数据	参见示例
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例：{"v":"1.0.0", "m":0, "cap":0, "p":"mhnmpqzf7ntzm***", "s":0,}

• v：MCU 版本号。示例为：1.0.0。

• m：配网方式。（网关 Pro 只支持默认配网）

  • 0：默认配网

• cap：设备支持的能力，取值为十六进制转十进制后的数值。比特位对应功能如下：

  • bit2：支持功能点（网关有DP功能）

  • bit4：支持 MCU 升级

  • bit5：群组控制指令支持 sub_id

  • 未用到的位默认置 0

    说明：例如，设备不支持本地群组（bit0 为 0），不支持本地场景（bit1 为 0），但支持功能点（bit2 为 1），即十六进制数据为 0000 0000 0000 0100，即 cap 值为 4。

• p：产品 PID。示例中 PID 为 mhnmpqzf7ntz****。

• s（可选）：是否为安防网关，需要安防能力支持，默认不支持安防能力。

  • 0：普通网关，无安防能力。
  • 1：安防网关，具备安防能力。

报告设备联网状态

• 当模组的联网状态发生变化，主动下发联网状态至 MCU。

设备联网状态	描述	状态值
状态2	AP 配置状态	0x01
状态3	Wi-Fi 已配置但未连上路由器	0x02
状态4	Wi-Fi 已配置且连上路由器	0x03
状态5	已连上路由器且连接到云端	0x04

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x03
数据长度	2	0x0001
数据	1	显示 Wi-Fi 工作状态。 0x01：状态 2 0x02：状态 3 0x03：状态 4 0x04：状态 5
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例：0x55aa 00 03 0001 00 03

MCU 返回

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

示例：0x55aa 00 03 0000 02

重置 Wi-Fi

说明：将网关解除绑定，Wi-Fi 状态恢复到 AP 配置状态。

MCU 发送

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

示例：0x55aa 00 04 0000 03

模组返回

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

示例：0x55aa 00 04 0000 03

允许子设备入网

App 发送允许入网指令至网关，允许子设备在指定时间内接入网络。

模组发送

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

MCU 返回

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

关闭子设备入网

App 发送关闭入网指令至网关。

模组发送

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

MCU 返回

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

添加子设备

• MCU 发送子设备入网请求至模块。
• pk_type 为可选字段，默认值为 1。
• channel 对于子设备需要 OTA 功能时一定要传输，默认为 10。硬件开发 > 新增自定义固件 > 升级通道号。

  注意：

  • 当前版本暂不支持子设备 OTA。
  • channel 配置错误可能导致 OTA 功能异常。

MCU 发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x08
数据长度	2	N
数据	N	数据示例： { “pk_type”:xx “sub_id”:“xxxx”, “pid”:“xxxx”, “ver”:“x.x.x”, “channel”:xxx, “ota”:x } 参数说明： pk_type: 用户自定义产品类型，可不传。 sub_id: 子设备标识，通常为 MAC 地址、芯片 ID 等，需要保证唯一性。不能为0000.0000等表示网关本身的通用标识。 pid： 产品 ID。 ver：版本号，例如：1.0.0。 channel：通道号。对应于涂鸦云创建产品后，上传拓展固件的升级通道号。默认值为 10。 ota：表示子设备是否支持 OTA 能力，默认不支持。0：表示不支持；1：表示支持。
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x08
数据长度	2	0x0001
数据	1	0x00：接收请求 0x01：拒绝请求 子设备实际是否入网成功，详见 返回添加设备结果
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

删除子设备

模块同步子设备删除信息到 MCU。

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x09
数据长度	2	N
数据	取决于具体数据	数据示例： { “sub_id”:“xxxx”, “devkey”:“xxx”, “tp”:xx } 参数说明： sub_id：需要删除的子设备 ID。 Devkey：可选，设备密钥，用于子设备移除。 tp： 0： 移除子设备。 1：App 恢复出厂设置。
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 返回

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

心跳检测

网关模组定时查询子设备心跳。查询周期和子设备数量相关，子设备数量越多，子设备心跳查询间隔越频繁。

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0A
数据长度	2	N
数据	取决于具体数据	数据示例：{ “sub_id”:“xxxx” } 参数说明：sub_id 为子设备 ID。
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 返回

说明： 在线的设备需要回复心跳，连续 2 个心跳周期不回复，则识别为设备离线。

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0A
数据长度	2	N
数据	取决于具体数据	数据示例：{ “sub_id”:“xxxx”,“lp”:x, “hb_time”:0 } 参数说明： sub_id：子设备 ID lp：子设备功耗类型 0：标准功耗设备 1：低功耗设备 hb_time：若用户需要自行管理心跳，则使用此字段。hb_time 为 0 的时候表示永久在线，并使用 0x2A 上报子设备状态
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

查询状态

用于同步子设备状态。

模组发送

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

MCU 返回（状态上报）

下发命令

控制命令下发。

• 功能点命令或状态数据部分除 raw 类型外，其他类型均属于 obj 型。
• 可同时下发多个功能点命令
• 命令下发为异步处理协议，对应于 MCU 的状态上报。

功能点命令或状态数据单元如下所示。

数据段	长度（字节）	说明
dpid	1	功能点序号
type	1	对应开放平台上功能点具体的数据类型： raw：raw 型功能点（模组输入） 表示值：0x00 长度（字节）：N bool：布尔型，取值为 0x00 或 0x01 表示值：0x01 长度（字节）：1 value：对应 int 类型，大端表示 表示值：0x02 长度（字节）：4 string：对应字符串 表示值：0x03 长度（字节）：N enum：枚举类型，取值范围 0~255 表示值：0x04 长度（字节）：1 bitmap：故障型，长度大于 1 字节时，大端表示 表示值：0x05 长度（字节）：1、2 或 4
len	2	长度对应 value 的字节数（大端）
value	1/2/4/N	hex 表示，大于 1字节采用大端传输

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0C
数据长度	2	N
数据	取决于具体数据	数据示例：id_len(1byte) + sub_id(nbyte)+ datapoint 参数说明： id_len: 子设备 ID 长度 sub_id: 子设备 ID。 说明：当 sub_id 为 0000 时，代表命令下发至网关自身（主设备）的功能点。 datapoint：控制命令功能点的集合
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

状态上报

子设备接收到命令下发后进行回复或接收到状态变化后主动推送该指令。

MCU 发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0D
数据长度	2	N
数据	取决于具体数据	数据示例：id_len(1byte) + sub_id(nbyte)+ datapoint 参数说明： id_len: 子设备 ID 长度 sub_id: 子设备 ID。 说明：当 sub_id 为 0000 时，代表命令下发至网关自身（主设备）的功能点。 datapoint: 控制命令功能点的集合
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

加入群组

支持将子设备加入本地群组。

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0E
数据长度	2	N
数据	取决于具体数据	数据示例：子设备12、34 和 56 加入群组 01，数据显示为{ "gid":"01", "cids":["12","34","56"] } 参数说明： gid：群组 ID cids：加入群组的子设备 ID 集合
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0E
数据长度	2	N
数据	取决于具体数据	数据示例：{ "gid":"12", "cids":["12","34","56"], "rets":[0,0,0] } 参数说明： gid：表示群组 ID cids：加入群组的子设备集合 rets：返回结果结合 0：添加成功 1：超过群组数上限 2：子设备超时 3：设置值超出范围 4：写文件错误 5：其他错误
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

群组子设备删除

本地群组子设备删除。

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0F
数据长度	2	N
数据	取决于具体数据	数据示例：子设备 12 从群组 01 中删除，{ "gid":"01", "cids":["12"] } 参数说明： gid：群组 ID cids：子设备 ID 集合
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x0F
数据长度	2	N
数据	取决于具体数据	数据示例：{ "gid":"01", "cids":["12"], "rets":[0] } 参数说明： gid：表示群组 ID cids：要删除群组的子设备集合 rets：返回结果结合 0：删除成功 1：超过群组数上限 2：子设备超时 3：设置值超出范围 4：写文件错误 5：其他错误
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

获取系统格林威治时间

MCU 发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x10
数据长度	2	0x0000
数据	0	示例：0x55aa 00 10 0000 0F
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x10
数据长度	2	0x0007
数据	7	数据示例：0x55aa 00 10 0007 01 10 04 13 05 06 07 50即格林威治时间 2016 年 4 月 19 日 5 时 6 分 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~31，即十六进制的 01~1f。十六进制 13 对应十进制数值为 19，即日期为 19 日。
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

获取本地时间

MCU 发送

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

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x11
数据长度	2	0x0008
数据	8	数据示例：0x55aa 00 10 0007 01 10 04 13 05 06 07 02 54即格林威治时间 2016 年 4 月 19 日 5 时 6 分 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 Data[7]：星期，范围为 1~7，1 表示周一
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

说明：

• 设备在国内激活：返回北京时间（东8区）。
• 设备在国外激活：返回设备所处时区时间。

批量添加设备

批量添加同一个 PID 的多个子设备。单次批量添加的子设备的上限为 32 。

注意：当前版本暂不支持子设备 OTA。

MCU 发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x12
数据长度	2	N
数据	取决于具体数据	数据示例： { "pid":" xxxx", "cids":["12","34","56"], "ver":"x.x.x","channel":xxx,"ota":x} 参数说明： pid：产品 ID cids：子设备 ID 集合 ver：版本号，例如1.0.0 channel：子设备升级通道号，对应于涂鸦 IoT 开发平台创建产品后上传拓展固件的升级通道号，默认为 10 ota：子设备是否支持 OTA 能力，默认不支持 0：不支持 1：支持
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x12
数据长度	2	N
数据	1	00：数据接收成功。 01：数据接收或者解析失败。
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

返回添加设备结果

设备添加完成后，通知 MCU 添加结果。

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x13
数据长度	2	N
数据	N	数据示例： { “cids”:[“12”,“34”,“56”], “rets”:[0,0,0], “key”:[“xxxx”,“xxx”], “virt_id”: [“xxxx”,“xxx”] } 参数说明： cids：子设备 ID 集合 channel：子设备升级通道号，对应于涂鸦 IoT 开发平台创建产品后上传拓展固件的升级通道号，默认为 10 ota：子设备是否支持 OTA 能力，默认不支持 0：不支持 1：支持 key：密钥，可选，目前仅单点设备支持该字段 virt_id：虚拟 ID，可选，目前仅单点设备支持该字段
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 返回

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

控制群组指令下发

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x14
数据长度	2	N
数据	取决于具体数据	数据示例：id_len(1byte) + grp_id(nbyte)+ datapoint 参数说明： id_len：群组 ID 长度 grp_id：群组 ID。 datapoint：控制命令功能点的集合
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 返回

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

Wi-Fi功能性测试

扫描指定的 SSID: tuya_mdev_test，返回扫描结果和信号强度百分比。

MCU 发送

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

模组返回

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

获取 Wi-Fi 状态

MCU 可根据此条命令获取 Wi-Fi 状态。具体 Wi-Fi 状态见 报告设备联网状态。网关在网络初始化完成前不会回复Wi-Fi 状态。

MCU 发送

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

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x16
数据长度	2	0x0001
数据	1	Wi-Fi 工作状态： 0x01：状态 2 0x02：状态 3 0x03：状态 4 0x04：状态 5
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

恢复出厂设置（可选）

本地（离线）恢复出厂指令，会导致云端信息和本地信息不同步，必须在设备在线状态下使用或者设备第一次激活前使用。

说明：本地恢复出厂（MCU 命令下发），蓝牙子设备不会挂到家庭下，而是直接删除。

MCU 发送

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

报告移除状态

网关收到移除或者恢复出厂命令时，会向 MCU 报告状态。

• 如果仅收到移除指令，网关只会移除配网，并不会删除子设备信息。下次联网时，子设备信息仍会在 App 上显示。
• 如果收到恢复出厂指令，网关会移除配网并且清除所有子设备信息。

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x18
数据长度	2	0x0001
数据	1	0x00：本地恢复出厂设置 0x01：远程移除 0x02：本地移除 0x03：远程恢复出厂设置 0x04：清除数据，但是网关不离网
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

本地删除子设备

MCU 发送删除子设备指令。

MCU 发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x19
数据长度	2	N
数据	取决于具体数据	示例：{ “sub_id”:“xxx” }
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x19
数据长度	2	0x0001
数据	1	0x00：删除成功 0x01：删除失败
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

本地允许/关闭添加子设备

MCU 发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x1A
数据长度	2	0x0003
数据	3	Data[0]: 00：关闭子设备添加 01：允许子设备添加 Data[1]: 允许添加时间（高字节） Data[2]: 允许添加时间（低字节）
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x1A
数据长度	2	0x0001
数据	1	00：成功 01：失败
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

查询子设备列表

MCU 可查询网关下所有子设备（MCU 管理的子设备）的列表。当列表数据大于 255 字节时分包发送。

MCU 发送

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

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x1C
数据长度	2	N
数据	取决于具体数据	数据示例：id(1byte)+sub_num(1byte)+sub1_len(1byte)+sub1_id+….. subn_len(1byte)+subn_id(1byte) 参数说明： id： 07： false：所有子设备地址已经发送完成。 true：后续仍有子设备地址，下一数据包中发送。 00-06：包序号，从 0 开始。 sub_num：本数据包中包含的子设备数量。 sub1_len：子设备 ID 长度。 sub1_id：子设备 ID。
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

远程升级服务

涂鸦 IoT 开发平台提供可视化配置选项，支持用户自行选择升级方式。模组仅作为支持 MCU 升级的数据传输通道，不对数据内容进行解析。

说明： Wi-Fi 模组发送完所有的升级包后发送 01 命令字查询产品信息 ，MCU 需要在一分钟内回复产品信息中的软件版本号和升级后的 MCU 版本号的合集。版本号需要和在涂鸦后台配置升级的版本号保持一致。

• MCU 远程升级方式：

  • App 提醒升级：App 端提供升级提醒弹窗，用户在 App 确认是否升级。
  • App 强制升级：App 端提供升级提醒弹窗，确认升级后才可以进行其他操作。
  • App 检测升级：App 端不提供升级提醒弹窗，用户需在 App 端自行检测固件版本，进行升级。

• App 自动升级（原静默升级）：App 端不提供提醒弹窗，固件上电后一分钟内进行升级检测，如果检测到高版本升级包则自动升级包下载和安装。自第一次上电后，每隔 24 小时进行升级检测。

• MCU 升级相关流程图：

  

MCU 启动升级

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x1D
数据长度	2	0x0004
数据	4	升级文件大小，大端模式
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 返回

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

MCU 升级包传输

• 升级包传输数据格式：包偏移（unsigned short） + 包数据。
• MCU 若收到该帧数据长度为 4 且包偏移大于等于固件大小，则包传输结束。

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x1E
数据长度	2	0x0004+m，m 为偏移字节
数据	offset_addr(4byte)+ pack(mbyte)	offset_addr: 包偏移地址 pack： 数据包内容
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

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

• 第一包数据，包偏移为 0x00000000，数据包长度为 256

  0x55aa 00 1e 0104 00000000 xx…xx XX

• 第二包数据，包偏移为 0x00000100，数据包长度为 256

  0x55aa 00 1e 0104 00000100 xx…xx XX

• 倒数第二包数据，包偏移为 0x00000200，数据包长度为 18

  0x55aa 00 1e 0016 00000200 xx…xx XX

• 最后一包，包偏移为 0x00000212，数据包长度为 0

  0x55aa 00 1e 0004 00000212 XX

MCU 返回

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

子设备启动升级

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x1F
数据长度	2	无
数据	取决于具体数据	数据示例：id_len(1byte) + sub_id(nbyte)+ file_size(4byte) 参数说明： id_len：子设备 ID 长度 sub_id：子设备 ID file_size：升级文件大小，大端模式
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 返回

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

子设备升级包传输

• 升级包传输数据格式：包偏移（unsigned short） + 包数据。
• MCU 若收到该帧数据长度为 4 且包偏移大于等于固件大小，则包传输结束。

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x20
数据长度	2	无
数据	取决于具体数据	数据示例：id_len(1byte) + sub_id(nbyte)+ offset_addr(4byte)+ pack(mbyte) 参数说明： id_len：子设备 ID 长度 sub_id：子设备 ID offset_addr：偏移地址 pack：数据包
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例：sub_id 为 1234，需要升级的文件大小 530 Byte。(最后一包数据可不回复。)

• 第一包数据，包偏移为 0x00000000，数据包长度为 256。

  0x55aa 00 20 0109 04 31 32 33 34 00000000 xx…xx XX

• 第二包数据，包偏移为 0x00000100，数据包长度为 256。

  0x55aa 00 20 0109 04 31 32 33 34 00000100 xx…xx XX

• 倒数第二包数据，包偏移为 0x00000200，数据包长度为 18。

  0x55aa 00 20 001B 04 31 32 33 34 00000200 xx…xx XX

• 最后一包，包偏移为 0x00000212，数据包长度为 0。

  0x55aa 00 20 0009 04 31 32 33 34 00000212 XX

MCU 返回

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

查询子设备版本号

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x21
数据长度	2	无
数据	取决于具体数据	数据示例：{"sub_id":"xxx"} 参数说明：sub_id 即子设备 ID
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x21
数据长度	2	无
数据	取决于具体数据	数据示例：{"sub_id":"xxx", "ver":"xx.xx.xx"} 参数说明： sub_id：子设备 ID ver：子设备固件版本号
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

控制群组指令下发（带 sub_id）

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x22
数据长度	2	N
数据	取决于具体数据	数据示例：grp_len(1byte) + grp_id(nbyte)+ sub_len(1byte) + sub_id(mbyte)+ datapoint 参数说明： grp_len：群组 ID 长度 grp_id：群组 ID sub_len：群组中指定子设备 ID 长度 sub_id：子设备 ID datapoint：控制命令数据点集合
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 返回

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

串口配网（一体式）

MCU 发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x23
数据长度	2	无
数据	取决于具体数据	数据示例：{ "s":"xxx", "p":"yyy", "t":"zzz" } 参数说明： s：SSID p：密码 t：Token，由 App 生成
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x23
数据长度	2	0x0001
数据	无	0x00：成功 0x01：不在配网状态 0x02：非法的 JSON 数据
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

查询 DP 状态

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x29
数据长度	2	N
数据	取决于具体数据	数据示例：{ "sub_id":"xxx", "dpid":[xx,xx,xx] } 参数说明： sub_id：设备 ID dpid：对应的 DPID 数组
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 返回状态上报

更新子设备在线/离线状态

MCU 发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x2A
数据长度	2	N
数据	取决于具体数据	数据示例：{"all":0,"cids":["xxx","xxx"],"state":1}或{"all":1,""state":1} 参数说明： all： 0：仅包含 cids 的数据 1：包括所有子设备，无需 cdis 字段 cids：设备 ID 组 state： 0：离线 1：在线
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x2A
数据长度	2	0x0001
数据	1	0x00：成功 0x01：失败
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

获取模组的 MAC 地址

说明： 目前返回的是 Wi-Fi 网卡地址。

MCU 发送

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

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x2B
数据长度	2	0x0007
数据	取决于具体数据	data[0]：获取 MAC 地址是否成功。 0x00：成功 0x01：失败 data[1]-data[6]：模组的 MAC 地址
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

记录型状态实时上报（带时间）

• 对于类似门锁等记录型的子设备，上报 DP 状态的同时也需要带上产生这些记录的时间戳。
• 此上报接口为同步上接口，MCU 数据上报后可以等待模组返回信息以判断上报是否成功。

MCU发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x2C
数据长度	2	N
时间	7	Data[0]：数据传输是否带时间标志位 0x00：不带后面的时间，模组认为时间数据无效不处理 0x01：上报当地时间（日期格式） 0x02：上报格林威治时间（日期格式） 0x03：时间数据位时间戳，精度到秒 Data[0]为 0x01 或 0x02 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[0]为 0x03 data[1]~data[4]：4字节时间戳，大端格式 data[5]~data[6]：用 0 填充
数据	取决于具体数据	数据示例：{ id_len(1byte)+sub_id(nbyte)+datapoint} 参数说明： id_len：子设备 ID 长度。 sub_id：子设备 ID。当 sub_id 为 0000 时，表示上报网关本身的 DP（主设备）。 datapoint：状态命令数据点集合。
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x2C
数据长度	2	0x0001
数据	1	0：成功 1：失败
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

查询子设备绑定状态

MCU 发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x2D
数据长度	2	N
数据	取决于具体数据	数据示例：{"sub_id":"xxx", "d_link":x "e_val":"xxx"} 参数说明： d_link：是否支持双链路，即子设备是否同时支持手机和网关绑定。 0：不支持 1：支持 e_val: 加密数值，可选字段。
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

模组回复

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x2D
数据长度	2	0x0007
数据	取决于具体数据	数据示例：{"sub_id":"xxx", "ret":x} 参数说明： sub_id: 子设备 ID。 ret：当前子设备绑定状态： 0：与网关绑定成功 1：网关中存在子设备记录但是未绑定（正在绑定中或云端没有该子设备记录） 3：与手机绑定，但是未和网关绑定 4：未与网关绑定，与手机绑定关系未知
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

查询群组中子设备信息

MCU 发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x2E
数据长度	2	N
数据	取决与具体数据	数据示例：{ "gid":"xxx", "idx":xx} 参数说明： gid：群组 ID。 idx：查询子设备的序号。例如，0 为查询第一个子设备。
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x2E
数据长度	2	N
数据	取决于具体数据	示例：{"gid":"xxx","sub_id":"xxxx" }
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

上报群组本地改变的 DP

MCU 发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x2F
数据长度	2	N
数据	取决于具体数据	数据示例：{"gid":"xxx", "dpid":xx} 参数说明： gid：群组 ID。 dpid：群组本地有改变的 DPID，模组收到该 DP 后会查询群组设备中的该 DP 最新状态。
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x2F
数据长度	2	0x0001
数据	1	0：成功 1：失败
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

拓展功能

带时区系统（格林威治）时间数据下发

MCU 发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x33
数据长度	2	0x0001
数据	1	命令字：0x03
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

示例：55 AA 00 33 00 01 03 36

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x33
数据长度	2	1+2+1+7
数据	11	子命令：1 字节，0x03。 时区：2 字节，示例：-750 表示西 7.5 区。 夏令时： 0x00：无 0x01：夏令时 时间数据， 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 求余

远程重启设备

MCU 发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x34
数据长度	2	2
数据	1	子命令：0x09
	状态	0：重启设备
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x34
数据长度	2	2
数据	1	子命令：0x09
	结果	0：成功 非 0：失败
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

打开/关闭 4G 通道

说明：本功能只对支持 4G 的模组有效。

MCU发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x72
数据长度	2	2
数据	1	子命令：0x01
	状态	0：关闭 4G 1：打开 4G
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0x72
数据长度	2	2
数据	1	子命令：0x01
	结果	0：成功 非 0：失败
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

安防传感扩展协议

此部分协议为安防相关功能指令，只描述指令内容。关于详细的对接流程，请参考 安防网关对接流程说明。

当前布防模式设置

用于设置当前的布防撤防模式。

• 进入布防模式后，需要在撤防后，再次设置布防模式。
• 当前此命令设置的布防延时时间无效，布防延时时间以 App 设置为准，布防延时字段数据请传 0。
• sub_id 字段传 NULL 代表网关本身。

MCU 发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xC0
数据长度	2	1+N
数据	取决于具体数据	子命令：0x00 示例：{ “mode”:“xxx”, “sub_id”:“xxxxx”, “delay”:xx} 参数说明： mode：布防模式： 0：撤防 1：在家布防 2：离家布防 sub_id：子设备 ID delay：延时布防时间 0：读取手机设置时间 非 0：延时时间，单位为秒
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xC0
数据长度	2	2
数据	1	子命令：0x00
	1	操作结果： 00：成功 非 00：失败
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

当前安防信息获取

用于获取当前的安防信息。

MCU 发送

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

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xC0
数据长度	2	1+N
数据	1	子命令：0x01
	取决于具体数据	示例：{操作结果} +{“mode”:“xxx”, “alarm”:x, “countdown”:x} 参数说明： 操作结果： 0：成功 1：失败 mode：布防模式： 0：撤防 1：在家布防 2：离家布防 alarm：报警状态 0：报警延时，报警中 非 0：无报警 countdown：布防延时状态 0：布防延时中 非 0：无布防延时
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

安防信息同步

当通过 App 设置安防信息后，模组以此条指令同步状态给 MCU。

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xC0
数据长度	2	1+N
数据	1	子命令：0x02
	取决于具体数据	示例：{“mode”:“xxx”, “delay”:xx, “sound”:x} 参数说明： mode：布防模式 0：撤防 1：在家布防 2：离家布防 delay：延时布防时间 0：无延迟 非 0：延时时长，单位为秒 sound：是否播放声音 0：需要播放 非 0：不需要播放
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 返回

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

设备安防事件同步

注意：收到撤防事件后，需要通过 DP32 上报取消报警，并设置模组报警状态。

安防事件模组通过本指令同步状态至 MCU。

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xC0
数据长度	2	1+N
数据	子命令	0x03
	取决于具体数据	示例：{ “status”:x, “data”:“xxx” } 参数说明： status：事件 0：撤防 1：进入布防 2：存在可忽略事件，触发声音播放 3：开始倒计时 data：事件信息 0：无倒计时 说明：目前仅当报警倒计时开启时，反馈倒计时时间。
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 返回

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

报警状态设置

注意：App 设置延迟报警，报警倒计时结束后，应设置模组报警状态，触发 App 报警。（未设置报警状态也能触发 App 报警，为云端容错逻辑，不建议这样使用。）

MCU 通过安防标准 DP32 有状态变化时，需要将状态同步给模组。

MCU 发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xC1
数据长度	2	2
数据	子命令	0x00
	报警状态	0：正常 非 0：报警中
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

模组返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xC1
数据长度	2	2
数据	子命令	0x00
	操作结果	0：成功 非 0：失败
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

设备报警延时状态同步

设备处于报警延时状态时，会通过此命令同步报警延时状态给 MCU。

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xC1
数据长度	2	2
数据	1	子命令：0x03
	1	报警延时状态。 0：报警延时未创建 1：报警延时进行中 2：报警延时结束
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xC1
数据长度	2	1
数据	1	子命令：0x03
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

新设备报警信息显示同步

此命令为新的设备报警信息同步，配合 01 命令字中 A 字段的 bit0 位使能，且使能后安防 0xc101 和 0xc102 命令字无需处理。

• 当前无 GP 字段。
• 非环境设备：非环境监测相关类设备。
• 环境设备：环境监测相关类设备等。
• 此命令统一用于报警信息同步命令，模组发送的数据内容不是固定的，会根据功能增加按照设备功能的支持情况，下发支持的字段数据。

目前预留多防区网关功能的字段。当前设备不返回此字段。

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xC1
数据长度	2	1+N
数据	1	子命令：0x04
	取决于具体数据	示例：{ “type”:x, “sub_id”:“xxx”, “dp_inf”:“xxx”, “gp”:“xxxx” } 参数说明： type：触发报警设备类型 0：非环境设备 1：环境设备 sub_id：设备 ID dpinf：触发报警 DP 信息，cJSON 字符串 gp：预留，为多防区功能使用，同步报警设备归属的防区。
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 返回

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

新设备报警状态同步

此命令为新的设备报警状态同步，配合 01 命令字中 A 字段的 bit0 位使能。

模组发送

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xC1
数据长度	2	2
数据	1	子命令：0x05
	Data	0：取消报警 1：报警中
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余

MCU 返回

字段	长度（字节）	说明
帧头	2	0x55aa
版本	1	0x00
命令字	1	0xC1
数据长度	2	1
数据	1	子命令：0x05
校验和	1	从帧头开始按字节求和，将得出的结果对 256 求余