DP Data Communication

A data point (DP) is the basic unit that describes a feature of a Tuya-enabled product. Tuya-enabled Bluetooth products and the Tuya app communicate by exchanging DP data. The DP data defines the data structure. The collection of DPs describes the features available in a Tuya-enabled product.

The TuyaOS Bluetooth Low Energy (LE) SDK offers a range of APIs for controlling and managing Bluetooth devices. These include DP data reporting, DP data querying, DP data receiving, and responding to DP data reports.

Concepts

PID and DP are two important concepts in DP communication.

Tuya provides solutions for various product categories, such as lights, sensors, and door locks. Each category includes diverse products with different sets of features. A product ID (PID) can contain multiple DPs. The structure of DP data consists of dp_id, dp_type, dp_data_len, and dp_data_value. The following diagram describes the position of DP data in the Tuya product architecture.

PID

A product ID (PID) is an abstract representation of a collection of product features (DPs). Each product created on the Tuya Developer Platform is assigned a unique PID that is associated with the product information, including DPs, app control panel, and purchase information. For more information, see Function Definition.

There are two methods to create a PID.

• Method 1: Create a product. For more information, see Create Products.

• Method 2: Copy a product. Click to copy a product for demonstration. You can get a product with the same features as the original one but a different PID.

  The copied product is only used for debugging, not for production.

DP

A DP is an abstract representation of a function defined for a physical product.

• DP data format

  Field	Length (byte)	Description
  dp_id	1	The ID of a DP.
  dp_type	1	The data type of a DP.
  dp_data_len	2	The data length of a DP.
  dp_data_value	Value of dp_data_len	The data of a DP.

• The value range and description of dp_type:

  dp_type	Value	Length (byte)	Description
  raw	0	1 to N	Raw
  bool	1	1	Boolean
  value	2	4	Value
  string	3	0 to 255	String
  enum	4	1	Enum
  bitmap	5	4	Fault

Data structure

demo_dp_t

typedef struct {
    UINT8_T dp_id;
    UINT8_T dp_type;
    UINT16_T dp_data_len;
    UINT8_T dp_data[600];
} demo_dp_t;

• dp_id: The ID of a DP.

• dp_type: The data type of the DP.

• dp_data_len: The length of DP data.

• dp_data: The DP data.

tuya_ble_dp_data_send_mode_t

typedef enum {
    DP_SEND_TYPE_ACTIVE = 0,       // The device actively sends dp data.
    DP_SEND_TYPE_PASSIVE,          // The device passively sends dp data. For example, in order to answer the dp query command of the mobile app. Currently only applicable to WIFI+BLE combo devices.
} tuya_ble_dp_data_send_type_t;

• DP_SEND_TYPE_ACTIVE: The device proactively reports data to the mobile phone.

• DP_SEND_TYPE_PASSIVE: The device passively reports data to the mobile phone, for example, in response to the TUYA_BLE_CB_EVT_DP_QUERY event. Currently, it only applies to Wi-Fi and Bluetooth LE combo devices.

tuya_ble_dp_data_send_ack_t

typedef enum {
    DP_SEND_WITH_RESPONSE = 0,    // Need a mobile app to answer.
    DP_SEND_WITHOUT_RESPONSE,     // No need for mobile app to answer.
} tuya_ble_dp_data_send_ack_t;

• DP_SEND_WITH_RESPONSE: The mobile phone needs to return an acknowledgment.

• DP_SEND_WITHOUT_RESPONSE: The mobile phone does not need to return an acknowledgment.

tuya_ble_dp_data_send_mode_t

typedef enum {
    DP_SEND_FOR_CLOUD_PANEL = 0,   // The mobile app uploads the received dp data to the cloud and also sends it to the panel for display.
    DP_SEND_FOR_CLOUD,             // The mobile app will only upload the received dp data to the cloud.
    DP_SEND_FOR_PANEL,             // The mobile app will only send the received dp data to the panel display.
    DP_SEND_FOR_NONE,              // Neither uploaded to the cloud nor sent to the panel display.
} tuya_ble_dp_data_send_mode_t;

• DP_SEND_FOR_CLOUD_PANEL: The device reports data to both the cloud and app panel.

• DP_SEND_FOR_CLOUD: The device reports data to the cloud only.

• DP_SEND_FOR_PANEL: The device reports data to the app panel only.

• DP_SEND_FOR_NONE: The device reports data neither to the app panel nor to the cloud, which is rarely used.

tuya_ble_dp_data_send_time_type_t

typedef enum {
    DP_TIME_TYPE_MS_STRING = 0,
    DP_TIME_TYPE_UNIX_TIMESTAMP,
} tuya_ble_dp_data_send_time_type_t;

• DP_TIME_TYPE_MS_STRING: 13-byte timestamp in milliseconds.

• DP_TIME_TYPE_UNIX_TIMESTAMP: 4-byte Unix timestamp.

API description

Report DP data

API description

tuya_ble_status_t tuya_ble_dp_data_send(UINT32_T sn,tuya_ble_dp_data_send_type_t type,tuya_ble_dp_data_send_mode_t mode,tuya_ble_dp_data_send_ack_t ack,UINT8_T *p_dp_data,UINT32_T dp_data_len);

Direction

Parameter description

Parameter	Description
sn	The sequence number of messaging, managed by the application layer. It starts from 0, incremented by 1. Refer to g_sn in the sample code.
type	Messaging type: DP_SEND_TYPE_ACTIVE: The device proactively reports data. DP_SEND_TYPE_PASSIVE: The device reports data after receiving a query (TUYA_BLE_CB_EVT_DP_QUERY) from the mobile app.
mode	Messaging mode: DP_SEND_FOR_CLOUD_PANEL: The device reports data to both the cloud and app panel. DP_SEND_FOR_CLOUD: The device reports data to the cloud only. DP_SEND_FOR_PANEL: The device reports data to the app panel only.
ack	Whether the receiver returns an acknowledgment. DP_SEND_WITH_RESPONSE: with acknowledgment. DP_SEND_WITHOUT_RESPONSE: with no acknowledgment.
p_dp_data	The content of the DP data.
dp_data_len	The length of the DP data.

Report DP data (with timestamp)

API description

tuya_ble_status_t tuya_ble_dp_data_with_time_send(UINT32_T sn,tuya_ble_dp_data_send_mode_t mode,tuya_ble_dp_data_send_time_type_t time_type,UINT8_T *p_time_data,UINT8_T *p_dp_data,UINT32_T dp_data_len);

Direction

Parameter description

Parameter	Description
sn	The sequence number of messaging, managed by the application layer. It starts from 0, incremented by 1. Refer to g_sn in the sample code.
mode	Messaging mode: DP_SEND_FOR_CLOUD_PANEL: The device reports data to both the cloud and app panel. DP_SEND_FOR_CLOUD: The device reports data to the cloud only. DP_SEND_FOR_PANEL: The device reports data to the app panel only.
time_type	Time type: DP_TIME_TYPE_MS_STRING: A 13-byte time string in milliseconds. DP_TIME_TYPE_UNIX_TIMESTAMP: A 4-byte Unix timestamp.
p_time_data	The time data, in a format determined by time_type.
p_dp_data	The content of the DP data.
dp_data_len	The length of the DP data.

Receive DP data

API description

TUYA_BLE_CB_EVT_DP_DATA_RECEIVED

Direction

Parameter description

Parameter	Description
p_data	The content of the DP data.
data_len	The length of the DP data.

Respond to DP data reporting

API description

TUYA_BLE_CB_EVT_DP_DATA_SEND_RESPONSE
TUYA_BLE_CB_EVT_DP_DATA_WITH_TIME_SEND_RESPONSE

Direction

Parameter description

Parameter	Description
status	The result of DP data reporting.

DP query

API description

TUYA_BLE_CB_EVT_DP_QUERY

Direction

Parameter description

Parameter	Description
p_data	Enum of dp_id to be queried.
data_len	The number of dp_id to be queried. 0 indicates all DPs are queried.

How to use

Communication process

Code development

See the APIs tuya_ble_dp_data_send and tuya_ble_dp_data_with_time_send in tal_sdk_test.c for details.

TUYA_WEAK_ATTRIBUTE OPERATE_RET test_group_data(UINT8_T cmd, UINT8_T *cmd_data, UINT32_T cmd_data_len, UINT8_T *p_rsp_data)
{
    TEST_GROUP_VARIABLE

    switch (cmd) {
        …………

        case TEST_CID_DP_REPORT: {
            ret = tuya_ble_dp_data_send(g_sn++, DP_SEND_TYPE_ACTIVE, DP_SEND_FOR_CLOUD_PANEL, cmd_data[0], &cmd_data[1], cmd_data_len-1);
            TEST_RSP
        } break;

        case TEST_CID_LONG_DP_REPORT: {
            UINT8_T* tmp_buf = tal_malloc(TUYA_BLE_SEND_MAX_DATA_LEN);
            if (tmp_buf) {
                UINT16_T dp_data_len = (cmd_data[5]<<8) + cmd_data[6];

                tmp_buf[0] = cmd_data[1];
                tmp_buf[1] = cmd_data[2];
                tmp_buf[2] = cmd_data[5];
                tmp_buf[3] = cmd_data[6];

                for (UINT32_T idx=0; idx<dp_data_len; idx++) {
                    tmp_buf[4+idx] = idx;
                }

                ret = tuya_ble_dp_data_send(g_sn++, DP_SEND_TYPE_ACTIVE, DP_SEND_FOR_CLOUD_PANEL, cmd_data[0], tmp_buf, dp_data_len + 4);

                tal_free(tmp_buf);
            } else {
                ret = OPRT_MALLOC_FAILED;
            }

            TEST_RSP
        } break;

        case TEST_CID_DP_REPORT_TIME: {
            if (cmd_data[0] == DP_TIME_TYPE_MS_STRING) {
                ret = tuya_ble_dp_data_with_time_send(g_sn++, DP_SEND_FOR_CLOUD_PANEL, cmd_data[0], &cmd_data[1], cmd_data+1+13, cmd_data_len-1-13);
            } else if (cmd_data[0] == DP_TIME_TYPE_UNIX_TIMESTAMP) {
                ret = tuya_ble_dp_data_with_time_send(g_sn++, DP_SEND_FOR_CLOUD_PANEL, cmd_data[0], &cmd_data[1], cmd_data+1+4, cmd_data_len-1-4);
            }

            TEST_RSP
        } break;

        case TEST_CID_LONG_DP_REPORT_TIME: {
            UINT8_T* tmp_buf = tal_malloc(TUYA_BLE_SEND_MAX_DATA_LEN);
            if (tmp_buf) {
                UINT16_T dp_data_len = (cmd_data[9]<<8) + cmd_data[10];

                tmp_buf[0] = cmd_data[5];
                tmp_buf[1] = cmd_data[6];
                tmp_buf[2] = cmd_data[9];
                tmp_buf[3] = cmd_data[10];

                for (UINT32_T idx=0; idx<dp_data_len; idx++) {
                    tmp_buf[4+idx] = idx;
                }

                if (cmd_data[0] == DP_TIME_TYPE_MS_STRING) {
                    ret = tuya_ble_dp_data_with_time_send(g_sn++, DP_SEND_FOR_CLOUD_PANEL, cmd_data[0], &cmd_data[1], tmp_buf, dp_data_len+4);
                } else if (cmd_data[0] == DP_TIME_TYPE_UNIX_TIMESTAMP) {
                    ret = tuya_ble_dp_data_with_time_send(g_sn++, DP_SEND_FOR_CLOUD_PANEL, cmd_data[0], &cmd_data[1], tmp_buf, dp_data_len+4);
                }

                tal_free(tmp_buf);
            } else {
                ret = OPRT_MALLOC_FAILED;
            }

            TEST_RSP
        } break;

        …………

        default: {
        } break;
    }

    return idx;
}

Functional testing

Prerequisites

• You have installed the Tuya app on your phone.
• Your device has been paired.

Procedure

Communicate with the mobile app using a host that simulates a real device.

1. Report LED on: The LED on the panel comes on.

2. Report LED off: The LED on the panel comes off.

3. Report welcome message: A welcome message is displayed on the app panel.

4. Report custom data: 123456 is displayed on the app panel.

5. Report a fault: Fault 2 alert is displayed on the app panel.

6. Report a fault: The alert disappears when no fault is reported.

   

If you have any problems with host usage, see Logic Host User Guide.

Support and help

If you have any problems with TuyaOS development, you can post your questions in the Tuya Developer Forum.