Tuya Cloud Controller

Read sensor data and control Tuya IoT devices via scripts/tuya_controller.py. Supports both Tuya Cloud API and direct local LAN control.

Device registry

Known controllable devices are defined in scripts/config.py as CONTROLLABLE_DEVICES (OPTIONAL).
Always consult this list first if exist to resolve a device name to its device_id.
For valve devices the valve key gives the DP code ( e.g. switch_1) to use as the command code.
Only call tuya_list_devices if the device is not listed in the config.

Setup

Add credentials to .env:

CODEBLOCK0

Regional endpoints: EU tuyaeu.com · US tuyaus.com · CN tuyacn.com · IN INLINECODE12

Enable IoT Core service in your Tuya IoT Platform project, and grant devices controllable permission (read-only by default).

Tools

tuya_list_devices

List all Tuya devices linked to the cloud project.

CODEBLOCK1

tuya_read_sensor

Read all sensor data from a Tuya device (temperature, humidity, battery, motion, door state, switch state).

CODEBLOCK2

INLINECODE15 interprets raw API keys:

Sensor	Raw keys	Notes
Temperature	INLINECODE16, temp_current, INLINECODE18	Divided by 10 (e.g. 245 → 24.5°C)
Humidity

va_humidity, humidity_value | Percentage as-is |
| Battery | battery_percentage, battery | Good >80% / Medium >20% / Low ≤20% |
| Motion | pir | "pir" value = detected |
| Door | doorcontact_state | Boolean → Open/Closed |
| State | state | Boolean → On/Off |
| Soil moisture | soil_moisture, humidity, va_humidity | Percentage as-is |

tuya_control_device

Send commands to a Tuya device (switch, valve, countdown timer). Pass a JSON array of {"code", "value"} pairs. Uses the IoT Core /v1.0/iot-03/ endpoint, which supports Zigbee sub-devices.

CODEBLOCK3

⚠️ countdown_1 / countdown_2 are in minutes. 10 = 10 min, 60 = 1 hour.

Dual-channel valve devices

Some valve devices expose two independent channels (e.g. left and right outlet). Each channel has its own switch and countdown DP:

Channel	Switch DP	Countdown DP
Left	INLINECODE37	INLINECODE38
Right

switch_2 | countdown_2 |

Control each channel independently:

CODEBLOCK4

To register a dual-channel valve in config.py, add both channels as separate entries or use a list:

CODEBLOCK5

Local LAN Tools

Control devices directly over the local network without cloud API calls. No credentials needed for scanning; local_key and ip required for read/control.

scan_local

Scan the local network for Tuya devices via UDP broadcast.

CODEBLOCK6

read_local

Read device status directly over LAN (no cloud round-trip).

CODEBLOCK7

control_local

Send commands to a device directly over LAN. Commands can use integer DP index (dp) or string DP name (code).

CODEBLOCK8

Use integer dp for maximum compatibility. String code requires the device to support it.

API Endpoints (internal)

• - Device list: INLINECODE51
• Device info: INLINECODE52
• Device status: INLINECODE53
• Send commands: INLINECODE54

Dependencies

CODEBLOCK9

Troubleshooting

Error	Fix
"Data center is not enabled"	Enable IoT Core in Tuya IoT Platform → Service API
"Permission denied"

Subscribe to IoT Core and enable Device Status Notification | | Device offline | online: false; soil moisture returns null | | Wrong endpoint | Match TUYA_API_ENDPOINT to your account region | | Local scan finds nothing | Check firewall; UDP broadcast may be blocked on some networks | | Local control fails for Zigbee devices | Zigbee sub-devices must be controlled via their gateway (use gateway ID + cid) |