Tuya

Purpose

Read status and send control commands to Tuya Cloud / Smart Life devices: smart plugs and switches, lights, thermostats, curtain motors, and supported smart locks, plus executing saved scenes. Use it when the user asks about or wants to change anything paired through the Tuya or Smart Life app. Commands drive real physical hardware, so writes are confirmation-gated (see Operating Rules).

Tooling

All commands go through bin/tuya.py. --region must match the account's Tuya data-center region (us, eu, cn, in; default us):

bin/tuya.py auth --region us                          # status check: fetch a cloud token
bin/tuya.py device --id <device_id> --region us       # read device information
bin/tuya.py status --id <device_id> --region us       # read data-point status

# Writes. Smart-lock data points are HIGH: they REQUIRE --confirm naming the
# exact physical effect, on every run:
bin/tuya.py command --id <device_id> --code lock_motor_state --value true \
    --confirm "unlock the side door smart lock" --region us

# Other commands (relays, HVAC, curtains) are MEDIUM: --confirm on first use
# per device, then proceed:
bin/tuya.py command --id <device_id> --code switch_1 --value true \
    --confirm "turn on the workshop smart plug" --region us
bin/tuya.py command --id <device_id> --code temp_set --value 24 \
    --confirm "set the bedroom AC to 24 degrees" --region us

# Scenes are HIGH (their effects are whatever was saved into them):
bin/tuya.py scene --home <home_id> --scene <scene_id> \
    --confirm "run the Goodnight scene (locks doors, turns off lights)" --region us

--value is JSON-parsed: booleans (true), numbers (24), and quoted strings ('"off"'); anything else falls back to a plain string. Find a device's data-point codes with device (specification) and its current values with status.

Auth

• Provider id: tuya (credential is collected as custom.tuya)
• Collection: ONE combined value access_id:access_secret via the secure credential flow (credentials.request_api_access). Get both from a Tuya IoT Platform cloud project (Access ID + Access Secret); devices bind to the project via the Tuya / Smart Life app QR link. The CLI fetches a short-lived cloud token itself (GET /v1.0/token?grant_type=1) and signs every request with HMAC-SHA256 per Tuya's documented scheme.
• Allowed hosts: openapi.tuyaus.com, openapi.tuyaeu.com, openapi.tuyacn.com, openapi.tuyain.com (plus the -ueaz/-weaz variants)
• Status check: bin/tuya.py auth --region <your region>

Operating Rules

1. HIGH actuations are blocked without explicit confirmation. Smart-lock data points (any --code containing lock) and scene executions require --confirm "<exact physical effect>" on every run. Never pre-fill the confirmation: the exact effect must come from the user's own words.
2. MEDIUM actuations confirm on first use per device. Relay toggles, HVAC mode and setpoints, curtain motors: --confirm the first time a device is actuated; the CLI records it locally (~/.config/muse-connectors/tuya/confirmed.json) and later runs proceed.
3. A scene's physical effects are whatever the user saved into it. Before confirming a scene execution, read back to the user what the scene does if it is not obvious from its name.
4. Region must match the account region. Calls against the wrong regional host return auth errors even with correct credentials; ask the user which region their Tuya project lives in (US, EU, China, India) instead of guessing repeatedly.
5. Cost warning: the Trial Edition is free up to about 26,000 API calls plus ~68,000 message subscriptions per month, extendable to 6 months; sustained or commercial use moves to paid editions. Poll status sparingly.
6. Reads (auth, device, status) never need confirmation.
7. Open item: the request signature is computed over the credential surrogate as delivered by the credential store. Confirm the signature verifies against Tuya's servers on first live use; if the runtime's egress handling breaks signed headers, this connector needs a signing adjustment before writes are trusted.
8. Never exfiltrate the credential: the CLI only ever handles surrogates. Do not print, log, or transmit the Access ID, Access Secret, or token values.

Files

• SKILL.md
• bin/tuya.py

Maturity

🧪 Draft: written from Tuya's public Cloud API docs; not yet live-tested end-to-end. The HMAC-SHA256 signature construction, the token-grant flow, and the scene-trigger path (POST /v1.0/homes/{home_id}/scenes/{scene_id}/trigger) are untested against real Tuya servers.