蓝牙 Mesh 遥控器协议

更新时间：2025-04-18 08:32:24下载pdf

本文为您介绍蓝牙 Mesh 遥控器协议。

蓝牙 Mesh 标准指令

Generic OnOff model

Generic OnOff messages

此模型消息相关信息在 Mesh model 1.1 > 3.2.1 章节中，下文仅介绍作为遥控器使用到的相关参数信息。如果想查询更多信息，请自行前往链接文档查看。

Generic OnOff Set

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

消息的结构如下表所示：

Field	Size (Octets)	Description
Opcode	2	The message opcode.
OnOff	1	The target value of the Generic OnOff state.
TID	1	Transaction Identifier.
Transition Time	1	见下表
Delay	1	Message execution delay in 5-millisecond steps.

Field	Size (Bits)	Description
Transition Number of Steps	6	The number of steps.
Transition Step Resolution	2	The resolution of the Default Transition Number of Steps field.

Generic OnOff Set Unacknowledged

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

消息的结构如下表所示：

Field	Size (Octets)	Description
Opcode	2	The message opcode.
OnOff	1	The target value of the Generic OnOff state.
TID	1	Transaction Identifier.
Transition Time	1	见下表
Delay	1	Message execution delay in 5-millisecond steps.

Field	Size (Bits)	Description
Transition Number of Steps	6	The number of steps.
Transition Step Resolution	2	The resolution of the Default Transition Number of Steps field.

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

以下为 发送开灯指令 的代码示例：

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

    tal_mesh_data_send(0, app_param.publish_address, TAL_MESH_OPCODE_ON_OFF_SET_UNACK, (UCHAR_T *)&generic_onoff_status, sizeof(TAL_MESH_GENERIC_ONOFF_SET_T));

开关结构和 opcode 已在 SDK 封装，不需要自己实现。

    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;

    #define TAL_MESH_OPCODE_ON_OFF_SET_UNACK                (0x8203)

其中，参数 app_param.publish_address 为设备订阅地址。

Generic Lightness model

Light Lightness messages

此模型消息相关信息在 Mesh model 1.1 > 6.3.1 章节中，以下只介绍作为遥控器使用到的相关参数信息。如果想查询更多信息，请自行前往链接文档查看。

Light Lightness Set

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

消息的结构如下表所示：

Field	Size (Octets)	Description
Opcode	2	The message opcode.
Lightness	2	The target value of the Light Lightness Actual state.
TID	1	Transaction Identifier.
Transition Time	1	见下表
Delay	1	Message execution delay in 5-millisecond steps.

Field	Size (Bits)	Description
Transition Number of Steps	6	The number of steps
Transition Step Resolution	2	The resolution of the Default Transition Number of Steps field.

Light Lightness Set Unacknowledged

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

消息的结构如下表所示：

Field	Size (Octets)	Description
Opcode	2	The message opcode.
Lightness	2	The target value of the Light Lightness Actual state.
TID	1	Transaction Identifier.
Transition Time	1	见下表
Delay	1	Message execution delay in 5-millisecond steps.

Field	Size (Bits)	Description
Transition Number of Steps	6	The number of steps.
Transition Step Resolution	2	The resolution of the Default Transition Number of Steps field.

代码示例：

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

    tal_mesh_data_send(0, app_param.publish_address, TAL_MESH_OPCODE_LIGHTNESS_SET_UNACK, (UCHAR_T *)&generic_onoff_status, sizeof(TAL_MESH_LIGHT_LIGHTNESS_SET_T));

Generic CTL model

Light CTL messages

此模型消息相关信息在 Mesh model 1.1 > 6.3.2 章节中，以下只介绍作为遥控器使用到的相关参数信息。如果想查询更多信息，请自行前往链接文档查看。

Light CTL Set

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

消息的结构如下表所示：

Field	Size (Octets)	Description
Opcode	2	The message opcode.
CTL Lightness	2	The target value of the Light CTL Lightness state.
CTL Temperature	2	The target value of the Light CTL Temperature state.
CTL Delta UV	2	The target value of the Light CTL Delta UV state.
TID	1	Transaction Identifier
Transition Time	1	见下表
Delay	1	Message execution delay in 5-millisecond steps.

Field	Size (Bits)	Description
Transition Number of Steps	6	The number of steps.
Transition Step Resolution	2	The resolution of the Default Transition Number of Steps field.

Light CTL Set Unacknowledged

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

消息的结构如下表所示：

Field	Size (Octets)	Description
Opcode	2	The message opcode.
CTL Lightness	2	The target value of the Light CTL Lightness state.
CTL Temperature	2	The target value of the Light CTL Temperature state.
CTL Delta UV	2	The target value of the Light CTL Delta UV state.
TID	1	Transaction Identifier
Transition Time	1	见下表
Delay	1	Message execution delay in 5-millisecond steps.

Field	Size (Bits)	Description
Transition Number of Steps	6	The number of steps.
Transition Step Resolution	2	The resolution of the Default Transition Number of Steps field.

代码示例：

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

    tal_mesh_data_send(0, app_param.publish_address, TAL_MESH_OPCODE_LIGHT_CTL_SET_UNACK, (UCHAR_T *)&generic_light_ctl_status, sizeof(TAL_MESH_LIGHT_CTL_SET_T));

Generic HSL model

Light HSL messages

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

Light HSL Set

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

消息的结构如下表所示：

Field	Size (Octets)	Description
Opcode	2	The message opcode.
HSL Lightness	2	The target value of the Light HSL Lightness state.
HSL Hue	2	The target value of the Light HSL Hue state.
HSL Saturation	2	The target value of the Light HSL Saturation state .
TID	1	Transaction Identifier
Transition Time	1	见下表
Delay	1	Message execution delay in 5-millisecond steps.

Field	Size (Bits)	Description
Transition Number of Steps	6	The number of steps.
Transition Step Resolution	2	The resolution of the Default Transition Number of Steps field.

Light HSL Set Unacknowledged

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

消息的结构如下表所示：

Field	Size (Octets)	Description
Opcode	2	The message opcode.
HSL Lightness	2	The target value of the Light HSL Lightness state.
HSL Hue	2	The target value of the Light HSL Hue state
HSL Saturation	2	The target Light HSL Saturation state.
TID	1	Transaction Identifier
Transition Time	1	见下表
Delay	1	Message execution delay in 5-millisecond steps.

Field	Size (Bits)	Description
Transition Number of Steps	6	The number of steps.
Transition Step Resolution	2	The resolution of the Default Transition Number of Steps field.

代码示例：

    STATIC TAL_MESH_LIGHT_HSL_SET_T     generic_light_hsl_status = {
      .lightness = 65535,
      .hue = 65535,
      .sat = 65535,
      .tid = 1,
    };

    tal_mesh_data_send(0, app_param.publish_address, TAL_MESH_OPCODE_LIGHT_HSL_SET_UNACK, (UCHAR_T *)&generic_light_hsl_status, sizeof(TAL_MESH_LIGHT_HSL_SET_T));

照明相关 opcode 在 Assigned Numbers > 4.2.1 章节中有相关参数的介绍，下表只展示照明相关 opcode value。如果需要其他 opcode value，请自行前往链接文档查找。

Message Opcode	Message Name
0x82 0x02	GenericOnOffSet
0x82 0x03	GenericOnOffSetUnacknowledged
0x82 0x4C	LightLightnessSet
0x82 0x4D	LightLightnessSetUnacknowledged
0x82 0x5E	LightCTLSet
0x82 0x5F	LightCTLSetUnacknowledged
0x82 0x64	LightCTLTemperatureSet
0x82 0x65	LightCTLTemperatureSetUnacknowledged
0x82 0x76	LightHSLSet
0x82 0x77	LightHSLSetUnacknowledged

tuyaos_sdk 中已经对灯相关模型进行了封装，以下为代码展示：

/* 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)

/* 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)

/* 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)

/* Temperature Model Opcode [Tuya Use] */
#define TAL_MESH_OPCODE_LIGHT_CTL_TEMP_GET              (0x8261)
#define TAL_MESH_OPCODE_LIGHT_CTL_TEMP_SET              (0x8264)
#define TAL_MESH_OPCODE_LIGHT_CTL_TEMP_SET_UNACK        (0x8265)
#define TAL_MESH_OPCODE_LIGHT_CTL_TEMP_STAT             (0x8266)

/* 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)

亮度调节指令

灯处于不同模式下，遥控器发送调节灯亮度的指令。如果处于白光模式或彩光模式或混光模式，模式应保持，单纯调节亮度。如果处于其他模式，应切换至白光模式。

遥控器发送

op_code: 0xC9D007 WRITE

op_code: 0xCAD007 WRITE_UNACK

字段	长度（Byte）	说明
命令字	1	0x83
数据长度	1	0x02
数据	Lightness (2 Byte)	Lightness：灯的亮度值

喜好收藏指令

该命令由两个控制组成：喜好收藏、喜好执行，最多 4 组喜好。

喜好收藏：收到该命令时设备将当前的状态记录下来，形成一个喜好组并收藏。
喜好执行：收到该命令时设备取出之前收藏的喜好组，并将设备状态切换为收藏的状态。

App 发送

op_code: 0xC9D007 WRITE

字段	长度（Byte）	说明
命令字	1	0x87
数据长度	1	0x02
数据	2	字节 1： 0x01：喜好收藏 0x02：喜好执行字节 2： 0x00-0x03：喜好组

字段

长度（Byte）

说明

命令字

0x87

数据长度

0x02

数据

字节 1：

0x01：喜好收藏
0x02：喜好执行

字节 2：

0x00-0x03：喜好组

遥控器特殊控制指令

针对遥控器特殊控制应用。

op_code: 0xC9D007 WRITE

op_code: 0xCAD007 WRITE_UNACK

字段	长度（Byte）	说明
命令字	1	0x8A
数据长度	1	N
数据	CMD (1 byte) + PARAM (N-1 byte)	CMD：0x01 亮度无极调节 PARAM: byte 1：0 - 连续加开始、1 - 连续减开始、2 - 连续结束、3 - 循环 byte 2：0 - 设备当前模式亮度、1 - 白光模式亮度、2 - 彩光模式亮度 byte 3：速率（每 1s 调节的百分比） byte 4：无极调节目标值
		CMD：0x02 色温无极调节 PARAM: byte 1：0 - 连续加开始、1 - 连续减开始、2 - 连续结束、3 - 循环 byte 2：速率（每 1s 调节的百分比）byte 3：无极调节目标值
		CMD：0x03 H 值无极调节 PARAM: byte 1：0 - 连续加开始、1 - 连续减开始、2 - 连续结束、3 - 循环 byte 2：速率（每 1s 调节的百分比） byte 3：无极调节目标值
		CMD：0x04 亮度步进调节 PARAM： byte 1: 0 步进加、1 步进减、2 步进循环 byte 2：0 - 设备当前模式亮度、1 - 白光模式亮度、2 - 彩光模式亮度 byte 3：步进值（1-100%）
		CMD：0x05 色温步进调节 PARAM： byte 1：0 步进加、1 步进减、2 步进循环 byte 2：步进值（1-100%）
		CMD：0x06 H 步进调节 PARAM： byte 1：0 步进加、1 步进减、2 步进循环 byte 2：步进值（1-100%）

上一篇蓝牙低功耗模式

下一篇蓝牙 Beacon Mesh