DP 数据通信

DP（Data Point）数据是描述涂鸦产品功能的基本单位。在涂鸦的蓝牙产品中，DP 数据通信是蓝牙设备和涂鸦智能 App 之间的基本通信方法。DP 数据定义了一种基本的数据结构，很多 DP 数据的集合就描述了涂鸦某一类产品的基本功能。

TuyaOS 蓝牙 LE SDK 提供了 DP 数据上报、DP 数据查询、DP 数据接收、DP 数据上报响应等基本功能接口，帮助您实现蓝牙设备的控制和管理。

概念介绍

想要对 DP 数据通信有一个全面的认识，首先需要了解 PID 和 DP 的概念。

涂鸦提供了照明、传感、门锁等多种品类，每种品类下涵盖了不同功能集合的 PID 定义，每个 PID 包含多个 DP 定义的功能点，DP 的基本结构为 dp_id、dp_type、dp_data_len 和 dp_data_value。下图描述了 DP 数据在涂鸦产品架构中的位置。

PID

PID（Product ID，产品 ID）是描述一类产品功能的集合。在 涂鸦开发者平台 创建的每一个产品，都会产生一个唯一的 PID，这个产品编号关联了产品具体的功能、App 控制面板、出货信息等所有跟这个产品相关的信息。关于 PID 相关的更多信息，请参考 产品定义。

PID 的创建方法有两种：

• 方式一：自行创建。详细步骤请参考 创建产品。

• 方式二：复制创建。您直接 复制一个 TyOS 演示设备 PID。复制产品的 PID 称为演示 PID，为 3aubjk7p，复制 PID 能在不同的开发者平台账号上创建相同功能的 PID。

  复制的 PID 仅用于测试/调试，不可用作生产。

DP

DP（Data Point），又称为 DP 或功能点，表示设备所具备的功能集合。

• DP 数据格式：

  字段	长度（Byte）	说明
  dp_id	1	DP 的指令码
  dp_type	1	DP 的数据类型
  dp_data_len	2	DP 的数据长度
  dp_data_value	dp_data_len 的取值	DP 的数据

• dp_type 的取值范围及含义（云端定义）如下：

  dp_type	取值	长度（Byte）	说明
  raw	0	1~N	透传型
  bool	1	1	布尔型
  value	2	4	数值型
  string	3	0~255	字符型
  enum	4	1	枚举型
  bitmap	5	4	故障型

• 演示 PID 3aubjk7p 的 DP 设置如下：

  

数据结构

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：DP 的指令码

• dp_type：DP 的数据类型

• dp_data_len：DP 的数据长度

• dp_data：DP 的数据

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：设备主动上报数据给手机。

• DP_SEND_TYPE_PASSIVE：设备被动上报数据给手机，例如，用于响应 TUYA_BLE_CB_EVT_DP_QUERY 事件，目前仅用于 Wi-Fi + 蓝牙 LE 双模设备。

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：需要手机响应。

• DP_SEND_WITHOUT_RESPONSE：不需要手机响应。

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：同时上报给面板和云端。

• DP_SEND_FOR_CLOUD：仅上报给云端。

• DP_SEND_FOR_PANEL：仅上报给面板。

• DP_SEND_FOR_NONE：既不上报给面板也不上报给云端（这种情况基本不用）。

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 字节 ms 字符串形式的时间戳。

• DP_TIME_TYPE_UNIX_TIMESTAMP：4 字节标准 Unix 时间戳。

接口说明

DP 上报

接口说明

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

数据流动

参数说明

参数	说明
sn	发送序列号，由应用层管理，从 0 开始，依次递增，可参考示例代码中的变量 g_sn
type	发送类型： DP_SEND_TYPE_ACTIVE：主动发送，设备主动上报数据 DP_SEND_TYPE_PASSIVE：被动发送，App 先询问设备（TUYA_BLE_CB_EVT_DP_QUERY），设备再上报数据
mode	发送模式： DP_SEND_FOR_CLOUD_PANEL：同时上报给云端和面板 DP_SEND_FOR_CLOUD：只上报给云端 DP_SEND_FOR_PANEL：只上报给面板
ack	是否有响应： DP_SEND_WITH_RESPONSE：有响应 DP_SEND_WITHOUT_RESPONSE：没有响应
p_dp_data	DP 数据内容
dp_data_len	DP 数据长度

DP 上报（带时间戳）

接口说明

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

数据流动

参数说明

参数	说明
sn	发送序列号，由应用层管理，从 0 开始，依次递增，可参考示例代码中的变量 g_sn
mode	发送模式： DP_SEND_FOR_CLOUD_PANEL：同时上报给云端和面板 DP_SEND_FOR_CLOUD：只上报给云端 DP_SEND_FOR_PANEL：只上报给面板
time_type	时间类型： DP_TIME_TYPE_MS_STRING：13 字节 ms 字符串 DP_TIME_TYPE_UNIX_TIMESTAMP：4 字节 unix 时间戳
p_time_data	时间数据，由 time_type 决定具体格式
p_dp_data	DP 数据内容
dp_data_len	DP 数据长度

DP 接收事件

接口说明

TUYA_BLE_CB_EVT_DP_DATA_RECEIVED

数据流动

参数说明

参数	说明
p_data	DP 数据内容
data_len	DP 数据长度

DP 上报响应

接口说明

TUYA_BLE_CB_EVT_DP_DATA_SEND_RESPONSE
TUYA_BLE_CB_EVT_DP_DATA_WITH_TIME_SEND_RESPONSE

数据流动

参数说明

参数	说明
status	DP 上报结果

DP 查询

接口说明

TUYA_BLE_CB_EVT_DP_QUERY

数据流动

参数说明

参数	说明
p_data	要查询的 dp_id 枚举
data_len	要查询的 dp_id 个数，为 0 表示查询全部的 DP

使用方法

通信流程

代码开发

请参考 tal_sdk_test.c 中关于接口 tuya_ble_dp_data_send 和 tuya_ble_dp_data_with_time_send 的使用方法：

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

功能测试

前置条件

• 您已经下载了涂鸦智能 App。
• 请确认您的设备已完成配网。

操作步骤

通过上位机（模拟实际产品）和手机 App 进行数据交互。如下所示：

1. 上报打开 LED：面板 LED 被点亮。

2. 上报关闭 LED：面板 LED 被熄灭。

3. 上报欢迎词：Welcome，面板显示欢迎词。

4. 上报自定义数据：123456，面板显示自定义数据。

5. 上报故障告警：故障 2，面板弹窗告警。

6. 上报故障告警：无故障，面板弹窗消失。

   

上位机使用的相关问题，请访问 Logic 上位机使用指南。

支持与帮助

在开发过程遇到问题，您可以登录 TuyaOS 开发者论坛 TuyaOS-蓝牙设备开发 版块进行沟通咨询。

咨询前建议首先查阅 官方资料 或参考已有帖子，并认真阅读 发帖规范。