homebridge-melcloud-control 4.11.2 → 4.12.0

package/CHANGELOG.md

@@ -25,6 +25,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - For plugin < v4.6.0 use Homebridge UI <= v5.5.0
 - For plugin >= v4.6.0 use Homebridge UI >= v5.13.0
 
+## [4.12.0] - (23.09.2026)
+
+### Changes
+
+- added: Home Assistant MQTT discovery (`HA Discovery` option in the MQTT section), using the built-in Home Assistant MQTT integration
+  - Air Conditioner as `climate` with modes, target and room temperature, action, fan speed, vertical and horizontal vane
+  - Heat Pump zones as `climate` with presets Room / Flow / Curve, hot water tank as `water_heater` with heat pump / eco / high demand modes
+  - Energy Recovery Ventilation as `fan` with speed and Lossnay / Bypass / Auto presets
+- added: MQTT availability topic (`<prefix>/Availability`, retained `online` / `offline` last will) when HA Discovery is enabled
+- readme update
+- sample config update
+
+## [4.11.3] - (23.09.2026)
+
+### Changes
+
+- readme update, added `mqtt.protocolVersion`
+- sample config update, added `restFul.token` and `mqtt.protocolVersion`
+
 ## [4.11.2] - (23.09.2026)
 
 ### Changes

package/README.md

@@ -45,7 +45,7 @@
   * Physical lock controls `LOCK/UNLOCK`, only MELCloud.
   * Functions, using extra `Buttons`, switch to `OFF` restore previous state.
   * Automations, shortcuts and Siri.
-  * External integrations, [RESTFul](https://github.com/grzegorz914/homebridge-melcloud-control?tab=readme-ov-file#restful-integration), [MQTT](https://github.com/grzegorz914/homebridge-melcloud-control?tab=readme-ov-file#mqtt-integration).
+  * External integrations, [RESTFul](https://github.com/grzegorz914/homebridge-melcloud-control?tab=readme-ov-file#restful-integration), [MQTT](https://github.com/grzegorz914/homebridge-melcloud-control?tab=readme-ov-file#mqtt-integration), [HA Discovery](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery).
 * Control devices over local network You need use ESP module and [Tasmota Control](https://github.com/grzegorz914/homebridge-tasmota-control) plugin.
 
 ### Control Mode
@@ -365,6 +365,8 @@
 | `mqtt.port` | Here set the `Port` for MQTT Broker, default 1883. |
 | `mqtt.clientId` | Here optional set the `Client Id` of MQTT Broker. |
 | `mqtt.prefix` | Here set the `Prefix` for `Topic` or leave empty. |
+| `mqtt.protocolVersion` | Here select the MQTT protocol version, `5.0` (default) or `3.1.1` for brokers that only support 3.1.1 (e.g. ioBroker MQTT adapter). |
+| `mqtt.haDiscovery` | If enabled, devices are published to Home Assistant with MQTT discovery. Air Conditioner as `climate`, Heat Pump zones as `climate` and hot water tank as `water_heater`, Energy Recovery Ventilation as `fan`. |
 | `mqtt.auth{}` | MQTT authorization object. |
 | `mqtt.auth.enable` | Here enable authorization for MQTT Broker. |
 | `mqtt.auth.user` | Here set the MQTT Broker user. |
@@ -437,6 +439,13 @@
 ### MQTT Integration
 
 * Subscribe data as a JSON Object `{"Power": true}`
+* HA Discovery - if enabled, devices appear in Home Assistant through the built-in [MQTT integration](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery), no custom integration is needed. Additional retained topics:
+  * `homeassistant/climate/melcloud_<id>/config` - Air Conditioner, modes off / heat / cool / dry / fan_only / auto, target and room temperature, fan speed, vertical and horizontal vane.
+  * `homeassistant/climate/melcloud_<id>_zone1/config`, `..._zone2/config` - Heat Pump zones, modes off / heat / cool, presets `Room`, `Flow`, `Curve`. Target temperature is the room or flow temperature of the current preset. `off` turns the whole heat pump off.
+  * `homeassistant/water_heater/melcloud_<id>_tank/config` - Heat Pump hot water tank, modes `heat_pump`, `eco` (MELCloud only), `high_demand` (forced hot water).
+  * `homeassistant/fan/melcloud_<id>/config` - Energy Recovery Ventilation, on / off, fan speed, presets `Lossnay`, `Bypass`, `Auto`.
+  * `HA State` - state for the entities above.
+  * `Availability` - `online`, `offline` (last will).
 
 | Direction | Topic | Message | Type |
 | --- | --- | --- | --- |

package/config.schema.json

@@ -2441,6 +2441,15 @@
                     "functionBody": "return model.accounts[arrayIndices[0]].mqtt.enable === true;"
                   }
                 },
+                "haDiscovery": {
+                  "title": "HA Discovery",
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Publish Home Assistant MQTT discovery messages. Air Conditioner as climate, Heat Pump zones as climate and hot water tank as water_heater, Energy Recovery Ventilation as fan. Uses the built-in Home Assistant MQTT integration.",
+                  "condition": {
+                    "functionBody": "return model.accounts[arrayIndices[0]].mqtt.enable === true;"
+                  }
+                },
                 "auth": {
                   "title": "Authorization",
                   "type": "object",
@@ -3098,6 +3107,7 @@
                             "accounts[].mqtt.clientId",
                             "accounts[].mqtt.prefix",
                             "accounts[].mqtt.protocolVersion",
+                            "accounts[].mqtt.haDiscovery",
                             {
                               "key": "accounts[].mqtt.auth",
                               "title": "Authorization",

package/index.js

@@ -296,6 +296,7 @@ class MelCloudPlatform {
 						clientId: mqtt.clientId ? `melcloud_${mqtt.clientId}_${Math.random().toString(16).slice(3)}` : `melcloud_${Math.random().toString(16).slice(3)}`,
 						prefix: mqtt.prefix ? `melcloud/${mqtt.prefix}/${deviceTypeString}/${deviceName}` : `melcloud/${deviceTypeString}/${deviceName}`,
 						protocolVersion: mqtt.protocolVersion,
+						haDiscovery: mqtt.haDiscovery,
 						user: mqtt.auth?.user,
 						passwd: mqtt.auth?.passwd,
 						logWarn: logLevel.warn,

package/package.json

@@ -1,7 +1,7 @@
 {
   "displayName": "MELCloud Control",
   "name": "homebridge-melcloud-control",
-  "version": "4.11.2",
+  "version": "4.12.0",
   "description": "Homebridge plugin to control Mitsubishi Air Conditioner, Heat Pump and Energy Recovery Ventilation.",
   "license": "MIT",
   "author": "grzegorz914",

package/src/deviceata.js

@@ -1,6 +1,7 @@
 import EventEmitter from 'events';
 import MelCloudAta from './melcloudata.js';
 import Functions from './functions.js';
+import HaDiscovery from './hadiscovery.js';
 import { TemperatureDisplayUnits, AirConditioner, DeviceType } from './constants.js';
 let Accessory, Characteristic, Service, Categories, AccessoryUUID;
 
@@ -1305,6 +1306,32 @@ class DeviceAta extends EventEmitter {
         }
     }
 
+    //home assistant discovery
+    haReady() {
+        if (!this.mqttConnected || !this.mqtt.haDiscovery) return false;
+        if (this.ha) return true;
+
+        try {
+            this.ha = new HaDiscovery(this.mqtt1, { deviceId: this.deviceId, name: this.deviceName, model: this.model });
+            return true;
+        } catch (error) {
+            if (!this.haErrorLogged && this.logWarn) this.emit('warn', `HA Discovery setup error: ${error.message ?? error}`);
+            this.haErrorLogged = true;
+            return false;
+        }
+    }
+
+    async haPublish(capabilities, state) {
+        if (!this.haReady()) return;
+
+        try {
+            await this.ha.publishEntity('climate', '', this.ha.ataClimate(capabilities));
+            await this.ha.updateState(HaDiscovery.ataState(state));
+        } catch (error) {
+            if (this.logWarn) this.emit('warn', `HA Discovery publish error: ${error.message ?? error}`);
+        }
+    }
+
     //start
     async start() {
         try {
@@ -1622,6 +1649,23 @@ class DeviceAta extends EventEmitter {
                     };
                     this.accessory = obj;
 
+                    //home assistant, device capabilities (not the HomeKit mode mapping)
+                    this.haPublish({
+                        supportsHeat: supportsHeat1,
+                        supportsCool: supportsCool1,
+                        supportsDry: supportsDry && !hideDryModeControl,
+                        supportsAuto: supportsAuto1,
+                        supportsFanSpeed,
+                        numberOfFanSpeeds,
+                        supportsAutomaticFanSpeed,
+                        supportsAirDirectionFunction: supportsAirDirectionFunction && !hideVaneControls,
+                        supportsSwingFunction,
+                        supportsWideVane: supportsWideVane && !hideVaneControls,
+                        minTemp: minSetHeatRoomTemperature,
+                        maxTemp: maxSetHeatCoolDryAutoRoomTemperature,
+                        tempStep: temperatureStep
+                    }, { power, operationMode, inStandbyMode, roomTemperature, setTemperature, setFanSpeed, vaneVerticalDirection, vaneHorizontalDirection });
+
                     //update services
                     for (const { type, value } of characteristics) {
                         if (!this.functions.isValidValue(value)) continue;

package/src/deviceatw.js

@@ -1,6 +1,7 @@
 import EventEmitter from 'events';
 import MelCloudAtw from './melcloudatw.js';
 import Functions from './functions.js';
+import HaDiscovery from './hadiscovery.js';
 import { TemperatureDisplayUnits, HeatPump, DeviceType } from './constants.js';
 let Accessory, Characteristic, Service, Categories, AccessoryUUID;
 
@@ -1577,6 +1578,41 @@ class DeviceAtw extends EventEmitter {
         };
     }
 
+    //home assistant discovery
+    haReady() {
+        if (!this.mqttConnected || !this.mqtt.haDiscovery) return false;
+        if (this.ha) return true;
+
+        try {
+            this.ha = new HaDiscovery(this.mqtt1, { deviceId: this.deviceId, name: this.deviceName, model: this.model });
+            return true;
+        } catch (error) {
+            if (!this.haErrorLogged && this.logWarn) this.emit('warn', `HA Discovery setup error: ${error.message ?? error}`);
+            this.haErrorLogged = true;
+            return false;
+        }
+    }
+
+    async haPublish(capabilities, power, zones, tank) {
+        if (!this.haReady()) return;
+
+        try {
+            const state = { power };
+            for (const zone of zones) {
+                const range = HaDiscovery.atwZoneRange(zone.operationMode);
+                await this.ha.publishEntity('climate', `zone${zone.zone}`, this.ha.atwZoneClimate(zone.zone, { name: zone.name, supportsCool: capabilities.supportsCool, tempStep: capabilities.tempStep, ...range }));
+                state[`zone${zone.zone}`] = HaDiscovery.atwZoneState(power, zone);
+            }
+            if (tank) {
+                await this.ha.publishEntity('water_heater', 'tank', this.ha.atwWaterHeater({ name: tank.name, supportsEco: capabilities.supportsEco, minTemp: tank.minTemp, maxTemp: tank.maxTemp, tempStep: capabilities.tempStep }));
+                state.tank = HaDiscovery.atwTankState(tank);
+            }
+            await this.ha.updateState(state);
+        } catch (error) {
+            if (this.logWarn) this.emit('warn', `HA Discovery publish error: ${error.message ?? error}`);
+        }
+    }
+
     //start
     async start() {
         try {
@@ -2256,6 +2292,18 @@ class DeviceAtw extends EventEmitter {
                     }
                     this.accessory = obj;
 
+                    //home assistant, zones and tank from device capabilities (not the HomeKit hide zone setting)
+                    const haZones = [
+                        { zone: 1, name: zone1Name, operationMode: operationModeZone1, setTemperature: setTemperatureZone1, setHeatFlowTemperature: setHeatFlowTemperatureZone1, setCoolFlowTemperature: setCoolFlowTemperatureZone1, roomTemperature: roomTemperatureZone1, idle: idleZone1 },
+                        ...(deviceData.Device.HasZone2 ? [{ zone: 2, name: zone2Name, operationMode: operationModeZone2, setTemperature: setTemperatureZone2, setHeatFlowTemperature: setHeatFlowTemperatureZone2, setCoolFlowTemperature: setCoolFlowTemperatureZone2, roomTemperature: roomTemperatureZone2, idle: idleZone2 }] : [])
+                    ];
+                    const haTank = deviceData.Device[supportHotWaterKey] ? { name: hotWaterName, forcedHotWaterMode, ecoHotWater, setTankWaterTemperature, tankWaterTemperature, minTemp: minSetTankTemperature, maxTemp: maxSetTankTemperature } : null;
+                    this.haPublish({
+                        supportsCool,
+                        supportsEco: accountTypeMelCloud,
+                        tempStep: temperatureIncrement === true || temperatureIncrement === 0.5 ? 0.5 : 1
+                    }, power, haZones, haTank);
+
                     //other sensors
                     if (this.temperatureOutdoorSensor && supportsOutdoorTemperature) this.outdoorTemperatureSensorService?.updateCharacteristic(Characteristic.CurrentTemperature, outdoorTemperature);
                     if (this.inStandbySensor && inStandbyMode != null) this.inStandbyService?.updateCharacteristic(Characteristic.ContactSensorState, inStandbyMode);

package/src/deviceerv.js

@@ -1,6 +1,7 @@
 import EventEmitter from 'events';
 import MelCloudErv from './melclouderv.js';
 import Functions from './functions.js';
+import HaDiscovery from './hadiscovery.js';
 import { TemperatureDisplayUnits, Ventilation, DeviceType } from './constants.js';
 let Accessory, Characteristic, Service, Categories, AccessoryUUID;
 
@@ -979,6 +980,32 @@ class DeviceErv extends EventEmitter {
         };
     }
 
+    //home assistant discovery
+    haReady() {
+        if (!this.mqttConnected || !this.mqtt.haDiscovery) return false;
+        if (this.ha) return true;
+
+        try {
+            this.ha = new HaDiscovery(this.mqtt1, { deviceId: this.deviceId, name: this.deviceName, model: this.model });
+            return true;
+        } catch (error) {
+            if (!this.haErrorLogged && this.logWarn) this.emit('warn', `HA Discovery setup error: ${error.message ?? error}`);
+            this.haErrorLogged = true;
+            return false;
+        }
+    }
+
+    async haPublish(capabilities, state) {
+        if (!this.haReady()) return;
+
+        try {
+            await this.ha.publishEntity('fan', '', this.ha.ervFan(capabilities));
+            await this.ha.updateState(HaDiscovery.ervState(state));
+        } catch (error) {
+            if (this.logWarn) this.emit('warn', `HA Discovery publish error: ${error.message ?? error}`);
+        }
+    }
+
     //start
     async start() {
         try {
@@ -1249,6 +1276,13 @@ class DeviceErv extends EventEmitter {
 
                     this.accessory = obj;
 
+                    //home assistant
+                    this.haPublish({
+                        supportsBypass: supportsBypassVentilationMode,
+                        supportsAuto: supportsAutoVentilationMode,
+                        numberOfFanSpeeds
+                    }, { power, setFanSpeed, ventilationMode });
+
                     //update services
                     for (const { type, value } of characteristics) {
                         if (!this.functions.isValidValue(value)) continue;

package/src/hadiscovery.js

@@ -0,0 +1,285 @@
+// Home Assistant MQTT discovery, native climate / water_heater / fan entities.
+// Commands go back to the existing <prefix>/Set topic as the JSON keys the plugin already handles.
+
+// MELCloud operation mode values
+const AtaModeToHa = { 1: 'heat', 2: 'dry', 3: 'cool', 7: 'fan_only', 8: 'auto', 9: 'heat', 10: 'dry', 11: 'cool' };
+const AtwZonePreset = { 0: 'Room', 1: 'Flow', 2: 'Curve', 3: 'Room', 4: 'Flow', 5: 'Room' };
+const VaneVerticalToHa = { 0: 'auto', 1: '1', 2: '2', 3: '3', 4: '4', 5: '5', 7: 'swing' };
+const VaneHorizontalToHa = { 0: 'auto', 1: '1', 2: '2', 3: '3', 4: '4', 5: '5', 8: 'split', 12: 'swing' };
+const VentilationModes = ['Lossnay', 'Bypass', 'Auto'];
+
+class HaDiscovery {
+    constructor(mqtt, config) {
+        // + and # are MQTT wildcards, Home Assistant would subscribe to a pattern instead of the device topic
+        if (/[+#]/.test(mqtt.config.prefix)) {
+            throw new Error(`MQTT prefix ${mqtt.config.prefix} must not contain + or #, rename the device or set a prefix`);
+        }
+
+        this.mqtt = mqtt;
+        this.baseId = `melcloud_${String(config.deviceId).replace(/[^a-zA-Z0-9_-]/g, '_')}`;
+        this.stateTopic = `${mqtt.config.prefix}/HA State`;
+        this.commandTopic = `${mqtt.config.prefix}/Set`;
+        this.device = {
+            identifiers: [this.baseId],
+            name: config.name,
+            manufacturer: 'Mitsubishi Electric',
+            ...(config.model ? { model: String(config.model) } : {}),
+            ...(config.swVersion ? { sw_version: String(config.swVersion) } : {})
+        };
+        this.origin = { name: 'homebridge-melcloud-control', url: 'https://github.com/grzegorz914/homebridge-melcloud-control' };
+
+        this.lastConfig = {};
+        this.lastState = '';
+    }
+
+    // Publish (or republish when changed) one retained discovery message
+    async publishEntity(component, suffix, entity) {
+        const objectId = suffix ? `${this.baseId}_${suffix}` : this.baseId;
+        const topic = `${this.mqtt.haPrefix}/${component}/${objectId}/config`;
+        const config = {
+            unique_id: objectId,
+            device: this.device,
+            origin: this.origin,
+            availability_topic: this.mqtt.availabilityTopic,
+            ...entity
+        };
+
+        const payload = JSON.stringify(config);
+        if (this.lastConfig[topic] === payload) return false;
+        this.lastConfig[topic] = payload;
+        await this.mqtt.publishRetained(topic, payload);
+        return true;
+    }
+
+    async updateState(state) {
+        const payload = JSON.stringify(state);
+        if (payload === this.lastState) return false;
+        this.lastState = payload;
+        await this.mqtt.publishRetained(this.stateTopic, payload);
+        return true;
+    }
+
+    // ---------------------------------------------------------------- ATA
+    ataClimate(c) {
+        const modes = ['off'];
+        if (c.supportsHeat) modes.push('heat');
+        if (c.supportsCool) modes.push('cool');
+        if (c.supportsDry) modes.push('dry');
+        modes.push('fan_only');
+        if (c.supportsAuto) modes.push('auto');
+
+        const entity = {
+            name: null,
+            modes,
+            mode_state_topic: this.stateTopic,
+            mode_state_template: '{{ value_json.mode }}',
+            mode_command_topic: this.commandTopic,
+            mode_command_template: '{% set m = {"heat": 1, "dry": 2, "cool": 3, "fan_only": 7, "auto": 8} %}{% if value == "off" %}{"Power": false}{% else %}{"Power": true, "OperationMode": {{ m[value] }}}{% endif %}',
+            power_command_topic: this.commandTopic,
+            power_command_template: '{"Power": {{ "true" if value == "ON" else "false" }}}',
+            temperature_state_topic: this.stateTopic,
+            temperature_state_template: '{{ value_json.target_temperature }}',
+            temperature_command_topic: this.commandTopic,
+            temperature_command_template: '{"SetTemperature": {{ value }}}',
+            current_temperature_topic: this.stateTopic,
+            current_temperature_template: '{{ value_json.current_temperature }}',
+            action_topic: this.stateTopic,
+            action_template: '{{ value_json.action }}',
+            min_temp: c.minTemp,
+            max_temp: c.maxTemp,
+            temp_step: c.tempStep,
+            precision: 0.1,
+            temperature_unit: 'C'
+        };
+
+        if (c.supportsFanSpeed && c.numberOfFanSpeeds > 0) {
+            const fanModes = c.supportsAutomaticFanSpeed ? ['auto'] : [];
+            for (let i = 1; i <= c.numberOfFanSpeeds; i++) fanModes.push(String(i));
+            Object.assign(entity, {
+                fan_modes: fanModes,
+                fan_mode_state_topic: this.stateTopic,
+                fan_mode_state_template: '{{ value_json.fan_mode }}',
+                fan_mode_command_topic: this.commandTopic,
+                fan_mode_command_template: '{"FanSpeed": {{ 0 if value == "auto" else value | int }}}'
+            });
+        }
+
+        if (c.supportsAirDirectionFunction) {
+            const swingModes = ['auto', '1', '2', '3', '4', '5', ...(c.supportsSwingFunction ? ['swing'] : [])];
+            Object.assign(entity, {
+                swing_modes: swingModes,
+                swing_mode_state_topic: this.stateTopic,
+                swing_mode_state_template: '{{ value_json.swing_mode }}',
+                swing_mode_command_topic: this.commandTopic,
+                swing_mode_command_template: '{% set m = {"auto": 0, "swing": 7} %}{"VaneVerticalDirection": {{ m[value] if value in m else value | int }}}'
+            });
+        }
+
+        if (c.supportsWideVane) {
+            const swingModes = ['auto', '1', '2', '3', '4', '5', 'split', ...(c.supportsSwingFunction ? ['swing'] : [])];
+            Object.assign(entity, {
+                swing_horizontal_modes: swingModes,
+                swing_horizontal_mode_state_topic: this.stateTopic,
+                swing_horizontal_mode_state_template: '{{ value_json.swing_horizontal_mode }}',
+                swing_horizontal_mode_command_topic: this.commandTopic,
+                swing_horizontal_mode_command_template: '{% set m = {"auto": 0, "split": 8, "swing": 12} %}{"VaneHorizontalDirection": {{ m[value] if value in m else value | int }}}'
+            });
+        }
+
+        return entity;
+    }
+
+    static ataState(d) {
+        const power = !!d.power;
+        const mode = power ? (AtaModeToHa[d.operationMode] ?? 'auto') : 'off';
+        const room = d.roomTemperature;
+        const target = d.setTemperature;
+        let action = 'off';
+        if (power) {
+            if (d.inStandbyMode) action = 'idle';
+            else if (mode === 'dry') action = 'drying';
+            else if (mode === 'fan_only') action = 'fan';
+            else if (mode === 'heat') action = room < target ? 'heating' : 'idle';
+            else if (mode === 'cool') action = room > target ? 'cooling' : 'idle';
+            else action = room < target ? 'heating' : room > target ? 'cooling' : 'idle';
+        }
+
+        return {
+            power,
+            mode,
+            action,
+            target_temperature: target,
+            current_temperature: room,
+            fan_mode: d.setFanSpeed === 0 ? 'auto' : String(d.setFanSpeed ?? ''),
+            swing_mode: VaneVerticalToHa[d.vaneVerticalDirection] ?? 'auto',
+            swing_horizontal_mode: VaneHorizontalToHa[d.vaneHorizontalDirection] ?? 'auto'
+        };
+    }
+
+    // ---------------------------------------------------------------- ATW
+    atwZoneClimate(zone, c) {
+        const z = `zone${zone}`;
+        const key = `Zone${zone}`;
+        const modes = ['off', 'heat', ...(c.supportsCool ? ['cool'] : [])];
+        const presets = ['Room', 'Flow', 'Curve'];
+
+        return {
+            name: c.name,
+            modes,
+            mode_state_topic: this.stateTopic,
+            mode_state_template: `{{ value_json.${z}.mode }}`,
+            mode_command_topic: this.commandTopic,
+            // Keep the current preset (room / flow / curve) when switching between heat and cool
+            mode_command_template: `{% set p = state_attr(entity_id, "preset_mode") %}{% if value == "off" %}{"Power": false}{% elif value == "cool" %}{"Power": true, "OperationMode${key}": {{ 4 if p == "Flow" else 3 }}}{% else %}{"Power": true, "OperationMode${key}": {{ 1 if p == "Flow" else 2 if p == "Curve" else 0 }}}{% endif %}`,
+            preset_modes: presets,
+            preset_mode_state_topic: this.stateTopic,
+            preset_mode_value_template: `{{ value_json.${z}.preset }}`,
+            preset_mode_command_topic: this.commandTopic,
+            preset_mode_command_template: `{% set cool = states(entity_id) == "cool" %}{% set m = {"Room": 3 if cool else 0, "Flow": 4 if cool else 1, "Curve": 3 if cool else 2} %}{"OperationMode${key}": {{ m.get(value, m["Room"]) }}}`,
+            temperature_state_topic: this.stateTopic,
+            temperature_state_template: `{{ value_json.${z}.target_temperature }}`,
+            temperature_command_topic: this.commandTopic,
+            // Flow presets set the flow temperature, the others the room temperature
+            temperature_command_template: `{% set p = state_attr(entity_id, "preset_mode") %}{% set cool = states(entity_id) == "cool" %}{% if p == "Flow" %}{"{{ "SetCoolFlowTemperature${key}" if cool else "SetHeatFlowTemperature${key}" }}": {{ value }}}{% else %}{"SetTemperature${key}": {{ value }}}{% endif %}`,
+            current_temperature_topic: this.stateTopic,
+            current_temperature_template: `{{ value_json.${z}.current_temperature }}`,
+            action_topic: this.stateTopic,
+            action_template: `{{ value_json.${z}.action }}`,
+            power_command_topic: this.commandTopic,
+            power_command_template: '{"Power": {{ "true" if value == "ON" else "false" }}}',
+            min_temp: c.minTemp,
+            max_temp: c.maxTemp,
+            temp_step: c.tempStep,
+            precision: 0.1,
+            temperature_unit: 'C'
+        };
+    }
+
+    static atwZoneState(power, d) {
+        const preset = AtwZonePreset[d.operationMode] ?? 'Room';
+        const cool = d.operationMode === 3 || d.operationMode === 4;
+        const mode = !power ? 'off' : cool ? 'cool' : 'heat';
+        const target = preset === 'Flow' ? (cool ? d.setCoolFlowTemperature : d.setHeatFlowTemperature) : d.setTemperature;
+        const action = !power ? 'off' : d.idle ? 'idle' : cool ? 'cooling' : 'heating';
+        return { mode, preset, action, target_temperature: target, current_temperature: d.roomTemperature };
+    }
+
+    // Temperature range shown in Home Assistant for the current zone mode
+    static atwZoneRange(operationMode) {
+        switch (operationMode) {
+            case 1: return { minTemp: 25, maxTemp: 60 }; // heat flow
+            case 3: return { minTemp: 16, maxTemp: 30 }; // cool room
+            case 4: return { minTemp: 16, maxTemp: 30 }; // cool flow
+            default: return { minTemp: 10, maxTemp: 30 }; // heat room / curve
+        }
+    }
+
+    atwWaterHeater(c) {
+        const modes = ['heat_pump', ...(c.supportsEco ? ['eco'] : []), 'high_demand'];
+        const resetEco = c.supportsEco ? ', "EcoHotWater": false' : '';
+        return {
+            name: c.name,
+            modes,
+            mode_state_topic: this.stateTopic,
+            mode_state_template: '{{ value_json.tank.mode }}',
+            mode_command_topic: this.commandTopic,
+            mode_command_template: `{% if value == "high_demand" %}{"ForcedHotWaterMode": true}{% elif value == "eco" %}{"ForcedHotWaterMode": false, "EcoHotWater": true}{% else %}{"ForcedHotWaterMode": false${resetEco}}{% endif %}`,
+            temperature_state_topic: this.stateTopic,
+            temperature_state_template: '{{ value_json.tank.target_temperature }}',
+            temperature_command_topic: this.commandTopic,
+            temperature_command_template: '{"SetTankWaterTemperature": {{ value }}}',
+            current_temperature_topic: this.stateTopic,
+            current_temperature_template: '{{ value_json.tank.current_temperature }}',
+            min_temp: c.minTemp,
+            max_temp: c.maxTemp,
+            precision: c.tempStep === 0.5 ? 0.5 : 1,
+            temperature_unit: 'C'
+        };
+    }
+
+    static atwTankState(d) {
+        const mode = d.forcedHotWaterMode ? 'high_demand' : d.ecoHotWater ? 'eco' : 'heat_pump';
+        return { mode, target_temperature: d.setTankWaterTemperature, current_temperature: d.tankWaterTemperature };
+    }
+
+    // ---------------------------------------------------------------- ERV
+    ervFan(c) {
+        const presets = VentilationModes.filter((mode, i) => i === 0 || (i === 1 && c.supportsBypass) || (i === 2 && c.supportsAuto));
+        const entity = {
+            name: null,
+            state_topic: this.stateTopic,
+            state_value_template: '{{ "ON" if value_json.power else "OFF" }}',
+            command_topic: this.commandTopic,
+            command_template: '{"Power": {{ "true" if value == "ON" else "false" }}}',
+            preset_modes: presets,
+            preset_mode_state_topic: this.stateTopic,
+            preset_mode_value_template: '{{ value_json.ventilation_mode }}',
+            preset_mode_command_topic: this.commandTopic,
+            preset_mode_command_template: '{% set m = {"Lossnay": 0, "Bypass": 1, "Auto": 2} %}{"VentilationMode": {{ m[value] }}}'
+        };
+
+        if (c.numberOfFanSpeeds > 0) {
+            Object.assign(entity, {
+                speed_range_min: 1,
+                speed_range_max: c.numberOfFanSpeeds,
+                percentage_state_topic: this.stateTopic,
+                // 0 is automatic fan speed, reported as no percentage
+                percentage_value_template: '{{ value_json.fan_speed if value_json.fan_speed > 0 else "None" }}',
+                percentage_command_topic: this.commandTopic,
+                percentage_command_template: '{"SetFanSpeed": {{ value }}}'
+            });
+        }
+
+        return entity;
+    }
+
+    static ervState(d) {
+        return {
+            power: !!d.power,
+            fan_speed: d.setFanSpeed ?? 0,
+            ventilation_mode: VentilationModes[d.ventilationMode] ?? 'Lossnay'
+        };
+    }
+}
+
+export default HaDiscovery;

package/src/mqtt.js

@@ -12,12 +12,20 @@ class Mqtt extends EventEmitter {
         const isV5 = protocolVersion === 5;
         this.isV5 = isV5;
 
+        // Home Assistant discovery, availability is reported with a retained last will
+        this.haDiscovery = config.haDiscovery === true;
+        this.haPrefix = config.haPrefix || 'homeassistant';
+        this.availabilityTopic = `${config.prefix}/Availability`;
+
         const options = {
             clientId: config.clientId,
             username: config.user,
             password: config.passwd,
             protocolVersion,
             clean: !isV5,
+            ...(this.haDiscovery ? {
+                will: { topic: this.availabilityTopic, payload: 'offline', qos: 1, retain: true }
+            } : {}),
             ...(isV5 ? {
                 properties: {
                     sessionExpiryInterval: 60 * 60,
@@ -36,6 +44,7 @@ class Mqtt extends EventEmitter {
             .on('connect', async () => {
                 hasConnected = true;
                 this.emit('connected', `MQTT v${protocolVersion} connected.`);
+                if (this.haDiscovery) this.publishRetained(this.availabilityTopic, 'online').catch(() => { });
 
                 try {
                     await new Promise((resolve, reject) => {
@@ -89,6 +98,24 @@ class Mqtt extends EventEmitter {
             });
     }
 
+    publishRetained(fullTopic, payload) {
+        return new Promise((resolve, reject) => {
+            // + and # are wildcards, the client would never complete such a publish
+            if (/[+#]/.test(fullTopic)) {
+                return reject(new Error(`Invalid topic ${fullTopic}, the name or prefix must not contain + or #`));
+            }
+
+            this.mqttClient.publish(fullTopic, payload, { qos: 1, retain: true }, (error) => {
+                if (error) {
+                    if (this.config.logWarn) this.emit('warn', `MQTT Publish error: ${error.message}`);
+                    return reject(error);
+                }
+                if (this.config.logDebug) this.emit('debug', `MQTT Publish retained Topic: ${fullTopic}, Payload: ${payload}`);
+                resolve();
+            });
+        });
+    }
+
     publish(topic, message) {
         return new Promise((resolve, reject) => {
             const fullTopic = `${this.config.prefix}/${topic}`;