通用对接 Bluetooth Mesh 标准模型指导

本文介绍如何使用 MCU 通用协议接入，通过 Bluetooth Mesh 标准通用模型控制涂鸦通用版本的灯开关、颜色、亮度等；也可以作为被控端，接收涂鸦标准遥控器发来的开关、颜色、亮度等指令。

涂鸦灯端和遥控器使用标准模型

模型	说明
Generic OnOff Model	设置设备的开关状态
Generic Lightness Model	照明设备的亮度
Generic CTL Model	照明设备的亮度和色温
Generic HSL Model	照明设备的彩光

标准模型介绍

Generic OnOff Model

在 Bluetooth Mesh 网络中，Generic OnOff Model 是一个非常基本的应用模型，用于控制设备状态的简单开关操作。它在智能照明系统、开关控制等应用中非常常见。以下是对 Bluetooth Mesh 中 Generic OnOff Model 的详细说明：

基本功能

此模型的主要功能是切换设备的状态，例如打开或关闭灯、开关电源装置等。它提供了一种简单而直接的方式来控制设备，实现最基础的开/关功能。

状态变量

OnOff State：定义设备的当前状态，即 “开” 或 “关”。此状态通常以布尔值表示（例如，0 表示 “关”，1 表示 “开”）。

消息操作

• Set 消息：用于设置设备的 OnOff 状态，并可选择包含 Transition Time（转换时间）和 Delay（延迟），实现平滑的状态过渡。
• Set Unacknowledged 消息：类似于 Set 消息，但不需要响应确认。
• Get 消息：请求设备报告其当前的 OnOff 状态。
• Status 消息：设备响应 Get 消息 或在状态变化时，主动发送其当前 OnOff 状态并回复 Set 消息。

Generic OnOff Set Unacknowledged

Generic OnOff Set Unacknowledged 是一种无需回复确认消息，用于设置元素的通用开关状态。

消息的结构如下表所示：

字段	大小（字节）	说明
Opcode	2	消息操作码
OnOff	1	Generic OnOff state 的目标值
TID	1	交易标识符，Transaction Identifier
Transition Time	1	见下表
Delay	1	消息执行延迟（以 5 毫秒为步长）

字段	大小（位）	说明
Transition Number of Steps	6	过渡步骤数量
Transition Step Resolution	2	默认过渡步骤数量字段（Transition Number of Steps）的分辨率（精度）

Mesh 相关 Opcode 在 Assigned Numbers > 4.2.1 章节中有相关参数，下表只展示通用开关相关 Opcode value，如果需要其他 Opcode value，请自行前往链接文档查找。

Message Opcode	Message Name
0x82 0x01	GenericOnOffGet
0x82 0x02	GenericOnOffSet
0x82 0x03	GenericOnOffSetUnacknowledged
0x82 0x04	GenericOnOffStatus

代码示例

通用对接协议接入开发遥控器，通过遥控器控制灯端开关状态，可以采用通用开关模型，发送开关命令控制对端设备。

/* Onoff Model Opcode [Tuya Use] */
#define TAL_MESH_OPCODE_ON_OFF_GET                      (0x8201)
#define TAL_MESH_OPCODE_ON_OFF_SET                      (0x8202)
#define TAL_MESH_OPCODE_ON_OFF_SET_UNACK                (0x8203)
#define TAL_MESH_OPCODE_ON_OFF_STAT                     (0x8204)
/* 通用对接串口协议（SIG_MODEL 透传-发送：CMD-0xBC）*/
#define         CMD_SIG_MODEL_SEND          0xBC  

typedef struct{
  UCHAR_T onoff;                      /**< The target value of the Generic OnOff state. */
  UCHAR_T tid;                        /**< Transaction Identifier */
  UCHAR_T transit_t;                  /**< Generic Default Transition Time(optional). */
  UCHAR_T delay;                      /**< If the transit_t field is present, the Delay field shall also be present; otherwise these fields shall not be present. */
}TAL_MESH_GENERIC_ONOFF_SET_T;

STATIC TAL_MESH_GENERIC_ONOFF_SET_T     generic_onoff_status = {
  .onoff = 1,
  .tid = 1,
};

UCHAR_T hsl_control_buf[255] = {0x00};
UCHAR_T length = 0;

/* 命令的目的地址 */
hsl_control_buf[0] = publish_address>>8;   
hsl_control_buf[1] = publish_address;
/* Opcode 参数 */
hsl_control_buf[2] = TAL_MESH_OPCODE_ON_OFF_SET_UNACK>>8;
hsl_control_buf[3] = TAL_MESH_OPCODE_ON_OFF_SET_UNACK;
/* 是否需要回复 */
hsl_control_buf[4] = 0x00;
/* 该命令长度 */
hsl_control_buf[5] = sizeof(TAL_MESH_GENERIC_ONOFF_SET_T);
/* 命令参数 */
memcpy(&hsl_control_buf[6],(UCHAR_T *)&generic_onoff_status,sizeof(TAL_MESH_GENERIC_ONOFF_SET_T));
length = set_bt_uart_buffer(length,hsl_control_buf,6+sizeof(TAL_MESH_GENERIC_ONOFF_SET_T));
bt_uart_write_frame(CMD_SIG_MODEL_SEND,length);

说明：

• 接口函数（set_bt_uart_buffer、bt_uart_write_frame）可以在 MCU SDK 移植代码中找到。
• publish_address 为订阅地址，使用时先使能互传（CMD-0xB1），然后通过获取 pub_address（CMD-B3） 得到。

参数：app_param.publish_address 为设备订阅地址。

应用场景

此模型非常适合简单设备控制场景，如灯光启闭、通风设备开关、以及其他需要简单控制的设备。

Generic Lightness Model

在 Bluetooth Mesh 网络中，Generic Lightness Model 是一种用于控制灯光亮度的标准化应用模型。它提供了丰富的功能来调节灯具的光输出，非常适合智能照明系统的应用。以下是对 Generic Lightness Model 的详细说明：

基本功能

Generic Lightness Model 主要用于控制灯光的亮度级别，允许调整灯光输出以满足不同的环境或用户需求。它提供了从完全关闭到最高亮度的调节范围。

状态变量

• Lightness Actual：当前实际的亮度值，可以是一个具体的数值，表示灯光的输出强度。
• Lightness Linear：线性亮度值，用于处理非线性调光设备。
• Lightness Last：上一次设定的亮度值，可以在恢复时使用。
• Lightness Default：灯初始启用时的默认亮度。
• Lightness Range：亮度的最小和最大值范围。

消息操作

• Set 消息：用于设置灯光的 Lightness Actual 或 Lightness Linear 状态，并可选包含转换时间和延迟。
• Set Unacknowledged 消息：类似于 Set 消息，但不需要确认响应。
• Get 消息：请求设备报告其当前的亮度状态。
• Status 消息：设备响应 Get 消息 或状态变化时，发送其当前亮度状态和回复 Set 消息。
• Default 消息：设置或获取默认亮度状态。
• Range 消息：设置或获取灯光亮度的有效范围。

Light Lightness messages

此模型消息（Light Lightness Get、Light Lightness Set、Light Lightness Set Unacknowledged、Light Lightness Status 等）相关信息在 Mesh Model > 6.3.1 章节中，以下只介绍作为遥控器使用到的相关参数（Light Lightness Set Unacknowledged）信息。如需查询更多信息，请自行前往链接文档查看。

Light Lightness Set Unacknowledged

Light Lightness Set Unacknowledged 是一种无需回复确认消息，用于设置元素的灯光实际亮度状态。

消息的结构如下表所示：

字段	大小（字节）	说明
Opcode	2	消息操作码
Lightness	2	Light Lightness Actual 状态的目标值
TID	1	交易标识符，Transaction Identifier
Transition Time	1	见下表
Delay	1	消息执行延迟（以 5 毫秒为步长）

字段	大小（位）	说明
Transition Number of Steps	6	过渡步骤数量
Transition Step Resolution	2	默认过渡步骤数量字段（Transition Number of Steps）的分辨率（精度）

Mesh 相关 Opcode 在 Assigned Numbers > 4.2.1 章节中有相关参数，下表只展示亮度控制相关 Opcode value。如果需要其他 Opcode value，请自行前往链接文档查找。

Message Opcode	Message Name
0x82 0x4B	Light Lightness Get
0x82 0x4C	Light Lightness Set
0x82 0x4D	Light LightnessSet Unacknowledged
0x82 0x4E	Light Lightness Status

代码示例

/* Lightness Model Opcode [Tuya Use] */
#define TAL_MESH_OPCODE_LIGHTNESS_GET                   (0x824B)
#define TAL_MESH_OPCODE_LIGHTNESS_SET                   (0x824C)
#define TAL_MESH_OPCODE_LIGHTNESS_SET_UNACK             (0x824D)
#define TAL_MESH_OPCODE_LIGHTNESS_STAT                  (0x824E)
/* 通用对接串口协议（SIG_MODEL 透传-发送：CMD-0xBC）*/
#define         CMD_SIG_MODEL_SEND          0xBC   

typedef struct{
    USHORT_T lightness;                 /**< The target value of the Light Lightness Actual state */
    UCHAR_T tid;                        /**< Transaction Identifier */
    UCHAR_T transit_t;                  /**< Generic Default Transition Time(optional) */
    UCHAR_T delay;                      /**< If the transit_t field is present, the Delay field shall also be present; otherwise these fields shall not be present. */
}PACKED TAL_MESH_LIGHT_LIGHTNESS_SET_T;

STATIC TAL_MESH_LIGHT_LIGHTNESS_SET_T     generic_lightness_status = {
  .lightness = 65535,
  .tid = 1,
};

UCHAR_T hsl_control_buf[255] = {0x00};
UCHAR_T length = 0;

/* 命令的目的地址 */
hsl_control_buf[0] = publish_address>>8;   
hsl_control_buf[1] = publish_address;
/* Opcode 参数 */
hsl_control_buf[2] = TAL_MESH_OPCODE_LIGHTNESS_SET_UNACK>>8;
hsl_control_buf[3] = TAL_MESH_OPCODE_LIGHTNESS_SET_UNACK;
/* 是否需要回复 */
hsl_control_buf[4] = 0x00;
/* 该命令长度 */
hsl_control_buf[5] = sizeof(TAL_MESH_LIGHT_LIGHTNESS_SET_T);
/* 命令参数 */
memcpy(&hsl_control_buf[6],(UCHAR_T *)&generic_lightness_status,sizeof(TAL_MESH_LIGHT_LIGHTNESS_SET_T));
length = set_bt_uart_buffer(length,hsl_control_buf,6+sizeof(TAL_MESH_LIGHT_LIGHTNESS_SET_T));
bt_uart_write_frame(CMD_SIG_MODEL_SEND,length);

说明：

• 接口函数（set_bt_uart_buffer、bt_uart_write_frame）可以在 MCU SDK 移植代码中找到。
• publish_address 为订阅地址，使用时先使能互传（CMD-0xB1），然后通过获取 pub_address（CMD-B3） 得到。

应用场景

从简单的灯到复杂的多通道灯具，用户可以通过此模型实现对灯光强度的精准控制.

Generic CTL Model

在 Bluetooth Mesh 网络中，Generic CTL Model（Color Temperature Lightness Model）是一个应用模型，用于同时控制灯光的亮度和色温。此模型对于需要动态调整光强和色温的照明系统非常有用，如环境照明和任务照明。以下是关于 Generic CTL Model 的详细说明：

基本功能

Generic CTL Model 允许用户控制灯具的亮度（Lightness）以及色温（Color Temperature），从而提供更舒适和合适的光环境。色温控制通过调整光线从暖色到冷色的变化来实现，这通常以开尔文度（Kelvin）为单位。

状态变量

• CTL Lightness：当前灯光的亮度值，可以是线性或真实（实际）亮度。
• CTL Temperature：光的色温值，用数值表示灯光的色调。
• CTL Delta UV：色温的微调参数，用于精细调整色温的色偏。

消息操作

• CTL Set 消息：设置灯光的亮度和色温状态，并可以选择性地包括转换时间和延迟。
• CTL Set Unacknowledged 消息：类似于 CTL Set 消息，但不需要确认响应。
• CTL Get 消息：请求设备报告其当前亮度和色温状态。
• CTL Status 消息：设备响应 Get 消息 或状态变化时，发送其当前亮度和色温状态，并回复 Set 消息。

Light CTL messages

此模型消息（Light CTL Get、Light CTL Set、Light CTL Set Unacknowledged、Light CTL Status 等）相关信息在 Mesh Model > 6.3.2 章节中，以下只介绍作为遥控器使用到的相关参数（Light CTL Set Unacknowledged）信息。如果想查询更多信息，请自行前往链接文档查看。

Light CTL Set Unacknowledged

Light CTL Set Unacknowledged 是一个无需回复确认的消息，用于设置元素的 Light CTL 亮度状态、Light CTL 温度状态以及 Light CTL Delta UV 状态。

消息的结构如下表所示：

字段	大小（字节）	说明
Opcode	2	消息操作码
CTL Lightness	2	Light CTL Lightness 状态的目标值
CTL Temperature	2	Light CTL Temperature 状态的目标值
CTL Delta UV	2	Light CTL Delta UV 状态的目标值
TID	1	交易标识符，Transaction Identifier
Transition Time	1	见下表
Delay	1	消息执行延迟（以 5 毫秒为步长）

字段	大小（位）	说明
Transition Number of Steps	6	过渡步骤数量
Transition Step Resolution	2	默认过渡步骤数量字段（Transition Number of Steps）的分辨率（精度）

Mesh 相关 Opcode 在 Assigned Numbers > 4.2.1 章节中有对应介绍，下表只展示亮度和色温相关 Opcode value，如果需要其他 Opcode value，请自行前往链接文档查找。

Message Opcode	Message Name
0x82 0x5D	Light CTL Get
0x82 0x5E	Light CTL Set
0x82 0x5F	Light CTL SetUnacknowledged
0x82 0x60	Light CTL Status

代码示例

/* Light CTL Model Opcode [Tuya Use] */
#define TAL_MESH_OPCODE_LIGHT_CTL_GET                   (0x825D)
#define TAL_MESH_OPCODE_LIGHT_CTL_SET                   (0x825E)
#define TAL_MESH_OPCODE_LIGHT_CTL_SET_UNACK             (0x825F)
#define TAL_MESH_OPCODE_LIGHT_CTL_STAT                  (0x8260)
/* 通用对接串口协议（SIG_MODEL 透传-发送：CMD-0xBC）*/
#define         CMD_SIG_MODEL_SEND          0xBC    


STATIC TAL_MESH_LIGHT_CTL_SET_T     generic_light_ctl_status = {
  .lightness = 65535,
  .temp = 20000,
  .tid = 1,
};

UCHAR_T hsl_control_buf[255] = {0x00};
UCHAR_T length = 0;

/* 命令的目的地址 */
hsl_control_buf[0] = publish_address>>8;   
hsl_control_buf[1] = publish_address;
/* opcode参数 */
hsl_control_buf[2] = TAL_MESH_OPCODE_LIGHT_CTL_SET_UNACK>>8;
hsl_control_buf[3] = TAL_MESH_OPCODE_LIGHT_CTL_SET_UNACK;
/* 是否需要回复 */
hsl_control_buf[4] = 0x00;
/* 该命令长度 */
hsl_control_buf[5] = sizeof(TAL_MESH_LIGHT_CTL_SET_T);
/* 命令参数 */
memcpy(&hsl_control_buf[6],(UCHAR_T *)&generic_light_ctl_status,sizeof(TAL_MESH_LIGHT_CTL_SET_T));
length = set_bt_uart_buffer(length,hsl_control_buf,6+sizeof(TAL_MESH_LIGHT_CTL_SET_T));
bt_uart_write_frame(CMD_SIG_MODEL_SEND,length);

说明：

• 接口函数（set_bt_uart_buffer、bt_uart_write_frame）可以在 MCU SDK 移植代码中找到。
• publish_address 为订阅地址，使用时先使能互传（CMD-0xB1），然后通过获取 pub_address（CMD-B3） 得到。

应用场景

非常适合需要根据活动和情境动态调整光强和颜色的场景，例如办公室照明、家庭环境照明和商用展示照明。

Generic HSL Model

在 Bluetooth Mesh 网络中，Generic HSL Model（Hue，Saturation，Lightness Model）是一种应用模型，用于控制灯光的颜色和亮度。这种模型特别适合需要动态调整颜色的照明系统，如智能家居中的彩色灯具。以下是 Generic HSL Model 的详细说明：

基本功能

Generic HSL Model 允许用户控制灯具的颜色，通过调整色调（Hue）、饱和度（Saturation）和亮度（Lightness）来实现。

色调决定颜色的基本类型，饱和度决定颜色的纯度或强度，亮度决定光的强弱。

状态变量

• HSL Hue：当前灯光的色调值，可以通过调整来改变灯光的颜色，例如从红色到蓝色。
• HSL Saturation：灯光的饱和度值，表示颜色的纯净程度，从淡到浓。
• HSL Lightness：灯光的亮度值，控制光强。

消息操作

• HSL Set 消息：设置灯光的色调、饱和度和亮度状态，并可选择性地包括转换时间和延迟。
• HSL Set Unacknowledged 消息：类似于 HSL Set 消息，但不需要确认响应。
• HSL Get 消息：请求设备报告其当前色调、饱和度和亮度状态。
• HSL Status 消息：设备响应 Get 消息 或状态变化时，发送其当前色调、饱和度、和亮度状态，并回复 HSL Set 消息。

Light HSL messages

此模型消息（Light HSL Get、Light HSL Set、Light HSL Set Unacknowledged、Light HSL Status）相关信息在 Mesh Model > 6.3.3 章节中，以下只介绍作为遥控器使用到的相关参数（Light HSL Set Unacknowledged）信息。如果想查询更多信息，请自行前往链接文档查看。

Light HSL Set Unacknowledged

Light HSL Set Unacknowledged 是一种无需回复确认消息，用于设置元素的灯光 HSL 亮度状态、灯光 HSL 色调状态和灯光 HSL 饱和度状态。

消息的结构如下表所示：

字段	大小（字节）	说明
Opcode	2	消息操作码
HSL Lightness	2	Light HSL Lightness 状态的目标值
HSL Hue	2	Light HSL Hue 状态的目标值
HSL Saturation	2	Light HSL Saturation 状态的目标值
TID	1	交易标识符，Transaction Identifier
Transition Time	1	见下表
Delay	1	消息执行延迟（以 5 毫秒为步长）

字段	大小（位）	说明
Transition Number of Steps	6	过渡步骤数量
Transition Step Resolution	2	默认过渡步骤数量字段（Transition Number of Steps）的分辨率（精度）

Mesh 相关 Opcode 在 Assigned Numbers > 4.2.1 章节中有对应介绍，下表只展示调节彩光相关 Opcode value，如果需要其他 Opcode value，请自行前往链接文档查找。

Message Opcode	Message Name
0x82 0x6D	Light HSL Get
0x82 0x76	Light HSL Set
0x82 0x77	Light HSL SetUnacknowledged
0x82 0x78	Light HSL Status

代码示例：

/* HSL Model Opcode [Tuya Use] */
#define TAL_MESH_OPCODE_LIGHT_HSL_GET                   (0x826D)
#define TAL_MESH_OPCODE_LIGHT_HSL_SET                   (0x8276)
#define TAL_MESH_OPCODE_LIGHT_HSL_SET_UNACK             (0x8277)
#define TAL_MESH_OPCODE_LIGHT_HSL_STAT                  (0x8278)
/* 通用对接串口协议(SIG_MODEL透传-发送:CMD-0xBC)*/
#define         CMD_SIG_MODEL_SEND          0xBC                          
typedef struct{
    USHORT_T lightness;                 /**< The target value of the Light HSL Lightness state */
    USHORT_T hue;                       /**< The target value of the Light HSL Hue state */
    USHORT_T sat;                       /**< The target value of the Light HSL Saturation state */
    UCHAR_T tid;                        /**< Transaction Identifier */
    UCHAR_T transit_t;                  /**< Generic Default Transition Time(Optional) */
    UCHAR_T delay;                      /**< If the transit_t field is present, the Delay field shall also be present; otherwise these fields shall not be present. */
}PACKED TAL_MESH_LIGHT_HSL_SET_T;

STATIC TAL_MESH_LIGHT_HSL_SET_T     generic_light_hsl_status = {
  .lightness = 65535,
  .hue = 0,
  .sat = 65535,
  .tid = 1,
};
UCHAR_T hsl_control_buf[255] = {0x00};
UCHAR_T length = 0;

/* 命令的目的地址 */
hsl_control_buf[0] = publish_address>>8;   
hsl_control_buf[1] = publish_address;
/* opcode参数 */
hsl_control_buf[2] = TAL_MESH_OPCODE_LIGHT_HSL_SET_UNACK>>8;
hsl_control_buf[3] = TAL_MESH_OPCODE_LIGHT_HSL_SET_UNACK;
/* 是否需要回复 */
hsl_control_buf[4] = 0x00;
/* 该命令长度 */
hsl_control_buf[5] = sizeof(TAL_MESH_LIGHT_HSL_SET_T);
/* 命令参数 */
memcpy(&hsl_control_buf[6],(UCHAR_T *)&generic_light_hsl_status,sizeof(TAL_MESH_LIGHT_HSL_SET_T));
length = set_bt_uart_buffer(length,hsl_control_buf,6+sizeof(TAL_MESH_LIGHT_HSL_SET_T));
bt_uart_write_frame(CMD_SIG_MODEL_SEND,length);

说明：

• 接口函数（set_bt_uart_buffer、bt_uart_write_frame）可以在 MCU SDK 移植代码中找到。
• publish_address 为订阅地址，使用时先使能互传（CMD-0xB1），然后通过获取 pub_address（CMD-B3） 得到。

应用场景

适用于智能家居、娱乐场所和商业展示等，需要个性化和动态调色的灯具系统。