DP (Data Point): Definition, Creation, and Usage

What Is a DP​

The official documentation defines a DP at three levels (quoted passages are English translations of the Chinese originals):

• Capability abstraction — Basic DP (TuyaOS docs): a DP, also called a function point, "describes a capability of a device. The Tuya Developer Platform abstracts all device capabilities into function points, supporting Value, Boolean, Enum, String, Fault, and Raw (pass-through) types."
• Data model — Terminologies (TuyaOpen docs): a DP is Tuya's data model for product capability definitions, used to describe the functions of a product.
• Data contract — Agent Development Guide (TuyaOpen docs): a DP defines every piece of data flowing between the device and the cloud — sensor readings, switch states, raw binary payloads, and so on. An Agent observes and controls a device by reading and writing DPs.

Take a two-gang switch: its capabilities are abstracted as two DPs, each of Boolean type. A DP carries read/write semantics — read fetches the current value, write changes it. When the app turns on the first gang, it writes true to DP 1; when the device reports the actual switch states to the cloud, the app and the Agent can see the latest state.

Key Characteristics of a DP​

The Four Elements​

Standard functions (also called standard DPCodes) are the function points with DPIDs below 100; see Creating DPs.

The Six Data Types​

Data Transfer Modes​

Message Formats​

On the Wi-Fi/cloud link, DPs travel as dps JSON whose keys are DPIDs in string form:

{"dps": {"1": true, "2": 25}}

On the cloud side, a DP is described by DPCode + type + constraints: functions is the command set that can be sent to the device, and there is a structurally identical status state set that can be reported (omitted here). Excerpt from the electric pressure cooker category in the official docs:

{
  "result": {
    "category": "dylg",
    "functions": [
      {"code": "switch", "type": "Boolean", "values": "{}"},
      {"code": "appointment_time", "type": "Integer",
       "values": "{\"unit\":\"min\",\"min\":0,\"max\":1440,\"scale\":0,\"step\":1}"}
    ]
  }
}

The cloud open-platform API for sending device commands is POST /v1.0/iot-03/devices/{device_id}/commands with body {"commands":[{"code":"<dpCode>","value":...}]} — the cloud-side semantics use the DPCode. The Bluetooth link uses binary frames instead: dp_id (1 byte) + dp_type (1 byte) + dp_data_len (2 bytes) + dp_data_value, with the on-wire type codes raw=0, bool=1, value=2, string=3, enum=4, and bitmap (Fault)=5.

Creating DPs​

DPs are created on the Tuya IoT Platform as part of product function definition:

1. Go to Product Development and create a product under a category.
2. Under 01 Function Definition > Product Functions, add functions: pick from the standard function library, or create custom functions.
3. For each function, fill in the DPCode, choose the data type, and set the constraints — each function becomes one DP.
4. Once the function definition is done, move on to firmware development and debugging (wiring the schema into agentic-kit, below).

The platform groups product functions into three classes:

An example function worksheet (modeled on the electric pressure cooker in the official docs):

Using DPs in agentic-kit​

The schema is the JSON expression of the platform's product function definition: per DP it describes the id, the mode (rw/ro/wr), and the property (data type and constraints). It is obtained from the activation response or exported from the platform.

Three Ways the Schema Reaches the Device​

The Device-Side Schema​

The device consumes the real Tuya schema format (taken from examples/posix/dp-management/):

[
  {"mode":"rw","property":{"type":"bool"},"id":1,"type":"obj"},
  {"mode":"ro","property":{"min":0,"max":100,"scale":0,"step":1,"type":"value"},"id":2,"type":"obj"},
  {"mode":"rw","property":{"min":0,"max":100,"scale":0,"step":1,"type":"value"},"id":3,"type":"obj"},
  {"mode":"ro","property":{"range":["none","charging","charge_done"],"type":"enum"},"id":4,"type":"obj"},
  {"mode":"ro","property":{"type":"raw"},"id":5,"type":"obj"}
]

The top-level type:"obj" marks an object DP; the data type lives in property.type. mode is rw/ro/wr, matching the transfer modes above.

Type and Constraint Mapping​

Constraint mapping: property.min/max → vmin/vmax (strictly validated); the Enum range → the table of legal values; maxlen for raw/string.

Core API​

All signatures are authoritative in modules/iot-client/include/iot_dp.h.

A Typical Code Flow​

Adapted from examples/posix/dp-management/dp_management_demo.c:

/* Cloud downlink callback: dispatched per dp_id; value is valid only during the call */
static void on_dp_downlink(uint8_t dp_id, const iot_dp_value_t *value, void *ud)
{
    /* Drive hardware/UI here */
}

/* 1. init: rebuild the DP registry from the persisted schema,
 *        then restore DP state after validating it */
iot_client_config_t cfg = {
    .schema    = saved_schema,             /* the product schema from the platform */
    .schema_id = saved_schema_id,
    .mqtt_disable_auto_connect = true,     /* the application owns connect timing */
    /* devid / secret_key / local_key / region / env ... */
};
iot_client_t *client = iot_client_init(&cfg);
if (saved_dp_state && iot_dp_validate_json(client, saved_dp_state) == OPRT_OK) {
    iot_dp_restore_json(client, saved_dp_state);   /* restore cache, no report */
}
iot_dp_set_callback(client, on_dp_downlink, NULL);
iot_dp_set_save_callback(client, on_dp_save, NULL);             /* persist on every write */
iot_dp_set_schema_update_callback(client, on_schema_update, NULL);   /* schema-upgrade notice */

/* 2. Right after connecting, report the full state — the cloud only trusts device reports */
iot_client_connect(client);
iot_dp_report_all(client);

/* 3. Steady-state loop */
while (g_running) {
    iot_client_process(client, 200);       /* pump the receive path, dispatch downlinks */

    iot_dp_value_t v = { .type = IOT_DP_TYPE_VALUE, .value.integer = 87 };
    iot_dp_set(client, 2, &v);             /* local change, marks dirty */
    iot_dp_report_all_dirty(client);       /* batch-report dirty DPs */

    iot_dp_schema_check_update(client);    /* poll for schema upgrades */
}

For a complete runnable sample see examples/posix/dp-management/; for obtaining the schema at activation see examples/posix/pair/api-activate/; for using DPs inside an AI session see examples/posix/ai/rtc-tcp-client/agent_trigger_demo.c. The full procedure for saving and restoring DP state across reboots is covered in DP State Persistence.

DP or Device-Side MCP​

Use DPs for stable, enumerable device capabilities and states (switches, brightness, temperature, modes) — the main callers are apps, cloud automations, and device linkages. Use device-side MCP for dynamic, task-shaped tools with complex parameters (reading sensors, taking photos, driving motors) — the main caller is the AI Agent. The two can coexist in one product; for the decision criteria see Core Concepts: Physical device control — DPs and device-side MCP.

References​

Official documentation:

• Basic DP - TuyaOS — one authoritative source for DP definitions, data types, and transfer modes.
• Terminologies - TuyaOpen — core terms including DP.
• Creating a New Product - TuyaOpen — the platform flow for creating products and function definitions.
• Agent Development Guide - TuyaOpen — DP semantics and best practices from the Agent's perspective.
• Bluetooth DP Data Format - TuyaOS — the Bluetooth binary DP frame layout and type codes.
• Miniapp DP API - Tuya Developer Platform — the miniapp-side DP publish interface.

On this site:

• Core Concepts: Physical device control — DPs and device-side MCP
• DP State Persistence — saving and restoring DP state across reboots.
• IoT Client API reference — activation, MQTT connection, and other iot-client core APIs.
• examples/posix/dp-management/ — the complete DP management sample.