Data Point (DP)

A data point (DP) is an abstract representation of a function defined for a physical product. The DP supports six data types including value, Boolean, enum, string, fault, and raw.

This topic describes how to implement device control and data reporting based on the DP.

Implementation

• Call tuya_gw_user_dp_reg to register DP handlers. In the callback, parse the DP data and execute the command accordingly.
• When the status of a DP changes, call the DP reporting API to send the data of this DP to the cloud.

Example

#include "tuya_gw_dp_mgr.h"

VOID __dp_cmd_obj(IN CONST TY_RECV_OBJ_DP_S *dp)
{
    UINT_T i = 0;

    PR_DEBUG("recv soc obj dp, cmd_tp: %d, dtt_tp: %d, dp_cnt: %u", dp->cmd_tp, dp->dtt_tp, dp->dps_cnt);

    for (i = 0; i < dp->dps_cnt; i++) {
        CONST TY_OBJ_DP_S *p_dp_obj = dp->dps + i;
        PR_DEBUG("idx: %d, dpid: %d, type: %d, ts: %u", index, p_dp_obj->dpid, p_dp_obj->type, p_dp_obj->time_stamp);
        switch (p_dp_obj->type) {
            case PROP_BOOL:     { PR_DEBUG("bool value: %d", p_dp_obj->value.dp_bool); break;}
            case PROP_VALUE:    { PR_DEBUG("int value: %d", p_dp_obj->value.dp_value); break;}
            case PROP_STR:      { PR_DEBUG("str value: %s", p_dp_obj->value.dp_str); break;}
            case PROP_ENUM:     { PR_DEBUG("enum value: %u", p_dp_obj->value.dp_enum); break;}
            case PROP_BITMAP:   { PR_DEBUG("bits value: 0x%X", p_dp_obj->value.dp_bitmap); break;}
            default:            { PR_DEBUG("idx: %d dpid: %d type: %d ts: %u is invalid", index, p_dp_obj->dpid, p_dp_obj->type, p_dp_obj->time_stamp); break;}
        }
    }
    // TODO: Parse DP data and act accordingly.

    // Report the data received from the sub-device as a response to the request.
    OPERATE_RET op_ret = dev_report_dp_json_async(NULL, dp->dps, dp->dps_cnt);
    if (OPRT_OK != op_ret) {
        PR_DEBUG("dev_report_dp_json_async err: %d", op_ret);
    }
}

VOID __dp_cmd_raw(IN CONST TY_RECV_RAW_DP_S *dp)
{
    PR_DEBUG("recv soc raw dp, cmd_tp: %d, dtt_tp: %d, dpid: %d, len: %u", dp->cmd_tp, dp->dtt_tp, dp->dpid, dp->len);

    // Parse raw data and act accordingly.
}

/**
 * @brief Query DP
 *
 * @param[in] dp_qry The list of queried DPs. See TY_DP_QUERY_S
 */
VOID __dp_cmd_query(IN CONST TY_DP_QUERY_S *dp_qry)
{
    UINT_T i = 0;

    PR_DEBUG("recv soc dp query");

    if (dp_qry->cnt == 0) {
        PR_WARN("query cnt is 0");
        return;
    } else {
        PR_DEBUG("query cnt: %d", dp_qry->cnt);
        for (i = 0; i < dp_qry->cnt; i++) {
            PR_DEBUG("dpid: %d", dp_qry->dpid[index]);
            // TODO: Read the current status of the specified DP and report it.
        }
    }
}

/**
 * @brief Example of registering DP reception.
 */
VOID demo_gw_dp(VOID)
{
    TY_GW_DP_CBS_S dp_cbs = {
        .obj   = __dp_cmd_obj,
        .raw   = __dp_cmd_raw,
        .query = __dp_cmd_query
    };

    tuya_gw_user_dp_reg(&dp_cbs);

    return;
}

/**
 * @brief Example of reporting object-type DP data.
 */
VOID demo_report_dp(VOID)
{
    TY_OBJ_DP_S dp;

    // Boolean
    memset(&dp, 0x00, SIZEOF(TY_OBJ_DP_S));
    dp.dpid = 101;
    dp.time_stamp = 0;
    dp.type = PROP_BOOL;
    dp.value.dp_bool = TRUE;
    TUYA_CALL_ERR_LOG(dev_report_dp_json_async(NULL, &dp, 1));

    // Value
    memset(&dp, 0x00, SIZEOF(TY_OBJ_DP_S));
    dp.dpid = 102;
    dp.time_stamp = 0;
    dp.type = PROP_VALUE;
    dp.value.dp_value = 2;
    TUYA_CALL_ERR_LOG(dev_report_dp_json_async(NULL, &dp, 1));

    // String
    memset(&dp, 0x00, SIZEOF(TY_OBJ_DP_S));
    dp.dpid = 103;
    dp.time_stamp = 0;
    dp.type = PROP_STR;
    dp.value.dp_str = "Hello";
    TUYA_CALL_ERR_LOG(dev_report_dp_json_async(NULL, &dp, 1));

    // String
    memset(&dp, 0x00, SIZEOF(TY_OBJ_DP_S));
    dp.dpid = 104;
    dp.time_stamp = 0;
    dp.type = PROP_STR;
    dp.value.dp_str = "Hello";
    TUYA_CALL_ERR_LOG(dev_report_dp_json_async(NULL, &dp, 1));

    // Enum
    memset(&dp, 0x00, SIZEOF(TY_OBJ_DP_S));
    dp.dpid = 105;
    dp.time_stamp = 0;
    dp.type = PROP_ENUM;
    dp.value.dp_enum = 0;
    TUYA_CALL_ERR_LOG(dev_report_dp_json_async(NULL, &dp, 1));    
}

API description

Receive DP

/**
 * @brief Register the gateway DP handler.
 *
 * @param cb The callback. See TY_GW_DP_CBS_S
 */
OPERATE_RET tuya_gw_user_dp_reg(TY_GW_DP_CBS_S *cb);

Report object-type DP

/**
 * @brief Report object-type DP data asynchronously.
 *
 * @param[in] dev_id  If the DP belongs to the gateway, report this parameter as NULL. Otherwise, report the device ID.
 * @param[in] dp_data The array of DP data.
 * @param[in] cnt dp  The length of the array of DP data.
 *
 * @return OPRT_OK for success. For other error codes, see tuya_error_code.h
 */
OPERATE_RET dev_report_dp_json_async(IN CONST CHAR_T *dev_id,
                                     IN CONST TY_OBJ_DP_S *dp_data,
                                     IN CONST UINT_T cnt)

Report raw DP

/**
 * @brief  Report raw DP data synchronously.
 *
 * @param[in] dev_id              If the DP belongs to the gateway, report this parameter as NULL. Otherwise, report the device ID.
 * @param[in] dpid                DP ID
 * @param[in] data                Raw data
 * @param[in] len                 The length of raw data
 * @param[in] timeout             The timeout value, in seconds.
 * @param[in] enable_auto_retrans Specifies whether to enable retransmission. TRUE for enable. FALSE for disable.
 *
 * @return OPRT_OK: success  Other: fail
 */
OPERATE_RET dev_report_dp_raw_sync_extend(IN CONST CHAR_T *dev_id,
                                          IN CONST BYTE_T dpid, \
                                          IN CONST BYTE_T *data,
                                          IN CONST UINT_T len, \
                                          IN CONST UINT_T timeout,
                                          IN CONST BOOL_T enable_auto_retrans);
#define dev_report_dp_raw_sync(dev_id, dpid, data, len, timeout) \
    dev_report_dp_raw_sync_extend(dev_id, dpid, data, len, timeout, TRUE)

Report queried object-type DP

/**
 * @brief  Report the queried object-type DP asynchronously. This does not trigger the linkage.
 *
 * @param[in] dev_id  If the DP belongs to the gateway, report this parameter as NULL. Otherwise, report the device ID.
 * @param[in] dp_data The array of DP data.
 * @param[in] cnt dp  The length of the array of DP data.
 *
 * @return OPRT_OK for success. For other error codes, see tuya_error_code.h
 */
OPERATE_RET dev_query_dp_json_async(IN CONST CHAR_T *dev_id,
                                    IN CONST TY_OBJ_DP_S *dp_data,
                                    IN CONST UINT_T cnt);

Report object-type DP of record-type

/**
 * @brief   Report the object-type DP of record-type synchronously. The timestamp when data is reported is recorded.
 *
 * @param[in] dev_id              If the DP belongs to the gateway, report this parameter as NULL. Otherwise, report the device ID.
 * @param[in] dp_data             The array of DP data.
 * @param[in] cnt dp              The length of the array of DP data.
 * @param[in] timeout             The timeout value, in seconds.
 * @param[in] enable_auto_retrans Specifies whether to enable retransmission. TRUE for enable. FALSE for disable.
 *
 * @return OPRT_OK for success. For other error codes, see tuya_error_code.h
 */
OPERATE_RET dev_report_dp_stat_sync_extend(IN CONST CHAR_T *dev_id,
                                           IN CONST TY_OBJ_DP_S *dp_data, \
                                           IN CONST UINT_T cnt,
                                           IN CONST UINT_T timeout,
                                           IN CONST BOOL_T enable_auto_retrans);
#define dev_report_dp_stat_sync(dev_id, dp_data, cnt, timeout) \
    dev_report_dp_stat_sync_extend(dev_id, dp_data, cnt, timeout, TRUE)