Data Point (DP)

NB-IoT devices exchange data with the cloud based on data points (DPs). This topic describes the DPs defined by TuyaOS.

Background

The types of DPs vary depending on product form factors. You can call the data type-specific APIs to assemble or parse packets. You can also report record-type data as required.

Example

Report multiple DPs

static void multi_dps_report_demo(void)
{
    int max_num_dp = 7;
    int dpid_cnt = 0;
    lwdp_object_t* dataP = tuya_user_api_lwdp_object_new(max_num_dp);
    if (dataP == NULL) {
        USER_API_LOGE("lwdp obj malloc fail");
        return;
    }

    // String DP
    dataP[dpid_cnt].id = 3;
    tuya_user_api_lwdp_encode_string("hello world", &dataP[dpid_cnt]);
    dpid_cnt++;

    // Bool DP
    dataP[dpid_cnt].id = 9;
    tuya_user_api_lwdp_encode_bool(true, &dataP[dpid_cnt]);
    dpid_cnt++;

    // Integer DP
    dataP[dpid_cnt].id = 10;
    tuya_user_api_lwdp_encode_int(123, &dataP[dpid_cnt]);
    dpid_cnt++;

    // Enum DP
    dataP[dpid_cnt].id = 12;
    tuya_user_api_lwdp_encode_enum(2, &dataP[dpid_cnt]);
    dpid_cnt++;

    // MAP DP
    dataP[dpid_cnt].id = 19;
    tuya_user_api_lwdp_encode_map(0xff55, &dataP[dpid_cnt]);
    dpid_cnt++;

    tuya_user_api_dp_report(true, dpid_cnt, dataP);
    tuya_user_api_lwdp_object_free(max_num_dp, dataP);
}

Process received commands

static uint8_t tuya_dp_write_cb(IN lwdp_object_t* dataP)
{
    uint16_t len;
    size_t str_len;
    int32_t value;

    if(NULL == dataP){
        USER_API_LOGE("dataP NULL");
        return CODE_UNKOWN_ERROR;
    }

    while(NULL != dataP){
        com_dp_data_t* dp_data = NULL;
        uint8_t* send_buffer = NULL;
        uint8_t* p_dp_data_buf = NULL;

        len = tuya_user_api_get_lwdp_object_length(dataP);
        send_buffer = (uint8_t*)Malloc(sizeof(com_dp_data_t) + len + 1);
        if (send_buffer == NULL) {
            USER_API_LOGE("send_buffer is NULL");
            return CODE_UNKOWN_ERROR;
        }

        memset(send_buffer, 0, sizeof(com_dp_data_t) + len + 1);
        dp_data = (com_dp_data_t*)send_buffer;
        p_dp_data_buf = (uint8_t *)dp_data + sizeof(com_dp_data_t);

        switch (dataP->type) {
        case DP_TYPE_BOOLEAN:
            tuya_user_api_lwdp_decode_bool(dataP, (bool*)p_dp_data_buf);
            break;

        case DP_TYPE_INTEGER:
            tuya_user_api_lwdp_decode_int(dataP, &value);
            value = DWORD_SWAP(value);
            memcpy(p_dp_data_buf, &value, sizeof(int32_t));
            break;

        case DP_TYPE_RAW:
            tuya_user_api_lwdp_decode_raw(dataP, p_dp_data_buf, &str_len);
            break;

        case DP_TYPE_ENUM:
            tuya_user_api_lwdp_decode_enum(dataP, p_dp_data_buf);
            break;

        case DP_TYPE_STRING:
            tuya_user_api_lwdp_decode_string(dataP, (char*)p_dp_data_buf, &str_len);
            break;
        }
        dp_data->dpid = dataP->id;
        dp_data->type = dataP->type;
        USER_API_LOGI("tuya_dp_write_cb DP:%d, type:%d, len:%d", dp_data->dpid, dp_data->type, len);

        dp_data->len = WORD_SWAP(len);

        if(DPID_HEARTBEAT_INTERVAL == dp_data->dpid){
            uint32_t lifetime = 0;
   			if (len == 4) {
		        ((uint8_t*)(&lifetime))[0] = p_dp_data_buf[3];
		        ((uint8_t*)(&lifetime))[1] = p_dp_data_buf[2];
		        ((uint8_t*)(&lifetime))[2] = p_dp_data_buf[1];
		        ((uint8_t*)(&lifetime))[3] = p_dp_data_buf[0];
	        	tuya_user_api_lifetime_set(lifetime);
	        }
        }

        //TODO: Process the DP data received from the cloud.

        Free(send_buffer);
        dataP = dataP->next;
    }

    return CODE_NO_ERROR;
}

API description

Set the callback for receiving DP from the cloud

Function prototype	int tuya_user_api_dp_write_default_cb (IN lwdp_write_callback_t cb)
Parameter	cb: The pointer to the callback to be set.
Description	Set the callback to invoke when DP data from the cloud is received.
Header file	#include <tuya_user_api.h>
Return value	0: Success. Other values: Failure.

Description

The function pointer lwdp_write_callback_t:

// Define a function implementation and pass in the API.
typedef uint8_t (*lwdp_write_callback_t)(lwdp_object_t* objectArrayP);

Set the callback for non-record type DP reporting

Function prototype	void tuya_user_api_dp_report_ack_register_cb (IN tuya_dp_ack_callback_t cb)
Parameter	cb: The pointer to the callback to be set.
Description	Set the callback for the result of non-record type DP data reporting.
Header file	#include <tuya_user_api.h>
Return value	0: Success. Other values: Failure.

Description

The function pointer tuya_dp_ack_callback_t:

// Define a function implementation and pass in the API.
typedef void (*tuya_dp_ack_callback_t)(uint16_t msgid, uint8_t result);

Get the number of non-record type data packets

Function prototype	int tuya_user_api_not_record_packet_count(void)
Parameter	None
Description	Get the number of non-record type data packets.
Header file	#include <tuya_user_api.h>
Return value	The number of non-record type data packets.

Set the callback for record-type DP data reporting

Function prototype	void tuya_user_api_dp_report_record_ack_register_cb (IN tuya_dp_ack_callback_t cb)
Parameter	cb: The pointer to the DP reporting callback to be set.
Description	Set the callback for the result of record-type DP data reporting.
Header file	#include <tuya_user_api.h>
Return value	None

Description

The function pointer tuya_dp_ack_callback_t:

// Define a function implementation and pass in the API.
typedef void (*tuya_dp_ack_callback_t)(uint16_t msgid, uint8_t result);

Report DP data to the cloud

Function prototype	int tuya_user_api_dp_report (IN bool is_record_type, IN int size, IN lwdp_object_t* dataP)
Parameter	is_record_type: true indicates the record type data. false indicates the non-record type data. size: The number of data sets. dataP: The pointer to the DP data. For more information, see the struct lwdp_object_t.
Description	Report DP data to the cloud.
Header file	#include <tuya_user_api.h>
Return value	0: Success Other values: Failure. The return value is invalid.

Create DP objects

Function prototype	lwdp_object_t* tuya_user_api_lwdp_object_new(IN int size)
Parameter	size: The number of DPs created.
Description	Create DP objects.
Header file	#include <tuya_user_api.h>
Return value	The pointer to the DP instance. For more information, see the struct lwdp_object_t.

Release DP objects

Function prototype	void tuya_user_api_lwdp_object_free (IN int size, IN lwdp_object_t* dataP)
Parameter	size: The number of DPs released. dataP: The start address of the DP data released. For more information, see the struct lwdp_object_t.
Description	Release DP objects.
Header file	#include <tuya_user_api.h>
Return value	The pointer to the DP instance.

Get the length of the current DP packet

Function prototype	uint16_t tuya_user_api_get_lwdp_object_length (IN lwdp_object_t* dataP)
Parameter	dataP: The lwdp_object_t object to be obtained. For more information, see the struct lwdp_object_t.
Description	Get the length of the current DP packet.
Header file	#include <tuya_user_api.h>
Return value	None

Decode Boolean DP data

Function prototype	int tuya_user_api_lwdp_decode_bool (IN lwdp_object_t* dataP, OUT bool* outP)
Parameter	dataP: The lwdp_object_t object to be decoded. For more information, see the struct lwdp_object_t. outP: The decoded Boolean data.
Description	Decode the DP data of Boolean type.
Header file	#include <tuya_user_api.h>
Return value	None

Decode integer DP data

Function prototype	int tuya_user_api_lwdp_decode_int (IN lwdp_object_t* dataP, OUT int32_t* outP)
Parameter	dataP: The lwdp_object_t object to be decoded. For more information, see the struct lwdp_object_t. outP: The decoded integer data.
Description	Decode the DP data of integer type.
Header file	#include <tuya_user_api.h>
Return value	0: Success. Other values: Failure. The return value is invalid.

Decode raw DP data

Function prototype	int tuya_user_api_lwdp_decode_raw (IN lwdp_object_t* dataP, OUT uint8_t* outP, OUT size_t* olen)
Parameter	dataP: The lwdp_object_t object to be decoded. For more information, see the struct lwdp_object_t. outP: The decoded raw data. olen: The length of the decoded raw data.
Description	Decode the DP data of raw type.
Header file	#include <tuya_user_api.h>
Return value	0: Success. Other values: Failure. The return value is invalid.

Decode string DP data.

Function prototype	int tuya_user_api_lwdp_decode_string (IN lwdp_object_t* dataP, OUT char* outP, OUT size_t* olen)
Parameter	dataP: The lwdp_object_t object to be decoded. For more information, see the struct lwdp_object_t. outP: The pointer to the decoded string. olen: The length of the decoded string.
Description	Decode the DP data of string type.
Header file	#include <tuya_user_api.h>
Return value	0: Success. Other values: Failure. The return value is invalid.

Decode enum DP data

Function prototype	int tuya_user_api_lwdp_decode_enum (IN lwdp_object_t* dataP, OUT uint8_t* enum_idx)
Parameter	dataP: The lwdp_object_t object to be decoded. For more information, see the struct lwdp_object_t. enum_idx: The decoded enum subscript.
Description	Decode the DP data of enum type.
Header file	#include <tuya_user_api.h>
Return value	0: Success. Other values: Failure. The return value is invalid.

Encode Boolean DP data

Function prototype	void tuya_user_api_lwdp_encode_bool (IN bool value, OUT lwdp_object_t* dataP)
Parameter	value: The Boolean data to be encoded. dataP: The lwdp_object_t object to be encoded. For more information, see the struct lwdp_object_t.
Description	Encode the DP data of Boolean type.
Header file	#include <tuya_user_api.h>
Return value	None

Encode raw DP data

Function prototype	void tuya_user_api_lwdp_encode_raw (IN uint8_t* buffer, IN size_t length, OUT lwdp_object_t* dataP)
Parameter	buffer: The pointer to the raw data to be encoded to the lwdp_object_t object. length: The length of the raw data to be encoded. dataP: The encapsulated object returned. For more information, see the struct lwdp_object_t.
Description	Encode the DP data of raw type.
Header file	#include <tuya_user_api.h>
Return value	None

Encode string DP data

Function prototype	void tuya_user_api_lwdp_encode_string (IN const char* string, OUT lwdp_object_t* dataP)
Parameter	string: The pointer to the string data to be encapsulated to the lwdp_object_t object. dataP: The encapsulated object returned. For more information, see the struct lwdp_object_t.
Description	Encode the DP data of string type.
Header file	#include <tuya_user_api.h>
Return value	None

Encode string DP data (with length)

Function prototype	void tuya_user_api_lwdp_encode_nstring (IN const char* string, IN size_t length, OUT lwdp_object_t* dataP)
Parameter	string: The pointer to the string data to be encoded to the lwdp_object_t object. length: The length of the string to be encoded. dataP: The encapsulated object returned. For more information, see the struct lwdp_object_t.
Description	Encode the DP data of string type.
Header file	#include <tuya_user_api.h>
Return value	None

Encode integer DP data

Function prototype	void tuya_user_api_lwdp_encode_int (IN int32_t value, OUT lwdp_object_t* dataP)
Parameter	value: The data to be encoded to integer data type. dataP: The encoded object returned. For more information, see the struct lwdp_object_t.
Description	Encode the DP data of integer type.
Header file	#include <tuya_user_api.h>
Return value	None

Encode enum DP data

Function prototype	void tuya_user_api_lwdp_encode_enum (IN uint32_t value, OUT lwdp_object_t* dataP)
Parameter	value: The data to be encoded to enum data type. dataP: The encoded object returned. For more information, see the struct lwdp_object_t.
Description	Encode the DP data of enum type.
Header file	#include <tuya_user_api.h>
Return value	None

Encode bitmap DP data

Function prototype	void tuya_user_api_lwdp_encode_map (IN uint32_t value, OUT lwdp_object_t* dataP)
Parameter	value: The data to be encoded to bitmap data type. dataP: The encoded object returned. For more information, see the struct lwdp_object_t.
Description	Encode the DP data of bitmap type.
Header file	#include <tuya_user_api.h>
Return value	None