Tuya Integration

Tuya Integration connects ThingsBoard to the Tuya IoT Platform (Tuya Cloud). It subscribes to the Tuya Message Service and receives status reports from devices added in the Smart Life or Tuya Smart app. An uplink data converter turns each report into telemetry and attributes. ThingsBoard can also send downlink commands to the devices through the Tuya OpenAPI.

Use Tuya Integration when:

• Your devices are Tuya-based and already connected to Tuya Cloud through the Smart Life or Tuya Smart app.
• You want to monitor them in ThingsBoard dashboards and process their data in the Rule Engine.
• You need to control them from ThingsBoard, for example switch a smart plug on or off.

This guide uses a Tuya Smart Plug. A virtual Tuya device works for testing too.

1. Receive data. The device reports its status to Tuya Cloud over Wi-Fi. The integration subscribes to the Message Service (an Apache Pulsar queue) with your cloud project credentials and receives each status report.
2. Decode the payload. The integration decrypts the report and passes it to the uplink converter, which returns the device name, telemetry, and attributes.
3. Process the message. ThingsBoard processes the converted data through the Rule Engine. If Allow create devices or assets is enabled, ThingsBoard creates the device on its first report.
4. Send downlink data (optional). The Rule Engine passes an RPC message to the integration. The downlink converter encodes it as a Tuya command, and the integration sends it to the Tuya OpenAPI, which delivers it to the device.

• Access to ThingsBoard Cloud with integrations enabled for your tenant.
• Permission to create integrations and data converters, and to edit rule chains for downlink.
• A Tuya IoT Platform account. To create one, see Create a Tuya IoT Platform Account.
• A Tuya device (physical or virtual) added in the Smart Life or Tuya Smart app. To add a smart plug, see Register the Smart Plug in the Tuya App.

Add the device to the Tuya app, create a cloud project, enable the Message Service, and link the app account to the project.

1. Open the Smart Life (or Tuya Smart) app and tap Add Device.
2. Open the Electrical category and tap Socket (Wi-Fi).
3. Power the plug off for 10 seconds, then power it back on.
4. Press and hold the RESET button for 5 seconds.
5. Check that the indicator blinks rapidly, then tap Next.
6. Wait until the app adds the device, then tap Done.
7. Open the device card and tap the power button to check that the plug responds.

Open the Smart Life app — tap Add Device on the home screen Select the Electrical category and tap Socket (Wi-Fi) Reset step 1 — power the device off, wait 10 seconds, then power it back on Reset step 2 — press and hold the RESET button for 5 seconds Reset step 3 — confirm the indicator light is blinking rapidly, then tap Next Device added successfully — tap Done Smart Plug control screen — the device is registered and currently off Tap the power button to turn the plug on and verify it responds

1. Open the Tuya IoT Platform login page and click Sign Up.
2. Enter your Email, the Verification Code sent to it, a Password, the Organization Name, and the Country/Region. Accept the terms and click Next.
3. Log in with the new account.

On the Tuya Developer Platform login page, click Sign Up to create a new account. Complete the registration form, request and enter the verification code, accept the terms, and click Next to create your Tuya account.

1. In the sidebar, go to Cloud ⇾ Cloud Project ⇾ Project Management.
2. Click Create Cloud Project. Enter a Project Name (for example, ThingsBoard), choose an Industry and a Development Method (for example, Custom), and select the Data Center. Click Create.
3. On the Authorize API Services screen, keep the recommended services (IoT Core is required) and click Authorize.
4. On the project Overview page, copy the Access ID/Client ID and Access Secret/Client Secret under Authorization Key. You need them, together with the data center, to create the integration.

In the sidebar, go to Cloud → Cloud Project → Project Management Click Create Cloud Project Fill in the project name and required fields, then click Create Review the recommended API services and click Authorize Copy the Access ID and Access Secret — you will need them when creating the integration

The Message Service pushes device status reports to subscribers such as the integration. Without it, no uplinks arrive.

1. In the cloud project, open the Message Service tab and turn on Message Service.
2. In the Configure Message Service dialog, select the Message Service Type and the Message encryption algorithm, then click OK. The integration decrypts both AES-ECB and AES-GCM messages.
3. Check that the tab shows the service as Enabled.

Open the Message Service tab in your cloud project and toggle Message Service on Select Message Service Type and encryption algorithm, then click OK The Message Service tab confirms the service is Enabled

A messaging rule defines which messages Tuya pushes. Tuya keeps separate rules and subscriptions for two environments:

The rule must be enabled in the environment where your device reports, and the integration must use the same environment. Otherwise the integration connects, but no uplinks arrive.

1. In the cloud project, open Message Service ⇾ Messaging Rules.
2. Select Production Environment for a real device, or Test Environment for a test device.
3. Turn on the rule. While it is off, the tab shows “The rules for the production environment are disabled, so all messages will not be pushed”.
4. Click Modify Messaging Rules, make sure BizCode includes statusReport (Status Report), and save. Optionally add online and offline.
5. Open Subscription Management, select the same environment, and check that the subscription <Access ID>-sub has Status = Good.

Under Messaging Rules → Production Environment, enable the rule and confirm BizCode includes statusReport. On Subscription Management, the subscription should show Status = Good. Accumulated Messages increases once the device reports.

Linking the app account adds its devices to the cloud project.

1. Go to Devices ⇾ Link App Account, click Add App Account, and select Tuya App Account Authorization.
2. Scan the QR code in the Smart Life (or Tuya Smart) app: Me ⇾ Scan.
3. In the Link App Account dialog, select Automatic Link and click OK.
4. Confirm the linking. Click Manage Devices on the app account row and check that the smart plug appears as Online.

Go to Devices → Link App Account, click Add App Account, and select Tuya App Account Authorization Scan the QR code with the Smart Life app (Me → Scan) Select Automatic Link and click OK Confirm the linking — the devices under the app account are linked to the project Open Manage Devices to confirm the Smart Plug is linked and Online

Create the uplink converter, assign it to a new Tuya integration, and trigger a status report from the device.

The uplink converter receives each status report as JSON, resolves the device by its Tuya ID, and returns its telemetry. Tuya Integration uses the Generic converter: you write the decoder in TBEL or JavaScript. For converter types and the full decoder reference, see Uplink data converter.

1. Go to Integrations ⇾ Data converters and click + Add data converter ⇾ Create new converter.

2. Converter type — keep Uplink.

3. Integration type — select Tuya.

4. Name — enter a name, for example Tuya Uplink Converter.

5. Main decoding configuration — the editor opens with the generic default decoder. Replace it with the decoder below. It reads the code–value pairs from the status array and scales the smart plug readings: cur_voltage and cur_power ÷ 10, cur_current ÷ 100. The editor opens in TBEL; use the TBEL / JS toggle to switch to JavaScript.

   • TBEL (Recommended)
   • JavaScript

   /** Decoder **/
   
   // Parse the incoming payload (byte array) into a JSON object.
   // decodeToJson is a built-in TBEL helper — no need to declare it.
   var data = decodeToJson(payload);
   // Also accept the integration event format { metadata, data },
   // for example when you test with a payload copied from the Events tab.
   if (data.?data != null) {
     data = data.data;
   }
   
   // Resolve the device name.
   // Try bizData.devId first (present in some Tuya message types);
   // fall back to devId otherwise. The .? operator safely returns null
   // if an intermediate field is missing (won't throw an error).
   

   ▼Expand

   To adapt:

   • Other data points — add or change the code branches. Codes without a branch are stored as received.
   • Other scaling — change the divisors. For example, some models report add_ele (energy, kWh) that needs ÷ 100 or ÷ 1000.
   • Friendly key names — map codes explicitly, for example cur_voltage to voltage.
   • Device timestamp — each status entry carries t (ms). Return { ts: data.status[i].t, values: res } instead of res to store it instead of the server time.
   • Device properties — add them to attributes, for example productKey: data.productKey.

6. Click Test decoder function and check the result (see Test the Decoder).

7. Click Add.

Decoder Inputs

The decoder signature is function decoder(payload, metadata): object | object[].

Status report fields:

The integration’s Events tab shows each message as { "metadata": {...}, "data": {...} }. The decoder receives only data as payload.

Test the Decoder

Click Test decoder function below the editor. Keep Payload content type set to JSON, paste this status report as the payload, and click Test:

{
  "dataId": "000657E477596B12C80347616A03002A",
  "devId": "bfac3c40adca459c9chaar",
  "productKey": "iq9hwd2bjsdgqiby",
  "status": [
    { "code": "cur_voltage", "t": 1785490000000, "value": 2086 },
    { "code": "cur_power", "t": 1785490000000, "value": 142 },
    { "code": "cur_current", "t": 1785490000000, "value": 63 }
  ]
}

The Output panel shows:

{
  "deviceName": "bfac3c40adca459c9chaar",
  "deviceType": "Tuya device",
  "attributes": {},
  "telemetry": [
    { "cur_voltage": 208.6 },
    { "cur_power": 14.2 },
    { "cur_current": 0.63 }
  ]
}

Check that deviceName equals the devId and that telemetry holds the scaled values. If the output is empty or shows an error, fix the decoder and test again.

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Integration type — select Tuya.
   • Name — enter a name, for example Tuya integration.
   • Enable integration and Allow create devices or assets — keep both on, so the device is created on its first report.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose Tuya Uplink Converter.
   • Alternatively, click Create new to write a decoder here.
   • Click Next.
4. Downlink data converter:
   • Click Skip. Add a downlink converter later if you need to send commands to devices.
5. Connection:
   • Region — select the data center of your cloud project.
   • Environment — select PROD for a real device or TEST for a test device.
   • Access Id and Access Key — paste the Access ID/Client ID and Access Secret/Client Secret from the cloud project.
   • See Connection Settings for details.
6. Click Add.

If the connection fails, the integration retries every 60 seconds and logs a CONNECT event with the error on its Events tab.

Trigger a status report, then confirm that ThingsBoard decoded it and created the device.

Unplug the smart plug and plug it back in, or switch it in the Smart Life app. The device sends a statusReport to Tuya Cloud, which pushes it to the integration.

• Integration events — go to Integrations ⇾ Integrations, open the integration, and click the Events tab. The uplink appears with status OK. Click ⋅⋅⋅ in the Message column to see the metadata and the report.
• Converter events — open Tuya Uplink Converter in Integrations ⇾ Data converters and click the Events tab. In shows the report, Out shows the decoded result, and Metadata shows the Message Service envelope.
• Device — go to Devices & assets ⇾ Devices. The integration has created a device named after the Tuya devId. Open it and check the Latest telemetry tab, for example cur_power, cur_voltage, cur_current, and switch_1.

ThingsBoard sends a command to the device when the Rule Engine routes an RPC request to the integration — for example, when a dashboard switch is toggled. The integration calls the Tuya OpenAPI of the selected region:

1. It takes the Tuya device ID from deviceId in the encoder’s output metadata, or from deviceName if deviceId is not set.
2. It sends data to POST /v1.0/iot-03/devices/{deviceId}/commands as { "commands": [...] }.

The encoder’s data must be one of:

Any other data, including {"commands": [...]}, fails with “Downlink message format is not correct, downlink message should contain one of the following: code field, service RPC method, commands array!”.

The downlink converter turns a Rule Engine message into a Tuya command. For the full encoder reference, see Downlink data converter.

The encoder below uses the RPC method as the Tuya command code and the RPC params as its value. It converts "true" and "false" to booleans, because RPC params arrive as strings. It sets deviceId to the device name, which is the Tuya devId.

1. Open the integration in Integrations ⇾ Integrations and click Toggle edit mode (pencil icon).
2. In the Downlink data converter field, click Create new. The Downlink converter type and Tuya integration type are preselected.
3. Enter a name, for example Tuya Downlink Converter.
4. In Main encoding configuration, replace the default encoder with the encoder below.
   • TBEL (Recommended)
   • JavaScript

   /** Encoder **/
   
   // The command object we will send to the Tuya device.
   var command = {};
   
   // msg.method — the RPC method name from ThingsBoard. Becomes the Tuya
   // command code, e.g. "switch_1", "bright_value", etc.
   command["code"] = msg.method;
   
   // msg.params — the command value.
   // If it is the string "true"/"false", convert it to a real boolean
   // (needed for switches, e.g. turning the plug on/off).
   if (msg.params == "false" || msg.params == "true") {
     command["value"] = Boolean.valueOf(msg.params);
   } else {
   // Otherwise pass it as-is (number, string, e.g. brightness level).
     command["value"] = msg.params;
   }
   
   // Build the result for the integration.
   

   ▼Expand

5. To record downlink events, click the debug icon next to the name, select All messages, and click Apply.
6. Click Add, then Apply changes.

RPC messages already carry deviceName in their metadata, so a single integration downlink node is enough.

1. Go to Data processing ⇾ Rule chains and open the Root Rule Chain.
2. From the Action section, drag an integration downlink node onto the canvas.
3. Enter a Name (for example, Downlink to Tuya), select your Tuya integration, and click Add.
4. Connect the message type switch node to the integration downlink node with the RPC Request to Device relation.
5. Click Apply changes.

Import the Tuya Smart Plug dashboard. It shows the uplink data and sends commands to the plug:

• Time series chart and Simple neon gauge — voltage, power, and current.
• Led indicator — the on/off state from the switch_1 telemetry.
• Round switch — sends an RPC with method switch_1 and params true or false.

1. Download tuya_smart_plug_dashboard.json.
2. Go to Dashboards, click + Add dashboard ⇾ Import dashboard, upload the file, and click Import.
3. Open the Tuya smart plug dashboard and enter edit mode.
4. Click the Entity aliases icon, click the pencil icon next to the smartPlug alias, select your device, and click Save. Then click Save in the lower-right corner.
5. Toggle the Round switch.

If a widget shows no data, edit it and change the data keys in Datasource to the codes your device reports.

• Device — the plug switches, and the Led indicator follows after the next status report.
• Converter events — open the downlink converter’s Events tab. In shows the RPC message, Out shows the encoded command, and Metadata shows the message metadata.
• Integration events — the Downlink event has status SUCCESS. On FAILURE, the event shows the error returned by Tuya Cloud.

To read debug events, open the integration or converter, click Events, and select an event: In is the received data, Out is the converter result, and Error holds the error text.

• Integrations overview — how integrations, converters, uplinks, and downlinks fit together.
• Uplink data converter — decoder inputs, output format, and scripting patterns.
• Downlink data converter — encoder reference.
• Remote Integration — run the integration outside the ThingsBoard cluster.
• TBEL — built-in functions and syntax for converter scripts.
• Rule Engine — how messages are processed after decoding.