gadget-tuya-cloud-devices

Tuya Cloud Devices: End-User API Control

Use this skill when the user supplies a Tuya end-user API key (sk-...) and asks to control or query devices from their Tuya app account. Devices are reached in the cloud, so no local keys or model-specific datapoint maps are needed. For direct local-TCP control with a confirmed key and datapoint schema, prefer Tuya Wi-Fi devices.

Prerequisites

Read and follow the Home Link networking and safety rules in ~/docs/devices/home_link.md.

• A user-supplied end-user API key, applied for at https://tuya.ai/. Treat it as a credential: pass it in a header, never log or echo it.

• Send Authorization: Bearer <key> on every call. Pick the base URL from the first two characters after sk-; it must match the account's region. If the prefix is not listed, ask the user to confirm the key was issued for an international account at https://tuya.ai/.

  Prefix	Base URL
  AZ	https://openapi.tuyaus.com
  EU	https://openapi.tuyaeu.com
  IN	https://openapi.tuyain.com
  UE	https://openapi-ueaz.tuyaus.com
  WE	https://openapi-weaz.tuyaeu.com
  SG	https://openapi-sg.iotbing.com

• Responses share one envelope: {"success": true, "result": ...} or {"success": false, "code", "msg"}. On 1010 the key expired — ask for a fresh one. On 429 back off and honor Retry-After. List endpoints return everything in one response; there is no pagination.

Workflow

1. List homes with GET /v1.0/end-user/homes/all, and rooms with GET /v1.0/end-user/homes/{home_id}/rooms when the user names one.
2. Locate the device: GET /v1.0/end-user/devices/all, or scope to .../homes/{home_id}/devices or .../homes/room/{room_id}/devices. Each entry in result.devices[] carries device_id, name, category, category_name, online and, under a home scope, room_id. Match the user's words against category_name first, then fuzzy-match name. With multiple matches, list the candidates with their rooms and ask.
3. Read GET /v1.0/end-user/devices/{device_id}/detail. A null result means the device does not exist or the key has no access — stop. online: false means report the device as offline and command nothing. result.properties maps each property code to its current value.
4. Read the thing model GET /v1.0/end-user/devices/{device_id}/model. Its result.model field is a JSON string that needs a second parse. services[].properties[] then defines each property's code, accessMode (ro properties are read-only — say so) and typeSpec:
   • value: min, max, step and scale — the real-world value is the raw number divided by 10^scale.
   • enum: the issued value must be one of range.
   • bool / string: true/false, and maxlen respectively. Common codes are switch_led/switch (bool power), bright_value/temp_value (0–1000), temp_set (16–30) and mode (enum) — the model response is always authoritative.
5. Issue POST /v1.0/end-user/devices/{device_id}/shadow/properties/issue with a body whose properties value is a JSON string, not an object — it is double-serialized: {"properties": "{\"switch_led\":true}"}. An empty result object means the command was accepted, not that it took effect. For relative asks ("a bit brighter"), adjust the current value by 10% of the typeSpec range for vague amounts or by the stated amount exactly, clamp to [min, max], honor scale and round to step.
6. Wait 1–2 seconds, re-read the detail and compare the mapped value before reporting success.