Device DP Parser

A data point (DP) is the smallest unit used to describe a device feature in device information. Each DP has two parts: DP configuration in product information and DP value in device information. Certain types of DP might possess extended properties.

Tuya categorizes the DP into three types based on their functionality: quick toggle, display, and operation. This topic describes how to use the device or group model to get DPs for displaying data and operating features on a custom app UI.

Procedure

1. Log in to the Tuya IoT Development Platform.
2. Select a product in the Developing state, and click Develop in the Operation column.
3. Choose Product Configuration > Quick Toggle > Settings.

You can configure quick toggles and common functions to present them on the device or group card.

Get the DP parsing module

val plugin = PluginManager.service(IAppDpParserPlugin::class.java)

API description

The DP parsing module does not listen for changes in the properties of the device or group. To use this module, call the update method at least once before requesting the cache DP model with API calls. The DP model IDeviceDpParser contains information about all DPs of the current device or group.

It is recommended to call the update method to update the cache when:

• The device list is returned.
• The DP data changes.

/**
* Update group information.
* @param groupBean The group model data to update.
* @return The group DP model after parsing.
*/
fun update(groupBean: GroupBean): IDeviceDpParser

/**
* Update device information.
* @param deviceBean The device model data to update.
* @return The device DP model after parsing.
*/
fun update(deviceBean: DeviceBean): IDeviceDpParser

After the update method is called, the respective DP model will be cached for use by other business logic.

/**
*  Get the parsed DP model data.
* @param id  The [DeviceBean.getDevId] of the device model or the [GroupBean.getId] of the group model.
* @return  Return the cache if it exists. Otherwise, return null.
*/
fun getParser(id: String): IDeviceDpParser?

When a device or group is longer needed, manually call the delete method to clear the existing cache DP model.

/**
* Remove the cache of the respective ID.
* @param id  The [DeviceBean.getDevId] of the device model or the [GroupBean.getId] of the group model.
*/
fun remove(id: String)

/**
* Remove all the caches of the respective IDs in the list.
* @param ids The IDs of the caches to remove.
*/
fun removeAll(ids: List<String>)

Device DP model

interface IDeviceDpParser {
    /**
     * The display DP.
     * @return  Return all the parsed display DPs of the current device or group. Return an empty list if no display DP exists.
     */
    fun getDisplayDp(): List<IDpParser<Any>>

    /**
     * The operation DP.
     * @return   Return all the parsed operation DPs of the current device or group. Return an empty list if no operation DP exists.
     */
    fun getOperableDp(): List<IDpParser<Any>>

    /**
     * All DPs of the current device. Only some methods are supported.
     * Supported methods: [IDpParser.getDpId], [IDpParser.getSchema], [IDpParser.getStandardSchema], and [IDpParser.getValue].
     * 
     * If the value of the DP does not exist in the current device or group, [IDpParser.getValue] returns [NoValue].
     *
     *If you call any methods not listed above, [UnsupportedOperationException] will be thrown.
     *@return  Return all the DPs configured in the product information of the current device.
     */
    fun getAllDp(): List<IDpParser<Any>>

    /**
     * Quick toggle
     * @return  Return the quick toggle of the current device. If no quick toggle exists, return null.
     */
    fun getSwitchDp(): ISwitch?
}

Generic DP: IDpParser

A generic DP refers to a single feature, such as on/off, temperature, and brightness. On the Tuya IoT Development Platform, you can configure whether to control or show them on the mobile app. Most DP values are displayed after being concatenated with a unit or converted.

interface IDpParser<T> {
    /**
     * The iconfont value of the current DP. It can be empty.
     */
    fun getIconFont(): String?

    /**
     * The name of the current DP.
     */
    fun getDisplayTitle(): String

    /**
     * The content displayed in the quick access area for the current operation DP.
     */
    fun getDisplayStatusForQuickOp(): String

    /**
     * The content displayed in the status view area for the current display DP.
     */
    fun getDisplayStatus(): String

    /**
     * The ID of the DP.
     */
    fun getDpId(): String

    /**
     * The UI style, such as percent, percent1, countdown, and countdown1.
     */
    fun getDpShowType(): String

    /**
     * The DP data type, such as Boolean, enum, number, and string.
     */
    fun getType(): String

    /**
     * The original DP configurations.
     */
    fun getSchema(): SchemaBean

    /**
     * The original DP configurations.
     */
    fun getStandardSchema(): FunctionSchemaBean?

    /**
     * This is used to generate the commands sent to the device.
     * @param status The target value to be sent to the device, which must match the DP data type.
     */
    fun getCommands(status: T): String

    /**
     * The current DP value.
     */
    fun getValue(): T
}

Below are the derived methods for different types of generic DPs.

• IBoolDp
• IEnumDp
• ILightDp
• INumDp
• IStringDp

This section describes the features of these derived methods.

Boolean type: IBoolDp

It indicates the on/off feature, with the value being either true or false.

interface IBoolDp : IDpParser<Boolean> {
    /**
     * Return the display text configured in the product information for the corresponding status. For example, true => "On", false => "Off"
     */
    fun getDisplayMessageForStatus(value: Boolean): String
}

Enum type: IEnumDp

The command sent to the device is one of the values returned by the getRange() method.

interface IEnumDp : IDpParser<String> {
    /**
     * The value range of the DP.
     */
    fun getRange(): List<String>

    /**
     * The display text for the DP value.
     */
    fun getNames(): List<String>
}

Number type: INumDp

You can set the value range, step, and scale for a DP of number type on the Tuya IoT Development Platform.

• Value range: specifies the range of valid values for a DP. The value sent to the device must be within the value range.
• Step: specifies the interval between adjacent values.
• Scale: specifies the number of decimal places of a value. Suppose that the value range of a temperature DP is [-100,100]. If the scale is 1, the range of the display value is [-10.0,10.0]. If the scale is 2, the range of the display value is [-1.0,1.0].

The DP display type determines the display value, and the calculation rule varies by display type.

interface INumDp : IDpParser<Int> {

    /**
     * The minimum value.
     */
    fun getMin(): Int

    /**
     * The maximum value.
     */
    fun getMax(): Int

    /**
     * The step.
     */
    fun getStep(): Int

    /**
     * The scale.
     */
    fun getScale(): Int

    /**
     * The unit.
     */
    fun getUnit(): String
}

Light source: ILightDp

interface ILightDp : IDpParser<String> {
    companion object {
        // The dpCode for legacy colored lights. 14-bit HSV value. The standard dpCode is colour_data.
        const val STRING_STANDARD_CODE_COLOUR_DATA_V1 = "colour_data"
        // The dpCode for new colored lights. 12-bit HSV value. The standard dpCode is colour_data_v2.
        const val STRING_STANDARD_CODE_COLOUR_DATA_V2 = "colour_data_v2"
    }

    // The light color, with values ranging from the minimum to the maximum. 
    fun getLightColorRange(): IntArray

    // The description of the current color, for example: red, green, and blue. If the description is not available, the key of the respective multilingual text is returned instead, which starts with color_, such as color_red, color_indigo, and color_cyan_green.
    fun getLightColorDesc(context: Context): String

    //The minimum value: [0] saturation, [1] brightness
    fun getColorMin(): IntArray

    //The maximum value: [0] saturation, [1] brightness
    fun getColorMax(): IntArray

    //The converted light color data: [0] hue, [1] saturation, [2] brightness.
    fun getColorCurrent(): FloatArray

    //Check the version of the data type. The parsing rule varies by version.
    fun isNewColorData(): Boolean

    //Convert color data to string.
    fun getStringColorHSV(hsvPoint: FloatArray, hsvValue: IntArray): String
}

String type: IStringDp

The DP of string type has no additional properties.

interface IStringDp : IDpParser<String>

Quick toggle: ISwitch

A quick toggle can consist of one or more DPs. It can be used to turn on or off multiple Boolean DPs at once.

You can set the data transfer type for a DP to report only, send only, or send and report.

• Report only: The device reports the status when the DP value changes, without receiving the DP control command.
• Send only: The device receives and acts on the DP control command, without reporting the DP status. This leaves you uninformed of the current status of the DP.
• Send and report: The device receives and acts on the DP control command, and then reports the DP status.

A quick toggle is used to control devices, so the report only type does not apply. There are two types of quick toggle:

• With status: corresponds to send and report. The device receives on/off commands and reports on/off status when it changes.
• Without status: corresponds to send only. The device receives and acts on the on/off command, without reporting the on/off status. Therefore, you need to reverse the value of the on/off DP before sending it to the device.

interface ISwitch {
    companion object {
        const val SWITCH_TYPE_NORMAL = -1
        const val SWITCH_TYPE_WRITE_ONLY = -2

        const val SWITCH_STATUS_ON = 1
        const val SWITCH_STATUS_OFF = 2
    }

    /**
     * All the DP IDs included in the current quick toggle.
     */
    fun getSwitchDpIds(): List<String>

    /**
     * The current status of the quick toggle. If the quick toggle consists of multiple DPs, setting any one of them to true will return true. False is returned when all DP values are set to false.
     */
    fun getValue(dpId: String): Boolean

    /**
     * The type of the quick toggle. Send and report: [SWITCH_TYPE_NORMAL]
     *                           Send only:  [SWITCH_TYPE_WRITE_ONLY]
     */
    fun getSwitchType(): Int

    /**
     * The status of the quick toggle, either [SWITCH_STATUS_ON] or [SWITCH_STATUS_OFF]
     */
    fun getSwitchStatus(): Int

    /**
     * This is used to generate the commands sent to the device.
     * @param obj The DP of the "send only" type does not use the Boolean parameter.
     */
    fun getCommands(obj: Any): String
}