Skip to main content

TCL Home smart home integration, free and open source

TCL Home integration for Gladys Assistant

Control your TCL air conditioners, dehumidifiers and purifiers through the TCL Home cloud.

This integration connects Gladys to your TCL Home account and drives the TCL appliances added to it: air conditioners, dehumidifiers and Breeva air purifiers.

Before you begin​

  • Gladys 5.3 or newer is required.
  • Your appliances must work in the TCL Home mobile app first: add them there, Gladys does not pair them.
  • This is a cloud integration: Gladys goes through the TCL Home cloud, like the app. Gladys needs Internet access, and nothing works while the TCL cloud is down. TCL appliances offer no local control.

TCL publishes no official API: this integration does what the TCL Home app does. TCL may change it at any time. It is not affiliated with TCL.

Configuration​

In Gladys, open Integrations → TCL Home → Configuration:

FieldWhat to enter
TCL Home e-mailThe e-mail you sign in to the TCL Home app with
TCL Home passwordThe password of that account
Refresh interval (s)How often each device is read, in seconds (60 to 3600, 60 by default)

Save, then press Test the connection: it lists the devices found, how many are online, and the TCL devices this integration does not drive (a TV, for example).

Then open the Discover tab of the integration and add your devices.

Tip: create a second TCL Home account, share your home with it from the app, and give that one to Gladys. Your own password then stays yours.

Devices and features​

A feature only appears when your unit reports it: a model without horizontal swing gets no horizontal swing control.

Air conditioners​

Split, window, portable, duct, cylindrical and fresh air units.

FeatureIn Gladys
PowerOn / off
ModeAuto, cool, dry, fan, heat (only the modes your unit has)
Target temperature16 to 31 °C, whole degrees
Fan speedAuto, quiet, low, medium-low, medium, medium-high, high, turbo
Vertical / horizontal swingOff, swing, or one of 5 fixed positions
Indoor temperatureMeasured by the unit
Outdoor unit temperatureWhen the unit reports it
Eco, sleep, health, anti-mold drying, display, beepOn / off switches

On a portable unit, the auto mode and the fan speed only exist on the models with a swing flap.

Dehumidifiers​

Power and room humidity.

Breeva air purifiers​

Power, PM2.5, display and child lock.

Refresh​

Gladys reads each device at the interval you chose. After an order, the integration reads the device again a few seconds later, so Gladys shows what the device really did.

A device that is offline shows an unreachable badge; online, a cloud badge.

Scenes​

Triggers​

TriggerWhenVariable
TCL device online / offlineA device loses or finds its connectionstatus: online or offline
TCL device errorA device starts reporting an error codecode: the code(s), comma-separated

Both can be limited to one device. They fire on a change: a device already offline, or an error already present when Gladys starts, does not fire them.

Actions​

ActionWhat it doesOutput
Set a TCL air conditionerTurns the unit on, with the mode, temperature and fan speed you chose (empty: unchanged)applied (true/false)
Turn off all TCL devicesTurns off every TCL device that is oncount
Start TCL self-cleaningStarts the self-cleaning cycle of the unit (it stops the unit), when the model has onestarted (true/false)

An offline unit does not stop the scene: the output is false, use it in a condition if needed.

Example: "When I leave home, turn off all TCL devices", or "At 6 pm in summer, set the living room unit to cool at 24 °C".

Dashboard widget​

Add the TCL Home widget to a dashboard. It shows:

  • the state of the TCL Home account, then each device: off, offline, or its mode and target temperature;
  • the live indoor temperature of the first air conditioners;
  • the buttons Set an air conditioner (unit, mode, temperature, fan), Turn everything off and Refresh.

Troubleshooting​

Message or symptomWhat to do
"TCL Home refused the e-mail or the password"Check them by signing in to the TCL Home app. An account created with Google or Apple has no password: set one in the app, or use a second account.
"TCL Home cannot be reached"Check Gladys' Internet access. The integration retries by itself every 5 minutes.
A device is missingIs it in the TCL Home app, on the same account? "Test the connection" lists the unsupported ones.
An order fails with "is offline"The device is not connected to the TCL cloud: check its Wi-Fi in the TCL Home app.
The state changes lateThe cloud is read at the refresh interval: lower it (60 s minimum).

Set the log level to debug (LOG_LEVEL environment variable) to see every call. Passwords and tokens are never written to the logs.

Privacy​

  • The password is stored by Gladys in a secret field and sent to TCL only, as an MD5 hash, like the app does.
  • The TCL tokens and the temporary AWS credentials stay in memory, nothing is written to disk.
  • The integration talks only to TCL (*.tcl.com, *.tcljd.com) and Amazon Web Services (*.amazonaws.com), over HTTPS.

Configuration settings​

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

SettingTypeRequiredDescription
Getting startedsectionNoThis integration goes through the TCL Home cloud, like the mobile app: your devices must first be added in the TCL Home app. Enter the e-mail and password of that account below. Gladys then reads the devices every minute (or at the interval you choose) and sends your orders through the cloud: an Internet connection is required.
TCL Home e-mailstringYesThe e-mail you sign in to the TCL Home app with.
TCL Home passwordsecretYesThe password of that account. It is only sent to TCL, never logged.
Refresh interval (s)numberNoHow often each device is read from the cloud, in seconds (60 to 3600).

How to install TCL Home in Gladys​

  1. In Gladys, open Integrations: TCL Home appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/prohand/gladys-tclhome:0.0.1), 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/prohand/gladys-tclhome.

TCL Home requires Gladys >=5.3.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​

TCL Home 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 prohand, 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 🙂