Control Data Points

A data point (DP) is an abstract representation of a function defined for a physical product. Control of a DP enables you to change the status of a device through the predefined function. For example, the on/off DP is used to turn on/off a device.

Concepts

• Data type: A data type is an attribute associated with a DP. It determines the values a DP may contain. Data types are broken down into two categories:

  • Object type:
    • Boolean
    • Value
    • Enum
    • String
    • Bitmap
  • Raw

• Purpose: Abstract descriptions of device properties and functions help to standardize and manage a myriad of smart devices in a unified way. Describing a sub-device with a set of DPs can shield the differences between underlying hardware for low coupling.

• Example: A smart light bulb has three major functions: on/off, brightness, and color temperature.

  

Description

• To send a DP command to the sub-device, the gateway should convert the DP data to the sub-device readable format. After the sub-device executes the command, the gateway reports the latest status of the sub-device to the cloud as a response to the command execution.

• The gateway should convert the data received from the sub-device into the DP data before reporting it to the cloud.

The following sequence diagram shows how they interact with each other:

The interaction can be broken down into two parts:

1. The SDK notifies the application of processing a DP command.
2. The application calls the SDK’s DP status reporting function to synchronize status to the cloud.

How to

• Send DP commands

  Call tuya_subdev_user_sigle_type_reg to register sub-device operations and implement the DP callback accordingly.

• Report DP status

  Call dev_report_dp_json_async or dev_report_dp_raw_sync to report the DP data of the sub-device to the cloud.

Data structure

• Object type:

  /**
  * @brief Definition of structured dp
  */
  typedef struct {
  	/** dp id */
  	BYTE_T dpid;
  	/** dp type, see DP_PROP_TP_E */
  	DP_PROP_TP_E type;
  	/** dp value, see TY_OBJ_DP_VALUE_U */
  	TY_OBJ_DP_VALUE_U value;
  	/** dp happen time. if 0, mean now */
  	UINT_T time_stamp;
  } TY_OBJ_DP_S;
  

  /**
  * @brief Definition of received structured dp
  */
  typedef struct {
  	/** see DP_CMD_TYPE_E */
  	DP_CMD_TYPE_E cmd_tp;
  	/** see DP_TRANS_TYPE_T */
  	DP_TRANS_TYPE_T dtt_tp;
  	/** if(NULL == cid), then the cid represents gwid */
  	CHAR_T *cid;
  	/** mb id */
  	CHAR_T *mb_id;
  	/** count of dp */
  	UINT_T dps_cnt;
  	/** the dp data */
  	TY_OBJ_DP_S dps[0];
  } TY_RECV_OBJ_DP_S;
  

• Raw type:

  typedef struct {
  	/** see DP_CMD_TYPE_E */
  	DP_CMD_TYPE_E cmd_tp;
  	/** see DP_TRANS_TYPE_T */
  	DP_TRANS_TYPE_T dtt_tp;
  	/** if(NULL == cid), then the cid represents gwid */
  	CHAR_T *cid;
  	/** dp id */
  	BYTE_T dpid;
  	/** mb id */
  	CHAR_T *mb_id;
  	/** data len */
  	UINT_T len;
  	/** the data */
  	BYTE_T data[0];
  } TY_RECV_RAW_DP_S;
  

API description

Register sub-device interfaces

/**
  * @brief register callback with protocol type
  *
  * @param[in] p_user_dev_node_cbs callback, see TY_GW_SUBDEV_MGR_CBS_S
  * @param[in] user_dev_type       custom protocol type, ranging from 10 to 19
  *
  * @return OPRT_OK on success. For others on error, please refer to tuya_error_code.h
  */
OPERATE_RET tuya_subdev_user_sigle_type_reg(TY_GW_SUBDEV_MGR_CBS_S *p_user_dev_node_cbs, BYTE_T user_dev_type);

The sub-device registers interface functions. Implement the functions to send DP commands of object type and raw type respectively and query DP status as well as other callbacks as needed.

Report DP data to the cloud

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 DP data to the cloud asynchronously, which requires you to concatenate the DP information.

Example

/**
 * @brief dp( object type ) callback
 * @param[in]     cmd      : struct of dp object type command
 */
STATIC VOID __dev_cmd_obj_cb(CONST TY_RECV_OBJ_DP_S *cmd)
{

     /**
      * TODO:
      *   In this callback, we should change to bus protocol
      *   from DP struct.
      */

     /**
      * Here we have an example :
      *     a) parse the DP value.
      *     b) print out the DP value.
      */
     for (INT_T i = 0; i < cmd->dps_cnt; i++) {
         PR_DEBUG("dpid: %d", cmd->dps[i].dpid);
             switch (cmd->dps[i].type) {
             case PROP_BOOL:
                 PR_DEBUG("dp_bool value: %d", cmd->dps[i].value.dp_bool);
                 break;
             case PROP_VALUE:
                 PR_DEBUG("dp_value value: %d", cmd->dps[i].value.dp_value);
                 break;
             case PROP_ENUM:
                 PR_DEBUG("dp_enum value: %d", cmd->dps[i].value.dp_enum);
                 break;
             case PROP_STR:
                 PR_DEBUG("dp_str value: %s", cmd->dps[i].value.dp_str);
                 break;
             }
     }

     dev_report_dp_json_async(cmd->cid, cmd->dps, cmd->dps_cnt);
}

/**
 * @brief dp( object type ) callback
 * @param[in] TY_GW_STY_GW_SUBDEV_MGR_CBS_S  ruct of dp raw type command
 */
STATIC VOID __dev_cmd_raw_cb(CONST TY_RECV_RAW_DP_S *dp)
{

    /**
     * TODO:
     *      It's raw callback. DIY for the user.
     */
}

TY_GW_SUBDEV_MGR_CBS_S dev_dp_cbs = {
    .dp_cmd_obj   = __dev_cmd_obj_cb,
    .dp_cmd_raw   = __dev_cmd_raw_cb,
};

tuya_subdev_user_sigle_type_reg( &dev_dp_cbs ,  DEV_ATTACH_MOD_1 );