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

更新时间:2025-05-28 06:17:41下载pdf

本文介绍如何使用 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 GetGeneric OnOff SetGeneric OnOff Set UnacknowledgedGeneric OnOff Status)相关信息在 Mesh Model > 3.2.1 章节中,以下只介绍作为遥控器使用到的相关参数(Generic OnOff Set Unacknowledged)信息。如果想查询更多信息,请自行前往链接文档查看。

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_bufferbt_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 ActualLightness Linear 状态,并可选包含转换时间和延迟。
  • Set Unacknowledged 消息:类似于 Set 消息,但不需要确认响应。
  • Get 消息:请求设备报告其当前的亮度状态。
  • Status 消息:设备响应 Get 消息 或状态变化时,发送其当前亮度状态和回复 Set 消息
  • Default 消息:设置或获取默认亮度状态。
  • Range 消息:设置或获取灯光亮度的有效范围。

Light Lightness messages

此模型消息(Light Lightness GetLight Lightness SetLight Lightness Set UnacknowledgedLight 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_bufferbt_uart_write_frame)可以在 MCU SDK 移植代码中找到。
  • publish_address 为订阅地址,使用时先使能互传(CMD-0xB1),然后通过获取 pub_address(CMD-B3) 得到。

应用场景

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

Generic CTL Model

在 Bluetooth Mesh 网络中,Generic CTL ModelColor 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 GetLight CTL SetLight CTL Set UnacknowledgedLight 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_bufferbt_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 GetLight HSL SetLight HSL Set UnacknowledgedLight 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_bufferbt_uart_write_frame)可以在 MCU SDK 移植代码中找到。
  • publish_address 为订阅地址,使用时先使能互传(CMD-0xB1),然后通过获取 pub_address(CMD-B3) 得到。

应用场景

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