tuya/tuya-openclaw-skills/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 — obtain it at tuyasmart.com (China Mainland) or tuya.ai (International). 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"

Where to get an API Key:

The API Key format is sk-<PREFIX><rest>, where the prefix is used to automatically identify the data center. Make sure the API Key region matches your Tuya account registration region.

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

1. 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)

1. 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

1. 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

1. 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

1. 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}"}

1. 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