TuyaOSBluetooth FrameworkCapability MapBluetooth MeshData Transmission and DP Control

Data Transmission and DP Control

Last Updated on : 2024-02-23 07:45:12download

The Bluetooth mesh specification states that devices communicate using the opcode defined in the mesh model. For more information, see Mesh Model 1.1. The Tuya IoT Development Platform uses the DP model for communication. You can check the DP details after you create a product on the platform. There is a conversion rule between the DP model and the standard mesh data model, which varies depending on the product category.

The mesh capability value determines the product category. See Mesh Category.

Category

Lighting products

The format of the Opcode data is defined in the Bluetooth mesh specification. Alternatively, you can review the struct definition in the tal_bluetooth_mesh_def.h. For example, the definition of Light Lightness set is as follows:

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;

Lighting is one of the most popular Bluetooth mesh models.

Mappings between DPs and mesh opcodes

DP ID	DP feature	Model	Opcode	Notes
1	Switch	Generic OnOff Model	Generic OnOff Get Generic OnOff Set Generic OnOff Set Unacknowledged Generic OnOff Status	-
2	Mode	Tuya Vendor Model	Vendor Read Vendor Write Vendor Write Unacknowledged Vendor Data	Used to switch between the white and colored lights. Note: The mode DP for lighting products does not use the Tuya vendor model. A 1-byte field represents the lighting mode. See the implementation in the demo.
3	Brightness	Light Lightness Model	Light Lightness Get Light Lightness Set Light Lightness Set Unacknowledged Light Lightness Status	Valid values range from 0 to 65535.
4	Color temperature	Light CTL Temperature Model	Light CTL Temperature Get Light CTL Temperature Set Light CTL Temperature Set Unacknowledged Light CTL Temperature Status	Valid values range from 800 to 20000.
5	Color	Light HSL Model	Light HSL Get Light HSL Set Light HSL Set Unacknowledged Light HSL Status	The Bluetooth mesh specification requires the use of the HSL model, while Tuya’s DP model uses the HSV model. Model conversion is needed.
6	Scene	Tuya Vendor Model	Vendor Read Vendor Write Vendor Write Unacknowledged Vendor Data	The scene DP data is compressed to reduce its length. See the lighting product development kit for details.
7	Music	Tuya Vendor Model	Vendor Read Vendor Write Vendor Write Unacknowledged Vendor Data	The music DP data is compressed to reduce its length.
Others	Other DPs	Tuya Vendor Model	Vendor Read Vendor Write Vendor Write Unacknowledged Vendor Data	The vendor model processes all other DP data.

Electrical products

The switch product may have multiple elements depending on the number of gangs it has.

DP ID	DP feature	Model	Opcode	Element index	Notes
1	Switch 1	Generic OnOff Model	Generic OnOff Get Generic OnOff Set Generic OnOff Set Unacknowledged Generic OnOff Status	0	The on/off control and status of gang 1.
2	Switch 2	Generic OnOff Model	Generic OnOff Get Generic OnOff Set Generic OnOff Set Unacknowledged Generic OnOff Status	1	The on/off control and status of gang 2.
3	Switch 3	Generic OnOff Model	Generic OnOff Get Generic OnOff Set Generic OnOff Set Unacknowledged Generic OnOff Status	2	The on/off control and status of gang 3.
4	Switch 4	Generic OnOff Model	Generic OnOff Get Generic OnOff Set Generic OnOff Set Unacknowledged Generic OnOff Status	3	The on/off control and status of gang 4.
5	Switch 5	Generic OnOff Model	Generic OnOff Get Generic OnOff Set Generic OnOff Set Unacknowledged Generic OnOff Status	4	The on/off control and status of gang 5.
6	Switch 6	Generic OnOff Model	Generic OnOff Get Generic OnOff Set Generic OnOff Set Unacknowledged Generic OnOff Status	5	The on/off control and status of gang 6.
Others	Other DPs	Tuya Vendor Model	Vendor Read Vendor Write Vendor Write Unacknowledged Vendor Data	0	The vendor model processes all other DP data.

When an electrical device has multiple switches, it uses the same opcode to control them. The address of the element is used to identify each switch. The address of element 0 (a.k.a. primary element) is the unicast address of a device. You can get this address using tal_primary_ele_addr_get().

Other categories and pass-through categories

All products, except for the lighting and electrical products, are processed using the vendor model. The category and subcategory specified in the Bluetooth Mesh Category are for record purposes only. No special processing is necessary.

DP ID	DP feature	Model	Opcode	Element index	Notes
All	All DPs	Tuya Vendor Model	Vendor Read Vendor Write Vendor Write Unacknowledged Vendor Data	0	The vendor model processes all other DP data.
None	None	Generic OnOff Model	Generic OnOff Get Generic OnOff Status	0	The always-powered devices should implement Generic OnOff Model, Generic OnOff Get, and Generic OnOff Status for heartbeat checks. If a device does not support on/off status, it can respond with `1` for Generic OnOff Status.

Communication process

Communication between mobile app and device

Note: Device control through the mobile app does not synchronize the device status with the cloud. To enable synchronization, the device needs to be controlled through the gateway.

Communication between gateway and device

Data structure

`TAL_MESH_ACCESS_MSG_T`

typedef struct {
    UINT_T    opcode;        /**< Mesh opcode. */
    UCHAR_T   *data;         /**< Mesh data. */
    USHORT_T  data_len;      /**< Mesh data lenth. */
} TAL_MESH_ACCESS_MSG_T;

opcode: The command defined in the Bluetooth mesh specification.
data: The pointer to the data. See tal_bluetooth_mesh_def.h for the data format.
data_len: The length of the data.

`TAL_MESH_ACCESS_MSG_T`

typedef struct {
    USHORT_T  src_addr;           /**< Source unicast address. */
    USHORT_T  dst_addr;           /**< Destination unicast address. */
    UINT_T    seq;                /**< Sequence num of this msg. */
    UCHAR_T   ttl;                /**< Time To Live. */
    USHORT_T  app_key_index;      /**< The appkey index of this msg ues. */
    USHORT_T  net_key_index;      /**< The networkkey index of this msg ues. */
    CHAR_T    rssi;               /**< used when rx in adv bearer. */
} TAL_MESH_NET_PARAM_T;

src_addr: The address of the node that sends the mesh message, which must be a unicast address.
dst_addr: The destination address for the mesh message, which can be a node address or a multicast address.
seq: The sequence number of the mesh message, used for anti-replay.
ttl: The time to live (TTL) of the mesh message, which is decremented as the message is relayed. The TTL defaults to 8 for the Tuya-enabled app and gateway. The receiving device can determine how many times a specific message has been relayed.
app_key_index: The application key index used for message encryption, defaulting to 0.
net_key_index: The network key index used for message encryption, defaulting to 0.
rssi: The signal strength of the current mesh advertising. It can be the signal strength of the transmitting node or the relay node.

`tal_mesh_msg_recv_cb`

typedef OPERATE_RET (*tal_mesh_msg_recv_cb)(TAL_MESH_ACCESS_MSG_T *msg_raw, TAL_MESH_NET_PARAM_T *net_param);

The callback for mesh data reception:

msg_raw: The mesh message.
net_param: The network parameters of the mesh message.

API description

Mesh data reception callback

OPERATE_RET tal_mesh_msg_recv_cb_init(tal_mesh_msg_recv_cb access_data_cb);

During initialization, register the callback for mesh data reception. This callback receives data sent from the mobile app, gateway, or other nodes.

Send mesh data

OPERATE_RET tal_mesh_data_send(USHORT_T src_addr, USHORT_T dst_addr, UINT_T opcode, UCHAR_T *data, USHORT_T data_len);

This callback allows you to send data to the destination address through the access layer API.

src_addr: The source address of the data. If this is the address of the device itself, you can get it using USHORT_T tal_primary_ele_addr_get(VOID);.
dst_addr: The destination address.
opcode: The opcode of the data to be sent. See tal_bluetooth_mesh_def.h for the data format.
data: The pointer to the data.
data_len: The length of the data.

Report mesh data

#define TUYA_REPROT_PUB_ADDR    0xD000

tal_mesh_data_send(tal_primary_ele_addr_get(), TUYA_REPROT_PUB_ADDR, TAL_MESH_OPCODE_ON_OFF_STAT, (UINT8_T*)&generic_onoff_status, 1);

Tuya-enabled devices can be controlled by mobile apps or associated gateways, so they cannot get the addresses of the currently connected mobile app or gateway. In other words, when devices proactively report data, they cannot use the address of the mobile app or gateway.

The Tuya-enabled mobile app or gateway will subscribe to the address TUYA_REPROT_PUB_ADDR. Therefore, use TUYA_REPROT_PUB_ADDR as the destination address for data reporting.

Tuya vendor model

This section describes the Tuya-specific vendor model for data pass-through, which enables the control logic or data transmission that cannot be implemented using the Bluetooth SIG models.

Overview

Tuya-enabled Bluetooth mesh supports product categories including lights, electrical products, sensors, and remote controls. Most Bluetooth mesh product categories are based on the Bluetooth SIG models. For example, the Generic OnOff Model makes it possible to switch a lighting device on or off.

However, the Bluetooth SIG models have their limits on implementing complex functions. In this case, the vendor model is used alternatively. For example, the vendor model is used to implement scene configuration and switching for Bluetooth mesh lights.

Vendor Model

Vendor Model ID

Server: 0x07D00004
Client: 0x07D00005

Vendor Model Opcode

Command	Op_code	Client: 0x07D00005	Server: 0x07D00004
WRITE	0xC9D007	Write data request.	-
WRITE_UNACK	0xCAD007	Write data request without acknowledgment.	-
READ	0xCCD007	Read status request.	-
STATUS	0xCBD007	-	Reserved
DATA	0xCDD007	-	Respond to commands and report status.

Data format and basic control protocol

Field	Bytes	Description
Command	1	Data type: `0x01`: DP data `0x02`: Time synchronization …
Data length	1	This field does not apply to the DP data unit.
Data	N	-

Note: To limit the length of access data and reduce the latency caused by packet segmentation, DP data does not include the data length field.

DP data unit

When the vendor model is used for DP data transmission, the mobile app or gateway passes through DP data by convention. The pass-through convention is as follows:

Field	Bytes	Description
dpid	1	The identifier of a DP (DP ID).
type	1	It indicates the specific data type of DP defined on the Tuya IoT Development Platform, which is represented by the following value.
		Type	Value	Length (byte)	Description
		Raw	0x00	N	Represents a DP of raw data type.
		Boolean	0x01	1	Represents a DP of Boolean data type. Valid values include 0x00 and 0x01.
		Value	0x02	4	Represents a DP of value data type, in big-endian format.
		String	0x03	N	Represents a DP of string data type.
		Enum	0x04	1	Represents a DP of enum data type, ranging from 0 to 0xFF.
		Bitmap	0x05	4	Data greater than one byte is transmitted in big-endian format.
len	1	The length of data. This field is required for data types of raw, string, and bitmap.
data	1/4/N	Represented in hexadecimal format. Data greater than one byte is transmitted in big-endian format.

Send command to device

op_code: 0xC9D007 (WRITE)

When the mobile app or gateway sends the WRITE command to the device, the device responds with the data 0xCDD007.
op_code: 0xCAD007 (WRITE_UNACK)

When the mobile app or gateway sends the WRITE_UNACK command to the device, the device does not return a response.

The mobile app or gateway sends the following data:

Field	Bytes	Description
Command	1	0x01 (DP data)
Data	N	DP group

Query device status

op_code: 0xCCD007 (READ)

The mobile app or gateway sends DP status queries to the device. If the device receives the DP ID of 0, it will report the status of all DPs.

The mobile app or gateway sends the following data:

Field	Bytes	Description
Command	1	0x01 (DP data)
Data length	1	N
Data	N × `DP_ID` (N × 1 byte)	An array of DP IDs.

Device returns a response

op_code: 0xCDD007 (data)

The sub-device responds to the WRITE and READ commands.

The device sends:

Field	Bytes	Description
Command	1	0x01 (DP data)
Data	N	DP group

How-to

Receive and respond to mesh data

The following code shows the callback for receiving mesh data. See the demo for more examples.

OPERATE_RET app_mesh_data_recv(TAL_MESH_ACCESS_MSG_T *msg_raw, TAL_MESH_NET_PARAM_T *net_param){
    TAL_MESH_GENERIC_ONOFF_STATUS_T     generic_onoff_status;

    switch(msg_raw->opcode){
        case TAL_MESH_OPCODE_ON_OFF_GET:
            generic_onoff_status.present = onoff_data;
            tal_mesh_data_send(net_param->dst_addr, net_param->src_addr, TAL_MESH_OPCODE_ON_OFF_STAT, (UINT8_T*)&generic_onoff_status, 1);
        break;
        case TAL_MESH_OPCODE_ON_OFF_SET:
        case TAL_MESH_OPCODE_ON_OFF_SET_UNACK:{
            TAL_MESH_GENERIC_ONOFF_SET_T *generic_onoff_set = (TAL_MESH_GENERIC_ONOFF_SET_T*)msg_raw->data;
            onoff_data = generic_onoff_set->onoff;
            if(TAL_MESH_OPCODE_ON_OFF_SET == msg_raw->opcode){
                generic_onoff_status.present = generic_onoff_set->onoff;
                tal_mesh_data_send(net_param->dst_addr, net_param->src_addr, TAL_MESH_OPCODE_ON_OFF_STAT, (UINT8_T*)&generic_onoff_status, 1);
            }
        }
        break;
        default:
        break;
    }

    return OPRT_OK;
}

Report mesh data proactively

TAL_MESH_GENERIC_ONOFF_STATUS_T generic_onoff_status;
generic_onoff_status.present = 0x01;
tal_mesh_data_send(tal_primary_ele_addr_get(), TUYA_REPROT_PUB_ADDR, TAL_MESH_OPCODE_ON_OFF_STAT, (UINT8_T*)&generic_onoff_status, 1);

The following code shows the device proactively reports its on/off status.

Multi-element control

Each element has only one OnOff Model. A multi-gang electrical product requires multiple elements. In this case, the destination address identifies the element to which the message is sent.

STATIC UINT8_T onoff_data[6] = {0};

OPERATE_RET app_mesh_data_recv(TAL_MESH_ACCESS_MSG_T *msg_raw, TAL_MESH_NET_PARAM_T *net_param){
    TAL_MESH_GENERIC_ONOFF_STATUS_T     generic_onoff_status;

    UINT8_T switch_index = net_param->dst_addr - tal_primary_ele_addr_get();
    switch(msg_raw->opcode){
        case TAL_MESH_OPCODE_ON_OFF_GET:
            generic_onoff_status.present = onoff_data[switch_index];
            tal_mesh_data_send(net_param->dst_addr, net_param->src_addr, TAL_MESH_OPCODE_ON_OFF_STAT, (UINT8_T*)&generic_onoff_status, 1);
        break;
        case TAL_MESH_OPCODE_ON_OFF_SET:
        case TAL_MESH_OPCODE_ON_OFF_SET_UNACK:{
            TAL_MESH_GENERIC_ONOFF_SET_T *generic_onoff_set = (TAL_MESH_GENERIC_ONOFF_SET_T*)msg_raw->data;
            onoff_data[switch_index] = generic_onoff_set->onoff;
            if(TAL_MESH_OPCODE_ON_OFF_SET == msg_raw->opcode){
                generic_onoff_status.present = generic_onoff_set->onoff;
                tal_mesh_data_send(net_param->dst_addr, net_param->src_addr, TAL_MESH_OPCODE_ON_OFF_STAT, (UINT8_T*)&generic_onoff_status, 1);
            }
        }
        break;

        default:
        break;
    }

    return OPRT_OK;
}

The above example shows a 6-gang switch receiving a control command. switch_index represents the index of a switch, which is the index of an element.

Prev DocBluetooth Mesh Networking

Next DocGroup