Homebridge TCL Home

A rudimentary Homebridge plugin for TCL Home air conditioners that brings your AC units into Apple HomeKit with full bidirectional control and real-time synchronisation.

Supported Devices

Currently tested and working with:

TCL P09F4CSW1K Portable Air Conditioner
Maybe other TCL Home app connected A/Cs (may require configuration)

Features

🌡️ Smart Temperature Control (18-30°C) - automatically enabled/disabled based on mode
❄️ AC Cooling Mode - full air conditioning with temperature control
💨 Pure Fan Mode - fan-only operation without cooling or dehumidifying
😴 Sleep Mode Toggle - energy-efficient sleep operation
📱 Real-time HomeKit Integration - instant bidirectional sync
🏠 Full Siri Voice Control - "Set the AC to 22 degrees", "Turn on auto mode"
⚡ Ultra-fast Polling - 3-second updates detect manual device changes instantly
🎛️ Context-Aware Fan Control - separate speed memory for Cool vs Fan modes
🔄 Enhanced Change Detection - optimized sync prevents unnecessary updates
🛡️ Robust Error Handling - automatic credential refresh and connection recovery
🚫 Simplified Mode Mapping - dehumidify modes excluded for cleaner interface

Installation

Via Homebridge UI (Recommended)

Open Homebridge UI
Go to "Plugins" tab
Search for "homebridge-tcl-home"
Click "Install"
Configure with your TCL Home credentials

Via Command Line

npm install -g homebridge-tcl-home

Configuration Options

Option	Required	Default	Description
`username`	Yes	-	Your TCL Home app email address
`password`	Yes	-	Your TCL Home app password
`debugMode`	No	`false`	Enable detailed logging for troubleshooting
`appLoginUrl`	No	Auto-configured	TCL authentication endpoint
`cloudUrls`	No	Auto-configured	TCL cloud services endpoint
`appId`	No	Auto-configured	TCL application identifier

Example Configuration

{
  "platforms": [
    {
      "platform": "TclHome",
      "name": "TCL Home",
      "username": "your.email@example.com",
      "password": "your_tcl_password",
      "debugMode": false
    }
  ]
}

Setup Instructions

Download TCL Home app and create an account
Add your AC to the TCL Home app
Install this plugin in Homebridge
Configure with your TCL Home credentials
Restart Homebridge

Your AC should appear in the Home app automatically!

HomeKit Controls

Main Thermostat

Power: On/Off control
Mode Selection:
- Off: Device powered off
- Cool: Full AC cooling with temperature control (workMode 0)
- Auto: Pure fan mode - air circulation only (workMode 2)
Temperature: 18-30°C target (automatically enabled in Cool mode, disabled in Auto/Fan mode)

Additional Controls

Night Mode Switch: Night operation toggle
AC Fan Control: Intelligent fan speed management
- Cool Mode: Controls AC compressor fan speed during cooling
- Auto/Fan Mode: Controls pure fan speed for air circulation
- Speed Levels: Low (50% = 1), High (100% = F2)
- Context Memory: Remembers separate speed settings for each mode

Mode Mapping Details

HomeKit Mode	AC Function	Temperature Control	Use Case
Cool	AC Cooling (workMode 0)	✅ Enabled	Full air conditioning with cooling
Auto	Pure Fan (workMode 2)	❌ Disabled	Air circulation without cooling
Off	Power Off	❌ Disabled	Device shutdown

Note: Dehumidify modes are intentionally excluded for simplified operation.

Troubleshooting

Debug Mode

Enable debugMode: true in your configuration to see detailed logs including:

Real-time device state changes
Mode mapping decisions
AWS credential refresh attempts
Polling sync information

Common Issues

Authentication Problems

Authentication failed: Verify your TCL Home app email/password are correct
Credentials expired: Plugin automatically handles this - wait for re-authentication
AWS errors: Connection will auto-recover with built-in retry logic

Device Communication

Device not found: Ensure AC is connected and working in TCL Home app
Commands not responsive: Check if device is online in TCL Home app
Slow updates: Plugin polls every 3 seconds - manual changes appear quickly

Mode Issues

Wrong mode displayed: Plugin maps workMode 0→Cool, workMode 2→Auto/Fan
Temperature control missing: Only available in Cool mode (by design)
Fan speeds not working: Separate speeds for Cool vs Auto modes are remembered

Performance

High CPU usage: Disable debug mode if enabled for production use
Network issues: Plugin includes automatic credential refresh and error recovery

Credits

This plugin is inspired by and builds upon the excellent work done by nemesa in the ha-tcl-home-unofficial-integration project for Home Assistant.

Special thanks for the API documentation and authentication flow analysis.

Usage Examples

Siri Voice Commands

"Set the AC to 22 degrees" - Changes to Cool mode and sets temperature
"Turn on the fan" - Switches to Auto/Fan mode for air circulation
"Turn on sleep mode" - Enables energy-efficient sleep operation
"Set the AC fan to high" - Changes fan speed to 100% (F2)
"Turn off the air conditioner" - Powers off the device

Home App Controls

Temperature Control: Use the thermostat when in Cool mode
Mode Switching: Tap the mode button to switch between Cool/Auto/Off
Fan Speed: Use the separate fan accessory to control air circulation
Sleep Mode: Toggle the sleep switch for overnight operation

Contributing

Contributions are welcome! This plugin has been extensively tested and improved for reliability.

Development Setup

Fork this repository
Install dependencies: npm install
Make your improvements
Test with your TCL devices

Adding Device Support

If you have a different TCL model:

Enable debug mode to see device capabilities
Check the workMode mappings for your device
Adjust mode constants if needed
Test all functionality thoroughly

Mode Mapping Reference

// HomeKit → TCL Device
Cool Mode → workMode: 0 (AC cooling with compressor)
Auto Mode → workMode: 2 (Pure fan, no cooling)
Off Mode → powerSwitch: 0

// Excluded: workMode 1 & 3 (dehumidify modes)

License

MIT License - see LICENSE file for details.

Disclaimer

This plugin is not affiliated with TCL. Use at your own risk.

Package detail