nemesa
nemesa
ha-tcl-home-unofficial-integration
Python

TCL Home - home assistant integration (unofficial)

Last updated Jul 4, 2026
92
Stars
18
Forks
25
Issues
0
Stars/day
Attention Score
36
View on GitHub ↗ Open in github.dev
Topics
#custom-component#home-assistant#homeassistant#python#tcl-home#unofficial
Language breakdown
Python 100.0%
▸ Files click to expand
README

ha-tcl-home-unofficial-integration

TCL Home - Home Assistant integration (unofficial)

Supported device types

  • Split AC
  • Split AC Fresh air
  • Portable AC
  • Window AC
  • Duct AC
  • Dehumidifier (DEM)
  • Dehumidifier (DF)
  • Breeva Air Purifier A2 (by Ajsalemo)
  • Breeva Air Purifier A3 (by Ajsalemo)
  • Breeva Air Purifier A5 (by Ajsalemo)
  • Cylindrical AC (by joe-sal)

Notes by device types

Portable AC

No ad-hoc temperature type change between Celsius and Fahrenheit; it will use the System-defined temperature type.

Unsupported device types

Devices not recognized by the integration will be create as a remote. The device type will be shown, under The Device Info in this sample it's "Smart TV" Use this type when requesting support for it

Not Implemented Sample

Credit

The idea for basic login is from DavidIlie’s project. The Home Assistant integration samples helped a lot.

Discord invite link

For direct messages or for collaboration with missing device types https://discord.gg/8AcrRmNfVj

How it works

This integration is the result of reverse-engineering the “TCL Home” Android app. For setup, we only need the username/password used for the app. Since this is not an official integration from TCL, I recommend creating a new user for this integration and sharing your devices with that user—just in case TCL decides to ban the account.

How to install

HACS

This integration is now awaliable in HACS, just search for "TCL Home"

HACS

Update from Manual to HACS

If you already had a manual installation by hand and now you want to use HACS, just simply download the integration with HACS; it will overwrite the manual installation. Then restart Home Assistant.

Manual instalion

Steps:

  • Download the ZIP from GitHub and extract ha-tcl-home-unofficial-integration-main.zip.
git download
  • At HomeAssistant Host, create a folder named custom_components next to your configuration.yaml (if you don't already have one).
  • Inside customcomponents, create a folder named tclhome_unofficial.
  • Copy all files from the ZIP’s /ha-tcl-home-unofficial-integration-main/customcomponents/tclhomeunofficial/ folder into your new customcomponents/tclhomeunofficial folder. Should look like this:
files in HA Note the translations folder with the en.json, you have to copy that foler and file too.
  • Restart Home Assistant.
  • In the Home Assitant go to Settings → Devices & Services → + Add Integration, then search for “TCL Home” and follow the setup steps.

Optionally, you can install the File Editor add-on to create the folders and upload files or to edit configuration.yaml Install it at: Home Assitant Settings → Add-ons, then search for “File editor.”

Logs

For info logs extend the configuration.yaml with 
logger:
      logs:
        customcomponents.tclhome_unofficial: info
Logs can be found in Home Assistant at Settings->System->Logs menu: then "Show full logs" in the "..." menu

Then the integration related logs will start with [customcomponents.tclhome_unofficial...

Diagnosics files

Config diagnostic

In Home Assistant go to Settings -> "Devices & services" -> on the Integrations tab find the "TCL Home - Unofficial" integartion In the "..." menu select the "Download diagnostics"

Device diagnostic

Same path as for the "Config diagnostic" select the device, then user the "DOWNLOAD DIAGNOSTICS" link

Power and work hours data

The integration will assume all devices have this data available. In the init phase, it will try to get this data, and if it fails, it won't try again ever. To force the integration to re-setup at the next reload, we can use these functions under the "Diagnostic" section:
  • "Try get Power Consumption Data" button
  • "Try get Work Time Data" button
Both are disabled by default. Just enable the buttons, and press them if you think your device has power or work hours data and they don't show up under the "Sensors" section.

Sensors

  • Today Energy Consumption
  • Yesterday Energy Consumption
  • Today Work Time
  • Yesterday Work Time
All sensors will be updated once every hour, as we don't know how the TCL APIs scale to serve this data. In the "TCL Home" app, we can only access this data on demand, and it is not auto-refreshed. Because of this, the value may not be refreshed before the counter resets back to 0, so we don't recommend using the "Today Energy Consumption" in the "Energy" module in HA. The "Yesterday Energy Consumption" should be more suitable for this, as it only changes once a day and will always show the correct value.

However, the "Sync with TCL Home" button in the "Diagnostics" section does refresh it and resets the 1-hour countdown for the next refresh. So if needed, one can manually sync the counter reset with the poll interval, and should get a good enough "Today Energy Consumption" value if needed. The integration doesn't do this automatically as it involves time zones, and it could be a different time by device. (Happy to review any code contributions to make this part nicer)

Functions map

SELECT_MODE

SELECT_MODE | Home Assistan | TCL app | Alternative (for different device type) | | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | | ||

MODEACAUTO

MODEACCOOL

MODEACDEHUMIDIFICATION

MODEACFAN

MODEACHEAT

SWITCH_POWER

SWITCH_POWER - Powers on or powers off the device

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | Off | | || | On | | ||

SELECTWINDSPEED

SELECTWINDSPEED -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | | | || | AUTO | | ||

SWITCH_BEEP

SWITCH_BEEP -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | Off | | || | On | | ||

SWITCH_ECO

SWITCH_ECO -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | Off | | || | On | | ||

SWITCHAIECO

SWITCHAIECO -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | | | ||

SWITCH_HEALTHY

SWITCH_HEALTHY -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | Off | | || | On | | ||

SWITCH_DRYING

SWITCH_DRYING -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | Off | | (in "... More") | (in Settings) | | On | | ||

SWITCH_SCREEN

SWITCH_SCREEN -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | Off | | || | On | | ||

SWITCHLIGHTSENSE

SWITCHLIGHTSENSE -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | Off | TODO:add pic | (in Settings) || | On | TODO:add pic |TODO:add pic ||

SWITCHSWINGWIND

SWITCHSWINGWIND -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | On | TODO:add pic |TODO:add pic || | Off | TODO:add pic |TODO:add pic ||

SWITCH_SLEEP

SWITCH_SLEEP -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | On | TODO:add pic |TODO:add pic || | Off | TODO:add pic |TODO:add pic ||

SWITCH8C_HEATING

SWITCH8C_HEATING -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | Off | | || | On | | ||

SWITCHSOFTWIND

SWITCHSOFTWIND -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | On | TODO:add pic |TODO:add pic || | Off | TODO:add pic |TODO:add pic ||

SWITCHFRESHAIR

SWITCHFRESHAIR -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | On | TODO:add pic |TODO:add pic || | Off | TODO:add pic |TODO:add pic ||

SELECTWINDSPEED7GEAR

SELECTWINDSPEED7GEAR -

| Home Assistan | TCL app | Alternative (for different device type) | | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

SELECTWINDOWASWINDSPEED

SELECTWINDOWASWINDSPEED -

| Home Assistan | TCL app | Alternative (for different device type) | | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

SELECTWINDFEELING

SELECTWINDFEELING -

| Home Assistan | TCL app | Alternative (for different device type) | | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

SELECTVERTICALDIRECTION

SELECTVERTICALDIRECTION -

| Home Assistan | TCL app | Alternative (for different device type) | | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | | ||

SELECTHORIZONTALDIRECTION

SELECTHORIZONTALDIRECTION -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | | ||

SELECTSLEEPMODE

SELECTSLEEPMODE -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | | ||

SELECTFRESHAIR

SELECTFRESHAIR -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

SELECTGENERATORMODE

SELECTGENERATORMODE -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

SELECTTEMPERATURETYPE

SELECTTEMPERATURETYPE - not enabled to any devices as integrations is using °C and the Home Assistant will convert the user's System Temperature Unit.

SELECTPORTABLEWIND_SPEED

SELECTPORTABLEWIND_SPEED -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

SELECTPORTABLEWIND4VALUESPEED

SELECTPORTABLEWIND4VALUESPEED -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------- | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

BUTTONSELFCLEAN

BUTTONSELFCLEAN -

| Value | Home Assistan | TCL app | Alternative (for different device type) | | :------------------ | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | press to start | | || | press to stop | TODO:Fix text ("start" should be "stop") | ||

NUMBERTARGETTEMPERATURE

NUMBERTARGETTEMPERATURE - NUMBERTARGETDEGREE NUMBERTARGETTEMPERATUREALLOWHALF_DIGITS

| Home Assistan | TCL app | Alternative (for different device type) | | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

CLIMATE

CLIMATE

| Home Assistan | TCL app | Alternative (for different device type) | | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

SENSORCURRENTTEMPERATURE

SENSORCURRENTTEMPERATURE

| Home Assistan | TCL app | Alternative (for different device type) | | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

SENSORINTERNALUNITCOILTEMPERATURE

SENSORINTERNALUNITCOILTEMPERATURE

| Home Assistan | TCL app | Alternative (for different device type) | | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

SENSOREXTERNALUNITCOILTEMPERATURE

SENSOREXTERNALUNITCOILTEMPERATURE

| Home Assistan | TCL app | Alternative (for different device type) | | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

SENSOREXTERNALUNIT_TEMPERATURE

SENSOREXTERNALUNIT_TEMPERATURE

| Home Assistan | TCL app | Alternative (for different device type) | | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

SENSOREXTERNALUNITEXHAUSTTEMPERATURE

SENSOREXTERNALUNITEXHAUSTTEMPERATURE

| Home Assistan | TCL app | Alternative (for different device type) | | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

USERCONFIGBEHAVIORMEMORIZETEMPBYMODE

USERCONFIGBEHAVIORMEMORIZETEMPBYMODE

| Home Assistan | TCL app | Alternative (for different device type) | | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

USERCONFIGBEHAVIORMEMORIZEFANSPEEDBY_MODE

USERCONFIGBEHAVIORMEMORIZEFANSPEEDBY_MODE

| Home Assistan | TCL app | Alternative (for different device type) | | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

USERCONFIGBEHAVIORSILENTBEEPWHENTURN_ON

USERCONFIGBEHAVIORSILENTBEEPWHENTURN_ON

| Home Assistan | TCL app | Alternative (for different device type) | | :------------------------------------------------------------: | :-------------------------------------------------------------: |:-:| | TODO:add pic |TODO:add pic ||

How the integration looks

Climate contoll implementaion:

Climate controll

Dashboard example: Dashboard example

🔗 More in this category
public-apis
public-apis/public-apis
A collective list of free APIs
★ 447.8k
 EbookFoundation
EbookFoundation/free-programming-books
:books: Freely available programming books
★ 391.5k
 vinta
vinta/awesome-python
An opinionated list of Python frameworks, libraries, tools, and resources
★ 307.0k
 tensorflow
tensorflow/tensorflow
An Open Source Machine Learning Framework for Everyone
★ 196.3k
 donnemartin
donnemartin/system-design-primer
Learn how to design large-scale systems. Prep for the system design interview. Includes Anki flashcards.
★ 356.6k
 TheAlgorithms
TheAlgorithms/Python
All Algorithms implemented in Python
★ 222.5k
 NousResearch
NousResearch/hermes-agent
The agent that grows with you
★ 212.6k
 Significant-Gravitas
Significant-Gravitas/AutoGPT
AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.
★ 185.4k
 huggingface
huggingface/transformers
🤗 Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.
★ 162.4k
 yt-dlp
yt-dlp/yt-dlp
A feature-rich command-line audio/video downloader
★ 176.2k
 langgenius
langgenius/dify
Production-ready platform for agentic workflow development.
★ 148.4k
 anthropics
anthropics/skills
Public repository for Agent Skills
★ 159.3k

© 2026 GitRepoTrend · nemesa/ha-tcl-home-unofficial-integration · Updated daily from GitHub