node-red-contrib-tuya-simple

A set of Node-RED nodes for integrating with the Tuya Cloud OpenAPI to monitor and control compatible smart home / IoT devices.

Features

• Fetch real-time device status (data points / DPs)
• Send commands to control devices
• Supports multiple Tuya data center regions (EU, US, CN, IN)
• Dynamic Device ID via msg, flow/global context, or environment variables
• Secure credential storage using Node-RED's built-in credentials system

Prerequisites

1. A Tuya IoT Platform account with a Cloud Project created
2. The Access Key (Client ID) and Secret Key (Client Secret) from your project
3. Devices linked to your Tuya project
4. Node-RED >= 4.0.0 running on Node.js >= 20

Installation

Install via the Node-RED Manage Palette menu, or from your Node-RED user directory:

npm install @lnowakowski/node-red-contrib-tuya-simple

Restart Node-RED after installation.

Nodes

tuya project config

A configuration node that stores your Tuya Cloud project credentials and API endpoint.

| Property | Description | |----------|-------------| | Access Key | The Access ID / Client ID from your Tuya IoT Platform project | | Secret Key | The Access Secret from your Tuya IoT Platform project | | API endpoint | Regional data center — Central Europe, Western America, China, or India |

Credentials can be found on Tuya Developer Platform under your Cloud Project → Overview section.

tuya fetch status

Fetches the current status of a device identified by its Device ID.

The Device ID can be provided as a static string or resolved dynamically from msg, flow context, global context, or an environment variable.

Output

msg.payload will contain:

{
    "deviceId": "bfd9163d4d...",
    "status": {
        "result": [
            { "code": "switch", "value": false },
            { "code": "battery_percentage", "value": 100 },
            { "code": "work_state", "value": "idle" }
        ],
        "success": true,
        "t": 1786011909023,
        "tid": "1977bdaa918111f1b7ee..."
    }
}

tuya send commands

Sends one or more commands to a device identified by its Device ID.

The input msg.payload must contain a valid Tuya command object:

{
    "commands": [
        { "code": "switch", "value": true },
        { "code": "weather_delay", "value": "cancel" },
        { "code": "countdown", "value": 0 }
    ]
}

Output

msg.payload will contain the Tuya API response indicating success or failure.

Finding command codes

The proper payload for commands can be discovered by:

• Using Device Debug on the Tuya Developer Platform
• Consulting the Tuya Cloud Device Control API docs

Example Flow

An example flow is included in the examples/ folder and is available in the Node-RED editor under Import → Examples → @lnowakowski/node-red-contrib-tuya-simple.

The example demonstrates:

• Fetching device status using a Device ID from msg.topic
• Sending commands with a JSONata-generated payload

Error Handling

If an API call fails (invalid credentials, unreachable endpoint, unknown device ID, or malformed commands), the node logs the error to the Node-RED debug sidebar. No output message is sent on failure.

To handle errors in your flow, you can use a Catch node scoped to the Tuya nodes.

API Details

This package uses the Tuya Cloud OpenAPI v1.0 endpoints:

| Operation | Method | Endpoint | |-----------|--------|----------| | Get token | GET | /v1.0/token?grant_type=1 | | Fetch status | GET | /v1.0/devices/{deviceId}/status | | Send commands | POST | /v1.0/devices/{deviceId}/commands |

Authentication uses HMAC-SHA256 request signing as per the Tuya API signing documentation.

License

MIT

Links

• GitHub Repository
• Tuya Developer Platform
• Tuya Cloud API Documentation
• Node-RED