Skip to main content

Tuya integration for Gladys Assistant

Tuya integration for Gladys Assistant

Tuya / Smart Life sockets, meters, ACs and pilot-wire heaters, cloud + optional local control.

View on GitHubAll external 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.
  • Pilot-wire (fil pilote) thermostats (RP5 family, Konyks eCosy): heating mode, target temperature, ambient temperature, child lock, energy.
  • Switches, lights and covers through the generic mappings.

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).

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 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…). You can add them by hand:

  1. Open the Configuration screen → Detect local protocol (manual IP) action.
  2. Enter the device (its Gladys name or its Tuya ID) and 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.

Useful actions​

  • Detect local protocol (manual IP): enable local mode for a device the scan did not find (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.

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.11.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 >=4.62.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