Skip to main content

Tuya smart home integration, free and open source

Tuya integration for Gladys Assistant

Tuya / Smart Life sockets, meters, ACs, heaters, cameras, doorbells, feeders, vacuums (cloud + LAN).

View on GitHubAll integrations

Control your Tuya / Smart Life devices from Gladys, over the cloud and, when possible, directly over your local network (LAN) for a faster, internet-independent experience.

Supported devices​

  • Smart plugs and sockets (including the LSC Power Plug FR with energy metering): on/off, child lock, power, voltage, current, energy.
  • Energy meters (including 3-phase): power, voltage, current, imported/exported energy.
  • Air conditioners: on/off, mode (auto / cool / heat / dry / fan), target temperature, ambient temperature, fan speed and both swing axes. Models with their own vocabulary are handled too (e.g. the MEDION P502 camping AC: uppercase modes, two-speed fan, swing on/off).
  • Pilot-wire (fil pilote) thermostats (RP5 family, Konyks eCosy): heating mode, target temperature, ambient temperature, child lock, energy.
  • Cameras (including LSC): privacy mode, motion detection, siren, motion tracking, human filter, recording, image flip, and a motion sensor usable in your scenes. PTZ cameras: pan/tilt from the dashboard (Gladys 4.86.1 or later). Settings as lists: night vision, motion and sound sensitivity, sound detection, recording mode, anti-flicker, timestamp overlay. Live snapshot: the camera image is a frame of the live stream, refreshed every 5 minutes and on demand (dashboard, "show me the camera", scenes); it needs the IoT Video Live Stream API service on your Tuya cloud project, otherwise the image only updates on a motion / ring event. Live video (WebRTC): with a Gladys that supports it (GladysAssistant/Gladys#3215), the Play button of the camera box opens the live video, straight from the Tuya cloud to your browser (H264 cameras; HEVC-only models are not playable in a browser).
  • Video doorbells: ring (a dedicated doorbell feature), snapshot of the visitor, motion detection, recording, status LED.
  • Pet feeders: feed on demand, last amount fed, slow feed, light, battery (percentage or raw voltage plus the low-battery flag, depending on the model), scheduled meals.
  • Fans and ventilation units (category fs, e.g. the AV-TTW5-W heat-recovery unit): on/off, speed (the device's own levels, e.g. 1 to 3), light, child lock, airflow direction, horizontal/vertical swing, ambient temperature when the device measures one.
  • Dehumidifiers (category cs, e.g. Qlima D825A): on/off, current humidity, temperature, fan speed, timer and time left, mode, target humidity (when offered as steps), child lock. Speeds, timer durations and modes list exactly the values your model declares.
  • Temperature & humidity sensors (category wsdcg, e.g. Konyks Termo): temperature, humidity, low-battery flag (and battery percentage on the models that measure one). Battery devices sleep between two reports: they are served by the cloud, not the LAN.
  • Water purifiers / reverse-osmosis units (category js, e.g. The Box): inlet and outlet TDS (ppm), remaining life of each filter stage (PP, CTO, RO) in percent and in days, working status. The "filter replaced" resets stay in the Tuya app (a misclick would wipe the filter's real wear).
  • Water valves / irrigation controllers (category sfkzq, e.g. R2601): open/close, valve state (water flowing or not), instant water flow, battery, child lock, watering mode (auto/manual), manual watering duration. Battery devices: served by the cloud. The watering programs stay in the Tuya app.
  • Three-phase meters / power clamps (category zndb, e.g. Power Clamp): power, current, voltage and consumed energy of each phase, total power, current and energy, internal temperature of the clamp. Cloud or local.
  • Motion sensors (category pir, e.g. Zigbee "Luminance Motion sensor" behind a Tuya gateway): motion (usable in scenes), illuminance, battery, motion sensitivity and hold time as lists. Served by the cloud (Zigbee sub-devices are reached through their gateway). The Zigbee gateway itself has nothing to control: it stays without features.
  • Robot vacuums (Honiture Q6 Pro): start/stop, pause, dock, cleaning state, battery, suction power, water level, carpet boost, custom (room) mode, Y-mop wash, dust-collection frequency, main/side brush remaining life. Note: on this product, turning Pause OFF while the robot is fully stopped also starts a new cleaning cycle — it is not purely a pause toggle.
  • Switches, lights and covers through the generic mappings.

Cameras and doorbells expose their snapshots, not a live video stream: Tuya publishes no stable local RTSP/ONVIF endpoint.

The doorbell ring and the air-conditioner fan speed / swings need Gladys 4.84.2 or later. The vacuum's suction power / water level / dust-collection frequency need Gladys 4.86.1 or later. On an older Gladys the integration keeps working, without those features.

New installs from the store require Gladys 4.86.1 or later; an integration already installed keeps updating on any Gladys version.

Every device shows a Local or Cloud badge so you always know how it communicates.

1. Create a Tuya IoT Cloud project​

The integration needs a (free) Tuya IoT Cloud project to reach your devices.

  1. Go to the Tuya IoT Platform and sign in (create an account if needed).
  2. Open Cloud → Development and click Create Cloud Project.
    • Give it any name.
    • Industry / Development method: keep the defaults (Smart Home).
    • Data Center: pick the region closest to you (e.g. Central Europe for France). Remember this choice — you will select the same region in Gladys.
  3. Once created, open the project. On the Overview tab, note the Access ID / Client ID and the Access Secret / Client Secret.
  4. Open the Service API tab and make sure IoT Core is authorized (subscribe to it if not — it is free). Cameras: also authorize IoT Video Live Stream (live snapshots).

⚠️ The IoT Core trial expires. Tuya grants this service as a free trial (one month, then renewable for six more months at no cost). Once it lapses, Tuya rejects every API call of your project and all your devices go offline in Gladys, with the message "IoT Core service subscription has expired".

To renew it: Cloud → Development → your project → Service API (or Cloud → Cloud Services → IoT Core), then Extend Trial Period. It is free and takes effect immediately. Set yourself a reminder — it has to be renewed every six months.

2. Link your Smart Life / Tuya app account​

Your devices must belong to a Tuya app account that the project can see.

  1. In the project, open Devices → Link Tuya App Account → Add App Account.
  2. Scan the QR code with your Smart Life or Tuya Smart phone app (Me → top-right scan icon).
  3. Back on the platform, open Devices → Link Tuya App Account: your devices now appear.
  4. Note your App account UID (shown next to the linked account).

3. Fill in the configuration in Gladys​

In the integration configuration screen, fill in:

FieldWhere to find it
EndpointThe Data Center region you chose in step 1
Client IDProject Overview → Access ID / Client ID
Client SecretProject Overview → Access Secret / Client Secret
App account UIDDevices → Link Tuya App Account → the linked account UID

Save. The Connection status at the bottom of the screen should turn to Connected. If it shows an error, the message tells you what to fix (wrong credentials, wrong region…).

4. Discover your devices​

Open the Discover tab and let Gladys list your Tuya devices, then create the ones you want. Each device appears with its features and a Local/Cloud badge.

Local mode (LAN)​

Local control is faster and keeps working without internet. It is enabled by the "Prefer the local connection" toggle (on by default).

  • When on, Gladys tries to reach each device on your network; if it can, the device shows a Local badge and its state updates instantly. If it cannot, the device automatically falls back to the Cloud.
  • Local control needs Gladys to know each device's IP address and protocol. Most devices are found automatically by the network scan during discovery.
  • A device that could run locally (its IP is known and the preference is on) but is currently running over the cloud keeps a Cloud badge with an orange dot — hover it to see why (device parked after failures, LAN info incomplete…). A genuine cloud-only device stays a plain blue Cloud badge.
  • A local device is read every 10 s over the LAN; what it can only report through the cloud (features without a local mapping, or everything while the LAN fails) is refreshed every 30 s at most, to spare the Tuya cloud quota.

A device stays on Cloud even though it is on your LAN​

Some devices are not found by the automatic scan (different subnet, asleep during the scan…). While a created device that can run locally still has no IP, the integration retries a LAN scan on its own every 15 minutes and switches it to local as soon as it answers — a device that was only asleep needs nothing more. For a device on another subnet (never reachable by the scan), add it by hand:

  1. Open the Configuration screen → Detect local protocol (manual IP) action.
  2. Pick the device in the list (or, if it is not created in Gladys yet, type its name or Tuya ID) and enter its IP address.
  3. Run it. On success, the device switches to local on the next cycle.

Tip: give your Tuya devices a fixed IP (DHCP reservation) on your router so they stay reachable.

Real-time cloud events (Pulsar) — optional​

For devices used over the cloud, Gladys can receive their state changes instantly (in ~1–2 s) instead of waiting for the next poll. This uses the Tuya Message Service (a.k.a. Pulsar). Devices already controlled locally already get instant feedback and do not need this.

Two steps to enable it:

  1. On the Tuya IoT Platform: open your project → Service API → subscribe to Message Service (free). Without it, the connection is refused and Gladys logs an explicit message.
  2. In Gladys: turn on the "Real-time cloud events (Pulsar)" toggle in the configuration, then save.

A device only reports through Pulsar what it actually sends to the Tuya cloud: some report their full state, some only a part (e.g. on/off), some nothing — those simply keep the regular cloud refresh. This is a device/firmware behaviour, not a limitation of Gladys.

Reporting an unsupported device​

A device created with no feature (or a single one) exposes Tuya codes the integration does not know yet — common across variants of the same model.

In the integration configuration, run the Device diagnostic action, pick the device in the list (or type its name or Tuya ID if it is not created in Gladys), and copy the result into a GitHub issue. The report lists every code the device reports, its value and what the integration does with it. It carries no local key, IP address nor Tuya device id: it can be pasted publicly as-is.

Feature names (language) — optional​

This integration's auto-generated feature names (e.g. "Dock", "Suction power") and option labels default to English, matching the convention of every device type it supports — a name actually read from the device itself (rare) is kept as-is regardless of this setting. The "Feature names" configuration option lets you switch newly discovered devices to French, German or Spanish instead, translated through a small built-in dictionary.

Feature names only change for newly discovered devices. Changing this option does not rename features already created in Gladys — rename them by hand there if you want, or delete and re-add the device from the Discover screen to pick up the new language. Option labels are the exception: on an existing device, the lists' labels (e.g. the vacuum's suction power) follow the new language at the next discovery, because Gladys re-syncs each device's options then. A feature name/label this integration does not yet have a translation for is kept in English either way, never guessed.

Dashboard widgets​

Gladys 5.1 or later: in a dashboard, Edit → Add a box → Integration widgets, the Tuya integration offers five widgets (choose the device in the widget settings):

  • Tuya camera: the live image of a camera (refreshed every minute while the dashboard is open), its privacy mode, motion detection and recording, the four PTZ arrows on a motorized camera (the image updates after the move), or a privacy toggle and a refresh button on a fixed one.
  • Tuya energy meter: for a three-phase meter, a smart meter or a socket measuring power — a power gauge (its maximum is a widget setting), the power of each phase in real time, current, energy, the power curve of the last 24 hours, the voltage and current of each phase.
  • Tuya devices: how many devices are online, local or on the cloud, the ones needing attention (offline, local unreachable), the cloud connection, local mode and real-time events, and a scan button.
  • Tuya robot vacuum: state, battery, brush wear, suction and water level, start / pause / dock buttons.
  • Tuya water purifier: the remaining life of each filter stage, inlet and outlet TDS, the days left (in orange under 15 days).

Useful actions​

  • Detect local protocol (manual IP): enable local mode for a device the scan did not find (see above).
  • Device diagnostic: builds the report of what a device exposes (see above).
  • Disconnect from the Tuya cloud: stops talking to the cloud until you save the configuration again.

Troubleshooting​

  • Connection shows an error → check the four credentials and that the Endpoint matches your project's Data Center.
  • A device has no state / no control → check its badge. On Cloud with nothing coming back, the device may be offline in the Tuya app.
  • Real-time cloud events do not start → make sure Message Service is subscribed on your Tuya project (a 401 in the logs means it is not).
  • Logs are available in the integration's Logs tab.

Configuration settings​

These are the settings Tuya asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Getting startedsectionNoThis integration talks to your devices through a Tuya IoT Cloud project. Create one (free) on the Tuya IoT Platform, subscribe the "IoT Core" service, link your Smart Life / Tuya app account, then copy the four values below. The full step-by-step is in the Documentation link above.
EndpointselectYesTuya data center region of your cloud project.
Client IDstringYesAccess ID / Client ID of your Tuya IoT cloud project.
Client SecretsecretYesAccess Secret / Client Secret of your Tuya IoT cloud project.
App account UIDstringYesUID of the Smart Life / Tuya app account linked to your cloud project.
Real-time cloud events (optional)sectionNoFor devices used over the cloud, Gladys can receive their state changes instantly instead of waiting for the next poll. This needs the "Message Service" subscribed on your Tuya IoT project, then the toggle below turned on. Devices already controlled locally already get instant feedback and do not need this.
Real-time cloud events (Pulsar)booleanNoInstant cloud state feedback via the Tuya Message Service. Requires 'Message Service' enabled on your Tuya IoT project.
Feature namesselectNoApplies to the names of newly discovered devices. This integration's feature names are auto-generated in English by default (repo-wide convention) — translate the ones this integration knows into French, German or Spanish, or keep English. On a device already created, option labels still follow the new language at the next discovery, but names do not. A feature not covered by the dictionary keeps its English name either way; you can always rename any feature afterwards in Gladys.

How to install Tuya in Gladys​

  1. In Gladys, open Integrations: Tuya appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/terdious/gladys-tuya:1.30.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/Terdious/gladys-tuya.

Tuya requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Tuya is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by Terdious, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on