homebridge-slwf-01pro 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -7,6 +7,32 @@ This package is a maintained fork of [`homebridge-esphome-ac`](https://github.co
 
 ---
 
+## [0.5.4] — 2026-05-13
+
+### Fixed
+
+- **Fault indicator (⚠️) no longer persists after a Homebridge restart.** Apple Home subscribes to HAP events asynchronously after the bridge starts; when a device had a fault from the previous session, the startup `StatusFault = NO_FAULT` push arrived before Apple Home subscribed and was silently missed, leaving the ⚠️ visible until the user manually interacted with the tile. A 3-second delayed re-push (`STARTUP_FAULT_CLEAR_DELAY_MS`) after accessory construction ensures the cleared state reaches Apple Home once it has subscribed.
+- **Fault indicator no longer flashes on transient standby disconnects.** ESPHome dongles that briefly lose their TCP connection when the AC unit enters standby would immediately set `StatusFault = GENERAL_FAULT`. A 15-second grace period (`DISCONNECT_FAULT_DELAY_MS`) now absorbs brief drops: if the device reconnects within the window, no fault is ever shown. Persistent disconnects (> 15 s) still correctly surface the fault. Both new timers call `.unref()` so they don't prevent clean process exit.
+
+---
+
+## [0.5.3] — 2026-05-06
+
+### Fixed
+
+- **Heat-only / auto-only devices no longer restore an unsupported COOL mode when turned back on.** `chooseInitialTargetMode` now considers `supportedModesList`, and `Active` uses that helper for cached restore modes too.
+- **External or stale HomeKit writes for unsupported HEAT/COOL target states are ignored** instead of sending unsupported ESPHome modes.
+- **Newly-enabled companion services on cached accessories now get `ConfiguredName` seeded.** Existing Apple Home renames are still preserved, but services that did not exist in the cache yet no longer start with a blank ConfiguredName.
+- **Hostless manual device entries are non-destructive.** Empty Homebridge UI form scaffolding is dropped before orchestration, and real but invalid manual entries now keep cached accessories instead of allowing orphan pruning while the config is incomplete.
+- **Main current-temperature updates are clamped to the HAP-safe range** before writing to `CurrentTemperature`.
+- **Linked services are not re-linked redundantly** when the service is already present in HAP-NodeJS's `linkedServices` list.
+
+### Internal
+
+- Added regression coverage for capability-aware restore modes, cached-service `ConfiguredName` seeding, current-temperature clamping, manual-device filtering, and invalid-config prune protection. 159 tests total.
+
+---
+
 ## [0.5.2] — 2026-05-06
 
 ### Fixed

package/README.md

@@ -15,7 +15,7 @@ The upstream plugin works for single-device setups but has a few sharp edges tha
 - **Multi-device command coalescing.** A module-level send timeout meant changing one AC could cancel a pending command on another. Each AC now owns its own debouncer.
 - **Crash on disconnected device.** The upstream `device disconnected` error path referenced an undefined `log` symbol → `ReferenceError` instead of a clean HomeKit error. Fixed.
 - **Auto-discovery via mDNS** — listed `_esphomelib._tcp` services are picked up automatically; you don't need to type six IP addresses for six ACs.
-- **Multi-entity bundling** — humidity, outdoor temperature, power consumption, beeper, display toggle, DRY, and FAN_ONLY all show up in HomeKit when the device exposes them.
+- **Multi-entity bundling** — humidity, outdoor temperature, power consumption, beeper, display toggle, DRY, and FAN_ONLY can be exposed when the device supports them; fresh installs hide the extras by default for a clean Apple Home pairing.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full restoration story.
 
@@ -30,7 +30,7 @@ Anything that publishes a `Climate` entity over the ESPHome native API will work
 | Alpine, Pioneer, Samsung, Toshiba, Zanussi | ~30 brands total — see [smartlight.me](https://smartlight.me/smart-home-devices/wifi-devices/wifi-dongle-air-conditioners-midea-idea-electrolux-for-home-assistant) for the full list |
 | Newer 2024+ AC firmwares with proprietary protocols | May not work — check the manufacturer's compatibility notes before buying |
 
-DRY and FAN_ONLY ESPHome modes are surfaced as **companion `Switch` services** ("AC Dry", "AC Fan Only") next to the main `HeaterCooler` tile. Toggling one ON puts the AC into that mode; toggling OFF restores the previous primary mode (HEAT/COOL/AUTO). Hide via `disableDryMode` / `disableFanOnlyMode`.
+DRY and FAN_ONLY ESPHome modes can be surfaced as **companion `Switch` services** ("AC Dry", "AC Fan Only") next to the main `HeaterCooler` tile. Set `disableDryMode: false` / `disableFanOnlyMode: false` to opt in. Toggling one ON puts the AC into that mode; toggling OFF restores the previous primary mode (HEAT/COOL/AUTO).
 
 ESPHome's **custom fan modes** (`silent`, `turbo` on Midea) and **presets** (`eco`, `boost`, `sleep`, `away`) are not yet surfaced — the plugin only handles the standard fan-modes list. See [ROADMAP.md](ROADMAP.md).
 
@@ -291,7 +291,7 @@ git clone https://github.com/nookied/homebridge-SLWF-01Pro.git
 cd homebridge-SLWF-01Pro
 npm install
 npm run lint                                  # ESLint
-npm test                                      # Jest — 144 unit tests across 7 suites
+npm test                                      # Jest — 159 unit tests across 8 suites
 node -e "require('./index.js')"               # smoke test (loads cleanly)
 ```
 

package/config.schema.json

@@ -43,7 +43,7 @@
         "default": true
       },
       "disablePowerSensor": {
-        "title": "Hide Power Usage characteristic (Eve.Energy)",
+        "title": "Hide linked Power Usage service (Eve.Energy)",
         "type": "boolean",
         "default": true
       },

package/lib/DeviceAccessory.js

@@ -26,6 +26,8 @@ let Characteristic;
 const { UUID_NAMESPACE, ACCESSORY_SCHEMA_VERSION } = require('./constants');
 
 const SET_DEBOUNCE_MS = 600;
+const DISCONNECT_FAULT_DELAY_MS = 15000;
+const STARTUP_FAULT_CLEAR_DELAY_MS = 3000;
 const PRIMARY_MODES = [ESP_MODE.COOL, ESP_MODE.HEAT, ESP_MODE.AUTO, ESP_MODE.HEAT_COOL];
 
 const DEFAULT_VISUAL_MIN_TEMP = 16;
@@ -119,7 +121,7 @@ class DeviceAccessory {
 			this.accessory.context.schemaVersion = ACCESSORY_SCHEMA_VERSION;
 			this.accessory.context.deviceId = this.id;
 			this.accessory.context.host = this.host;
-			this.accessory.context.lastTargetState = chooseInitialTargetMode(this.state.mode);
+			this.accessory.context.lastTargetState = chooseInitialTargetMode(this.state.mode, this.config.supportedModesList);
 			platform.accessories.push(this.accessory);
 			this.api.registerPlatformAccessories(platform.PLUGIN_NAME, platform.PLATFORM_NAME, [this.accessory]);
 		} else {
@@ -128,7 +130,7 @@ class DeviceAccessory {
 			this.accessory.context.schemaVersion = ACCESSORY_SCHEMA_VERSION;
 			this.accessory.context.host = this.host;
 			if (PRIMARY_MODES.includes(this.state.mode)) {
-				this.accessory.context.lastTargetState = this.state.mode;
+				this.accessory.context.lastTargetState = chooseInitialTargetMode(this.state.mode, this.config.supportedModesList);
 			}
 		}
 
@@ -145,6 +147,19 @@ class DeviceAccessory {
 
 		this.esphome.on('state', this.updateClimateState.bind(this));
 		this.attachOptionalEntityListeners();
+
+		// Apple Home subscribes to HAP events asynchronously after startup.
+		// Re-push the cleared fault state after a short delay so it isn't
+		// missed if Apple Home hadn't subscribed when addClimateService ran.
+		setTimeout(() => {
+			if (this.connected !== false && this.HeaterCoolerService && Characteristic) {
+				try {
+					this.HeaterCoolerService.getCharacteristic(Characteristic.StatusActive).updateValue(true);
+					this.HeaterCoolerService.getCharacteristic(Characteristic.StatusFault)
+						.updateValue(Characteristic.StatusFault.NO_FAULT);
+				} catch (_e) { /* characteristic update on startup */ }
+			}
+		}, STARTUP_FAULT_CLEAR_DELAY_MS).unref();
 	}
 
 	linkOptionalServices() {
@@ -161,6 +176,7 @@ class DeviceAccessory {
 		for (const svc of candidates) {
 			if (!svc) continue;
 			try {
+				if (Array.isArray(this.HeaterCoolerService.linkedServices) && this.HeaterCoolerService.linkedServices.includes(svc)) continue;
 				this.HeaterCoolerService.addLinkedService(svc);
 			} catch (err) {
 				this.log.easyDebug(`linkOptionalServices: could not link ${svc.displayName}: ${err.message || err}`);
@@ -201,11 +217,10 @@ class DeviceAccessory {
 			if (service.testCharacteristic && !service.testCharacteristic(Characteristic.ConfiguredName)) {
 				service.addOptionalCharacteristic(Characteristic.ConfiguredName);
 			}
-			// Only seed ConfiguredName for newly-created accessories. For cached ones,
-			// the user may have renamed the device in Apple Home — overwriting that on
-			// every restart would clobber their choice. The HAP database keeps the
-			// previous value across restarts, so the rename persists if we leave it alone.
-			if (!this.isNewAccessory) return;
+			const configuredName = service.getCharacteristic(Characteristic.ConfiguredName);
+			// Preserve user-chosen names on cached services, but still seed ConfiguredName
+			// when a newly-enabled companion service didn't exist in the cache yet.
+			if (!this.isNewAccessory && typeof configuredName.value === 'string' && configuredName.value.length > 0) return;
 			service.setCharacteristic(Characteristic.ConfiguredName, name);
 		} catch (err) {
 			this.log.easyDebug(`setConfiguredName(${name}) failed: ${err.message || err}`);
@@ -270,7 +285,7 @@ class DeviceAccessory {
 		const visualStep = isPresent(this.config.visualTargetTemperatureStep) ? this.config.visualTargetTemperatureStep : DEFAULT_VISUAL_TEMP_STEP;
 
 		const safeCurrent = isPresent(this.state.currentTemperature)
-			? this.state.currentTemperature
+			? clampRange(this.state.currentTemperature, -100, 100)
 			: (visualMin + visualMax) / 2;
 		this.HeaterCoolerService.getCharacteristic(Characteristic.CurrentTemperature)
 			.setProps({ minValue: -100, maxValue: 100, minStep: 0.1 })
@@ -322,12 +337,31 @@ class DeviceAccessory {
 	setConnectedStatus(connected) {
 		this.connected = connected;
 		if (!this.HeaterCoolerService || !Characteristic) return;
-		try {
-			this.HeaterCoolerService.getCharacteristic(Characteristic.StatusActive).updateValue(!!connected);
-			this.HeaterCoolerService.getCharacteristic(Characteristic.StatusFault)
-				.updateValue(connected ? Characteristic.StatusFault.NO_FAULT : Characteristic.StatusFault.GENERAL_FAULT);
-		} catch (err) {
-			this.log.easyDebug(`setConnectedStatus failed for ${this.name}: ${err.message || err}`);
+		if (connected) {
+			if (this._disconnectFaultTimer) {
+				clearTimeout(this._disconnectFaultTimer);
+				this._disconnectFaultTimer = null;
+			}
+			try {
+				this.HeaterCoolerService.getCharacteristic(Characteristic.StatusActive).updateValue(true);
+				this.HeaterCoolerService.getCharacteristic(Characteristic.StatusFault)
+					.updateValue(Characteristic.StatusFault.NO_FAULT);
+			} catch (err) {
+				this.log.easyDebug(`setConnectedStatus failed for ${this.name}: ${err.message || err}`);
+			}
+		} else {
+			this._disconnectFaultTimer = setTimeout(() => {
+				this._disconnectFaultTimer = null;
+				if (!this.connected) {
+					try {
+						this.HeaterCoolerService.getCharacteristic(Characteristic.StatusActive).updateValue(false);
+						this.HeaterCoolerService.getCharacteristic(Characteristic.StatusFault)
+							.updateValue(Characteristic.StatusFault.GENERAL_FAULT);
+					} catch (err) {
+						this.log.easyDebug(`setConnectedStatus failed for ${this.name}: ${err.message || err}`);
+					}
+				}
+			}, DISCONNECT_FAULT_DELAY_MS).unref();
 		}
 	}
 
@@ -587,7 +621,7 @@ class DeviceAccessory {
 		this.state = state;
 		this.syncModeSwitches(this.state.mode);
 
-		safeUpdate(this.HeaterCoolerService.getCharacteristic(Characteristic.CurrentTemperature), this.state.currentTemperature);
+		safeUpdate(this.HeaterCoolerService.getCharacteristic(Characteristic.CurrentTemperature), clampRange(this.state.currentTemperature, -100, 100));
 
 		if (this.state.mode === ESP_MODE.OFF) {
 			this.HeaterCoolerService.getCharacteristic(Characteristic.Active).updateValue(0);

package/lib/esphome.js

@@ -79,11 +79,7 @@ async function init() {
 	evictStaleSchemaAccessories(platform);
 	detectOrphanedAccessories(platform);
 
-	const manualDevices = (platform.devices || []).map(d => ({
-		...d,
-		port: d.port || 6053,
-		discovered: false,
-	}));
+	const { manualDevices, invalidManualDeviceCount } = collectManualDevices(platform.devices || [], platform.log);
 
 	const allDevices = manualDevices.slice();
 	let discoverySucceeded = !platform.autoDiscover;
@@ -111,6 +107,11 @@ async function init() {
 	}
 
 	if (allDevices.length === 0) {
+		if (invalidManualDeviceCount > 0) {
+			platform.log.warn('No valid manual device hosts were configured. Keeping cached accessories until the device list is fixed.');
+			if (platform.autoDiscover) pruneOrphanedAccessories(platform, []);
+			return;
+		}
 		if (manualDevices.length === 0 && (!platform.autoDiscover || discoverySucceeded)) {
 			platform.log('No SLWF-01Pro / ESPHome devices configured and none discovered. Plugin will idle.');
 			pruneOrphanedAccessories(platform, []);
@@ -135,9 +136,34 @@ async function init() {
 	}
 
 	const liveHosts = allDevices.map(d => d.host).filter(Boolean);
+	if (invalidManualDeviceCount > 0 && !platform.autoDiscover) {
+		platform.log.warn('One or more manual device entries are missing a host. Skipping orphan pruning to avoid removing cached accessories while the config is invalid.');
+		return;
+	}
 	pruneOrphanedAccessories(platform, liveHosts);
 }
 
+function collectManualDevices(devices, log) {
+	const manualDevices = [];
+	let invalidManualDeviceCount = 0;
+	for (const d of devices) {
+		const device = {
+			...d,
+			port: d.port || 6053,
+			discovered: false,
+		};
+		if (device.host) {
+			manualDevices.push(device);
+			continue;
+		}
+		if (looksLikeRealEntry(device)) {
+			invalidManualDeviceCount++;
+			log.warn(`Skipping device "${device.name || '(unnamed)'}" — no host configured.`);
+		}
+	}
+	return { manualDevices, invalidManualDeviceCount };
+}
+
 function spawnClient(platform, device) {
 	const client = new Client({
 		host: device.host,
@@ -264,4 +290,4 @@ function pruneOrphanedAccessories(platform, liveHosts) {
 	}
 }
 
-module.exports = { init, pruneOrphanedAccessories, looksLikeRealEntry };
+module.exports = { init, pruneOrphanedAccessories, looksLikeRealEntry, collectManualDevices };

package/lib/state.js

@@ -79,10 +79,6 @@ function fanModeToSpeed(fanMode, fanModesList) {
 	return Math.ceil((idx + 1) * (100 / fanModesList.length));
 }
 
-function chooseInitialTargetMode(stateMode) {
-	return [ESP_MODE.COOL, ESP_MODE.HEAT, ESP_MODE.AUTO, ESP_MODE.HEAT_COOL].includes(stateMode) ? stateMode : ESP_MODE.COOL;
-}
-
 function nonEmpty(value) {
 	return typeof value === 'string' && value.length > 0;
 }
@@ -106,6 +102,22 @@ function pickAutoMode(supportedModesList) {
 	return null;
 }
 
+function chooseInitialTargetMode(stateMode, supportedModesList) {
+	const supported = Array.isArray(supportedModesList) ? supportedModesList : null;
+	const isSupported = mode => !supported || supported.includes(mode);
+
+	if ([ESP_MODE.COOL, ESP_MODE.HEAT, ESP_MODE.AUTO, ESP_MODE.HEAT_COOL].includes(stateMode) && isSupported(stateMode)) {
+		return stateMode;
+	}
+	if (supported) {
+		if (supported.includes(ESP_MODE.COOL)) return ESP_MODE.COOL;
+		if (supported.includes(ESP_MODE.HEAT)) return ESP_MODE.HEAT;
+		const autoMode = pickAutoMode(supported);
+		if (autoMode !== null) return autoMode;
+	}
+	return ESP_MODE.COOL;
+}
+
 function supportsCool(supportedModesList) {
 	if (!supportedModesList) return false;
 	return supportedModesList.includes(ESP_MODE.COOL)

package/lib/stateManager.js

@@ -1,4 +1,4 @@
-const { fanSpeedToFanMode, pickAutoMode, ESP_MODE, HK_TARGET } = require('./state');
+const { fanSpeedToFanMode, pickAutoMode, chooseInitialTargetMode, ESP_MODE, HK_TARGET } = require('./state');
 
 const ACTIVE_BATCH_MS = 100;
 const TEMP_BATCH_MS = 50;
@@ -70,7 +70,9 @@ module.exports = {
 					const wantOn = !!active;
 					const isOn = this.state.mode != null && this.state.mode !== ESP_MODE.OFF;
 					if (wantOn === isOn) return resolve();
-					this.state.mode = wantOn ? (this.accessory.context.lastTargetState || ESP_MODE.COOL) : ESP_MODE.OFF;
+					this.state.mode = wantOn
+						? chooseInitialTargetMode(this.accessory.context.lastTargetState, this.config.supportedModesList)
+						: ESP_MODE.OFF;
 					markDirty(this, 'mode');
 					this.log(`${this.name} - Setting AC Active to ${wantOn ? 'ON' : 'OFF'}`);
 					sendState(this).then(resolve).catch(reject);
@@ -80,16 +82,25 @@ module.exports = {
 
 		TargetHeaterCoolerState(hkTarget) {
 			return new Promise((resolve, reject) => {
+				const supportedModes = Array.isArray(this.config.supportedModesList) ? this.config.supportedModesList : [];
 				let espMode;
 				let logMode;
 				switch (hkTarget) {
 					case HK_TARGET.AUTO:
-						espMode = pickAutoMode(this.config.supportedModesList);
+						espMode = pickAutoMode(supportedModes);
 						if (espMode === null) return resolve();
 						logMode = espMode === ESP_MODE.HEAT_COOL ? 'HEAT_COOL' : 'AUTO';
 						break;
-					case HK_TARGET.HEAT: espMode = ESP_MODE.HEAT; logMode = 'HEAT'; break;
-					case HK_TARGET.COOL: espMode = ESP_MODE.COOL; logMode = 'COOL'; break;
+					case HK_TARGET.HEAT:
+						if (!supportedModes.includes(ESP_MODE.HEAT)) return resolve();
+						espMode = ESP_MODE.HEAT;
+						logMode = 'HEAT';
+						break;
+					case HK_TARGET.COOL:
+						if (!supportedModes.includes(ESP_MODE.COOL)) return resolve();
+						espMode = ESP_MODE.COOL;
+						logMode = 'COOL';
+						break;
 					default: return resolve();
 				}
 				if (this.state.mode === espMode) return resolve();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-slwf-01pro",
   "description": "Homebridge plugin for the SMLIGHT SLWF-01Pro Wi-Fi AC dongle. Auto-discovery, multi-entity bundling, and full Midea-protocol support over the ESPHome native API.",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nookied/homebridge-SLWF-01Pro.git"