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 the APIs that the laser navigation robot vacuum uses to report DPs. For more information about the concepts of DPs, descriptions, and APIs, see DP Model and Control Protocol.

Implementation

The following callbacks are registered in the TuyaOS SDK:

• ty_cmd_handle_dp_cmd_objs: Notify you of an object DP command.
• robotics_app_dp_raw_objs: Notify you of a raw DP command.
• robotics_app_dp_query_objs: Notify you of a query for the current status of the specified DP.

Example

/**
 * @brief   Sync DP when the device is online.
 * @param  [unsigned char*] p_obj_dp
 * @param  [unsigned int] len
 * @return [*]
 */
OPERATE_RET dp_handle_sync_to_cloud(void)
{
    /*****
     * Process business logic.
     * Cloud traffic limitations: Do not exceed 3,500 reports per day, and the number of DP reports within a 10-minute period should not exceed 1,200.
     * To resolve this limit, report multiple DPs in a request.
     *******/

    PR_DEBUG("update all dp to cloud");
    OPERATE_RET ret = 0;
    TY_OBJ_DP_S *dp_obj_buf = NULL;

    char num = 5;

    dp_obj_buf = malloc(num * sizeof(TY_OBJ_DP_S));
    if(dp_obj_buf == NULL) {
        PR_ERR("ty_sdk_adapter_dp_num_report malloc error");
    }

    memset(dp_obj_buf, 0, num * sizeof(TY_OBJ_DP_S));

    TY_OBJ_DP_S* obj_data_tmp = dp_obj_buf;

//switch go DP
    obj_data_tmp->dpid = TUYA_DP_SWITCH_GO;
    obj_data_tmp->type = PROP_BOOL;
    obj_data_tmp->value.dp_bool = 1;

    obj_data_tmp += 1;

//pause DP
    obj_data_tmp->dpid = TUYA_DP_PAUSE;
    obj_data_tmp->type = PROP_BOOL;
    obj_data_tmp->value.dp_bool = 0;

    obj_data_tmp += 1;

//switch charge DP
    obj_data_tmp->dpid = TUYA_DP_SWITCH_CHARGE;
    obj_data_tmp->type = PROP_BOOL;
    obj_data_tmp->value.dp_bool = 0;

    obj_data_tmp += 1;

//work mode DP
    obj_data_tmp->dpid = TUYA_DP_WORK_MODE;
    obj_data_tmp->type = PROP_ENUM;
    obj_data_tmp->value.dp_enum = 0;

    obj_data_tmp += 1;

//status DP
    obj_data_tmp->dpid = TUYA_DP_STATUS;
    obj_data_tmp->type = PROP_ENUM;
    obj_data_tmp->value.dp_enum = DP_ST_STANDBY;

    obj_data_tmp += 1;

    ret = dev_report_dp_json_async(NULL, dp_obj_buf, num);

    if(dp_obj_buf) {
        free(dp_obj_buf);
        dp_obj_buf = NULL;
    }
}
/**
 * @brief  Receive object DP data.
 * @param  [TY_RECV_OBJ_DP_S*] p_obj_dp
 * @param  [*]
 * @return [*]
 */
VOID robotics_app_dp_cmd_objs(IN CONST TY_RECV_OBJ_DP_S* dp_rev)
{
    TY_OBJ_DP_S* dp_data = (TY_OBJ_DP_S*)(dp_rev->dps);
    UINT_T cnt = dp_rev->dps_cnt;
    INT_T table_idx = 0;
    INT_T table_count = (sizeof(s_dp_table) / sizeof(s_dp_table[0]));
    INT_T index = 0;
    for (index = 0; index < cnt; index++) {
        TY_OBJ_DP_S* p_dp_obj = dp_data + index;
        PR_DEBUG("recv dpid:[%d]\r\n", p_dp_obj->dpid);
       /* Simply parse the received data. Execute the specific actions in a different task.*/
    }
}

/**
 * @brief  Receive raw DP data.
 * @param  [TY_RECV_RAW_DP_S*] p_obj_dp
 * @return [*]
 */
VOID robotics_app_dp_raw_objs(IN CONST TY_RECV_RAW_DP_S* dp_rev)
{
    unsigned char * dp_data = dp_rev->data;
    int table_idx = 0;
    int table_count = (sizeof(s_raw_dp_table) / sizeof(s_raw_dp_table[0]));

    PR_DEBUG("dpid:%d cmd_tp:%d", dp_rev->dpid, dp_rev->cmd_tp);
    for (table_idx = 0; table_idx < table_count; table_idx++) {
        /*Simply parse the received data. Execute the specific actions in a different task.*/
        /* For the received data, refer to the laser robot vacuum protocol.*/
    }
}

/**
 * @brief   Receive DP queries.
 * @param  [TY_DP_QUERY_S*] p_obj_dp
 * @param  [*]
 * @return [*]
 */
VOID robotics_app_dp_query_objs(IN CONST TY_DP_QUERY_S* dp_query)
{
    if (!dp_query->cnt) {
        PR_DEBUG("recv query objs cnt = 0");
        return;
    }
    dp_handle_sync_to_cloud();   // The DP query command for the robot vacuum. The device should synchronize the DP status with the app accordingly.
}
   /**
* @brief main initialization
* @param [*]
* @return [*]
*/
OPERATE_RET main(void)
{
   char s_mqtt_online_status = FALSE;
    TY_IOT_CBS_S iot_cbs = {0};
    iot_cbs.dev_obj_dp_cb   = ty_cmd_handle_dp_cmd_objs;     //  Register the object DP receiving function.
    iot_cbs.dev_raw_dp_cb   = ty_cmd_handle_dp_raw_objs;     // Register the raw DP receiving function.
    iot_cbs.dev_dp_query_cb = ty_cmd_handle_dp_query_objs;   // Register the DP query function.
    // Invoked when the device is online to sync DP data.
    if(TRUE == s_mqtt_online_status) {
       OPERATE_RET ret = dp_handle_sync_to_cloud();
       if(ret != OPRT_OK) {
          PR_ERR("dp sync to cloud err %d", ret);
          return ret;
       }
       // To receive and report different types of DPs and raw DPs, see the implementation in the demo.
    }
}

API description

Report object DP asynchronously

/**
 * @brief dev_report_dp_json_async
 * @desc report dp info a-synced.
 *
 * @param[in] dev_id: if sub-device, then devid = sub-device_id
 *                if gateway/soc/mcu, then devid = NULL
 * @param[in] dp_data: dp array header
 * @param[in] cnt: dp array count
 *
 * @return OPRT_OK: success, other: fail
 */
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 synchronously

/**
 * @brief dev_report_dp_raw_sync_extend
 * @desc report dp raw info synced.
 *
 * @param[in] dev_id: if sub-device, then devid = sub-device_id
 *                if gateway/soc/mcu, then devid = NULL
 * @param[in] dpid: raw dp id
 * @param[in] data: raw data
 * @param[in] len: len of raw data
 * @param[in] timeout: function blocks until timeout seconds
 * @param[in] enable_auto_retrans
 *
 * @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 DP asynchronously

/**
 * @brief dev_query_dp_json_async
 * @desc report dp info a-synced.
 *
 * @param[in] dev_id: if sub-device, then devid = sub-device_id
 *                if gateway/soc/mcu, then devid = NULL
 * @param[in] dp_data: dp array header
 * @param[in] cnt: dp array count
 *
 * @return OPRT_OK: success, other: fail
 */
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 record-type object DP synchronously

/**
 * @brief dev_report_dp_stat_sync_extend
 * @desc: report dp status info synced.
 *        if time_stamp==0, time_stamp = time of msg arrival of the server
 *
 * @param[in] dev_id: if sub-device, then devid = sub-device_id
 *                    if gateway/soc/mcu, then devid = NULL
 * @param[in] dp_data: dp status array header
 * @param[in] cnt: dp status array count
 * @param[in] timeout: function blocks until timeout seconds
 * @param[in] enable_auto_retrans
 *
 * @return OPRT_OK: success, other: fail
 */
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);