Bluetooth Mesh Remote Control

This topic describes the Bluetooth mesh protocol for remote controls.

Standard Bluetooth mesh commands

Generic OnOff model

Generic OnOff messages

The information about this model message is in the Mesh Model v1.1 section 3.2.1. The following only describes the parameters applicable to remote controls. You can click the link for more information.

Generic OnOff Set

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

The following table describes the structure of the message.

Field	Size (Octets)	Description
Opcode	2	The message opcode.
OnOff	1	The target value of the Generic OnOff state.
TID	1	The transaction identifier.
Transition Time	1	See the table below.
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 is an unacknowledged message used to set the Generic OnOff state of an element.

The following table describes the structure of the message.

Field	Size (Octets)	Description
Opcode	2	The message opcode.
OnOff	1	The target value of the Generic OnOff state.
TID	1	The transaction identifier.
Transition Time	1	See the table below.
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: is used to develop remote controls to control the on/off state of lights. A generic on/off model can be used to send on/off commands to control the device.

The following code snippet shows how to send commands to turn on a light.

    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));

    typedef struct{
        UCHAR_T onoff;                      /**< The target value of the Generic OnOff state. */
        UCHAR_T tid;                        /**< The 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)

The parameter app_param.publish_address is the device subscription address.

Generic lightness model

Light lightness messages

The information about this model message is in the Mesh Model v1.1 section 6.3.1. The following only describes the parameters applicable to remote controls. You can click the link for more information.

Light lightness set

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

The following table describes the structure of the message.

Field	Size (Octets)	Description
Opcode	2	The message opcode.
Lightness	2	The target value of the Light Lightness Actual state.
TID	1	The transaction identifier.
Transition Time	1	See the table below.
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

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	Size (Octets)	Description
Opcode	2	The message opcode.
Lightness	2	The target value of the Light Lightness Actual state.
TID	1	The transaction identifier.
Transition time	1	See the table below.
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.

Sample code:

    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

The information about this model message is in the Mesh Model v1.1 section 6.3.2. The following only describes the parameters applicable to remote controls. You can click the link for more information.

Light CTL set

Light CTL Set is an acknowledged 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	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	The transaction identifier.
Transition time	1	See the table below.
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 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	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	The transaction identifier.
Transition time	1	See the table below.
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.

Sample code:

    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

The information about this model message is in the Mesh Model v1.1 section 6.3.3. The following only describes the parameters applicable to remote controls. You can click the link for more information.

Light HSL set

The Light HSL Set is an acknowledged 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	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	The transaction identifier.
Transition time	1	See the table below.
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

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	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	The transaction identifier.
Transition time	1	See the table below.
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.

Sample code:

    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));

Lighting-related opcodes are described in Assigned Numbers > Section 4.2.1. The following table only shows the opcode values for lighting. You can click the link for more information about other opcode values.

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

The light-related models have been encapsulated in tuyaos_sdk. Here is the sample code:

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

Lightness adjustment commands

When the light is in different modes, the remote control sends commands to adjust the lightness. If the light is in white light mode, colored light mode, or mixed light mode, the mode shall remain unchanged, and only the lightness is adjusted. If the light is in any other mode, the light should switch to white light mode.

The remote control sends:

• op_code: 0xC9D007 (WRITE)

• op_code: 0xCAD007 (WRITE_UNACK)

Field	Length (byte)	Description
Command	1	0x83
Data length	1	0x02
Data	Lightness (2 bytes)	Lightness: The lightness of the light

Add favorites

This command consists of two parts: Add to favorites and execute favorites. Up to 4 favorite groups can be added.

• Add favorites: When a light receives this command, it adds the current state to a favorite group.

• Execute favorites: When a light receives this command, it changes the current state to a selected favorite state.

The mobile app sends:

op_code: 0xC9D007 (WRITE)

Field	Length (byte)	Description
Command	1	0x87
Data length	1	0x02
Data	2	Byte 1: 0x01: Add favorites 0x02: Execute favorites Byte 2: 0x00 to 0x03: Favorite groups

Special control commands

These commands apply to special control of the remote control.

• op_code: 0xC9D007 (WRITE)

• op_code: 0xCAD007 (WRITE_UNACK)

Field	Length (byte)	Description
Command	1	0x8A
Data length	1	N
Data	CMD (1 byte) + PARAM (N-1 byte)	CMD: 0x01, stepless adjustment of lightness PARAM: Byte 1: 0 – Start incrementing. 1 – Start decrementing. 2 – Stop adjustment. 3 – Loop. Byte 2: 0 – Lightness of the current mode. 1 – Lightness of white light. 2 – Lightness of colored light. Byte 3: Rate (adjustment percentage per second). Byte 4: The target value.
		CMD: 0x02, stepless adjustment of color temperature PARAM: Byte 1: 0 – Start incrementing. 1 – Start decrementing. 2 – Stop adjustment. 3 – Loop. Byte 2: Rate (adjustment percentage per second). Byte 3: The target value.
		CMD: 0x03, stepless adjustment of hue PARAM: Byte 1: 0 – Start incrementing. 1 – Start decrementing. 2 – Stop adjustment. 3 – Loop. Byte 2: Rate (adjustment percentage per second). Byte 3: The target value.
		CMD: 0x04, step adjustment of lightness PARAM: Byte 1: 0 – Step up. 1 – Step down. 2 – Step loop. Byte 2: 0 – Lightness of the current mode. 1 – Lightness of white light. 2 – Lightness of colored light. Byte 3: Step value ranging from 1% to 100%.
		CMD: 0x05, step adjustment of color temperature PARAM: Byte 1: 0 – Step up. 1 – Step down. 2 – Step loop. Byte 2: Step value ranging from 1% to 100%.
		CMD: 0x06, step adjustment of hue PARAM: Byte 1: 0 – Step up. 1 – Step down. 2 – Step loop. Byte 2: Step value ranging from 1% to 100%.