串口协议

涂鸦蓝牙 Mesh 串口通用协议为涂鸦定制的蓝牙 Mesh 模组串口通用协议，主要用于涂鸦蓝牙 Mesh 模组与其它 MCU 串口直连做串口通信。涂鸦蓝牙 Mesh 串口通用协议适用于下图中的通讯方案架构。

串口通讯约定

名词	说明
波特率（bit/s）	9600/19200/115200 自适应波特率
数据位	8
奇偶校验	无
停止位	1
数据流控	无

名词解释

名词	说明
DP	一个 DP（Data Point） 指的是一个功能点或者一条/一对指令码。
PID	您在涂鸦 IoT 开发平台创建的每一个产品都会产生一个唯一的产品编号，即 PID（Product ID）。PID 关联了产品具体的功能点、App 控制面板、出货信息等所有跟这个产品相关的信息。PID 相当于产品的身份证。
Mesh 点播	点对点通信，也就是两个设备之间的通信，不允许第三个设备收到信息。
Mesh 组播	把网络中的节点分组，一个节点发出的信息，只有相同组号的组员才能收到。
Mesh 广播	一个设备上发出的信息所有设备都能接收到。
节点地址	同一个蓝牙 Mesh 网络，每个节点都有一个唯一的地址，可以理解为每个设备的门牌号。取值范围：0x0001~0x5FFF
组地址	同一个蓝牙 Mesh 网络的每个节点可以被同时划分到不同组内，每个组都有一个唯一的地址，可以理解为 几幢几单元、哪个小区。取值范围：0xC000~0xFEFF
广播地址	同一个蓝牙 Mesh 网络，广播命令可以被所有节点收到，广播命令需要填写的目的地址为广播地址，取值范围：0xFFFF

帧格式说明

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

DP 格式说明

数据段	长度（字节）	说明
dpid	1	功能点序号
type	1	对应平台上某功能点具体的数据类型，通过如下表示值标识
		类型	表示值	长度（字节）	说明
		raw	0x00	N	对应于 raw 型 datapoint
		bool	0x01	1	value 范围：0x00/0x01
		value	0x02	4	对应 int 类型，大端表示
		string	0x03	N	对应于具体字符串
		enum	0x04	1	枚举类型，范围 0-255
		bitmap	0x05	2001/2/4	长度大于 1 字节时，大端表示
len	2	长度对应 value 的字节数
value	1/2/4/N	hex 表示，大于 1 字节采用大端传输

通用对接协议

心跳包（CMD-0x00）

• 模组上电后，以 300 ms 的间隔定期发送心跳。收到 MCU 的心跳包回应后，模组会认为 MCU 正常工作。在 MCU 首次（上电或重启）回复心跳包后，模组会向 MCU 查询产品信息。

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

• 模组在获取 MCU 信息之后，正常功耗模式下以 10s 的间隔定期发送心跳。

• 模组在低功耗模式下，低功耗蓝牙 Mesh 设备添加到 Mesh 网络后，无心跳。每次蓝牙 Mesh 模组重启，仅向 MCU 返回当前配网状态信息。

  低功耗蓝牙 Mesh 模组在低功耗下无心跳，因此也无法检测 MCU 是否发生重启。

模组发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x00
4 5	2	数据长度	0x00 0x00
6	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

MCU 返回

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x00
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	仅 MCU 上电后第一次收到模组心跳包后的返回值，模组也可依据这一点判断工作过程中 MCU 是否重启。
0x01	除 MCU 重启后第一次返回 0x00 外，其余均返回 0x01。

获取 MCU 信息（CMD-0x01）

• Product key：固定为 8 字节，由涂鸦 IoT 开发平台生成，用于云端记录产品相关信息。
• 产品信息主要是 PID 信息。

模组发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x01
4 5	2	数据长度	0x00 0x00
6	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

MCU 返回

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x01
4 5	2	数据长度	0x00 0x0d
6~18	0x0d	Data	见下表
19	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

• Data 格式：

  1~8	9~13
  PID	保留字段，填充的是 MCU 软件版本号，但模组目前不对该字段做解析，字段保留。

• 示例：55 AA 00 01 00 0D 66 74 62 38 78 32 78 30 31 2E 30 2E 30 C0，表示 PID 为 ftb8x2x0，MCU 版本 为 1.0.0。

发送模组工作状态（CMD-0x03）

• 模组工作状态：0x00 表示未绑定，0x02 表示已绑定。
• 当模组收到 MCU 请求模组工作模式并且回复 CMD 0x02 后，则会向 MCU 下发模组工作状态。
• 当模组检测到模组状态发生变化，则主动下发模组的工作状态至 MCU。

模组发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x03
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status	工作状态说明	备注
0x00	未绑定	可以用手机搜索添加该设备，处于未被 App 绑定的状态
0x02	已绑定	处于已经被 App 绑定的状态

设备上电后，与 MCU 的主要交互流程如下：

重置模组（CMD-0x04）

将蓝牙模组从当前蓝牙 Mesh 网络移出，解除蓝牙绑定关系，模组变为未绑定状态。

MCU 发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x04
4 5	2	数据长度	0x00 0x00
6	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

示例：55 aa 00 04 00 00 03

模组回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x04
4 5	2	数据长度	0x00 0x00
6	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

示例：55 AA 00 04 00 00 03

命令下发（CMD-0x06）

• 功能点信息参考概述中 DP 格式说明部分。
• 命令下发 只包含单条功能点 命令数据单元。
• 命令下发 为异步处理协议，对应于 MCU 的 DP 状态上报，即当下发关灯 DP 时，MCU 通过 0x07 命令回复灯状态为关。

模组发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x06
4 5	2	数据长度 Len	Len 高 8 位 Len 低 8 位
6~6+Len-1	Len	datapoint	见下表
6+Len	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

• datapoint 格式：
  只包含单条 DP 数据。

  1	2	3~4	5~
  dp1_id	dp1_type	dp1_len	dp1_data

• 示例：55 aa 00 06 00 05 03 01 00 01 01 10，表示 MCU 下发的信息是：

  内容	对应字段	字段取值
  03	dp1_id	3
  01	dp1_type	bool
  00 01	dp1_len	1 byte
  01	dp1_data	true

MCU 返回

无

状态上报（CMD-0x07）

• 功能点参考 DP 格式说明章节。
• 状态上报 可含多个功能点 命令数据单元。
• 状态上报 为异步处理协议，状态上报 触发机制有三类：
  • MCU 收到命令下发处理帧时，正确执行相应功能点命令，再通过 状态上报 帧将变化后的功能点状态发送至模组。
  • MCU 主动检测到功能点存在变化，将变化后的功能点状态发送至模组。
  • MCU 收到状态查询帧时，将所有的功能点状态发送至模组。

MCU 发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x07
4 5	2	数据长度 Len	Len 高 8 位 Len 低 8 位
6~6+Len-1	Len	datapoint	见下表
6+Len	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

• datapoint格式：
  和下发不同，上报的 data point 可以包含多个 DP 数据。

  1	2	3~4	5~	…	n	n+1	n+2~n+3	n+4 ~
  dp_id	dp_type	dp_len	dp_data	…	dpN_id	dpN_type	dpN_len	dpN_data

• 示例：55 aa 00 07 00 05 03 01 00 01 01 11

模组返回

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x07
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	成功
0x01	失败

状态查询（CMD-0x08）

• 状态查询 为异步处理协议，主要用于模组查询 MCU 所有可上报的功能点状态。当 MCU 收到此帧时，通过 CMD 0x07 状态上报帧上报功能点状态。
• 状态查询 发送时机主要有两种：
  • 模组绑定接状态下，检查到 MCU 发生重启（通过 心跳 回复判断），查询发送。
  • 在 App 中打开对应设备的控制面板时，会触发查询。

模组发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x08
4 5	2	数据长度	0x00 0x00
6	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

示例：55 aa 00 08 00 00 07

MCU 返回

无

主动上报带回复（CMD-0x09）

• 功能点参考 DP 格式说明章节。
• 主动上报带回复 可含多个功能点 命令数据单元。
• 主动上报带回复 为阻塞式上报，只有当数据上报成功或者失败后，才会接收下一包数据。如果上一包数据还未回复 MCU 上报结果，此时输入数据会回复繁忙。
• 主动上报带回复 默认将数据上报两次，上报后会通过 CMD-0x0B 回复 MCU。

MCU 发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x09
4 5	2	数据长度 Len	Len 高 8 位 Len 低 8 位
6	1	模式	0x00
7	1	TID	包序号（MCU 自己维护，每次上报累加）
8~8+Len-3	Len	Data Point	见下表
8+Len	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

• Data Point 格式：（上报的 Data Point 可以包含多个 DP 数据）

  1	2	3~4	5~	…	n	n+1	n+2~n+3	n+4 ~
  dp_id	dp_type	dp_len	dp_data	…	dpN_id	dpN_type	dpN_len	dpN_data

模组返回

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x09
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	超时时间	单位：秒
8	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	成功
0x01	上报 busy，稍后再试

• 超时时间为 MCU 发送给模组上报消息后，一直等待结果回复的最大时间。如果超过这个时间未接收到回复，MCU 可判断为上报失败。

主动上报结果回复（CMD-0x0B）

此接口会回复 MCU 需要上报数据的结果，会带有上报的结果，同时也带有上报的具体信息（TID）。如果失败，MCU 可以再重新上报。

模组发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x0B
4 5	2	数据长度 Len	Len 高 8 位 Len 低 8 位
6	1	TID	包序号
7	1	Status	见下表
8+Len	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	成功
0x01	重传周期内未上报成功

MCU 返回

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x0B
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	成功
0x01	失败

产测相关接口

RF 射频测试（CMD-0x0E）

为了检测出厂后蓝牙模组的射频是否正常工作，需要测试模组的 RSSI 信号强度。
测试工具：通过涂鸦提供的蓝牙信标，发射名称为 ty_mdev 的广播信号。
测试步骤：首先将信标放在距离模组较近（0.5 米左右）的位置，然后通过串口发送该 RF 射频测试指令，模组会搜索蓝牙信标并返回信号强度值。一般，信号强度大于 -70db 认为模组射频工作正常。

MCU 发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x0E
4 5	2	数据长度	0x00 0x00
6	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

模组回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0x0E
4 5	2	数据长度 Len	Len 高 8 位 Len 低 8 位
6~6+Len-1	Len	Data	见下表
6+Len	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

Data	说明
{“ret”:true,“rssi”:“-55”}	信号强度为 -55db
{“ret”:false}	没有搜索到该信号

低功耗功能附加协议

使能低功耗功能（CMD-0xE5）

低功耗实现原理：MCU 通过三极管/MOS 管控制给蓝牙模组上电断电实现低功耗，同时设置进入低功耗模式后，设备上电会减少不必要的指令交互，快速完成初始化，以减少每次唤醒时间。流程参考下图：

对电路设计的要求：

MCU 上报数据注意事项：每次唤醒根据上报 DP 的长度来决定保持上电时长，(dp.len + 3) ÷ 4 × 400ms。

MCU 发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xE5
4 5	2	数据长度	0x00 0x01
6	1	Data	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

Data	说明
0x00	关闭低功耗功能
0x01	打开低功耗功能

模组回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xE5
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	设置成功
其他	设置失败

预控和 beacon 遥控器协议

使能预控和 beacon 遥控器（CMD-0xA1）

• 预控和遥控器默认不使能，需要通过此命令打开对应功能。
• 使能遥控器后，模组上电 60 秒内允许遥控器配对，60 秒后禁止遥控器配对。
• 遥控器最大配对数量为 5。若超出遥控器配对上限，会循环顶替，即最后一个配对的遥控器顶替第一个配对的遥控器。
• 该配置将永久存储，只需设置一次，支持掉电记忆。

MCU 发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xA1
4 5	2	数据长度	0x00 0x01
6	1	Data	见下表
6	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

Data	说明
0x00	关闭预控和 beacon 遥控器功能
0x01	打开 beacon 遥控器功能
0x02	打开预控功能
0x03	打开预控和 beacon 遥控器功能

模组回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xA1
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	设置成功
其他	设置失败

Beacon 遥控器数据通知（CMD-0xB0)

该服务的前提是需要使能 beacon 遥控器功能。

模组发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB0
4 5	2	数据长度	Len 高 8 位 Len 低 8 位
6	len	Data	见下表
6+len	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

Data	长度	说明
Data[0~5]	6	配对的遥控器 MAC 地址
Data[6]	1	数据长度
Data[7]	1	DPID（固定值：0x0b）
Data[8]	1	DP TYPE+DP LEN（固定值：0x07）
Data[9]	1	ID
Data[10~15]	6	beacon 遥控器控制码表

MCU 回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB0
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	设置成功
其他	设置失败

预控数据通知（CMD-0xA2)

该服务的前提是需要使能预控功能。

模组发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xA2
4 5	2	数据长度	Len 高 8 位 Len 低 8 位
6	len	Data	见下表
6	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

Data	长度	说明
Data[0]	1	预控命令字
Data[1~12]	12	预控参数

MCU 回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB0
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	设置成功
其他	设置失败

Mesh 特有协议

Mesh 互传使能（CMD-0xB1）

• App 限制：v3.20 及以上。仅 v3.20 及以上版本的 App 支持此功能。

• MCU 在使用 CMD 0XB1 指令使能模组的互传功能后，模组会从云端申请 8 个发布消息的地址 pub_address 存储在模组中，与此同时快速配网失效。快速配网能达到平均 3~5 秒添加一个设备，非快速配网需要 10 秒左右添加一个设备。

• 使用 8 个 pub_address 实现设备与设备之间的本地联动的方法如下：

  

  如左图所示，遥控器的主页面，单击 配置群组 A 打开右边的群组管理页面，将灯加入或移除群组 A。

  群组 A 的地址即 8 个 pub_address 中的一个。

  在 App 上建立本地联动的步骤：

  1. App 从云端获取群组 A 对应的 pub_address。
  2. App 从云端获取已经在群组 A 中的设备列表，以及可支持加入到群组 A 的设备列表。
  3. 用户单击设备，App 向选中设备发送添加或移除群组 A 的命令，完成关联或解除关联。

  本地联动实施策略是：

  1. 按动遥控器的开关按钮。
  2. 遥控器利用 互传命令，将目的地址写为对应的 pub_address，发送灯泡的开关功能点。
  3. 属于对应群组（群组地址 = pub_address）的灯泡，收到遥控器发来的控制命令，进行开关切换。

MCU 发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB1
4 5	2	数据长度	0x00 0x01
6	1	Data	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

Data	说明
0x00	关闭本地互传
0x01	使能本地互传

模组回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB1
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	设置成功
其他	设置失败

Mesh 互传（CMD-0xB2）

蓝牙 Mesh 的核心功能是节点与节点互相通信，以实现本地应用的联动。
能充分发挥该命令价值的前提是发送方提前获取接收方的地址，支持以下四种方法：

• 方法一：发送方在被绑定添加时，单独给其分配 8 个发布消息的地址 pub_address，将被控对象按需分配到这 8 个群组中。例如，带有 8 个分组功能的遥控器。
• 方法二：发送的命令为广播命令，目的地址填写：0xFFFF。
• 方法三：发送方 读取自身所在群组的地址，将该地址作为目的地址，可以实现同一组内的设备联动。例如，停车场感应灯，一个灯感应触发一排灯响应。
• 方法四：借助 App 的控制面板，通过 DP 将被控对象目的地址传给发送方。

注意事项：

• 当前版本 v0.9 的 Mesh 通用对接固件，只支持方法二和方法四。
• 方法三将在 v1.0 版本支持。
• 方法四将在 v1.1 版本支持。v1.1 会增加 MCU 通信协议，支持以下功能：

  • 支持 获取设备被 App 绑定时所分配的地址。

    用于设备向群组发布/发送命令，也称这 8 个地址为：pub_address。

  • 支持 获取设备本身所在的群组地址。

MCU 发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB2
4 5	2	数据长度	Len 高 8 位 Len 低 8 位
6	N	Data	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

Data 序号	长度	字段	说明
0 1	2	目的地址	大端表示 可以填写 节点地址、组地址或者广播地址（0xFFFF）
2～N	N-1	DPs 数据	DPs 格式参考 状态上报（CMD-0x07） 中 data point 格式

获取 8 个 PUB_ADDRESS（CMD-0xB3）

MCU 获取存储在 Mesh 模组中的 8 个发布消息的地址 pub_address。

MCU 发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB3
4 5	2	数据长度	0x00 0x00
6	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

模组回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB3
4 5	2	数据长度 Len	Len 高 8 位 Len 低 8 位
6~6+Len-1	Len	Data	见下表
6+Len	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

Data 序号	长度	字段	说明
1	1	adr_num	获取 pub_address 的数量 0：没有任何 pub_address 8：存在 8 个 pub_address 当 adr_num 为 8 时，后面还有 16 字节的 8 个 pub_address，格式为：adr1 adr2 ... adr8（每个群组地址为 2 个字节）
2~17	16	pub_address	adr1 adr2 ... adr8（每个群组地址为 2 个字节，大端）

获取自身所属群组（CMD-0xB4）

支持查询所属群组，常用于停车场雷达灯商业照明方案。例如，将每排灯分别加入同一个群组，一排灯中任何一个灯感应到车辆，向全组发送开灯指令。

MCU 发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB4
4 5	2	数据长度	0x00 0x00
6	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

模组回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB4
4 5	2	数据长度 Len	Len 高 8 位 Len 低 8 位
6~6+Len-1	Len	Data	见下表
6+Len	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

Data 序号	长度	字段	说明
1	1	adr_num	获取群组地址的数量 0：不属于任何群组 8：可能 属于 8 个群组 当 adr_num 为 8 时，后面还有 16 字节的 8 个群组地址，格式为：adr1 adr2 ... adr8（每个群组地址为 2 个字节） 注意：当 adr == 0 时，表示该地址无效。
2~17	16	pub_address	adr1 adr2 ... adr8（每个群组地址为 2 个字节，大端）

本地对码（CMD-0xB5）

根据对码的时候是否要借助手机 App，涂鸦体系的遥控器产品与被控设备之间的对码方式有两种：

• 线上对码，参考 CMD 0xB1
• 线下对码

线上和线下的区别是：对码的时候是否要借助手机 App。

涂鸦体系遥控器与被控设备的线下对码一般操作方式为：

• 通过按键长按/上下电等外部事件触发，让被控设备进入待对码状态（CMD 0xB6）。
• 通过长按/组合按键等外部事件触发，让遥控器开始发送对码指令（CMD 0xB5）。
• 被对码成功的设备会闪烁指示灯，提示对码成功。
• 对码成功后：遥控器设备可以向 pub_address 地址发布消息/命令（利用 CMD 0xB2）。被对码设备（如灯），可以接收到发送到 pub_address 地址的消息。如果希望 MCU 和蓝牙通用对接设备作为被对码设备，请参考 CMD 0xB6。

MCU 发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB5
4 5	2	数据长度	Len 高 8 位 Len 低 8 位
6	Len	Data	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

字段	取值	说明
data[0]	0x00 0x01	unpair pair
data[1]	address type	0x00：目的地址采用 pub_address 偏移的方式，data[2] 填写 offset，该命令会让目标设备订阅/绑定 pub_address[offset] 地址。 0x01：目的地址为实际地址，data[2~3] 填写实际目的地址，大端表示。该命令会让目标设备订阅所传的地址。

模组回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB5
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	成功
其他	失败

开启本地对码时间窗（CMD-0xB6）

使用 CMD 0xB5 命令时，设备作为遥控器身份来使用，可以对其他设备对码和控制。使用 CMD 0xB6 命令时，设备作为被对码设备，可以被其他遥控器对码并被控制。一般情况下，一个设备不会既做遥控器，又做被对码设备，当然不排除特殊需求，这种双重身份也是支持的。

由于对码时间窗一般不会一直开启，因此增加 CMD 0xB6 来启动开启对码时间窗，并可以设置该时间窗的时间长短。这样，可以让其他遥控器只有在该时间窗内才能与设备对码。例如：

• 球泡灯：每次重新上电，开启对码时间窗 10s。
• 排插：每次长按子插按钮，开启该子插的对码时间窗 10s。

MCU 发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB6
4 5	2	数据长度	0x00 0x01
6	1	Data	时间窗的值，单位是秒，1 字节
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

模组回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB6
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	成功
0x01	失败
0x02	超时关闭
0x03	被对码

喜好收藏功能设置（CMD-0xB7）

喜好收藏功能设置，是遥控器设备对支持喜好收藏功能的被控设备（如涂鸦通用版本球泡灯）来使用的命令。当被控设备收到喜好收藏命令时，会记录当前设备状态。当被控设备收到喜好执行命令时，会提取喜好收藏，并进行加载执行。默认最多支持 4 组收藏。

常见的应用场景是：将智能家具中的一组设备，分别调节到目标状态，然后执行收藏操作。之后如果想要一键恢复之前收藏的状态，可以实施喜好执行命令。

MCU 发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB7
4 5	2	数据长度	Len 高 8 位 Len 低 8 位
6	Len	Data	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

字段	取值	说明
data[0]	0x01 0x02	喜好收藏 喜好执行
data[1]	收藏 ID (0x00~0x03)	总共支持 4 组喜好，编号分别是：0，1，2，3
data[2]	address type	0x00：目的地址采用 pub_address 偏移的方式，data[3] 填写 offset，该命令会让目标设备订阅/绑定 pub_address[offset] 地址。 0x01：目的地址为实际地址，data[3~4] 填写实际目的地址，大端表示。

模组回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB7
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	成功
其他	失败

喜好收藏功能被设置通知（CMD-0xB8）

模组发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB8
4 5	2	数据长度	0x00 0x02
6	2	Data	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

字段	取值	说明
data[0]	0x01 0x02	喜好收藏 喜好执行
data[1]	id (0x00~0x03)	总共支持 4 组喜好，编号分别是：0，1，2，3

MCU 回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xB8
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	成功
其他	失败

SIG MODEL 透传-发送（CMD-0xBC）

该命令可以直接让 MCU 和蓝牙向目标地址发送标准 Mesh Model 数据，例如：使用 MCU 和蓝牙做的遥控器，控制涂鸦通用版本灯的开关（需要合成发送标准的 on/off model）、亮度、颜色等。

涂鸦内部使用的标准 model 命令

model	适用
Generic OnOff Model	照明产品的开关、电工产品的开关
Light Lightness Model	照明亮度
Light CTL Temperature Model	照明色温
Light HSL Model	彩光（DP 是 HSV 颜色模型，传输采用 HSL 颜色模型，传到 MCU 是 HSV 颜色模型）

MCU 发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xBC
4 5	2	数据长度	Len 高 8 位 Len 低 8 位
6	Len	Data	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

字段	取值	说明
data[0~1]	dst_address 参数，采用 2 字节的大端格式表示	命令的目的地址
data[2~3]	opcode 参数，采用 2 字节的大端格式表示	设备通信用的命令字，请参考 蓝牙官网 了解详情
data[4]	is_rsp (0 = no; 1 = is rsp)	该命令是否是回复命令
data[5]	cmd_params_len	该命令中的参数部分长度
data[6~n]	cmd_params	该命令的参数

模组回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xBC
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	成功
其他	失败

SIG MODEL 透传-接收（CMD-0xBD）

该命令可以让 MCU 和蓝牙接收遥控器发来的标准 Mesh Model 数据。例如，使用 MCU 和蓝牙做的灯，想要被涂鸦通用版本遥控器控制，遥控器部分命令采用标准 Mesh Model 发送数据。

模组发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xBD
4 5	2	数据长度	Len 高 8 位 Len 低 8 位
6	Len	Data	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

字段	取值	说明
data[0~1]	src_address 参数，采用 2 字节的大端格式表示	命令的源地址
data[2~3]	dst_address 参数，采用 2 字节的大端格式表示	命令的目的地址
data[4~5]	opcode 参数，采用 2 字节的大端格式表示	设备通信用的命令字，请参考 蓝牙官网 了解详情
data[6]	is_ack (0 = no; 1 = need ack)	该命令是否需要回复
data[7]	cmd_params_len	该命令中的参数部分长度
data[8~n]	cmd_params	该命令的参数

MCU 回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xBD
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	成功
其他	失败

VENDOR 透传-发送（CMD-0xBE）

该命令可以直接让 MCU 和蓝牙向目标地址发送标准 Vendor Mesh 数据。例如，使用 MCU 和蓝牙做的遥控器，去控制涂鸦通用版本灯的场景切换。需要借助 Vendor 通道，发送遥控器协议指令。

MCU 发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xBE
4 5	2	数据长度	Len 高 8 位 Len 低 8 位
6	Len	Data	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

字段	取值	说明
data[0~1]	dst_address，采用 2 字节的大端格式表示	命令的目的地址
data[2]	is_rsp (0 = no; 1 = is rsp)	该命令是否是回复命令
data[3]	cmd_params_len	该命令中的参数部分长度
data[4~n]	cmd_params	该命令的参数

模组回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xBE
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	成功
其他	失败

VENDOR 透传-接收（CMD-0xBF）

该命令可以让 MCU 和蓝牙接收遥控器发来的标准 Vendor Model 数据。例如，使用 MCU 和蓝牙做的灯，想要被涂鸦通用版本遥控器控制。遥控器部分命令采用 Vendor Model 发送数据。

模组发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xBF
4 5	2	数据长度	Len 高 8 位 Len 低 8 位
6	Len	Data	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Data 格式

字段	取值	说明
data[0~1]	src_address，采用 2 字节的大端格式表示	命令的源地址
data[2~3]	dst_address，采用 2 字节的大端格式表示	命令的目的地址
data[4]	is_ack (0 = no; 1 = need ack)	该命令是否需要回复
data[5]	cmd_params_len	该命令中的参数部分长度
data[6~n]	cmd_params	该命令的参数

MCU 回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xBF
4 5	2	数据长度	0x00 0x01
6	1	Status	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

Status 返回值	说明
0x00	成功
其他	失败

其他功能

获取时间（CMD-0xD1）

MCU 发送

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xD1
4 5	2	数据长度	0x00 0x01
6	1	获取分类	Flag，低 5 位分别指示 Unix、时区、经纬度、日出日落和星期 24 小时计时是否有效 例如，0x0001 1111 表示获取 Unix、时区、经纬度、日出日落和星期 24 小时计时信息，后面将把所有这些信息拼接返回
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

模组回复

序号	长度（字节）	字段	说明
0 1	2	帧头	0x55 0xAA
2	1	版本号	0x00
3	1	命令字 CMD	0xD1
4 5	2	数据长度	n
6	n	时间数据	见下表
7	1	CRC8	从帧头开始按字节求和得出的结果对 256 求余

字段说明

字段	长度	说明
flag 字段	1 字节	第一字节对应请求时的 flag。例如，0b0001 1111，低 5 位全为 1，分别表示将要回复 Unix、时区、经纬度、日出日落和星期 24 小时计时字段。
Unix 字段	4 字节	当 flag 中对应字段为 1，则回复数据包的 Byte2~Byte5 用于表示 Unix 时间。 如果该时间字段是 0xFFFFFFFF，意味着设备还没有自己的时间。
时区字段	2 字节	时区信息，为实际时区的 100 倍，有符号型。例如，北京东八区为 8 × 100 = 800，西 7.5 区为 -750。
经纬度字段	4 字节	经度：东经 23°27′30" = 东经 23.45833°，舍去秒，最大 180.00。实际扩大 100 倍，有符号型。东经 23°27′ 为 2345，西经 23°30′ 为 -2350。 纬度的转换方法同经度：北纬 23°27′ 为 2345，南纬 23°30′ 为 -2350。
日出日落字段	4 字节	日出时间（2 字节），分钟表示，一天 24 小时，00:00 是第 0 分钟。 日落时间（2 字节），分钟表示，一天 24 小时，00:00 是第 0 分钟。
星期 + 24 小时计时字段	3 字节	星期（1 字节），星期天 0，星期 1~6 分别为 1~6。 当天的 24 小时制时间（2 字节）：分钟表示，一天 24 小时，00:00 是第 0 分钟。