Tuya Smart Device Control

Overview

Control smart devices and scene automation remotely through Tuya IoT Cloud Development Platform API interfaces, supporting:

• Device Control: On/off control, status queries, brightness/temperature adjustment, batch operations
• Scene Management: Create scene automation, query scene automation
• Device Search: Search devices by name, get device list and status
• Automation Rules: Trigger device operations based on conditions, e.g., "Turn off desk lamp when socket is turned on"

When to Use

digraph tuya_flow {
    "User requests smart device control" [shape=diamond];
    "Mentions Tuya/smart home" [shape=diamond];
    "Needs on/off/adjust device" [shape=diamond];
    "Use this skill" [shape=box];
    "Use other approach" [shape=box];

    "User requests smart device control" -> "Mentions Tuya/smart home" [label="yes"];
    "User requests smart device control" -> "Use other approach" [label="no"];
    "Mentions Tuya/smart home" -> "Needs on/off/adjust device" [label="yes"];
    "Mentions Tuya/smart home" -> "Use other approach" [label="no"];
    "Needs on/off/adjust device" -> "Use this skill" [label="yes"];
    "Needs on/off/adjust device" -> "Use other approach" [label="no"];
}

Use cases:

• User says "Turn on/off smart device/lamp/AC"
• User says "Adjust light brightness" "Set temperature"
• User mentions "涂鸦" "Tuya" "smart home"
• User needs to query device status
• User needs to batch control multiple devices
• User needs to manage scene automation: "create automation", "query automation", "set automation rules"
• User mentions "场景" "scene" "自动化" "automation"

Not applicable for:

• Non-Tuya platform devices (Xiaomi, HomeKit, etc.)
• Pure documentation queries (use Read tool directly)
• Device firmware updates or advanced configuration

Implementation

Step 1: Environment Configuration ⚠️ CRITICAL: Environment Variable Management

Please read reference/config.md for detailed instructions and examples on environment variable configuration.

Step 2: Verify Configuration

Read environment variables from config.env. If any are missing (TUYA_ACCESS_ID, TUYA_ACCESS_SECRET, TUYA_UID,TUYA_ENDPOINT), prompt the user that these configurations must be provided and stop executing subsequent operations. If configuration exists, continue with the workflow.

Step 3: Workflow

1. Device-Related Operations

If involving:

• Device search
• Device list
• Turn on device
• Turn off device
• Adjust device (brightness, temperature)
• Device control (on/off, adjust)
• Status query
• Batch operations, turn on, turn off
• Set temperature

Please read reference/device.md for detailed steps and example commands.

2. Scene-Related Operations

If involving:

• When one device turns on, need to control another device
• Automatically turn on socket at 19:00 every day
• Open curtains when weather is sunny
• Scene automation
• Scene query Please read reference/scene.md for detailed steps and example commands.

Script File Structure and CLI Tool Design:

Important: Script files are located in the project root directory, with the skill directory containing symbolic links to maintain a single source of truth.

• CLI Tool: scripts/tuya-cli.py
• Core Manager: scripts/tuya_manager.py
• Python Dependencies: scripts/requirements.txt
• Environment Variable Configuration: Environment variables are set through the config.env file
• Environment Setup: Python scripts use venv to manage dependencies. Ensure you are executing in the correct environment. Don't forget to run source venv/bin/activate && source config.env when running Python scripts.

Error Handling Flow

digraph error_handling {
    "Command execution" [shape=diamond];
    "Success" [shape=diamond];
    "Verify status" [shape=box];
    "Report success" [shape=box];
    "Failure" [shape=diamond];
    "Missing env variables" [shape=box];
    "Device not found" [shape=box];
    "Operation failed" [shape=box];

    "Command execution" -> "Success" [label="success"];
    "Command execution" -> "Failure" [label="failure"];
    "Success" -> "Verify status";
    "Verify status" -> "Report success";
    "Failure" -> "Missing env variables" [label="environment"];
    "Failure" -> "Device not found" [label="search"];
    "Failure" -> "Operation failed" [label="API call"];
}

Common Mistakes

Red Flags - STOP and Check

These signs indicate you may have skipped critical steps:

• ❌ Executing commands directly without checking environment variables - Must first verify TUYA_ACCESS_ID, TUYA_ACCESS_SECRET, TUYA_UID
• ❌ Not verifying status after executing control commands - Must use status command to confirm operation succeeded
• ❌ Giving up after trying only one search keyword - Should try multiple variations ("客厅灯", "客厅", "light")
• ❌ Automatically selecting first result when device search returns multiple - Must let user confirm which one to select
• ❌ Ignoring API error messages and retrying directly - Should analyze error cause and take appropriate measures
• ❌ Executing commands in wrong directory - Must execute in project root directory
• ❌ Assuming device is on/off without verification - Must use status command to confirm

If you find yourself doing any of the above, stop and start over.