Tuya Integration

Tuya is an IoT platform that enables device manufacturers and solution providers to connect, manage, and control smart devices through the Tuya Cloud. The ThingsBoard Tuya integration subscribes to the Tuya Message Queue Service using your project credentials and receives device status reports in real time. It automatically creates ThingsBoard devices from the incoming data and, in the reverse direction, forwards RPC commands from ThingsBoard to Tuya devices via the Tuya Device Control API.

This guide walks through an end-to-end integration using a Tuya Smart Plug. A virtual Tuya device can also be used for testing.

• A ThingsBoard PE account with permission to create integrations.
• A Tuya IoT Platform account.
• At least one Tuya device (physical or virtual).
• The Smart Life or Tuya Smart app installed and signed in on your mobile device.

1. Open the Smart Life (or Tuya Smart) app. Tap Add Device on the home screen.
2. Browse to the Electrical category and tap Socket (Wi-Fi).
3. Follow the on-screen reset instructions: power off the device for 10 seconds, then power it back on.
4. Press and hold the RESET button for 5 seconds.
5. Confirm the indicator light is blinking rapidly, then tap Next.
6. Wait for the app to discover and add the device. Tap Done when the success screen appears.
7. Open the device card and tap the power button to verify the plug responds to commands.

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. In the Tuya IoT Platform, go to Cloud ⇾ Project Management and click Create Cloud Project.
2. Fill in the required fields in the pop-up window and click Create.
3. In the Authorize API Services window, complete the settings and click Authorize.
4. Note the Access ID/Client ID and Access Secret/Client Secret — you will need them when creating the ThingsBoard integration.

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

The Tuya Message Service delivers real-time device status reports to the ThingsBoard integration via AMQP.

1. In your cloud project, go to the Message Service tab and toggle Message Service on.
2. In the pop-up, configure Message Service Type and Message encryption algorithm, then click Ok.

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

You need to link your devices to this project using your Smart Life app account.

1. Go to Cloud ⇾ Project Management, select your project, then navigate to Devices ⇾ Link App Account.
2. Click Add App Account and select Tuya App Account Authorization.
3. Scan the QR code with the Smart Life app to authorize.
4. In the pop-up, select Automatic Link and click Ok.

Your devices now appear under the All Devices tab of the project.

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 The app account is linked — your devices will appear under the All Devices tab

Enable a messaging rule so the project receives device status uplinks via statusReport.

1. On the Message Service tab, click Create Messaging Rules.
2. Click Add Message Filtering Rule.
3. Select statusReport from the BizCode list and click Release Rule.
4. Enable the rule.

Open the Message Service tab in your cloud project and click Create Messaging Rules Click Add Message Filtering Rule Select statusReport and click Release Rule Enable the messaging rule — click Messaging Rules and activate the rule you just created

The uplink converter decodes the Tuya statusReport payload. Tuya uses a generic uplink converter. It reads code/value pairs from the status array, applies unit scaling (cur_voltage and cur_power ÷ 10; cur_current ÷ 100), and maps the result to ThingsBoard telemetry. The device name comes from the devId field (or bizData.devId for some message types).

Download the uplink converter file:

The decoder function used in this tutorial:

/** Decoder **/

// decode payload to JSON
var data = decodeToJson(payload);

var deviceName = data.?bizData.?devId != null ? data.?bizData.?devId : data.?devId;
var deviceType = 'Tuya device';

var telemetry = [];
if (data.status != null) {
    for (var i = 0; i < data.status.length; i++) {
        var res = {};
        var code = data.status[i].code;
        var value = data.status[i].value;
        if (code == "cur_voltage" || code == "cur_power") {
            value = data.status[i].value / 10;
        } else if (code == "cur_current") {
            value = data.status[i].value / 100;
        }
        res[code] = value;
        telemetry.push(res);
    }
} else {
    telemetry = data;
}

var result = {
    deviceName: deviceName,
    deviceType: deviceType,
    attributes: {},
    telemetry: telemetry
};

/** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/

return result;

/** Decoder **/

// decode payload to JSON
var data = decodeToJson(payload);

var deviceName = data.devId;
var deviceType = 'Tuya device';

var telemetry = [];
if (data.status != null) {
    for (var i = 0; i < data.status.length; i++) {
        var res = {};
        var code = data.status[i].code;
        var value = data.status[i].value;
        if (code == "cur_voltage" || code == "cur_power") {
            value = data.status[i].value / 10;
        } else if (code == "cur_current") {
            value = data.status[i].value / 100;
        }
        res[code] = value;
        telemetry.push(res);
    }
} else {
    telemetry = data;
}

var result = {
   deviceName: deviceName,
   deviceType: deviceType,
   attributes: {},
   telemetry: telemetry
};

/** Helper functions **/

function decodeToString(payload) {
   return String.fromCharCode.apply(String, payload);
}

function decodeToJson(payload) {
   var str = decodeToString(payload);
   var data = JSON.parse(str);
   return data;
}

return result;

1. Go to Integrations center ⇾ Data converters.
2. Click + Add data converter ⇾ Import converter.
3. Drag and drop the downloaded JSON file into the Import converter window and click Import.

The downlink converter encodes ThingsBoard RPC messages into the Tuya Device Control API format. For the full encoder reference, see Downlink data converter. It maps msg.method to the Tuya command code and msg.params to the command value, with automatic string-to-boolean conversion for on/off commands. The target device is identified via metadata.deviceName.

Download the downlink converter file:

The encoder function used in this tutorial:

/** Encoder **/

var command = {};
command["code"] = msg.method;
if (msg.params == "false" || msg.params == "true") {
    command["value"] = Boolean.valueOf(msg.params);
} else {
    command["value"] = msg.params;
}

var result = {
    contentType: "JSON",
    data: JSON.stringify(command),
    metadata: {
        deviceId: metadata.deviceName
    }
};

return result;

/** Encoder **/

const command = {
    code: msg.method,
    value:
        msg.params === "false" || msg.params === "true"
            ? msg.params === "true"
            : msg.params
};
const result = {
    contentType: "JSON",
    data: JSON.stringify(command),
    metadata: {
        deviceId: metadata.deviceName
    }
};
return result;

1. Go to Integrations center ⇾ Data converters.
2. Click + Add data converter ⇾ Import converter.
3. Drag and drop the downloaded JSON file into the Import converter window and click Import.

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Set Integration type to Tuya.
   • Enable integration and Allow create devices or assets are on by default.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose the previously created Tuya Uplink Converter.
   • Click Next.
4. Downlink data converter:
   • Click Select existing and choose the previously created Tuya Downlink Converter.
   • Click Next.
5. Connection settings:
   • Region — select the region matching your Tuya account.
   • Environment — select PROD for a real physical device, or TEST for a virtual device.
   • Access Id and Access Key — paste the Access ID/Client ID and Access Secret/Client Secret from your Tuya cloud project.
6. Click Add to save the integration.

Set Integration type to Tuya, enter a name, and click Next Click Select existing, choose Tuya Uplink Converter, and click Next Click Select existing, choose Tuya Downlink Converter, and click Next Select Region and Environment, paste Access Id and Access Key from your Tuya project, then click Add

To forward RPC commands from ThingsBoard to Tuya devices, add an Integration Downlink node to the Root Rule Chain and connect it to the RPC Request to Device relation.

1. Go to Rule chains and open the Root Rule Chain in edit mode.
2. Find the Integration Downlink node in the node panel, drag it onto the canvas, enter a name (e.g. Tuya integration), select the Tuya integration, and click Add.
3. Connect the Message Type Switch node to the Integration Downlink node using the RPC Request to Device relation.
4. Click Apply changes to save the rule chain.

Drag the Integration Downlink node from the panel onto the canvas Enter a name, select the Tuya integration, and click Add Connect Message Type Switch → RPC Request to Device → Integration Downlink, then click Apply changes

Disconnect your Smart Plug from power and reconnect it. The device sends an uplink statusReport message to Tuya, which forwards it to ThingsBoard through the integration. Go to Entities ⇾ Devices — a device named after the Tuya devId is automatically created with the latest telemetry.

Import the ready-made dashboard to visualize Smart Plug telemetry and send RPC commands.

1. Download the dashboard: tuya_smart_plug_dashboard.json
2. Go to Dashboards and click + ⇾ Import dashboard.
3. Drop the downloaded JSON file into the import window and click Import.
4. Open the Tuya Smart Plug dashboard and enter Edit mode.
5. Click Entity Aliases, set the smartPlug alias to your provisioned device, and click Save.
6. Update the time series data keys in each widget to match the code values reported by your device if the widgets show no data.

Go to Dashboards, click + → Import dashboard, and drop the downloaded JSON file into the import window In Edit mode, open Entity Aliases and set the smartPlug alias to your provisioned device If widgets show no data, update the time series keys to match the data point codes reported by your device Smart Plug dashboard with live telemetry — voltage, power, and current data flowing from the device Smart Plug is on — click the On/Off switch widget to send a turn-off RPC command to the device Smart Plug turned off — power consumption drops to zero, confirming the RPC command was delivered

• Integration Overview
• Uplink Converters
• Downlink Converters
• Rule Engine
• ThingsBoard Expression Language (TBEL)