Tuya
IoT platform behind many white-label Wi-Fi and Zigbee smart devices, controlled through the Smart Life / Tuya Smart apps and the Tuya cloud.
platform
also known as Smart Life, Tuya Smart, Tuya IoT Platform
Knowledge about Tuya
- Control a Tuya plug locally from Python with TinyTuyacode · unverified · Read status and switch a Tuya Wi-Fi outlet over the LAN with TinyTuya, using the device ID, IP, local key and protocol version. Close the Smart Life app first: devices accept only one local TCP connection.
- Get the device ID and local key of your own Tuya devicesprocedure · unverified · Local control needs each device's ID, IP address, local key and protocol version. The TinyTuya wizard fetches IDs and keys from your own account through a Tuya IoT cloud project linked to your Smart Life app. Keys change whenever a device is re-paired.
- LocalTuya can stop loading after a Home Assistant update: check its issue tracker before updatingwarning · unverified · LocalTuya is a custom integration and has repeatedly broken on Home Assistant releases (e.g. 2025.1, 2025.5, 2025.12, 2026.3). Fixes often land in the repository before a release. Back up before updating and check the tracker first.
- Replacing Tuya firmware: check the chip first. tuya-convert only fits old ESP-based deviceswarning · unverified · tuya-convert only flashes ESP82xx-based devices and newer firmware is patched. Many current Tuya devices use Beken BK7231 or Realtek chips: use tuya-cloudcutter (unpatched firmware only), OpenBeken, or ESPHome via LibreTiny, often via serial flashing. Never open or flash a device while it is connected to mains power.
- Tuya Zigbee devices in Zigbee2MQTT and ZHA: the _TZE fingerprint and the Tuya clusterguide · unverified · Many Tuya Zigbee devices send data over a custom manuSpecificTuya cluster using data points instead of standard Zigbee clusters. Zigbee2MQTT matches them by model ID plus manufacturer name (e.g. _TZE200_...); ZHA uses quirks built with TuyaQuirkBuilder.
- Tuya Zigbee devices: same model ID, different datapointswarning · unverified · Many Tuya Zigbee devices use the manufacturer-specific manuSpecificTuya cluster with Tuya datapoints (DPs) instead of standard Zigbee clusters, and share model IDs across different hardware. Support is per manufacturerName (e.g. _TZE200_...).
- Tuya data points (DPS/DP IDs): what the numbers mean and how to map themguide · unverified · Tuya devices expose their state as numbered data points. Types include Boolean, Integer, Enum, String and JSON in Tuya's standard instruction set, and the meaning of each number differs per device, so you map them by observation.
- Tuya devices: cloud, local control or new firmware? The three pathsguide · unverified · Many cheap Wi-Fi and Zigbee smart devices run on Tuya. You can use them through the Tuya cloud, control them locally with the device's local key, or replace the firmware. Each path trades convenience against independence.
- Tuya in Home Assistant: official integration vs Tuya Local vs LocalTuyacomparison · unverified · The official Tuya integration is cloud push with QR login via the Smart Life app. Tuya Local and LocalTuya control devices over the LAN with local keys; Tuya Local supports protocol 3.5 and ships device definitions, LocalTuya covers protocols 3.1 to 3.4.
- Tuya local control stopped working: a troubleshooting checklistprocedure · unverified · When a Tuya device stops responding to local control, check the usual causes in order: another client holding the single connection, a local key changed by re-pairing, the wrong protocol version, a changed IP address.
- Tuya protocol 3.4 device worked for days, now 'Check device key or version' (914): power-cycle it before re-fetching keyswarning · unverified · A protocol 3.4 device that worked and then fails with error 914 does not necessarily have a new local key. Tuya Local's maintainer describes devices getting stuck after repeated connection errors until they are power-cycled.
Related
- depends on (from): TinyTuya – Uses the Tuya local protocol; the Tuya cloud API is only needed to fetch local keys.