homebridge-melcloud-control 4.11.3 → 4.13.0

package/CHANGELOG.md

@@ -25,6 +25,30 @@ 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.13.0] - (24.09.2026)
+
+### Changes
+
+- added: HA Discovery, device locks as one `select` in the device configuration
+  - Air Conditioner (MELCloud only): `Off`, `Power`, `Mode`, `Mode Power`, `Temp`, `Temp Power`, `Temp Mode`, `All`
+  - Heat Pump: `Off`, `Zone 1`, `Zone 1 Zone 2`, `Zone 1 Water`, `Zone 2`, `Zone 2 Water`, `Water`, `All` (zone locks MELCloud only)
+- added: RESTFul request rate limit, 600 requests per minute per client and at most 1000 clients per minute, answered with `429` and `Retry-After`, one log warning per client and minute. Replaces the approach proposed in #261 which blocked clients polling faster than every 0.6 s, kept every client address forever and logged every rejected request
+- fix: HA Discovery, vertical vane (`swing_mode`) was not shown when the device reports `AirDirectionFunction: false` (the i-See air direction function, not the vane). It is now shown whenever the device reports a vertical vane position
+- fix: MELCloud (classic) any setting change (temperature, fan speed, vane, mode, locks, hot water...) switched an OFF device ON. Since v4.7.9 every command was sent with a forced `Power: true` and the Power effective flag. Now only an explicit `Power` command changes the power state, like before v4.7.9 when the current power state was sent
+- readme update
+
+## [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

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
@@ -366,6 +366,7 @@
 | `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. |
@@ -438,6 +439,14 @@
 ### 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`.
+  * `homeassistant/select/melcloud_<id>_prohibit/config` - locks as one select in the device configuration. Air Conditioner (MELCloud only): `Off`, `Power`, `Mode`, `Mode Power`, `Temp`, `Temp Power`, `Temp Mode`, `All`. Heat Pump: `Off`, `Zone 1`, `Zone 1 Zone 2`, `Zone 1 Water`, `Zone 2`, `Zone 2 Water`, `Water`, `All` (zone locks MELCloud only).
+  * `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.3",
+  "version": "4.13.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,40 @@ 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));
+            const haState = HaDiscovery.ataState(state);
+
+            // Locks work only with MELCloud
+            if (capabilities.supportsProhibit) {
+                const parts = [{ name: 'Temp', key: 'ProhibitSetTemperature' }, { name: 'Mode', key: 'ProhibitOperationMode' }, { name: 'Power', key: 'ProhibitPower' }];
+                await this.ha.publishEntity('select', 'prohibit', this.ha.prohibitSelect(parts));
+                haState.prohibit = HaDiscovery.prohibitName(parts, [state.prohibitSetTemperature, state.prohibitOperationMode, state.prohibitPower]);
+            }
+            await this.ha.updateState(haState);
+        } catch (error) {
+            if (this.logWarn) this.emit('warn', `HA Discovery publish error: ${error.message ?? error}`);
+        }
+    }
+
     //start
     async start() {
         try {
@@ -1622,6 +1657,25 @@ 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,
+                        // AirDirectionFunction is the i-See air direction, not the vertical vane itself
+                        supportsVaneVertical: vaneVerticalDirection !== null && vaneVerticalDirection !== undefined && !hideVaneControls,
+                        supportsSwingFunction,
+                        supportsWideVane: supportsWideVane && !hideVaneControls,
+                        minTemp: minSetHeatRoomTemperature,
+                        maxTemp: maxSetHeatCoolDryAutoRoomTemperature,
+                        tempStep: temperatureStep,
+                        supportsProhibit: accountTypeMelCloud
+                    }, { power, operationMode, inStandbyMode, roomTemperature, setTemperature, setFanSpeed, vaneVerticalDirection, vaneHorizontalDirection, prohibitSetTemperature, prohibitOperationMode, prohibitPower });
+
                     //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,58 @@ 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);
+            }
+
+            // Zone locks work only with MELCloud, the hot water lock with both accounts
+            const parts = [];
+            const values = [];
+            for (const zone of zones) {
+                if (!capabilities.supportsZoneProhibit) continue;
+                parts.push({ name: `Zone ${zone.zone}`, key: `ProhibitZone${zone.zone}` });
+                values.push(zone.prohibit);
+            }
+            if (tank) {
+                parts.push({ name: 'Water', key: 'ProhibitHotWater' });
+                values.push(tank.prohibit);
+            }
+            if (parts.length > 0) {
+                await this.ha.publishEntity('select', 'prohibit', this.ha.prohibitSelect(parts, 'lexical'));
+                state.prohibit = HaDiscovery.prohibitName(parts, values);
+            }
+            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 +2309,19 @@ 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, prohibit: prohibitZone1 },
+                        ...(deviceData.Device.HasZone2 ? [{ zone: 2, name: zone2Name, operationMode: operationModeZone2, setTemperature: setTemperatureZone2, setHeatFlowTemperature: setHeatFlowTemperatureZone2, setCoolFlowTemperature: setCoolFlowTemperatureZone2, roomTemperature: roomTemperatureZone2, idle: idleZone2, prohibit: prohibitZone2 }] : [])
+                    ];
+                    const haTank = deviceData.Device[supportHotWaterKey] ? { name: hotWaterName, forcedHotWaterMode, ecoHotWater, setTankWaterTemperature, tankWaterTemperature, minTemp: minSetTankTemperature, maxTemp: maxSetTankTemperature, prohibit: prohibitHotWater } : null;
+                    this.haPublish({
+                        supportsCool,
+                        supportsEco: accountTypeMelCloud,
+                        supportsZoneProhibit: 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,339 @@
+// 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.supportsVaneVertical) {
+            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'
+        };
+    }
+
+    // ---------------------------------------------------------------- prohibit
+    // One select with every combination of the device locks, parts: [{ name, key }].
+    // order 'binary' - first part is the highest bit: Off, Power, Mode, Mode Power, Temp, Temp Power, Temp Mode, All
+    // order 'lexical' - combinations in part order: Off, Zone 1, Zone 1 Zone 2, Zone 1 Water, Zone 2, Zone 2 Water, Water, All
+    prohibitSelect(parts, order = 'binary') {
+        const combos = HaDiscovery.prohibitCombos(parts, order);
+        const options = combos.map(values => HaDiscovery.prohibitName(parts, values));
+        const masks = JSON.stringify(Object.fromEntries(combos.map((values, i) => [options[i], values.reduce((mask, v, bit) => mask | (v ? 1 << bit : 0), 0)])));
+        const values = parts.map((p, bit) => `"${p.key}": {{ "true" if (m[value] // ${1 << bit}) % 2 == 1 else "false" }}`).join(', ');
+        return {
+            name: 'Prohibit',
+            icon: 'mdi:lock',
+            entity_category: 'config',
+            options,
+            state_topic: this.stateTopic,
+            value_template: '{{ value_json.prohibit }}',
+            command_topic: this.commandTopic,
+            command_template: `{% set m = ${masks} %}{${values}}`
+        };
+    }
+
+    // Every lock combination as an array of booleans in part order
+    static prohibitCombos(parts, order = 'binary') {
+        const n = parts.length;
+        if (order === 'binary') {
+            return [...Array(1 << n).keys()].map(mask => parts.map((p, i) => ((mask >> (n - 1 - i)) & 1) === 1));
+        }
+
+        const combos = [];
+        const walk = (start, picked) => {
+            for (let i = start; i < n; i++) {
+                const next = [...picked, i];
+                combos.push(next);
+                walk(i + 1, next);
+            }
+        };
+        walk(0, []);
+        const toValues = (picked) => parts.map((p, i) => picked.includes(i));
+        const partial = combos.filter(picked => n === 1 || picked.length < n).map(toValues);
+        return [parts.map(() => false), ...partial, ...(n > 1 ? [parts.map(() => true)] : [])];
+    }
+
+    static prohibitOptions(parts, order = 'binary') {
+        return HaDiscovery.prohibitCombos(parts, order).map(values => HaDiscovery.prohibitName(parts, values));
+    }
+
+    // Name of a lock combination, values in the same order as parts
+    static prohibitName(parts, values) {
+        const locked = parts.filter((p, i) => values[i]);
+        if (locked.length === 0) return 'Off';
+        if (parts.length > 1 && locked.length === parts.length) return 'All';
+        return locked.map(p => p.name).join(' ');
+    }
+
+    // ---------------------------------------------------------------- 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/melcloudata.js

@@ -220,7 +220,7 @@ class MelCloudAta extends EventEmitter {
                                 changes.setTemperature = (deviceData.Device.DefaultCoolingSetTemperature + deviceData.Device.DefaultHeatingSetTemperature) / 2;
                             }
 
-                            //rebuild effective flags from only the fields that actually changed, Power always stays forced
+                            //rebuild effective flags from only the fields that actually changed
                             const flagBits = {
                                 operationMode: AirConditioner.EffectiveFlags.OperationMode,
                                 setTemperature: AirConditioner.EffectiveFlags.SetTemperature,
@@ -231,11 +231,12 @@ class MelCloudAta extends EventEmitter {
                                 prohibitOperationMode: AirConditioner.EffectiveFlags.Prohibit,
                                 prohibitPower: AirConditioner.EffectiveFlags.Prohibit,
                             };
-                            flag = Object.keys(changes).reduce((acc, key) => acc | (flagBits[key] ?? 0), AirConditioner.EffectiveFlags.Power);
+                            // Only an explicit Power command may switch the device on or off, other settings keep the current power state
+                            const powerFlag = changes.power !== undefined ? AirConditioner.EffectiveFlags.Power : 0;
+                            flag = Object.keys(changes).reduce((acc, key) => acc | (flagBits[key] ?? 0), powerFlag);
 
                             payload = this.functions.toPascalCaseKeys({
                                 ...changes,
-                                power: changes.power !== false,
                                 deviceID: deviceData.Device.DeviceID,
                                 effectiveFlags: flag,
                                 hasPendingCommand: true,

package/src/melcloudatw.js

@@ -194,7 +194,7 @@ class MelCloudAtw extends EventEmitter {
                                 return true;
                             }
 
-                            //rebuild effective flags from only the fields that actually changed, Power always stays forced
+                            //rebuild effective flags from only the fields that actually changed
                             //NOTE: use + not | - some HeatPump flags exceed 32 bits (e.g. SetHeatFlowTemperatureZone1 = 2^48), and
                             //the bitwise OR operator truncates to a 32-bit int in JS, silently corrupting large flag values
                             const flagBits = {
@@ -215,11 +215,12 @@ class MelCloudAtw extends EventEmitter {
                                 prohibitZone2: HeatPump.EffectiveFlags.ProhibitHeatingZone2,
                                 prohibitHotWater: HeatPump.EffectiveFlags.ProhibitHotWater,
                             };
-                            flag = Object.keys(changes).reduce((acc, key) => acc + (flagBits[key] ?? 0), HeatPump.EffectiveFlags.Power);
+                            // Only an explicit Power command may switch the device on or off, other settings keep the current power state
+                            const powerFlag = changes.power !== undefined ? HeatPump.EffectiveFlags.Power : 0;
+                            flag = Object.keys(changes).reduce((acc, key) => acc + (flagBits[key] ?? 0), powerFlag);
 
                             payload = this.functions.toPascalCaseKeys({
                                 ...changes,
-                                power: changes.power !== false,
                                 deviceID: deviceData.Device.DeviceID,
                                 effectiveFlags: flag,
                                 hasPendingCommand: true,

package/src/melclouderv.js

@@ -211,7 +211,7 @@ class MelCloudErv extends EventEmitter {
                                     break;
                             };
 
-                            //rebuild effective flags from only the fields that actually changed, Power always stays forced
+                            //rebuild effective flags from only the fields that actually changed
                             const flagBits = {
                                 operationMode: Ventilation.EffectiveFlags.OperationMode,
                                 ventilationMode: Ventilation.EffectiveFlags.VentilationMode,
@@ -222,11 +222,12 @@ class MelCloudErv extends EventEmitter {
                                 prohibitOperationMode: Ventilation.EffectiveFlags.Prohibit,
                                 prohibitPower: Ventilation.EffectiveFlags.Prohibit,
                             };
-                            flag = Object.keys(changes).reduce((acc, key) => acc | (flagBits[key] ?? 0), Ventilation.EffectiveFlags.Power);
+                            // Only an explicit Power command may switch the device on or off, other settings keep the current power state
+                            const powerFlag = changes.power !== undefined ? Ventilation.EffectiveFlags.Power : 0;
+                            flag = Object.keys(changes).reduce((acc, key) => acc | (flagBits[key] ?? 0), powerFlag);
 
                             payload = this.functions.toPascalCaseKeys({
                                 ...changes,
-                                power: changes.power !== false,
                                 deviceID: deviceData.Device.DeviceID,
                                 effectiveFlags: flag,
                                 hasPendingCommand: true,

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}`;

package/src/restful.js

@@ -24,6 +24,49 @@ class RestFul extends EventEmitter {
         try {
             const app = express();
             app.set('json spaces', 2);
+
+            // Request rate limit per client, protects Homebridge from request floods (CWE-770)
+            const rateLimitWindow = 60 * 1000;
+            const rateLimitMax = 600;
+            const rateLimitClients = 1000;
+            const clients = new Map();
+            let clientsLimitWarned = 0;
+            app.use((req, res, next) => {
+                const now = Date.now();
+
+                // Drop expired windows so the map cannot grow without limit
+                if (clients.size > 100) {
+                    for (const [ip, client] of clients) {
+                        if (now - client.start >= rateLimitWindow) clients.delete(ip);
+                    }
+                }
+
+                let client = clients.get(req.ip);
+                if (!client || now - client.start >= rateLimitWindow) {
+                    // Hard limit of tracked addresses, new addresses wait until older windows expire
+                    if (!client && clients.size >= rateLimitClients) {
+                        if (now - clientsLimitWarned >= rateLimitWindow) {
+                            clientsLimitWarned = now;
+                            if (this.logWarn) this.emit('warn', `RESTFul too many clients (${rateLimitClients}) in one minute, new clients are rejected until the window ends`);
+                        }
+                        res.set('Retry-After', String(Math.ceil(rateLimitWindow / 1000)));
+                        return res.status(429).json({ error: 'RESTFul Too Many Requests' });
+                    }
+                    client = { count: 0, start: now, warned: false };
+                    clients.set(req.ip, client);
+                }
+
+                if (++client.count > rateLimitMax) {
+                    // Warn once per client and window, a flood must not flood the log too
+                    if (!client.warned && this.logWarn) this.emit('warn', `RESTFul rate limit ${rateLimitMax} requests per minute exceeded by: ${req.ip}, further requests are rejected until the window ends`);
+                    client.warned = true;
+                    res.set('Retry-After', String(Math.ceil((client.start + rateLimitWindow - now) / 1000)));
+                    return res.status(429).json({ error: 'RESTFul Too Many Requests' });
+                }
+
+                next();
+            });
+
             app.use(json());
 
             // Optional token auth, when a token is configured every route requires "Authorization: Bearer <token>"