homebridge-echonetlite2mqtt-aircon

Homebridge plugin for controlling ECHONET Lite air conditioners through echonetlite2mqtt and MQTT.

Overview

This plugin exposes air conditioners managed by echonetlite2mqtt to Apple Home through Homebridge.

The expected communication path is:

Air conditioner
  -> ECHONET Lite
  -> echonetlite2mqtt
  -> MQTT broker
  -> homebridge-echonetlite2mqtt-aircon
  -> Apple Home

This plugin does not provide an ECHONET Lite gateway or MQTT broker.

Features

• Apple Home HeaterCooler accessory
• Optional Thermostat accessory representation
• Power on and off
• Cooling mode
• Heating mode
• Automatic mode
• Dry mode through configurable mode mapping
• Fan-only mode through configurable mode mapping
• Target temperature control
• Current room temperature display
• Configurable minimum, maximum, step, and rounding for temperatures
• Independent target temperatures for cooling and heating modes
• Apple Home automation support
• MQTT state synchronization
• Configurable target-temperature debounce
• Optional power-on reassert guard for devices with delayed state responses

Requirements

• Homebridge 2.x
• Node.js 22 or later
• MQTT broker
• A working echonetlite2mqtt environment
• An air conditioner exposed through compatible echonetlite2mqtt MQTT topics

Installation

npm install -g homebridge-echonetlite2mqtt-aircon

After installation, restart Homebridge and configure the plugin using the Homebridge UI.

Configuration

The plugin can be configured through the Homebridge UI.

MQTT settings

• MQTT broker URL
• MQTT base topic
• State request interval

Air-conditioner settings

• Accessory name
• Display name
• echonetlite2mqtt device ID
• Manufacturer and model metadata
• Minimum and maximum target temperature
• Temperature step and rounding method
• HomeKit service type
• Operation-mode mappings for the HomeKit Cool, Heat, and Auto controls
• Modes for which target-temperature transmission should be skipped
• Power-on reassert guard time
• Target-temperature debounce time

Device IDs depend on the local echonetlite2mqtt environment and must be entered for each air conditioner.

Verified Devices

This plugin has been tested with the following air-conditioner series:

| Manufacturer | Series | |---|---| | Panasonic | Eolia | | Mitsubishi Electric | Kirigamine Z | | Daikin | Urusara X |

The list above indicates devices used for actual testing. Compatibility with other models is not guaranteed.

Limitations

The following features are not currently supported:

• Swing mode
• Fan-speed control

Supported operation modes and available properties depend on the values exposed by each air conditioner through echonetlite2mqtt.

Troubleshooting

When an accessory does not respond or update:

1. Confirm that the MQTT broker is reachable.
2. Confirm that echonetlite2mqtt is running.
3. Confirm that the required MQTT device and property topics are available.
4. Confirm that the configured device ID matches the target air conditioner.
5. Confirm that the selected operation-mode mappings are supported by the device.
6. Restart Homebridge after changing the plugin configuration.

Notes and Disclaimer

This plugin is an independent open-source project.

It is not an official product of Panasonic, Mitsubishi Electric, Daikin, Apple, the ECHONET Consortium, Homebridge, or any other manufacturer or organization.

This project is not affiliated with, endorsed by, certified by, or supported by those companies or organizations.

This software is provided "as is", without warranty of any kind.

Use this software entirely at your own risk. The author and contributors are not responsible for equipment damage, malfunction, unintended operation, data loss, network problems, or any other issue resulting from installation or use of this software.

Compatibility depends on the ECHONET Lite properties exposed by each air conditioner and on the behavior of echonetlite2mqtt.

Changelog

v0.2.1

Fixed

• Fixed Accessory reported an internal timeout when Apple Home scenes or automations changed Active, operation mode, and target temperature together.
• HomeKit setters now complete immediately while MQTT commands run in a background serial queue.
• Simultaneous Active, mode, cooling-temperature, and heating-temperature writes are coalesced into one ordered device command.
• Removed duplicate target-temperature transmission from the same HomeKit scene.

Changed

• Device-state refresh requests are scheduled asynchronously and no longer delay HomeKit write completion.
• Superseded in-flight command sequences stop before sending stale mode or temperature steps.

v0.2.0

Added

• Support for target-temperature changes from Apple Home automations.
• Independent target-temperature storage for cooling and heating modes.
• Mode-specific target-temperature transmission after operation-mode changes.

Changed

• Improved synchronization between Apple Home characteristics and MQTT states.
• Improved handling of delayed and stale MQTT responses during commands.
• Improved target-temperature debouncing for Apple Home adjustments.

Fixed

• Fixed an issue where an Apple Home automation could restore a previous target temperature.
• Fixed incorrect target-temperature transmission after changing between cooling and heating modes.
• Fixed target-temperature synchronization when Apple Home sends mode, power, and temperature changes together.