Integration of Bluetooth Mesh Models

This topic describes how to use the MCU standard protocol to control Tuya-standard lights on/off, color, and lightness via Bluetooth mesh generic models. Alternatively, function as a controlled device to receive on/off, color, and lightness commands from Tuya-standard remote controls.

Generic models for lights and remote controls

Model	Description
Generic OnOff Model	Set the on/off status of a device.
Generic Lightness Model	Set the lightness of a lighting device.
Generic CTL Model	Set the lightness and color temperature of a lighting device.
Generic HSL Model	Set the colored light of a lighting device.

Standard models

Generic OnOff Model

The Generic OnOff Model is a fundamental application model in Bluetooth mesh networks, designed for basic on/off control of devices. It is widely used in smart lighting systems, on/off controls, and similar applications. The following section describes the Generic OnOff Model in Bluetooth mesh networks.

Basic features

This model primarily toggles device states, such as turning lights on/off or switching power devices. It provides a simple and direct control method for implementing basic on/off functionality.

Status variables

OnOff State: Define the current device status as either on or off. The status is typically represented by a boolean value. For example, 0 for off and 1 for on.

Message action

• Set message: Set the device’s OnOff status with optional Transition Time (smooth fading) and Delay (scheduled execution).
• Set Unacknowledged message: Similar to Set but requires no response.
• Get message: Request the device to report its current OnOff status.
• Status message: The device responds to a Get message or proactively sends its current OnOff status and replies to a Set message when the status changes.

Generic OnOff Set Unacknowledged

Generic OnOff Set Unacknowledged is an unacknowledged message used to set the Generic OnOff state of an element.

The following table describes the structure of the message.

Field	Bytes	Description
Opcode	2	The message opcode.
OnOff	1	The target value of Generic OnOff state.
TID	1	The transaction identifier.
Transition time	1	See the following table.
Delay	1	The delay in message execution (in 5-millisecond steps).

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

Mesh-related opcodes are specified in Assigned Numbers > Section 4.2.1. The table below only displays Generic OnOff-related opcode values. For other opcode values, refer to the linked document.

Message opcode	Message name
0x82 0x01	GenericOnOffGet
0x82 0x02	GenericOnOffSet
0x82 0x03	GenericOnOffSetUnacknowledged
0x82 0x04	GenericOnOffStatus

Example

The general integration protocol is used to develop a remote control and control the on/off status of a light via the remote control. Generic OnOff Model is used to send on/off commands to control the peer device.

/* 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)
/* General serial port protocol (SIG_MODEL transparent transmission-send: 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;

/* Destination address of the command */
hsl_control_buf[0] = publish_address>>8;   
hsl_control_buf[1] = publish_address;
/* Opcode parameter */
hsl_control_buf[2] = TAL_MESH_OPCODE_ON_OFF_SET_UNACK>>8;
hsl_control_buf[3] = TAL_MESH_OPCODE_ON_OFF_SET_UNACK;
/* Indicates whether a reply is required */
hsl_control_buf[4] = 0x00;
/*Length of the command */
hsl_control_buf[5] = sizeof(TAL_MESH_GENERIC_ONOFF_SET_T);
/* Command parameters */
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);

Note:

• The interfaces (set_bt_uart_buffer and bt_uart_write_frame) can be found in the MCU SDK porting code.
• publish_address is the subscription address. To use it, enable mutual communication (0xB1), and then get pub_address via 0xB3.

The parameter app_param.publish_address is the device subscription address.

Application scenarios

This model is ideally suited for simple device control scenarios, such as turning on/off the lights, ventilation devices, and other devices requiring basic binary control.

Generic Lightness Model

The Generic Lightness Model is a standardized application model designed for controlling lightness in Bluetooth mesh networks. It provides comprehensive functionality to adjust luminaire light output, making it ideal for smart lighting systems. Below is a detailed explanation of the Generic Lightness Model.

Basic features

Generic Lightness Model is primarily used to control light brightness levels, enabling adjustable light output to meet diverse environmental or user needs. It offers a full range of control from complete shutdown to maximum lightness.

Status variables

• Lightness Actual: The current actual lightness value, which can be a specific value, indicating the output intensity of the light.
• Lightness Linear: The linear lightness value, used to handle nonlinear dimming devices.
• Lightness Last: The previously set lightness value, used for power restore scenarios.
• Lightness Default: The default lightness applied when the light is initially enabled.
• Lightness Range: The minimum and maximum range of lightness.

Message action

• Set message: Set Lightness Actual or Lightness Linear status with optional Transition Time (smooth fading) and Delay (scheduled execution).
• Set Unacknowledged message: Similar to Set but requires no response.
• Get message: Request the device to report its current lightness status.
• Status message: The device responds to a Get message or proactively sends its current lightness status and replies to a Set message when the status changes.
• Default message: Set or get the default lightness status.
• Range message: Set or get the valid range of lightness.

Light Lightness messages

Refer to Mesh Model > 6.3.1 for information about this model’s messages (Light Lightness Get, Light Lightness Set, Light Lightness Set Unacknowledged, and Light Lightness Status). The following only introduces the relevant parameter (Light Lightness Set Unacknowledged) when it is used as a remote controller. You can click the link for more information.

Light Lightness Set Unacknowledged

The Light Lightness Set Unacknowledged is an unacknowledged message used to set the Light Lightness Actual state of an element.

The following table describes the structure of the message.

Field	Bytes	Description
Opcode	2	The message opcode.
Lightness	2	The target value of Light Lightness Actual.
TID	1	The transaction identifier.
Transition time	1	See the following table.
Delay	1	The delay in message execution (in 5-millisecond steps).

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

Mesh opcodes are described in Assigned Numbers > Section 4.2.1. The following table only shows the opcode values for lightness control. You can click the link for more information about other opcode values.

Message opcode	Message name
0x82 0x4B	Light Lightness Get
0x82 0x4C	Light Lightness Set
0x82 0x4D	Light Lightness Set Unacknowledged
0x82 0x4E	Light Lightness Status

Example

/* 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)
/* General serial port protocol (SIG_MODEL transparent transmission-send: 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;

/* Destination address of the command */
hsl_control_buf[0] = publish_address>>8;   
hsl_control_buf[1] = publish_address;
/* Opcode parameter */
hsl_control_buf[2] = TAL_MESH_OPCODE_LIGHTNESS_SET_UNACK>>8;
hsl_control_buf[3] = TAL_MESH_OPCODE_LIGHTNESS_SET_UNACK;
/* Indicates whether a reply is required */
hsl_control_buf[4] = 0x00;
/*Length of the command */
hsl_control_buf[5] = sizeof(TAL_MESH_LIGHT_LIGHTNESS_SET_T);
/* Command parameters */
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);

Note:

• The interfaces (set_bt_uart_buffer and bt_uart_write_frame) can be found in the MCU SDK porting code.
• publish_address is the subscription address. To use it, enable mutual communication (0xB1), and then get pub_address via 0xB3.

Application scenarios

From simple lights to complex multi-channel lights, this model enables users to achieve precise control over light intensity.

Generic CTL Model

The Generic CTL (Color Temperature, Lightness) Model is an application model in Bluetooth mesh networks, designed for simultaneous control of lightness and color temperature. This model is useful for lighting systems that require dynamic adjustment of both intensity and color temperature, such as ambient lighting and task lighting. Below is a detailed explanation of the Generic CTL Model.

Basic features

The Generic CTL Model allows users to control the lightness and color temperature of lights to provide a more comfortable and appropriate lighting environment. Color temperature control means to adjust light from warm to cool tones, typically measured in Kelvin (K) units.

Status variables

• CTL Lightness: The lightness value of the current light, which can be linear or real (actual) lightness.
• CTL Temperature: The color temperature value of light. It uses a numerical value to represent the hue of the light.
• CTL Delta UV: A fine-tuning parameter for color temperature adjustment, used to precisely correct color bias in light output.

Message action

• CTL Set message: Set the lightness and color temperature state of a light and optionally include transition times and delays.
• CTL Set Unacknowledged message: Similar to CTL Set but requires no response.
• CTL Get message: Request the device to report its current lightness and color temperature status.
• CTL Status message: The device responds to a Get message or proactively sends its current lightness and color temperature status and replies to a Set message when the status changes.

Light CTL messages

Refer to Mesh Model > 6.3.2 for information about this model’s messages (Light CTL Get, Light CTL Set, Light CTL Set Unacknowledged, and Light CTL Status). The following only introduces the relevant parameter (Light CTL Set Unacknowledged) when it is used as a remote controller. You can click the link for more information.

Light CTL Set Unacknowledged

Light CTL Set Unacknowledged is an unacknowledged message used to set the Light CTL Lightness state, Light CTL Temperature state, and the Light CTL Delta UV state of an element.

The following table describes the structure of the message.

Field	Bytes	Description
Opcode	2	The message opcode.
CTL Lightness	2	The target value of Light CTL Lightness.
CTL Temperature	2	The target value of Light CTL Temperature.
CTL Delta UV	2	The target value of Light CTL Delta UV.
TID	1	The transaction identifier.
Transition time	1	See the following table.
Delay	1	The delay in message execution (in 5-millisecond steps).

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

Mesh-related opcodes are specified in Assigned Numbers > Section 4.2.1. The table below only displays opcode values related to the lightness and color temperature. For other opcode values, refer to the linked document.

Message opcode	Message name
0x82 0x5D	Light CTL Get
0x82 0x5E	Light CTL Set
0x82 0x5F	Light CTL Set Unacknowledged
0x82 0x60	Light CTL Status

Example

/* 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)
/* General serial port protocol (SIG_MODEL transparent transmission-send: 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;

/* Destination address of the command */
hsl_control_buf[0] = publish_address>>8;   
hsl_control_buf[1] = publish_address;
/* Opcode parameter */
hsl_control_buf[2] = TAL_MESH_OPCODE_LIGHT_CTL_SET_UNACK>>8;
hsl_control_buf[3] = TAL_MESH_OPCODE_LIGHT_CTL_SET_UNACK;
/* Indicates whether a reply is required */
hsl_control_buf[4] = 0x00;
/*Length of the command */
hsl_control_buf[5] = sizeof(TAL_MESH_LIGHT_CTL_SET_T);
/* Command parameters */
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);

Note:

• The interfaces (set_bt_uart_buffer and bt_uart_write_frame) can be found in the MCU SDK porting code.
• publish_address is the subscription address. To use it, enable mutual communication (0xB1), and then get pub_address via 0xB3.

Application scenarios

This model is ideally suited for scenarios that require dynamic adjustment of light intensity and color based on activities and contexts, such as office lighting, home ambient lighting, and commercial display lighting.

Generic HSL Model

The Generic HSL (Hue, Saturation, Lightness) Model is an application model in Bluetooth mesh networks, designed for control of lighting color and lightness. This model is ideally suited for lighting systems that need to dynamically adjust color, such as colored lights in smart homes. Below is a detailed explanation of the Generic HSL Model.

Basic features

The Generic HSL Model allows users to control the color of a light by adjusting the hue, saturation, and lightness.

Hue determines the basic type of color, saturation determines the color purity or intensity, and lightness determines the light intensity.

Status variables

• HSL Hue: The hue value of the light. You can adjust it to change the color of the light, for example, from red to blue.
• HSL Saturation: The saturation value of the light, indicating the purity of the color, from light to dark.
• HSL Lightness: The lightness value of the light, which controls the light intensity.

Message action

• HSL Set message: Set the hue, saturation, and lightness status of a light and optionally include transition times and delays.
• HSL Set Unacknowledged message: Similar to HSL Set but requires no response.
• HSL Get message: Request the device to report its current hue, saturation, and lightness status.
• HSL Status message: The device responds to a Get message or proactively sends its current hue, saturation, and lightness status and replies to a HSL Set message when the status changes.

Light HSL messages

Refer to Mesh Model > 6.3.3 for information about this model’s messages (Light HSL Get, Light HSL Set, Light HSL Set Unacknowledged, and Light HSL Status). The following only introduces the relevant parameter (Light HSL Set Unacknowledged) when it is used as a remote controller. You can click the link for more information.

Light HSL Set Unacknowledged

The Light HSL Set Unacknowledged is an unacknowledged message used to set the Light HSL Lightness state, the Light HSL Hue state, and the Light HSL Saturation state of an element.

The following table describes the structure of the message.

Field	Bytes	Description
Opcode	2	The message opcode.
HSL Lightness	2	The target value of Light HSL Lightness.
HSL Hue	2	The target value of Light HSL Hue.
HSL Saturation	2	The target value of Light HSL Saturation.
TID	1	The transaction identifier.
Transition time	1	See the following table.
Delay	1	The delay in message execution (in 5-millisecond steps).

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

Mesh-related opcodes are specified in Assigned Numbers > Section 4.2.1. The table below only displays opcode values related to colored light. For other opcode values, refer to the linked document.

Message opcode	Message name
0x82 0x6D	Light HSL Get
0x82 0x76	Light HSL Set
0x82 0x77	Light HSL SetUnacknowledged
0x82 0x78	Light HSL Status

Example:

/* 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)
/* General serial port protocol (SIG_MODEL transparent transmission-send: 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;

/* Destination address of the command */
hsl_control_buf[0] = publish_address>>8;   
hsl_control_buf[1] = publish_address;
/* Opcode parameter */
hsl_control_buf[2] = TAL_MESH_OPCODE_LIGHT_HSL_SET_UNACK>>8;
hsl_control_buf[3] = TAL_MESH_OPCODE_LIGHT_HSL_SET_UNACK;
/* Indicates whether a reply is required */
hsl_control_buf[4] = 0x00;
/*Length of the command */
hsl_control_buf[5] = sizeof(TAL_MESH_LIGHT_HSL_SET_T);
/* Command parameters */
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);

Note:

• The interfaces (set_bt_uart_buffer and bt_uart_write_frame) can be found in the MCU SDK porting code.
• publish_address is the subscription address. To use it, enable mutual communication (0xB1), and then get pub_address via 0xB3.

Application scenarios

Ideal for lighting systems requiring personalized and dynamic color control, including smart home, entertainment venues, and commercial displays.