homebridge-actron-neo

Control your ActronAir Neo system with Apple HomeKit using Homebridge.

Table of Contents

• Current Status
• Features
• Installation
• Configuration
• Controlling Zone Temperature Settings
• Zones as Heater/Cooler Accessories
• Error Handling
• Troubleshooting
• Contributing
• License

Current Status

This is an 'almost' feature complete implementation of the Neo platform in HomeKit.

Features

• Control either a single zone or multi-zone system
• Master controller and each zone sensor exposed as unique, controllable accessories in HomeKit
• "Away mode" accessory
• "Quiet mode" accessory
• "Continuous mode" accessory
• Temperature and humidity data from all zones and master controller reported in HomeKit
• Battery level reporting on zone sensors with low battery alerts in the Home app
• Support for Homebridge Config UI X

Installation

GUI Install

1. Search for "ActronAir Neo" on the plugin screen of Homebridge Config UI X
2. Find: homebridge-actronair-neo
3. Click Install
4. Enter your account details in the settings screen displayed

CLI Install

npm install -g homebridge-actronair-neo

Configure account details in the homebridge config.json file as below.

Configuration

The plugin implements the Homebridge config UI service. Simply install the plugin and you will be guided through the setup.

If you are not using the Homebridge config UI, you can add the following to your homebridge configuration:

"platforms": [
    {
        "platform": "ActronNeo",
        "name": "ActronNeo",
        "username": "<your_username>",
        "password": "<your_password>",
        "clientName": "homebridgeNeo",
        "zonesFollowMaster": true,
        "zonesPushMaster": true,
        "zonesAsHeaterCoolers": false,
        "refreshInterval": 60,
        "commandDebounceMs": 500,
        "setpointDebounceMs": 1000,
        "stateSyncGraceMs": 90000,
        "debug": false,
        "deviceSerial": "",
        "maxCoolingTemp": 32,
        "minCoolingTemp": 20,
        "maxHeatingTemp": 26,
        "minHeatingTemp": 10,
    }
]

Command Debouncing

When you make several changes in quick succession — dragging a temperature slider, toggling several zones on/off, or turning the unit on/off right after a zone change — the plugin waits briefly for you to finish and then sends a single, consolidated command. This prevents the changes from racing each other on the Neo cloud, which previously could leave only the last change applied or land a temperature somewhere between the start and target value.

There are two separate debounce windows, because the two kinds of input behave differently:

• commandDebounceMs (default 500) applies to discrete actions: turning the unit on/off, changing mode or fan, and toggling zones. These are single taps, so a shorter window keeps them feeling responsive while still batching a rapid multi-zone toggle into one send.
• setpointDebounceMs (default 1000) applies to temperature setpoints (master and zone). A slider drag fires a flood of intermediate values, so a longer window collapses the whole drag into a single command that carries only the final value.

Lower values feel snappier; higher values coalesce more aggressively. Commands are also serialised, so they always apply to the unit in the order you made them.

State Sync Grace Window

The Neo cloud's status endpoint is eventually consistent: for a short time after you change a setting, it can keep reporting the old value. Without protection a status refresh landing in that window would overwrite the value you just set, making it briefly bounce back to the old value (or the unit flick "off" right after you turn it on) until the cloud catches up.

To prevent this, after you change a setting the plugin keeps trusting your value over status refreshes until the cloud reports the same value back, or until the grace window lapses, whichever comes first. If the cloud never agrees (for example the unit clamped or rejected the change), the guard expires and the next refresh is accepted as-is, so the display always self-heals.

stateSyncGraceMs (default 90000, i.e. 90 seconds) sets this window. Increase it if you still see values briefly bounce back after setting them. Decrease it if you want changes made elsewhere (such as on the physical wall controller) to be picked up sooner while you are also using HomeKit.

Debug Logging

Set debug to true to surface the plugin's detailed debug logs — command queueing and coalescing, API requests and responses, and state reconciliation — directly in the Homebridge log. This works without running the whole Homebridge instance in debug mode (homebridge -D), so you can troubleshoot just this plugin. Leave it off (false, the default) for normal use.

Controlling Zone Temperature Settings

When modifying the zone temperature settings, the Neo system only allows you to set a temperature that is within -2 degrees (Heating) or +2 degrees (Cooling) of the Master Control temperature. With version 1.1.0, the default behaviour has been modified to automatically adjust the master temp if required when modifying a zone temp.

Setting zonesPushMaster to false will revert to the prior behaviour of constraining zones to the allowable max/min based on the current master setting. If you set a zone temperature that is outside of the +/- 2 degree range from the master, the plugin will translate the set temp to the allowable range.

Zones as Heater/Cooler Accessories

By default, each zone appears as a simple on/off switch in HomeKit. If you want more granular control over zone temperatures, you can enable the zonesAsHeaterCoolers option.

When enabled, each zone will appear as a full Heater/Cooler accessory in HomeKit with:

• Active state (on/off)
• Current temperature reading
• Heating threshold temperature (adjustable)
• Cooling threshold temperature (adjustable)
• Current heating/cooling state (inherited from master)

To enable this feature, set zonesAsHeaterCoolers to true in your configuration.

Important: This feature requires your ActronAir Neo system to support zone-based temperature control. Not all units have this capability. If your system does not support per-zone temperature setpoints, enabling this option may result in errors or unexpected behaviour. If you encounter issues, set zonesAsHeaterCoolers back to false.

Note that zones cannot independently change the climate mode (heat/cool/auto) - they follow the master controller's mode. Only the temperature setpoints can be adjusted per-zone.

Error Handling

The plugin is built to degrade gracefully. When something goes wrong it favours keeping Homebridge running on the last known good state and recovering automatically once the problem clears, rather than crashing or leaving accessories in a broken state. The main behaviours are:

• Authentication and tokens. Bearer tokens are refreshed automatically. If a request returns 401 Unauthorized, the plugin fetches a fresh token and retries (a few times, with a short delay between attempts). If authentication keeps failing, or a 400 indicates a credential problem, the cached tokens are cleared so a Homebridge restart can re-pair cleanly. Tokens are persisted to disk, so a restart does not force a full re-login when they are still valid.
• Transient server errors (5xx) and gateway timeouts. These are retried a few times with a delay. If they still fail, the plugin returns a handled error and continues using cached state instead of throwing, since these are usually temporary problems on the Neo service.
• Network outages. Common connectivity errors (host unreachable, timeouts, DNS failures, and similar) are caught and logged as warnings. The plugin keeps serving the last known state and resumes normally once the connection returns.
• Invalid or incomplete API data. Every response is validated against an expected schema. If the cloud returns data that fails validation, the plugin logs a warning and keeps the previous cached values rather than applying bad data.
• Command failures. Every command reports whether it succeeded. If a command is rejected, the plugin re-reads the true state from the cloud and pushes that back to HomeKit so the display resyncs with reality. If the cloud is unreachable when sending, it logs a warning and keeps the last known state. Commands are serialised, so one failed send never blocks the ones after it.
• Master controller offline. If the master controller loses its internet/WiFi connection, accessories keep showing their last known values. Attempts to change a setting while it is offline surface a communication error in the Home app instead of silently doing nothing.
• Eventual consistency. Immediately after a change, the Neo cloud can briefly keep reporting the old value. The plugin trusts your change until the cloud agrees or the grace window lapses. See State Sync Grace Window for details and the stateSyncGraceMs option.

If you want to see exactly what the plugin is doing while diagnosing an issue, enable Debug Logging. The Troubleshooting section below lists the most common specific errors and what to do about them.

Troubleshooting

Here are some common issues and their solutions:

1. HTTP Error 400: Check your username and password in the configuration. If you recently revoked client access through the Neo online portal, try restarting Homebridge.

2. HTTP Error 401: The plugin will automatically request a new bearer token. If the issue persists after multiple retries, try restarting Homebridge.

3. HTTP Error 5xx: These are server-side errors from the Neo API. The plugin will retry a few times. If the issue persists, it's likely a temporary problem with the Neo service.

4. Network Outages: The plugin will attempt to gracefully recover from network outages. Ensure your network connection is stable.

5. Master Controller Offline: Check your Master Controller's internet/WiFi connection if you see a message about it being offline.

6. Schema Validation Errors: These occur when the API returns incomplete data. The plugin will attempt to continue operation using cached data.

For the general approach behind these behaviours, see the Error Handling section above. Enabling Debug Logging can help pin down intermittent issues.

Contributing

Contributions to this plugin are welcome! Please follow these steps:

1. Fork the repository
2. Create a new branch for your feature or bug fix
3. Make your changes and commit them with a clear commit message
4. Push your changes to your fork
5. Submit a pull request

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

Support

If you encounter any issues or have feature requests, please open an issue on GitHub.