homebridge-melcloud-control 4.12.0 → 4.13.0

package/CHANGELOG.md

@@ -25,6 +25,18 @@ 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

package/README.md

@@ -444,6 +444,7 @@
   * `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).
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "displayName": "MELCloud Control",
   "name": "homebridge-melcloud-control",
-  "version": "4.12.0",
+  "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

@@ -1326,7 +1326,15 @@ class DeviceAta extends EventEmitter {
 
         try {
             await this.ha.publishEntity('climate', '', this.ha.ataClimate(capabilities));
-            await this.ha.updateState(HaDiscovery.ataState(state));
+            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}`);
         }
@@ -1658,13 +1666,15 @@ class DeviceAta extends EventEmitter {
                         supportsFanSpeed,
                         numberOfFanSpeeds,
                         supportsAutomaticFanSpeed,
-                        supportsAirDirectionFunction: supportsAirDirectionFunction && !hideVaneControls,
+                        // 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
-                    }, { power, operationMode, inStandbyMode, roomTemperature, setTemperature, setFanSpeed, vaneVerticalDirection, vaneHorizontalDirection });
+                        tempStep: temperatureStep,
+                        supportsProhibit: accountTypeMelCloud
+                    }, { power, operationMode, inStandbyMode, roomTemperature, setTemperature, setFanSpeed, vaneVerticalDirection, vaneHorizontalDirection, prohibitSetTemperature, prohibitOperationMode, prohibitPower });
 
                     //update services
                     for (const { type, value } of characteristics) {

package/src/deviceatw.js

@@ -1607,6 +1607,23 @@ class DeviceAtw extends EventEmitter {
                 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}`);
@@ -2294,13 +2311,14 @@ class DeviceAtw extends EventEmitter {
 
                     //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 }] : [])
+                        { 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 } : null;
+                    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);
 

package/src/hadiscovery.js

@@ -104,7 +104,7 @@ class HaDiscovery {
             });
         }
 
-        if (c.supportsAirDirectionFunction) {
+        if (c.supportsVaneVertical) {
             const swingModes = ['auto', '1', '2', '3', '4', '5', ...(c.supportsSwingFunction ? ['swing'] : [])];
             Object.assign(entity, {
                 swing_modes: swingModes,
@@ -156,6 +156,60 @@ class HaDiscovery {
         };
     }
 
+    // ---------------------------------------------------------------- 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}`;

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/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>"