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
| Module |
Capabilities |
Reference |
| Home Management |
List all homes, list rooms in a home |
references/home-and-space.md |
| Device Query |
All devices, devices by home/room, single device detail (including current property states) |
references/device-query.md |
| Device Control |
Query device Thing Model, issue property commands |
references/device-control.md |
| Device Management |
Rename device |
references/device-management.md |
| Weather Service |
Current and forecast weather |
references/weather.md |
| Notifications |
SMS, voice call, email, App push |
references/notifications.md |
| Data Statistics |
Hourly statistics config query, statistics value query |
references/statistics.md |
| IPC Cloud Capture |
Cloud snapshot and short video capture for IPC cameras |
references/ipc-cloud-capture.md |
| Device Message Subscription |
Real-time WebSocket subscription for device property changes and online/offline events |
references/device-message.md |
| Error Handling |
Error codes and recovery strategies |
references/error-handling.md |
| API Conventions |
Request/response format, data center mapping |
references/api-conventions.md |
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":
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
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)
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
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.:
- Read the current value from
properties in the device detail (Step 2)
- Read
min, max, step from the Thing Model typeSpec (Step 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
- 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
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}"}
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
- Locate the device using Workflow 1 Step 1 to obtain the device_id
- Call the "Rename Device" API with the new name
- Return the result
Workflow 3: Notifications
- Identify the message type: SMS / Voice / Email / App Push
- Extract required parameters (message content; email and push also need a subject)
- Call the corresponding API (all notification APIs are self-send — messages can only be sent to the current logged-in user)
- Return the send result
Workflow 4: Weather Query
- 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)
- Determine which weather attributes to query (default: temperature, humidity, weather condition)
- Call the weather query API
- Translate the returned data into a human-readable description
Workflow 5: Data Statistics
- Locate the device (same as Workflow 1 Step 1)
- Call the "Statistics Config Query" API to confirm whether the device has the corresponding statistics capability
- 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
- 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?":
- Locate the device and get current state (same as Workflow 1 Steps 1-2; stop if device not found or offline)
- 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":
- Call "List All Devices" API and filter matching devices by
category_name or device name keyword
- For each matching device: check
online status (skip offline devices and note them), then execute Workflow 1 Steps 3-6
- Aggregate results: report how many devices succeeded, which ones failed or were offline
- Add a brief delay (0.5-1s) between requests to avoid rate limiting
Workflow 8: IPC Cloud Capture
When the user asks to "take a photo with the camera" or "record a short video from the camera":
- Locate the IPC device — same as Workflow 1 Step 1, filter by camera category
- Determine capture type:
- Snapshot →
PIC (optional pic_count, 1-5)
- Short video →
VIDEO (optional video_duration_seconds, 1-60, default 10)
- Execute capture — Use the all-in-one helper methods:
- For PIC:
api.ipc_ai_capture_pic_allocate_and_fetch(device_id, pic_count=1)
- For VIDEO:
api.ipc_ai_capture_video_allocate_and_fetch(device_id, video_duration_seconds=5)
- These methods handle the full allocate → wait → poll → retry flow automatically
- Return the result — Extract the URL from the resolve result:
- PIC with consent:
resolve["decrypt_image_url"]
- VIDEO with consent:
resolve["decrypt_video_url"] (cover image may be null if still uploading)
- If
status is still NOT_READY after all retries, inform the user that the device may be slow to upload and suggest trying again later
Workflow 9: IPC Visual Recognition
When the user asks "What's in front of my camera?", "Is there anyone at the door?", or "Describe what the camera sees":
- Capture a snapshot — Follow Workflow 8 Steps 1-3 to take a PIC capture
- Get the image URL — Extract
resolve["decrypt_image_url"] from the capture result. If the resolve failed or returned NOT_READY, inform the user and stop
- Download the image — Fetch the image content from the decrypted URL
- Send to AI vision model — Pass the image to the AI large model for visual understanding. Describe the image content in natural language based on the user's question:
- General question ("What's there?") → describe the overall scene, objects, and people
- Specific question ("Is there a package?", "Is anyone at the door?") → focus on answering the specific question
- Return the description — Respond to the user with the visual analysis result in conversational language
Workflow 10: Real-Time Device Monitoring
When the user asks to "monitor device changes in real time", "watch for property updates", or "notify me when a device goes offline":
- Determine scope — Ask which devices to monitor (all or specific device IDs). If specific, locate devices using Workflow 1 Step 1
- Determine event types — Property changes (
on_property_change), online/offline status (on_online_status), or both
- Write the subscription script — Using
TuyaDeviceMQClient from scripts/tuya_device_mq_client.py:
- Import and instantiate with
api_key=os.environ["TUYA_API_KEY"] (WebSocket URI auto-detected from key prefix)
- Register appropriate handlers using decorators
- Call
await client.connect() to start listening
- Apply throttling — If the subscription triggers notifications or device control actions, implement a cooldown mechanism (minimum 30-minute interval for notifications)
- Cross-reference with REST API — Property codes from WebSocket events correspond to Thing Model codes. Use
api.get_device_model(device_id) to look up property names and value ranges when needed
Workflow 11: Event-Driven Automation
When the user asks to "turn on the hallway light when the door opens" or "send me a notification when the AC turns off":
- Identify trigger and action — Parse the trigger device, trigger condition (property code + value), and the action to execute
- Locate devices — Use Workflow 1 Step 1 to find both the trigger device and the action device
- Write the automation script — Combine
TuyaDeviceMQClient for event listening with TuyaAPI for device control:
- Subscribe to the trigger device's property changes
- When the trigger condition is met, call
api.issue_properties() to control the action device
- Implement notification throttling (30-minute cooldown) if sending notifications
- Verify — Confirm the trigger condition and action mapping with the user before running
Important Notes
- Device name matching uses fuzzy matching; when multiple results are found, ask the user to confirm
- The statistics API time format is
yyyyMMddHH, and the time range cannot exceed 24 hours per request
- All four notification APIs are self-send only — messages can only be sent to the currently logged-in user
- The weather query requires latitude and longitude; if unavailable from the Home API, ask for the user's city
- Base URL is auto-detected from API key prefix. See
references/api-conventions.md for details
- If you encounter issues, visit https://github.com/tuya/tuya-openclaw-skills for announcements and troubleshooting
- Never log or display the
TUYA_API_KEY value in output
- CLI exits with code
2 for usage/validation errors, and 1 for runtime/API/network errors
Supported and Unsupported Operations
Supported Property Types for Control
Only basic data type properties are currently supported for device control:
| Type |
Description |
Example |
| bool |
Boolean on/off |
Turn light on/off, turn AC on/off, turn plug on/off |
| enum |
Enumeration selection |
Switch AC mode (auto/cold/hot), set fan speed (low/mid/high) |
| value (Integer) |
Numeric value |
Adjust brightness (0-1000), set temperature (16-30) |
| string |
String value |
Set device display text |
Unsupported Operations
The following operations involve sensitive actions or complex data types and are NOT supported:
- Lock control — Unlock doors, lock/unlock smart locks (security-sensitive)
- Live video streaming — Pull real-time video streams or view camera live footage (cloud snapshot/short video capture IS supported — see Workflow 8)
- Image operations — Retrieve or push images from/to devices
- Complex data type control — Properties with
raw, bitmap, struct, or array typeSpec are not supported for issuing commands
- Firmware upgrades — OTA firmware update operations
- Device pairing/removal — Adding new devices or removing existing devices
If the user requests any of these unsupported operations, clearly inform them that the operation is not available through this skill and suggest using the Tuya App directly.
Data Egress Statement
This skill sends data to the Tuya Open Platform:
| Data Type |
Sent To |
Purpose |
Required |
| Api-key |
User-configured base_url |
API authentication |
Required |
| Device ID |
User-configured base_url |
Device query and control |
Required |
| Control commands |
User-configured base_url |
Device property issuance |
Required |
| Api-key |
Auto-detected WebSocket URI |
Real-time event subscription authentication |
Required for message subscription |
1---2name: tuya-smart-control3description: Control Tuya smart home devices via natural language. Use when the user asks to control smart devices (turn on/off lights, AC, plugs, adjust brightness/temperature/mode), query device status or list devices, manage homes and rooms, rename devices, check weather by location, send notifications (SMS, voice call, email, or App push), view device data statistics (e.g. energy/power consumption), capture snapshots/short videos from IPC cameras, or subscribe to real-time device events (property changes, online/offline status) via WebSocket. Requires TUYA_API_KEY.4metadata:5 source: https://skillmd.com/skills/tuya/tuya-smart-control6 openclaw:7 version: 1.0.08 emoji: 🏠9 requires:10 env:11 - TUYA_API_KEY12 pip:13 - requests>=2.28.014 - websockets>=12.015 primaryEnv: TUYA_API_KEY16---1718# Tuya Smart Home Device Control Skill1920## Basic Information2122- **Official Website**: https://www.tuya.com/23- **Source Code**: https://github.com/tuya/tuya-openclaw-skills24- **Authentication**: Via Header `Authorization: Bearer {Api-key}`25- **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`.26- **API Reference**: See individual files under `references/`27- **Python SDK**: See `scripts/tuya_api.py`28- **Device Message Client**: See `scripts/tuya_device_mq_client.py` (real-time WebSocket subscription)2930## Environment Variable Configuration3132Set the following environment variable before use:3334```bash35export TUYA_API_KEY="your-tuya-api-key"36# TUYA_BASE_URL is optional — auto-detected from API key prefix37# Override only if needed: export TUYA_BASE_URL="https://openapi.tuyaus.com"38```3940The 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.4142The skill will not load if the `TUYA_API_KEY` environment variable is missing.4344## Usage4546**Always prefer Method 1 (Command Line)** — single command, no boilerplate code. It handles authentication, URL resolution, JSON serialization, and error handling automatically.4748### Method 1: Via Command Line (Recommended)4950```bash51python3 {baseDir}/scripts/tuya_api.py <command> [params...]52# Examples:53python3 {baseDir}/scripts/tuya_api.py homes54python3 {baseDir}/scripts/tuya_api.py devices55python3 {baseDir}/scripts/tuya_api.py devices --home 505355956python3 {baseDir}/scripts/tuya_api.py devices --room 12345657python3 {baseDir}/scripts/tuya_api.py device_detail <device_id>58python3 {baseDir}/scripts/tuya_api.py model <device_id>59python3 {baseDir}/scripts/tuya_api.py control <device_id> '{"switch_led":true}'60python3 {baseDir}/scripts/tuya_api.py rename <device_id> "New Name"61python3 {baseDir}/scripts/tuya_api.py weather 39.90 116.4062python3 {baseDir}/scripts/tuya_api.py sms "Your message"63python3 {baseDir}/scripts/tuya_api.py voice "Your message"64python3 {baseDir}/scripts/tuya_api.py mail "Subject" "Content"65python3 {baseDir}/scripts/tuya_api.py push "Subject" "Content"66python3 {baseDir}/scripts/tuya_api.py stats_config67python3 {baseDir}/scripts/tuya_api.py stats_data <dev_id> <dp_code> <type> <start> <end>68python3 {baseDir}/scripts/tuya_api.py ipc_pic_fetch <device_id> <consent> [pic_count] [home_id]69python3 {baseDir}/scripts/tuya_api.py ipc_video_fetch <device_id> <duration> <consent> [home_id]70```7172CLI validation rules:73- `devices` supports only one scope flag at a time: `--home <id>` or `--room <id>`74- `control` requires `properties_json` to be a valid JSON object (not array/string)75- `weather` validates coordinate range: latitude `[-90, 90]`, longitude `[-180, 180]`76- `stats_data` validates `start`/`end` format `yyyyMMddHH` and max 24-hour window77- `ipc_pic_fetch` args: `<device_id> <consent> [pic_count] [home_id]` — consent `1` = decrypted URL78- `ipc_video_fetch` args: `<device_id> <duration> <consent> [home_id]` — duration in seconds (1-60)79- Use `python3 {baseDir}/scripts/tuya_api.py --help` for command help and examples8081### Method 2: Via Python SDK8283Use when you need to chain multiple API calls or do complex logic in a single script:8485```python86import sys87sys.path.insert(0, "{baseDir}/scripts")88from tuya_api import TuyaAPI8990api = TuyaAPI()9192homes = api.get_homes()93devices = api.get_all_devices()94detail = api.get_device_detail("device_id_here")95result = api.issue_properties("device_id_here", {"switch_led": True, "bright_value": 500})96weather = api.get_weather(lat="39.90", lon="116.40")97# IPC cloud capture — take a snapshot and get decrypted URL98capture = api.ipc_ai_capture_pic_allocate_and_fetch("device_id_here")99```100101### Method 3: Device Message Subscription (WebSocket)102103Use when you need real-time device event monitoring (property changes, online/offline status):104105```python106import asyncio107import os108import sys109sys.path.insert(0, "{baseDir}/scripts")110from tuya_device_mq_client import TuyaDeviceMQClient111112async def main():113 # Uses TUYA_API_KEY for auth; WebSocket URI auto-detected from key prefix114 client = TuyaDeviceMQClient(115 api_key=os.environ["TUYA_API_KEY"],116 device_ids=None, # None = all devices; or pass a list of device IDs117 )118119 @client.on_property_change120 async def on_prop(device_id, properties):121 for prop in properties:122 t = TuyaDeviceMQClient.format_timestamp(prop["time"])123 print(f"[{t}] Device {device_id}: {prop['code']} = {prop['value']}")124125 @client.on_online_status126 async def on_status(device_id, status, timestamp_ms):127 t = TuyaDeviceMQClient.format_timestamp(timestamp_ms)128 print(f"[{t}] Device {device_id} is now {status}")129130 await client.connect()131132asyncio.run(main())133```134135> **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.136137## Feature Overview138139| Module | Capabilities | Reference |140|--------|-------------|-----------|141| Home Management | List all homes, list rooms in a home | `references/home-and-space.md` |142| Device Query | All devices, devices by home/room, single device detail (including current property states) | `references/device-query.md` |143| Device Control | Query device Thing Model, issue property commands | `references/device-control.md` |144| Device Management | Rename device | `references/device-management.md` |145| Weather Service | Current and forecast weather | `references/weather.md` |146| Notifications | SMS, voice call, email, App push | `references/notifications.md` |147| Data Statistics | Hourly statistics config query, statistics value query | `references/statistics.md` |148| IPC Cloud Capture | Cloud snapshot and short video capture for IPC cameras | `references/ipc-cloud-capture.md` |149| Device Message Subscription | Real-time WebSocket subscription for device property changes and online/offline events | `references/device-message.md` |150| Error Handling | Error codes and recovery strategies | `references/error-handling.md` |151| API Conventions | Request/response format, data center mapping | `references/api-conventions.md` |152153## Core Workflows154155### Workflow 1: Device Control156157When the user says things like "turn on the living room light" or "set the AC temperature to 26 degrees":1581591. **Locate the device** — Find the target device based on the device name or location mentioned by the user. Follow this priority:160 - **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`161 - **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 match162 - **Priority 3 — Disambiguation**: If multiple devices match, list all candidates with their room information and ask the user to choose1631642. **Get current state** — Call the "Get Single Device Detail" API165 - **If `result` is `null`**: the device does not exist or you have no permission — inform the user and stop166 - **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 further167 - Only continue when `result` is valid and `online` is `true`168 - The `properties` field contains current values of each functional property (e.g. switch state, brightness, temperature)1691703. **Query capabilities** — Call the "Query Device Thing Model" API to get the device's supported property list171 - **Important**: The `result.model` field is a JSON **string** that must be parsed again (e.g. `json.loads(result["model"])`) to obtain the property definitions172 - Check each property's `accessMode`:173 - `ro` (read-only): cannot be controlled, only queried — inform the user "this property is read-only"174 - `wr` (write-only): can be controlled but current value cannot be read175 - `rw` (read-write): can be both controlled and queried1761774. **Map the command** — Map the user's intent to Thing Model properties:178 - Turn on/off → find a bool-type switch property (e.g. `switch_led`, `switch`)179 - Adjust brightness → find a value-type brightness property180 - Adjust temperature → find a value-type temp property181 - If the device does not support the requested function, inform the user and list supported functions182 - **Relative adjustments** — When the user says "a bit brighter", "lower the temperature by 2 degrees", etc.:183 1. Read the current value from `properties` in the device detail (Step 2)184 2. Read `min`, `max`, `step` from the Thing Model `typeSpec` (Step 3)185 3. Calculate the target value:186 - Vague ("a bit", "a little") → current value ± (max - min) × 10%187 - Specific ("by 2 degrees", "by 100") → current value ± the specified amount188 4. Clamp the target value within [min, max] and round to the nearest `step`189 - **Validate value range**: Before issuing, confirm the target value is within the `typeSpec` min/max range1901915. **Issue the command** — Call the "Issue Properties" API using the Python SDK: `api.issue_properties(device_id, {property_code: value})`192 - The SDK handles `properties` JSON string serialization automatically193 - 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}"}`1941956. **Verify and return result** — After issuing the command:196 - Wait 1-2 seconds, then call "Get Device Detail" again to read the updated `properties`197 - Compare the target value with the actual value to confirm execution198 - If values match: inform the user the operation succeeded199 - If values differ: tell the user "command sent, but the device state has not updated yet — there may be a delay"200201### Workflow 2: Rename Device2022031. Locate the device using Workflow 1 Step 1 to obtain the device_id2042. Call the "Rename Device" API with the new name2053. Return the result206207### Workflow 3: Notifications2082091. Identify the message type: SMS / Voice / Email / App Push2102. Extract required parameters (message content; email and push also need a subject)2113. Call the corresponding API (all notification APIs are self-send — messages can only be sent to the current logged-in user)2124. Return the send result213214### Workflow 4: Weather Query2152161. **Obtain coordinates**:217 - First call Home List API and check the `latitude` / `longitude` fields218 - **Note**: the coordinate format is `{"Value": "30.3"}` — you must extract the `.Value` field (e.g. `home["latitude"]["Value"]`)219 - 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`)2202. Determine which weather attributes to query (default: temperature, humidity, weather condition)2213. Call the weather query API2224. Translate the returned data into a human-readable description223224### Workflow 5: Data Statistics2252261. Locate the device (same as Workflow 1 Step 1)2272. Call the "Statistics Config Query" API to confirm whether the device has the corresponding statistics capability2283. If available, call the "Statistics Value Query" API229 - **Time inference**: Convert the user's natural language to `yyyyMMddHH` format:230 - "today" → start = today 00:00, end = current hour231 - "yesterday" → start = yesterday 00:00, end = yesterday 23:00232 - The time range cannot exceed 24 hours per request — for longer ranges, make multiple requests and aggregate233 - Format example: `2024010100` = January 1, 2024 00:002344. Aggregate and return the results235236### Workflow 6: Device Status Query237238When the user asks "Is the living room light on?" or "What's the AC set to?":2392401. Locate the device and get current state (same as Workflow 1 Steps 1-2; stop if device not found or offline)2412. 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")242243### Workflow 7: Multi-Device Batch Control244245When the user says "Turn off all lights" or "Set all ACs to 26 degrees":2462471. Call "List All Devices" API and filter matching devices by `category_name` or device `name` keyword2482. For each matching device: check `online` status (skip offline devices and note them), then execute Workflow 1 Steps 3-62493. Aggregate results: report how many devices succeeded, which ones failed or were offline2504. Add a brief delay (0.5-1s) between requests to avoid rate limiting251252### Workflow 8: IPC Cloud Capture253254When the user asks to "take a photo with the camera" or "record a short video from the camera":2552561. **Locate the IPC device** — same as Workflow 1 Step 1, filter by camera category2572. **Determine capture type**:258 - Snapshot → `PIC` (optional `pic_count`, 1-5)259 - Short video → `VIDEO` (optional `video_duration_seconds`, 1-60, default 10)2603. **Execute capture** — Use the all-in-one helper methods:261 - For PIC: `api.ipc_ai_capture_pic_allocate_and_fetch(device_id, pic_count=1)`262 - For VIDEO: `api.ipc_ai_capture_video_allocate_and_fetch(device_id, video_duration_seconds=5)`263 - These methods handle the full allocate → wait → poll → retry flow automatically2644. **Return the result** — Extract the URL from the resolve result:265 - PIC with consent: `resolve["decrypt_image_url"]`266 - VIDEO with consent: `resolve["decrypt_video_url"]` (cover image may be null if still uploading)267 - If `status` is still `NOT_READY` after all retries, inform the user that the device may be slow to upload and suggest trying again later268269### Workflow 9: IPC Visual Recognition270271When the user asks "What's in front of my camera?", "Is there anyone at the door?", or "Describe what the camera sees":2722731. **Capture a snapshot** — Follow Workflow 8 Steps 1-3 to take a PIC capture2742. **Get the image URL** — Extract `resolve["decrypt_image_url"]` from the capture result. If the resolve failed or returned `NOT_READY`, inform the user and stop2753. **Download the image** — Fetch the image content from the decrypted URL2764. **Send to AI vision model** — Pass the image to the AI large model for visual understanding. Describe the image content in natural language based on the user's question:277 - General question ("What's there?") → describe the overall scene, objects, and people278 - Specific question ("Is there a package?", "Is anyone at the door?") → focus on answering the specific question2795. **Return the description** — Respond to the user with the visual analysis result in conversational language280281### Workflow 10: Real-Time Device Monitoring282283When the user asks to "monitor device changes in real time", "watch for property updates", or "notify me when a device goes offline":2842851. **Determine scope** — Ask which devices to monitor (all or specific device IDs). If specific, locate devices using Workflow 1 Step 12862. **Determine event types** — Property changes (`on_property_change`), online/offline status (`on_online_status`), or both2873. **Write the subscription script** — Using `TuyaDeviceMQClient` from `scripts/tuya_device_mq_client.py`:288 - Import and instantiate with `api_key=os.environ["TUYA_API_KEY"]` (WebSocket URI auto-detected from key prefix)289 - Register appropriate handlers using decorators290 - Call `await client.connect()` to start listening2914. **Apply throttling** — If the subscription triggers notifications or device control actions, implement a cooldown mechanism (minimum 30-minute interval for notifications)2925. **Cross-reference with REST API** — Property codes from WebSocket events correspond to Thing Model codes. Use `api.get_device_model(device_id)` to look up property names and value ranges when needed293294### Workflow 11: Event-Driven Automation295296When the user asks to "turn on the hallway light when the door opens" or "send me a notification when the AC turns off":2972981. **Identify trigger and action** — Parse the trigger device, trigger condition (property code + value), and the action to execute2992. **Locate devices** — Use Workflow 1 Step 1 to find both the trigger device and the action device3003. **Write the automation script** — Combine `TuyaDeviceMQClient` for event listening with `TuyaAPI` for device control:301 - Subscribe to the trigger device's property changes302 - When the trigger condition is met, call `api.issue_properties()` to control the action device303 - Implement notification throttling (30-minute cooldown) if sending notifications3044. **Verify** — Confirm the trigger condition and action mapping with the user before running305306## Important Notes3073081. Device name matching uses fuzzy matching; when multiple results are found, ask the user to confirm3092. The statistics API time format is `yyyyMMddHH`, and the time range cannot exceed 24 hours per request3103. All four notification APIs are self-send only — messages can only be sent to the currently logged-in user3114. The weather query requires latitude and longitude; if unavailable from the Home API, ask for the user's city3125. Base URL is auto-detected from API key prefix. See `references/api-conventions.md` for details3136. If you encounter issues, visit https://github.com/tuya/tuya-openclaw-skills for announcements and troubleshooting3147. Never log or display the `TUYA_API_KEY` value in output3158. CLI exits with code `2` for usage/validation errors, and `1` for runtime/API/network errors316317## Supported and Unsupported Operations318319### Supported Property Types for Control320321Only basic data type properties are currently supported for device control:322323| Type | Description | Example |324|------|-------------|---------|325| bool | Boolean on/off | Turn light on/off, turn AC on/off, turn plug on/off |326| enum | Enumeration selection | Switch AC mode (auto/cold/hot), set fan speed (low/mid/high) |327| value (Integer) | Numeric value | Adjust brightness (0-1000), set temperature (16-30) |328| string | String value | Set device display text |329330### Unsupported Operations331332The following operations involve sensitive actions or complex data types and are **NOT supported**:333334- **Lock control** — Unlock doors, lock/unlock smart locks (security-sensitive)335- **Live video streaming** — Pull real-time video streams or view camera live footage (cloud snapshot/short video capture IS supported — see Workflow 8)336- **Image operations** — Retrieve or push images from/to devices337- **Complex data type control** — Properties with `raw`, `bitmap`, `struct`, or `array` typeSpec are not supported for issuing commands338- **Firmware upgrades** — OTA firmware update operations339- **Device pairing/removal** — Adding new devices or removing existing devices340341If the user requests any of these unsupported operations, clearly inform them that the operation is not available through this skill and suggest using the Tuya App directly.342343## Data Egress Statement344345**This skill sends data to the Tuya Open Platform**:346347| Data Type | Sent To | Purpose | Required |348|-----------|---------|---------|----------|349| Api-key | User-configured base_url | API authentication | Required |350| Device ID | User-configured base_url | Device query and control | Required |351| Control commands | User-configured base_url | Device property issuance | Required |352| Api-key | Auto-detected WebSocket URI | Real-time event subscription authentication | Required for message subscription |