Skip to content

README.md

Latest commit

 

History

History
147 lines (106 loc) · 5 KB

README.md

File metadata and controls

147 lines (106 loc) · 5 KB
Raw

homebridge-broadlink-cloud-ac

Control your Broadlink AC unit through Homebridge.

Support This Project

If you find this plugin helpful, consider supporting its development:

Donate

Changelog

See CHANGELOG.md for release notes.

Features

  • Auto-discovery: Automatically finds and adds all AUX AC units in your account
  • Cloud-based control: Works with any AUX AC unit that's connected to the AUX Cloud service
  • Real-time updates: A supervised websocket connection to the AUX/BroadLink relay delivers device state pushes and carries commands for near-instant control, with automatic HTTP fallback
  • Full HomeKit integration: Control power, temperature, mode, fan speed, and swing
  • Device management: Hide specific devices using device IDs or friendly names
  • Automatic reconnection: Handles session expiry and network issues

Requirements

  • Node.js 18.0.0 or later
  • Homebridge 1.6.0 or later
  • An AUX AC unit connected to the AUX Cloud service
  • AUX Cloud account (AC Freedom app account)

Installation

npm install -g homebridge-broadlink-cloud-ac

Or install through the Homebridge UI.

Configuration

Platform Configuration (Auto-Discovery)

Recommended: Use the platform configuration to automatically discover all your AUX Cloud devices:

{
    "platform": "AuxCloudPlatform",
    "name": "AUX Cloud",
    "email": "your@email.com",
    "password": "your_password",
    "region": "eu"
}

Finding Your Device ID

The package ships a discovery helper that lists every device in your account with its endpoint ID:

# from a source checkout
node discover-devices.js your@email.com your_password eu

# or from an installed plugin directory
node node_modules/homebridge-broadlink-cloud-ac/discover-devices.js your@email.com your_password eu

You can also read the endpoint IDs from the Homebridge startup logs, where every discovered device is logged with its name and endpoint ID.

Platform Configuration Options

Option Type Required Default Description
name string Yes "AUX Cloud" Name for the platform
email string Yes - Your AUX Cloud account email
password string Yes - Your AUX Cloud account password
region string No "eu" Your AUX Cloud region ("eu", "usa", or "cn")
hiddenDevices string[] No [] List of device IDs to hide from HomeKit
discoveryInterval number No 0 Re-discovery interval in minutes (0 = disabled)

All devices in the account are discovered automatically; there is no autoDiscover toggle. Manual per-accessory configuration ("accessory": "AirCondionerAccessory") is not supported — this plugin registers a platform only.

Hiding Devices

With the platform configuration, you can hide specific devices from HomeKit by adding their device IDs to the hiddenDevices array:

{
    "platform": "AuxCloudPlatform",
    "name": "AUX Cloud",
    "email": "your@email.com",
    "password": "your_password",
    "region": "eu",
    "hiddenDevices": [
        "device_endpoint_id_1",
        "Bedroom AC",
        "device_endpoint_id_3"
    ]
}

You can use either:

  • Device endpoint ID: The unique identifier (e.g., "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p")
  • Friendly name: The device name as shown in the AC Freedom app (e.g., "Bedroom AC")

Region Selection

  • eu: Europe - https://app-service-deu-f0e9ebbb.smarthomecs.de
  • usa: United States - https://app-service-usa-fd7cc04c.smarthomecs.com
  • cn: China - https://app-service-chn-31a93883.ibroadlink.com

Supported Features

Main Controls

  • Power: On/Off control
  • Mode: Auto, Cool, Heat
  • Temperature: 16-32°C
  • Fan Speed: HomeKit's native AC Fan speed control
  • Swing: HomeKit's native fan oscilation control

Troubleshooting

Login Issues

  • Ensure your email and password are correct
  • Make sure you're using the correct region
  • Try logging out and back in to the AC Freedom app

Connection Issues

  • The plugin will automatically attempt to reconnect on errors
  • Check your internet connection
  • Verify the AUX Cloud service is accessible

Real-time Updates

On startup the plugin opens a single websocket connection to the AUX/BroadLink relay:

  • Device state changes are pushed to HomeKit as they happen instead of waiting for the next poll.
  • Commands are sent over the websocket for faster response.
  • If the websocket is unavailable or a command is rejected, the plugin automatically falls back to the HTTP API and polls every 10 seconds until the relay is healthy again.
  • While the websocket is connected, a full HTTP refresh still runs every 10 minutes as a safety net.

Websocket messages are logged at the debug level, and connection state changes are logged at the info/warn level, so you can follow the relay health in the Homebridge logs.