Skip to content

Tuya integration. Updated guide #2572

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ashvayka merged 2 commits into from
Feb 10, 2026
Merged

Tuya integration. Updated guide #2572

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
58fef0f
Updated guide for Tuya integration
stitenko Feb 9, 2026
5eeffac
Updated Uplink and Downlink converters
stitenko Feb 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
211 changes: 77 additions & 134 deletions _includes/docs/pe/user-guide/integrations/tuya.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,226 +3,169 @@
* TOC
{:toc}

## Overview
Tuya is an IoT platform that enables device manufacturers and solution providers to connect, manage, and control smart devices through the Tuya Cloud.

Tuya is a cloud platform that connects a range of devices via the IoT. After integrating Tuya with the ThingsBoard, you can connect, manage, communicate, process and visualize data from your devices in the ThingsBoard IoT platform.
The Tuya Cloud Integration in ThingsBoard allows you to:
- Connect Tuya-managed devices to ThingsBoard
- Receive telemetry and device state updates
- Send control commands from ThingsBoard to Tuya devices
- Visualize device data and manage devices centrally

## Tuya Integration Tutorial
This guide describes how to configure an end-to-end integration using a real device - **Tuya Smart Plug**.
Also, you can use a [virtual Tuya device](https://developer.tuya.com/en/docs/iot/manage-virtual-devices?id=Ka4725tiyfhg0){:target="_blank"} for testing.

In this tutorial we will use a real device - Smart Plug.
## Prerequisites

Also, you can use a [**virtual device**](https://developer.tuya.com/en/docs/iot/manage-virtual-devices?id=Ka4725tiyfhg0). Virtual devices help you to perform cloud development without an actual IoT device.
Before starting, ensure you have:
- A ThingsBoard account with permission to create integrations
- A Tuya IoT Platform account
- At least one Tuya device (physical or virtual)
- Tuya Smart App installed and logged in

### Prerequisites
## Install smart device control application

The first step is to install the smart device control application (Smart Life, Tuya Smart, or other) on your mobile device and register your Smart Plug device in the application.

{% include images-gallery.html imageCollection="tuya-application-add-device" %}

### Tuya setup
## Tuya cloud configuration

#### Create cloud project
### Create cloud project

The next step is to register an account on [Tuya](https://www.tuya.com/) and create cloud project.
The next step is to register an account on [Tuya](https://www.tuya.com/){:target="_blank"} and create cloud project.
- Go to the **Cloud** tab ⇾ **Project Management**. Click the **Create Cloud Project** button.
- In a pop-up window, fill required fields and click "Create".
- Make additional settings in the **Authorize API Services** window and click **Authorize**.
- Now your cloud project is created. In this window, remember the **Access ID/Client ID** and **Access Secret/Client Secret** values. These values will be needed during the Tuya Integration setup.

{% include images-gallery.html imageCollection="tuya-create-cloud-project" showListImageTitles="true" %}

#### Enable Tuya message service
### Enable Tuya message service

Enable the message service to timely receive messages about device registration, data reporting, and status change.
- Go to the **Message Service** tab.
- Toggle to enable Message Service.
- In the pop-up window, set up the messaging service. Configure the settings for **Message Service Type** and **Alert Contact**. Click **Ok**.
- Message Service enabled.

{% include images-gallery.html imageCollection="tuya-message-service-enable" showListImageTitles="true" %}

#### Link Tuya App Account
### Link Tuya App account

You need to link your devices to this project using your Smart Life app account.
- Go to **Cloud** tab -> **Project management**. Select your project.
- Navigate to the **Devices** tab -> select the **Link App Account** tab. Click **Add App Account**.
- Select Tuya Account Authorization option.
- Scan the QR code with Smart Life App to authorize.
- In the pop-up window, select Automatic Link and Click **Ok**.
- Now your devices under the mobile app account have been added to the project.
- Navigate to the "All Devices" tab. You can see your device added to the project.

{% include images-gallery.html imageCollection="tuya-add-smart-life-app" showListImageTitles="true" %}

<br>
**Note:**
<br>
Make sure you enabled Messaging rule (filter) to receive uplinks. The very basic filter (statusReport) should be sufficient for testing purposes
Make sure you enabled Messaging rule (filter) to receive uplinks. The very basic filter (statusReport) should be sufficient for testing purposes:

{% include images-gallery.html imageCollection="tuya-enable-rules-environment" showListImageTitles="true" %}

## Tuya Integration Configuration
## ThingsBoard integration configuration

### Uplink Converter
Let&#39;s move on to setting up the integration between the ThingsBoard platform and Tuya.

Before setting up a **Tuya integration**, you need to create an **Uplink Converter** which is a script for parsing and transforming the data received by Tuya integration to a format that ThingsBoard can consume.
<b><font size="4">1. Basic settings</font></b>

To create an **Uplink Converter**, go to the **Data Converters** section and click **Add new data converter —> Create new converter**, name it **"Tuya Uplink Converter"** and select type **Uplink**. Use debug mode for now.
- Log in to your ThingsBoard account.
- Go to the **Integrations center** &#8702; **Integrations**.
- Click **+** (**plus**) button.
- From the list, select **Tuya** integration type.
- If you&#39;d like to monitor events and troubleshoot, enable **debug mode**.
> Enabling debug mode allows you to track events, states, and potential errors related to the execution of . This greatly simplifies development and troubleshooting.
- Click **Next**.

{% assign feature = "integrations" %}{% include templates/debug-mode.md %}
<b><font size="4">2. Uplink data converter</font></b>

**Choose device payload type to for decoder configuration:**
Uplink is necessary in order to convert the incoming data from the device into the required format for displaying them in ThingsBoard.
- Enter a name for the converter. It must be unique.
- To view the events, enable debug mode.
- In the **Main decoding configuration** section, provide your own script or use the script below.

{% include templates/tbel-vs-js.md %}

{% capture tuyauplink %}
TBEL<small>Recommended</small>%,%accessToken%,%templates/integration/tuya/tuya-uplink-tbel.md%br%
JavaScript<small></small>%,%anonymous%,%templates/integration/tuya/tuya-uplink-java.md{% endcapture %}

{% include content-toggle.liquid content-toggle-id="tuyauplink" toggle-spec=tuyauplink %}

### Downlink Converter
- Once the uplink converter is set up, click **Next**.

The Downlink converter transforming outgoing RPC message and then the Integration sends it to your device.
<b><font size="4">3. Downlink data converter</font></b>

Create another converter with the name **"Tuya Downlink Converter"** and type **Downlink**. To see events - enable Debug.
The Downlink converter transforming outgoing RPC message and then the Integration sends it to your device.
You can use our example of Downlink Converter, or write your own according to your configuration:

{% capture tuyadownlink %}
TBEL<small>Recommended</small>%,%accessToken%,%templates/integration/tuya/tuya-downlink-tbel.md%br%
JavaScript<small></small>%,%anonymous%,%templates/integration/tuya/tuya-downlink-java.md{% endcapture %}

{% include content-toggle.liquid content-toggle-id="tuyadownlink" toggle-spec=tuyadownlink %}

### Tuya Integration Setup
- Click **Next**.

Go to **Integrations** section and click Add new integration button. Name it **Tuya Integration**, select type **Tuya**;

{% if docsPrefix == "pe/" %}
![image](/images/user-guide/integrations/tuya/tuya-create-integration-1-pe.png)
{% endif %}
{% if docsPrefix contains "paas/" %}
![image](/images/user-guide/integrations/tuya/tuya-create-integration-1-pe.png)
{% endif %}

In this step, you can select the recently created **Tuya Uplink Converter** or create a new uplink data converter;

{% if docsPrefix == "pe/" %}
![image](/images/user-guide/integrations/tuya/tuya-create-integration-2-pe.png)
{% endif %}
{% if docsPrefix contains "paas/" %}
![image](/images/user-guide/integrations/tuya/tuya-create-integration-2-pe.png)
{% endif %}

Add **Tuya Downlink Converter** to the integration or create a new downlink data converter;

{% if docsPrefix == "pe/" %}
![image](/images/user-guide/integrations/tuya/tuya-create-integration-3-pe.png)
{% endif %}
{% if docsPrefix contains "paas/" %}
![image](/images/user-guide/integrations/tuya/tuya-create-integration-3-pe.png)
{% endif %}
<b><font size="4">4. Connection</font></b>

In the last step, fill in the following fields:

- **Region** - specify your region;
- **Environment**:
- Choose **PROD** for real devices.
- Select **TEST** if you want to connect a **virtual device** to Thingsboard and test its operation before you buy it.
- **Access Id** and **Access Key** is an authorization certificate distributed by Tuya. Paste [previously copied Access Id and Access Key](#create-cloud-project) into the integration.
- Click **Add** to create an integration.

- **Environment:** choose **PROD** or **TEST**. Choose **PROD** for real devices. Select **TEST** if you want to connect a [**virtual device**](https://developer.tuya.com/en/docs/iot/manage-virtual-devices?id=Ka4725tiyfhg0) to Thingsboard and test its operation before you buy it.

- **Access Id** and **Access Key** is an authorization certificate distributed by Tuya. Paste previously copied **Access Id** and **Access Key** into the integration.

Click "Add" to create an integration.

{% if docsPrefix == "pe/" %}
![image](/images/user-guide/integrations/tuya/tuya-create-integration-4-pe.png)
{% endif %}
{% if docsPrefix contains "paas/" %}
![image](/images/user-guide/integrations/tuya/tuya-create-integration-4-pe.png)
{% endif %}

### Rule Chain configuration
## Rule Chain configuration

When integration configured and ready to use, we need to go to **Rule Chains**, choose **"Root Rule Chain"** and here create rule node **Integration Downlink**. Input some name here, choose earlier created Tuya integration, and tap **Add**.

{% if docsPrefix == "pe/" %}
![image](/images/user-guide/integrations/tuya/tuya-rule-chain-downlink-1-pe.png)
{% endif %}
{% if docsPrefix contains "paas/" %}
![image](/images/user-guide/integrations/tuya/tuya-rule-chain-downlink-1-pe.png)
{% endif %}

After these steps, we need to tap on a right grey circle of rule node **message type switch** and drag this circle to left side of **Integration Downlink**. In pop-up window add **"RPC Request to Device"** linl, and tap "Add". Save the Root Rule Chain.
After these steps, we need to tap on a right grey circle of rule node **message type switch** and drag this circle to left side of **Integration Downlink**. In pop-up window add **"RPC Request to Device"** link, and tap **Add**. **Save** the Root Rule Chain.

{% if docsPrefix == "pe/" %}
![image](/images/user-guide/integrations/tuya/tuya-rule-chain-downlink-2-pe.png)
{% endif %}
{% if docsPrefix contains "paas/" %}
![image](/images/user-guide/integrations/tuya/tuya-rule-chain-downlink-2-pe.png)
{% endif %}

### Uplink message
## Uplink message

Once ThingsBoard **Tuya Integration** has been created, you must disconnect Smart Plug from power and reconnect. The device will send an uplink message with telemetry and attributes to the integration
Once ThingsBoard Tuya Integration has been created, you must disconnect Smart Plug from power and reconnect. The device will send an uplink message with telemetry and attributes to the integration.

Go to **Device Groups** -> **All** you should find your device provisioned by the Integration. In my case it is - **SmartPlug268970**.
Go to **Entities &#8702; Devices**. You should find your device provisioned by the Integration.

{% if docsPrefix == "pe/" %}
![image](/images/user-guide/integrations/tuya/tuya-integration-create-device-pe.png)
{% endif %}
{% if docsPrefix contains "paas/" %}
![image](/images/user-guide/integrations/tuya/tuya-integration-create-device-pe.png)
{% endif %}
In my case it is - **SmartPlug268970**.

### Tuya Smart Plug Dashboard
## Tuya Smart Plug Dashboard

To visualize the Smart Plug data and test RPC commands, we will create the **Tuya Smart Plug** dashboard.
- Download the [tuya_smart_plug_dashboard.json](/docs/user-guide/resources/tuya_smart_plug_dashboard.json){:target="_blank" download="tuya_smart_plug_dashboard.json"} file.
- Go to the **Dashboards**.
- Click the **+** (**plus**) icon at the upper right corner of the table, and select **Import dashboard**.
- Drag the previously downloaded JSON file into the window.
- Tap **Import**.

- Download the [**tuya_smart_plug_dashboard.json**](/docs/user-guide/resources/tuya_smart_plug_dashboard.json) file
- Go to the **Dashboard groups** tab. Create dashboard group - **Smart Plug** and go to it.
- To import this JSON file, click the `import` button at the upper right corner of the dashboard group page and drag the previously downloaded file into the window. Tap **Import**.

{% if docsPrefix == "pe/" %}
![image](/images/user-guide/integrations/tuya/tuya-dashboard-1-pe.png)
{% endif %}
{% if docsPrefix contains "paas/" %}
![image](/images/user-guide/integrations/tuya/tuya-dashboard-1-pe.png)
{% endif %}

- Open the **Tuya Smart Plug** dashboard
- **Enter edit mode**, click **Entity aliases** button and add your device to **smartPlug** alias
- Open the **Tuya Smart Plug** dashboard.
- Enter **Edit mode**, and update **Entity aliases** - specify your device as target device in the **smartPlug** alias

{% if docsPrefix == "pe/" %}
![image](/images/user-guide/integrations/tuya/tuya-alias-1-pe.png)
{% endif %}
{% if docsPrefix contains "paas/" %}
![image](/images/user-guide/integrations/tuya/tuya-alias-1-pe.png)
{% endif %}

{% capture difference %}
**NOTE:**
<br>
time series data keys of your device may differ from those presented. If necessary, you will need to replace them, according to the documentation for your device (for each widget).
**NOTE:** Time series data keys of your device may differ from those presented. If necessary, you will need to replace them, according to the documentation for your device (for each widget).
{% endcapture %}
{% include templates/info-banner.md content=difference %}

{% if docsPrefix == "pe/" %}
![image](/images/user-guide/integrations/tuya/tuya-edit-timeseries-data-keys-pe.png)
{% endif %}
{% if docsPrefix contains "paas/" %}
![image](/images/user-guide/integrations/tuya/tuya-edit-timeseries-data-keys-pe.png)
{% endif %}

<br>
If you have everything configured correctly, you will see Smart Plug status light (on/off) and telemetry for the last hour: voltage, power, and current.

{% if docsPrefix == "pe/" %}
![image](/images/user-guide/integrations/tuya/tuya-dashboard-2-pe.png)
{% endif %}
{% if docsPrefix contains "paas/" %}
![image](/images/user-guide/integrations/tuya/tuya-dashboard-2-pe.png)
{% endif %}

Smart Plug status light is green. Try to switch off the Smart Plug by clicking on the **On/Off Round switch**

{% if docsPrefix == "pe/" %}
![image](/images/user-guide/integrations/tuya/tuya-dashboard-3-pe.png)
{% endif %}
{% if docsPrefix contains "paas/" %}
![image](/images/user-guide/integrations/tuya/tuya-dashboard-3-pe.png)
{% endif %}

The Smart Plug status indicator turns grey. Power consumption stops.

{% if docsPrefix == "pe/" %}
![image](/images/user-guide/integrations/tuya/tuya-dashboard-4-pe.png)
{% endif %}
{% if docsPrefix contains "paas/" %}
![image](/images/user-guide/integrations/tuya/tuya-dashboard-4-pe.png)
{% endif %}

## Next steps

Expand Down
38 changes: 10 additions & 28 deletions _includes/templates/integration/tuya/tuya-downlink-java.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,38 +1,20 @@
You can use our example of Downlink Converter, or write your own according to your configuration:

```javascript
/** 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 = {

// downlink data content type: JSON, TEXT or BINARY (base64 format)
const command = {
code: msg.method,
value:
msg.params === "false" || msg.params === "true"
? msg.params === "true"
: msg.params
};
const result = {
contentType: "JSON",

// downlink data
data: JSON.stringify(command),

// Optional metadata object presented in key/value format
metadata: {
deviceId: metadata.deviceName
deviceId: metadata.deviceName
}

};

return result;
```
{: .copy-code}

{% if docsPrefix == "pe/" %}
![image](/images/user-guide/integrations/tuya/tuya-create-downlink-converter-java-pe.png)
{% endif %}
{% if docsPrefix contains "paas/" %}
![image](/images/user-guide/integrations/tuya/tuya-create-downlink-converter-java-pe.png)
{% endif %}
{: .copy-code}
13 changes: 2 additions & 11 deletions _includes/templates/integration/tuya/tuya-downlink-tbel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
You can use our example of Downlink Converter, or write your own according to your configuration:

```javascript
/** Encoder **/

Expand All @@ -21,18 +19,11 @@ var result = {

// Optional metadata object presented in key/value format
metadata: {
deviceId: metadata.deviceName
deviceId: metadata.deviceName
}

};

return result;
```
{: .copy-code}

{% if docsPrefix == "pe/" %}
![image](/images/user-guide/integrations/tuya/tuya-create-downlink-converter-tbel-pe.png)
{% endif %}
{% if docsPrefix contains "paas/" %}
![image](/images/user-guide/integrations/tuya/tuya-create-downlink-converter-tbel-pe.png)
{% endif %}
{: .copy-code}
Loading