Tuya Smart Control

Tuya Smart Home Device Control Skill

Basic Information

• Official Website: https://www.tuya.com/
• Source Code: https://github.com/tuya/tuya-openclaw-skills
• Authentication: Via Header Authorization: Bearer {Api-key}
• Credentials: Read from environment variable TUYA_API_KEY. Base URL is auto-detected from API key prefix. See references/api-conventions.md for the prefix-to-region mapping table. You can override by setting TUYA_BASE_URL.
• API Reference: See individual files under references/
• Python SDK: See scripts/tuya_api.py
• Device Message Client: See scripts/tuya_device_mq_client.py (real-time WebSocket subscription)

Environment Variable Configuration

Set the following environment variable before use:

export TUYA_API_KEY="your-tuya-api-key"
# TUYA_BASE_URL is optional — auto-detected from API key prefix
# Override only if needed: export TUYA_BASE_URL="https://openapi.tuyaus.com"

The same TUYA_API_KEY is used for both the REST API and WebSocket message subscription. The WebSocket URI is auto-detected from the API key prefix (same 7 data centers as the REST API). See references/device-message.md for the full mapping table.

The skill will not load if the TUYA_API_KEY environment variable is missing.

Usage

Always prefer Method 1 (Command Line) — single command, no boilerplate code. It handles authentication, URL resolution, JSON serialization, and error handling automatically.

Method 1: Via Command Line (Recommended)

python3 {baseDir}/scripts/tuya_api.py <command> [params...]
# Examples:
python3 {baseDir}/scripts/tuya_api.py homes
python3 {baseDir}/scripts/tuya_api.py devices
python3 {baseDir}/scripts/tuya_api.py devices --home 5053559
python3 {baseDir}/scripts/tuya_api.py devices --room 123456
python3 {baseDir}/scripts/tuya_api.py device_detail <device_id>
python3 {baseDir}/scripts/tuya_api.py model <device_id>
python3 {baseDir}/scripts/tuya_api.py control <device_id> '{"switch_led":true}'
python3 {baseDir}/scripts/tuya_api.py rename <device_id> "New Name"
python3 {baseDir}/scripts/tuya_api.py weather 39.90 116.40
python3 {baseDir}/scripts/tuya_api.py sms "Your message"
python3 {baseDir}/scripts/tuya_api.py voice "Your message"
python3 {baseDir}/scripts/tuya_api.py mail "Subject" "Content"
python3 {baseDir}/scripts/tuya_api.py push "Subject" "Content"
python3 {baseDir}/scripts/tuya_api.py stats_config
python3 {baseDir}/scripts/tuya_api.py stats_data <dev_id> <dp_code> <type> <start> <end>
python3 {baseDir}/scripts/tuya_api.py ipc_pic_fetch <device_id> <consent> [pic_count] [home_id]
python3 {baseDir}/scripts/tuya_api.py ipc_video_fetch <device_id> <duration> <consent> [home_id]

CLI validation rules:

• devices supports only one scope flag at a time: --home <id> or --room <id>
• control requires properties_json to be a valid JSON object (not array/string)
• weather validates coordinate range: latitude [-90, 90], longitude [-180, 180]
• stats_data validates start/end format yyyyMMddHH and max 24-hour window
• ipc_pic_fetch args: <device_id> <consent> [pic_count] [home_id] — consent 1 = decrypted URL
• ipc_video_fetch args: <device_id> <duration> <consent> [home_id] — duration in seconds (1-60)
• Use python3 {baseDir}/scripts/tuya_api.py --help for command help and examples

Method 2: Via Python SDK

Use when you need to chain multiple API calls or do complex logic in a single script:

import sys
sys.path.insert(0, "{baseDir}/scripts")
from tuya_api import TuyaAPI

api = TuyaAPI()

homes = api.get_homes()
devices = api.get_all_devices()
detail = api.get_device_detail("device_id_here")
result = api.issue_properties("device_id_here", {"switch_led": True, "bright_value": 500})
weather = api.get_weather(lat="39.90", lon="116.40")
# IPC cloud capture — take a snapshot and get decrypted URL
capture = api.ipc_ai_capture_pic_allocate_and_fetch("device_id_here")

Method 3: Device Message Subscription (WebSocket)

Use when you need real-time device event monitoring (property changes, online/offline status):

import asyncio
import os
import sys
sys.path.insert(0, "{baseDir}/scripts")
from tuya_device_mq_client import TuyaDeviceMQClient

async def main():
    # Uses TUYA_API_KEY for auth; WebSocket URI auto-detected from key prefix
    client = TuyaDeviceMQClient(
        api_key=os.environ["TUYA_API_KEY"],
        device_ids=None,  # None = all devices; or pass a list of device IDs
    )

    @client.on_property_change
    async def on_prop(device_id, properties):
        for prop in properties:
            t = TuyaDeviceMQClient.format_timestamp(prop["time"])
            print(f"[{t}] Device {device_id}: {prop['code']} = {prop['value']}")

    @client.on_online_status
    async def on_status(device_id, status, timestamp_ms):
        t = TuyaDeviceMQClient.format_timestamp(timestamp_ms)
        print(f"[{t}] Device {device_id} is now {status}")

    await client.connect()

asyncio.run(main())

Important: The WebSocket client runs server-side only. It reuses the same TUYA_API_KEY — no separate credentials needed. The WebSocket URI is auto-detected from the key prefix (same 7 data centers as the REST API). Notification throttling (minimum 30-minute cooldown) is mandatory when triggering notifications from device events. See references/device-message.md for message format details and more examples.

Feature Overview

Core Workflows

Workflow 1: Device Control

When the user says things like "turn on the living room light" or "set the AC temperature to 26 degrees":

1. Locate the device — Find the target device based on the device name or location mentioned by the user. Follow this priority:

   • Priority 1 — Room + category match: If the user mentions a room (e.g. "living room AC"), first query the home list → room list to match the room, then list devices in that room and match by category_name or device name
   • Priority 2 — Device name match: If the user only mentions a device name (e.g. "AC"), call "List All Devices" API and match by category_name first, then by device name fuzzy match
   • Priority 3 — Disambiguation: If multiple devices match, list all candidates with their room information and ask the user to choose

2. Get current state — Call the "Get Single Device Detail" API

   • If result is null: the device does not exist or you have no permission — inform the user and stop
   • If online is false: the device is offline — tell the user "Device XX is currently offline, please check its power and network connection" and do not proceed further
   • Only continue when result is valid and online is true
   • The properties field contains current values of each functional property (e.g. switch state, brightness, temperature)

3. Query capabilities — Call the "Query Device Thing Model" API to get the device's supported property list

   • Important: The result.model field is a JSON string that must be parsed again (e.g. json.loads(result["model"])) to obtain the property definitions
   • Check each property's accessMode:
     • ro (read-only): cannot be controlled, only queried — inform the user "this property is read-only"
     • wr (write-only): can be controlled but current value cannot be read
     • rw (read-write): can be both controlled and queried

4. Map the command — Map the user's intent to Thing Model properties:

   • Turn on/off → find a bool-type switch property (e.g. switch_led, switch)
   • Adjust brightness → find a value-type brightness property
   • Adjust temperature → find a value-type temp property
   • If the device does not support the requested function, inform the user and list supported functions
   • Relative adjustments — When the user says "a bit brighter", "lower the temperature by 2 degrees", etc.:
     1. Read the current value from properties in the device detail (Step 2)
     2. Read min, max, step from the Thing Model typeSpec (Step 3)
     3. Calculate the target value:
        • Vague ("a bit", "a little") → current value ± (max - min) × 10%
        • Specific ("by 2 degrees", "by 100") → current value ± the specified amount
     4. Clamp the target value within [min, max] and round to the nearest step
   • Validate value range: Before issuing, confirm the target value is within the typeSpec min/max range

5. Issue the command — Call the "Issue Properties" API using the Python SDK: api.issue_properties(device_id, {property_code: value})

   • The SDK handles properties JSON string serialization automatically
   • If not using the SDK: the properties field must be a JSON string, not a JSON object. You must double-serialize: {"properties": "{\"switch_led\":true}"}

6. Verify and return result — After issuing the command:

   • Wait 1-2 seconds, then call "Get Device Detail" again to read the updated properties
   • Compare the target value with the actual value to confirm execution
   • If values match: inform the user the operation succeeded
   • If values differ: tell the user "command sent, but the device state has not updated yet — there may be a delay"

Workflow 2: Rename Device

1. Locate the device using Workflow 1 Step 1 to obtain the device_id
2. Call the "Rename Device" API with the new name
3. Return the result

Workflow 3: Notifications

1. Identify the message type: SMS / Voice / Email / App Push
2. Extract required parameters (message content; email and push also need a subject)
3. Call the corresponding API (all notification APIs are self-send — messages can only be sent to the current logged-in user)
4. Return the send result

Workflow 4: Weather Query

1. Obtain coordinates:
   • First call Home List API and check the latitude / longitude fields
   • Note: the coordinate format is {"Value": "30.3"} — you must extract the .Value field (e.g. home["latitude"]["Value"])
   • If the home has no location set, ask the user for their city and convert to coordinates (see common city coordinates in references/weather.md)
2. Determine which weather attributes to query (default: temperature, humidity, weather condition)
3. Call the weather query API
4. Translate the returned data into a human-readable description

Workflow 5: Data Statistics

1. Locate the device (same as Workflow 1 Step 1)
2. Call the "Statistics Config Query" API to confirm whether the device has the corresponding statistics capability
3. If available, call the "Statistics Value Query" API
   • Time inference: Convert the user's natural language to yyyyMMddHH format:
     • "today" → start = today 00:00, end = current hour
     • "yesterday" → start = yesterday 00:00, end = yesterday 23:00
     • The time range cannot exceed 24 hours per request — for longer ranges, make multiple requests and aggregate
     • Format example: 2024010100 = January 1, 2024 00:00
4. Aggregate and return the results

Workflow 6: Device Status Query

When the user asks "Is the living room light on?" or "What's the AC set to?":

1. Locate the device and get current state (same as Workflow 1 Steps 1-2; stop if device not found or offline)
2. Read properties values, cross-reference with the Thing Model property names/descriptions, and translate to natural language (e.g. "switch_led": true → "the light is currently on")

Workflow 7: Multi-Device Batch Control

When the user says "Turn off all lights" or "Set all ACs to 26 degrees":

1. Call "List All Devices" API and filter matching devices by category_name or device name keyword
2. For each matching device: check online status (skip offline devices and note them), then execute Workflow 1 Steps 3-6
3. Aggregate results: report how many devices succeeded, which ones failed or were offline
4. Add a brief delay (0.5-1s) between requests to avoid rate limiting