homebridge-slwf-01pro 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -7,6 +7,75 @@ This package is a maintained fork of [`homebridge-esphome-ac`](https://github.co
 
 ---
 
+## [0.3.1] — 2026-05-06
+
+Hotfix for "Out of compliance" error when adding the bridge to Apple Home.
+
+### Fixed
+
+- **Apple Home flagged the child bridge as "Out of compliance" during pairing.** Root cause: `DeviceAccessory` was constructed immediately on the ESPHome client's `'initialized'` event, but ESPHome state messages may not have arrived yet at that moment. Required HomeKit characteristics like `CurrentTemperature`, `CoolingThresholdTemperature`, and `HeatingThresholdTemperature` got `.updateValue(undefined)` calls. When Apple Home read the accessory tree during pairing, those characteristics returned `null` instead of valid floats — Apple's HAP validator rejects this as malformed metadata and refuses to pair.
+
+  Three layers of defense applied:
+  1. **Wait for first state event** — `lib/esphome.js` now defers `DeviceAccessory` construction until the climate entity has emitted at least one `'state'` event (5 s timeout fallback). For most devices this adds < 100 ms to startup; for slow-responding devices the warning logs and we proceed with safe defaults.
+  2. **Safe defaults at construction** — `addClimateService()` substitutes the visual-min/max-temperature midpoint for `CurrentTemperature` and `visualMinTemperature` for the threshold characteristics if state is still missing (defense in depth).
+  3. **`safeUpdate(characteristic, value)` helper** — wraps every characteristic update; skips the call entirely when value is `null` / `undefined` / `NaN` / `Infinity`.
+
+- **`FirmwareRevision` validation.** HAP requires the format `\d+(\.\d+){0,2}` (e.g. `2024.7.3`). ESPHome's `esphomeVersion` sometimes carries suffixes like `-dev` or `-beta`, which would have produced an invalid characteristic value. New `sanitizeFirmwareRevision(raw)` helper strips anything past the SemVer prefix; if the prefix doesn't match, the characteristic is omitted (Apple Home falls back to the plugin version).
+
+- **Primary service marked explicitly.** `addClimateService()` now calls `setPrimaryService(true)` on the `Service.HeaterCooler`. With companion DRY/FAN_ONLY/Beeper/Display Switch services on the same accessory, the absence of an explicit primary previously left the choice up to HAP-NodeJS — Apple Home iOS 16+ is stricter about this and could pick a Switch as primary, leading to a confusing accessory tile in Home.
+
+### Internal
+
+- New constants: `FIRST_STATE_TIMEOUT_MS = 5000` in `lib/esphome.js`.
+- New helpers: `isPresent(value)`, `safeUpdate(characteristic, value)`, `sanitizeFirmwareRevision(raw)` in `lib/DeviceAccessory.js`.
+
+---
+
+## [0.3.0] — 2026-05-06
+
+Final piece of the "fully independent plugin" story: HomeKit UUIDs are now namespaced so this plugin can run **alongside** upstream `homebridge-esphome-ac` (or any other plugin that hashes from the same ESPHome `unique_id`) on the same Homebridge bridge without UUID collisions.
+
+### ⚠️ Breaking — accessories will re-pair
+
+The UUID input is now `homebridge-slwf-01pro:<deviceId>` instead of bare `<deviceId>`. The same device gets a new UUID under this plugin → Apple Home treats it as a new accessory. **You'll lose room assignments, scenes, and automations** wired to the old accessory tiles. They need to be re-set up in Apple Home after the upgrade.
+
+The plugin **automatically evicts** old-schema cached accessories on startup (no manual cleanup required) and registers fresh ones with the new UUIDs.
+
+### Why
+
+Before 0.3.0, both upstream and this fork derived HomeKit UUIDs from `entity.config.uniqueId` (or its fallback). For a user with both plugins running in the **same** Homebridge bridge (not child-bridged) and both auto-discovering the same physical AC:
+
+- Upstream registers UUID `abc-123` for "Air Conditioner"
+- Our fork tries to register UUID `abc-123` too
+- HomeKit rejects the second one (UUID collision within a bridge)
+
+Child bridges (which the user is using) insulate against this — each child bridge is its own HomeKit instance — so the bug is theoretical for child-bridge users. But for users who run plugins on the main Homebridge bridge, the fix is mandatory. And it costs nothing to apply universally.
+
+After 0.3.0, the two plugins produce **deterministically different UUIDs** for the same device. Both can be installed on the same Homebridge with full auto-discovery enabled and no interaction.
+
+### Added
+
+- **`accessory.context.schemaVersion`** — stamped on every accessory created or restored. Currently `2` (1 was the unstamped pre-0.3.0 schema). Future schema breakages bump this number.
+- **`evictStaleSchemaAccessories(platform)`** in `lib/esphome.js` — runs first thing in `init()`. Walks `platform.staleAccessories` (populated by `configureAccessory` for entries with the wrong schema version) and unregisters them in one batch via `api.unregisterPlatformAccessories`. Clean cache transition with no manual user action.
+- **`UUID_NAMESPACE = 'homebridge-slwf-01pro'`** constant in `lib/DeviceAccessory.js`. Prefixed onto the device id before hashing.
+
+### Changed
+
+- **HomeKit UUID input format**: `homebridge-slwf-01pro:<deviceId>` (was bare `<deviceId>`). For devices with `unique_id` set in YAML, the old UUID was the same as upstream's; now ours is distinct. For devices without `unique_id` (the SLWF-01Pro/Midea default), the old UUID was already MAC-based via `deriveDeviceId` (added in 0.1.2); the prefix makes it distinct from upstream regardless.
+- **`configureAccessory` in `index.js`** now diverts schema-mismatched cached entries to `this.staleAccessories` and emits a warning. The init flow evicts them before doing anything else.
+
+### Migration
+
+For anyone on `homebridge-slwf-01pro@0.2.x` or earlier:
+1. `sudo npm install -g homebridge-slwf-01pro@latest`
+2. Restart Homebridge.
+3. The log shows `Evicting N cached accessor… from an older plugin schema. They will be re-registered fresh with stable UUIDs.` Old accessories disappear from Apple Home; new ones appear with the same names but no automations attached.
+4. Re-add the new accessories to your Apple Home rooms / scenes / automations.
+
+For anyone migrating from upstream: same as 0.2.0 (config.json edit `"ESPHomeAC"` → `"SLWFOnePro"`), plus the same UUID-driven re-pairing.
+
+---
+
 ## [0.2.0] — 2026-05-06
 
 Clean separation from upstream `homebridge-esphome-ac`. Breaking config change (one-line edit) but eliminates all namespace collision risk.

package/index.js

@@ -2,6 +2,7 @@ const ESPHome = require('./lib/esphome');
 
 const PLUGIN_NAME = 'homebridge-slwf-01pro';
 const PLATFORM_NAME = 'SLWFOnePro';
+const ACCESSORY_SCHEMA_VERSION = 2;
 
 class ESPHomeAC {
 	constructor(log, config, api) {
@@ -9,9 +10,11 @@ class ESPHomeAC {
 		this.log = log;
 
 		this.accessories = [];
+		this.staleAccessories = [];
 		this.esphomeDevices = {};
 		this.PLUGIN_NAME = PLUGIN_NAME;
 		this.PLATFORM_NAME = PLATFORM_NAME;
+		this.ACCESSORY_SCHEMA_VERSION = ACCESSORY_SCHEMA_VERSION;
 		this.name = config.name || PLATFORM_NAME;
 		this.devices = config.devices || [];
 		this.debug = config.debug || false;
@@ -40,6 +43,12 @@ class ESPHomeAC {
 	}
 
 	configureAccessory(accessory) {
+		const cachedVersion = accessory.context && accessory.context.schemaVersion;
+		if (cachedVersion !== ACCESSORY_SCHEMA_VERSION) {
+			this.log.warn(`Cached accessory "${accessory.displayName}" is from an older plugin schema (v${cachedVersion || 1}); will be re-registered with the current schema (v${ACCESSORY_SCHEMA_VERSION}).`);
+			this.staleAccessories.push(accessory);
+			return;
+		}
 		this.log.easyDebug(`Found cached accessory: ${accessory.displayName} (${accessory.context.deviceId || 'no id'})`);
 		this.accessories.push(accessory);
 	}

package/lib/DeviceAccessory.js

@@ -26,6 +26,9 @@ let Characteristic;
 const SET_DEBOUNCE_MS = 600;
 const PRIMARY_MODES = [ESP_MODE.COOL, ESP_MODE.HEAT, ESP_MODE.AUTO, ESP_MODE.HEAT_COOL];
 
+const UUID_NAMESPACE = 'homebridge-slwf-01pro';
+const ACCESSORY_SCHEMA_VERSION = 2;
+
 function readSensorValue(entity) {
 	if (!entity || !entity.state) return null;
 	if (entity.state.missingState) return null;
@@ -40,6 +43,24 @@ function clampRange(value, min, max) {
 	return value;
 }
 
+function isPresent(value) {
+	if (value == null) return false;
+	if (typeof value === 'number' && !Number.isFinite(value)) return false;
+	return true;
+}
+
+function safeUpdate(characteristic, value) {
+	if (!characteristic) return;
+	if (!isPresent(value)) return;
+	characteristic.updateValue(value);
+}
+
+function sanitizeFirmwareRevision(raw) {
+	if (typeof raw !== 'string' || raw.length === 0) return undefined;
+	const match = raw.match(/^\d+(?:\.\d+){0,2}/);
+	return match ? match[0] : undefined;
+}
+
 const SUPPLEMENTARY_SWITCH_KEYS = ['dryMode', 'fanOnlyMode', 'beeperSwitch', 'displaySwitch'];
 const OPTIONAL_SENSOR_KEYS = ['humiditySensor', 'outdoorTempSensor', 'powerSensor'];
 
@@ -74,7 +95,7 @@ class DeviceAccessory {
 		this.serial = this.deviceInfo.macAddress || this.id;
 		this.manufacturer = this.deviceInfo.manufacturer || 'ESPHome';
 		this.model = this.deviceInfo.model || climate.name || 'ESPHome AC';
-		this.firmwareRevision = this.deviceInfo.esphomeVersion || undefined;
+		this.firmwareRevision = sanitizeFirmwareRevision(this.deviceInfo.esphomeVersion);
 
 		this.state = climate.state || {};
 		this.connected = true;
@@ -84,12 +105,13 @@ class DeviceAccessory {
 
 		this.swingModeValue = pickDefaultSwingValue(this.config.supportedSwingModesList);
 
-		this.UUID = this.api.hap.uuid.generate(this.id);
+		this.UUID = this.api.hap.uuid.generate(`${UUID_NAMESPACE}:${this.id}`);
 		this.accessory = platform.accessories.find(acc => acc.UUID === this.UUID);
 
 		if (!this.accessory) {
 			this.log(`Creating new ESPHome AC accessory: "${this.name}"`);
 			this.accessory = new this.api.platformAccessory(this.name, this.UUID);
+			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);
@@ -97,6 +119,7 @@ class DeviceAccessory {
 			this.api.registerPlatformAccessories(platform.PLUGIN_NAME, platform.PLATFORM_NAME, [this.accessory]);
 		} else {
 			this.log(`ESPHome device "${this.name}" reconnected.`);
+			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;
@@ -155,6 +178,12 @@ class DeviceAccessory {
 		this.HeaterCoolerService = this.accessory.getService(Service.HeaterCooler)
 			|| this.accessory.addService(Service.HeaterCooler, this.name);
 
+		// Mark HeaterCooler as the accessory's primary service so Apple Home picks it
+		// for the main tile when companion Switch services (DRY/FAN_ONLY/Beeper/Display) are present.
+		if (typeof this.HeaterCoolerService.setPrimaryService === 'function') {
+			this.HeaterCoolerService.setPrimaryService(true);
+		}
+
 		this.HeaterCoolerService.getCharacteristic(Characteristic.Active)
 			.onSet(stateManager.set.Active.bind(this))
 			.updateValue(this.isModeActive(this.state.mode) ? 1 : 0);
@@ -173,27 +202,36 @@ class DeviceAccessory {
 			.onSet(stateManager.set.TargetHeaterCoolerState.bind(this))
 			.updateValue(espModeToHkTargetState(this.accessory.context.lastTargetState));
 
+		// CurrentTemperature MUST be a valid number for HAP (Apple Home flags accessories with
+		// undefined CurrentTemperature as "Out of compliance" during pairing). Default to a
+		// safe midpoint if state hasn't arrived yet.
+		const safeCurrent = isPresent(this.state.currentTemperature)
+			? this.state.currentTemperature
+			: (this.config.visualMinTemperature + this.config.visualMaxTemperature) / 2;
 		this.HeaterCoolerService.getCharacteristic(Characteristic.CurrentTemperature)
 			.setProps({ minValue: -100, maxValue: 100, minStep: 0.1 })
-			.updateValue(this.state.currentTemperature);
+			.updateValue(safeCurrent);
 
 		const tempProps = {
 			minValue: this.config.visualMinTemperature,
 			maxValue: this.config.visualMaxTemperature,
 			minStep: this.config.visualTargetTemperatureStep,
 		};
+		const safeTarget = isPresent(this.state.targetTemperature)
+			? this.clampTargetTemperature(this.state.targetTemperature)
+			: this.config.visualMinTemperature;
 
 		if (this.supportsCooling()) {
 			this.HeaterCoolerService.getCharacteristic(Characteristic.CoolingThresholdTemperature)
 				.setProps(tempProps)
 				.onSet(stateManager.set.CoolingThresholdTemperature.bind(this))
-				.updateValue(this.clampTargetTemperature(this.state.targetTemperature));
+				.updateValue(safeTarget);
 		}
 		if (this.supportsHeating()) {
 			this.HeaterCoolerService.getCharacteristic(Characteristic.HeatingThresholdTemperature)
 				.setProps(tempProps)
 				.onSet(stateManager.set.HeatingThresholdTemperature.bind(this))
-				.updateValue(this.clampTargetTemperature(this.state.targetTemperature));
+				.updateValue(safeTarget);
 		}
 
 		if (this.swingModeValue) {
@@ -202,9 +240,10 @@ class DeviceAccessory {
 				.updateValue(this.state.swingMode ? 1 : 0);
 		}
 		if (this.supportsFanControl()) {
+			const safeSpeed = fanModeToSpeed(this.state.fanMode, this.config.supportedFanModesList);
 			this.HeaterCoolerService.getCharacteristic(Characteristic.RotationSpeed)
 				.onSet(stateManager.set.RotationSpeed.bind(this))
-				.updateValue(fanModeToSpeed(this.state.fanMode, this.config.supportedFanModesList));
+				.updateValue(isPresent(safeSpeed) ? safeSpeed : 0);
 		}
 
 		this.HeaterCoolerService.getCharacteristic(Characteristic.StatusActive).updateValue(true);
@@ -430,8 +469,7 @@ class DeviceAccessory {
 		this.state = state;
 		this.syncModeSwitches(this.state.mode);
 
-		this.HeaterCoolerService.getCharacteristic(Characteristic.CurrentTemperature)
-			.updateValue(this.state.currentTemperature);
+		safeUpdate(this.HeaterCoolerService.getCharacteristic(Characteristic.CurrentTemperature), this.state.currentTemperature);
 
 		if (this.state.mode === ESP_MODE.OFF) {
 			this.HeaterCoolerService.getCharacteristic(Characteristic.Active).updateValue(0);
@@ -445,18 +483,17 @@ class DeviceAccessory {
 
 			const clampedTarget = this.clampTargetTemperature(this.state.targetTemperature);
 			if (this.supportsHeating()) {
-				this.HeaterCoolerService.getCharacteristic(Characteristic.HeatingThresholdTemperature).updateValue(clampedTarget);
+				safeUpdate(this.HeaterCoolerService.getCharacteristic(Characteristic.HeatingThresholdTemperature), clampedTarget);
 			}
 			if (this.supportsCooling()) {
-				this.HeaterCoolerService.getCharacteristic(Characteristic.CoolingThresholdTemperature).updateValue(clampedTarget);
+				safeUpdate(this.HeaterCoolerService.getCharacteristic(Characteristic.CoolingThresholdTemperature), clampedTarget);
 			}
 
 			if (this.swingModeValue) {
 				this.HeaterCoolerService.getCharacteristic(Characteristic.SwingMode).updateValue(this.state.swingMode ? 1 : 0);
 			}
 			if (this.supportsFanControl()) {
-				this.HeaterCoolerService.getCharacteristic(Characteristic.RotationSpeed)
-					.updateValue(fanModeToSpeed(this.state.fanMode, this.config.supportedFanModesList));
+				safeUpdate(this.HeaterCoolerService.getCharacteristic(Characteristic.RotationSpeed), fanModeToSpeed(this.state.fanMode, this.config.supportedFanModesList));
 			}
 
 			this.HeaterCoolerService.getCharacteristic(Characteristic.TargetHeaterCoolerState)

package/lib/esphome.js

@@ -7,6 +7,7 @@ const { bundleEntities } = require('./classifyEntity');
 
 const RECONNECT_INTERVAL_MS = 5000;
 const DEFAULT_DISCOVERY_TIMEOUT_S = 5;
+const FIRST_STATE_TIMEOUT_MS = 5000;
 
 const UPSTREAM_PLUGIN_NAME = 'homebridge-esphome-ac';
 const LEGACY_PLATFORM_NAME = 'ESPHomeAC';
@@ -60,10 +61,23 @@ function detectOrphanedAccessories(platform) {
 	}
 }
 
+function evictStaleSchemaAccessories(platform) {
+	if (!platform.staleAccessories || platform.staleAccessories.length === 0) return;
+	const stale = platform.staleAccessories.slice();
+	platform.staleAccessories = [];
+	platform.log(`Evicting ${stale.length} cached accessor${stale.length === 1 ? 'y' : 'ies'} from an older plugin schema. They will be re-registered fresh with stable UUIDs.`);
+	try {
+		platform.api.unregisterPlatformAccessories(platform.PLUGIN_NAME, platform.PLATFORM_NAME, stale);
+	} catch (err) {
+		platform.log.error(`Failed to evict stale-schema accessories: ${err.message || err}`);
+	}
+}
+
 async function init() {
 	const platform = this;
-	detectOrphanedAccessories(platform);
 	platform._clients = [];
+	evictStaleSchemaAccessories(platform);
+	detectOrphanedAccessories(platform);
 
 	const manualDevices = (platform.devices || []).map(d => ({
 		...d,
@@ -166,19 +180,47 @@ function spawnClient(platform, device) {
 		}
 
 		const displayName = device.name || (deviceInfo && deviceInfo.name) || device.host;
-		try {
-			const accessory = new DeviceAccessory({
-				device: { ...device, name: displayName },
-				deviceInfo,
-				entities: bundle,
-				platform,
-			});
-			platform.esphomeDevices[device.host] = accessory;
-			const count = Object.keys(bundle).length;
-			platform.log(`Initialized "${displayName}" with ${count} mapped entit${count === 1 ? 'y' : 'ies'}`);
-		} catch (err) {
-			platform.log.error(`Failed to initialize "${displayName}": ${err.message || err}`);
+
+		const create = () => {
+			try {
+				const accessory = new DeviceAccessory({
+					device: { ...device, name: displayName },
+					deviceInfo,
+					entities: bundle,
+					platform,
+				});
+				platform.esphomeDevices[device.host] = accessory;
+				const count = Object.keys(bundle).length;
+				platform.log(`Initialized "${displayName}" with ${count} mapped entit${count === 1 ? 'y' : 'ies'}`);
+			} catch (err) {
+				platform.log.error(`Failed to initialize "${displayName}": ${err.message || err}`);
+			}
+		};
+
+		// Wait for the climate's first state event before creating the accessory.
+		// HAP characteristic values must be defined when Apple Home pairs (otherwise → "out of compliance").
+		// 5s timeout fallback: if state never arrives, create with whatever defaults the device gives us.
+		if (bundle.climate.state && bundle.climate.state.mode != null) {
+			create();
+			return;
 		}
+
+		platform.log.easyDebug(`${displayName}: waiting for first climate state event before creating accessory…`);
+		let created = false;
+		const onState = () => {
+			if (created) return;
+			created = true;
+			clearTimeout(timer);
+			create();
+		};
+		bundle.climate.once('state', onState);
+		const timer = setTimeout(() => {
+			if (created) return;
+			created = true;
+			bundle.climate.removeListener('state', onState);
+			platform.log.warn(`${displayName}: no climate state received within ${FIRST_STATE_TIMEOUT_MS / 1000}s — creating accessory with default values.`);
+			create();
+		}, FIRST_STATE_TIMEOUT_MS);
 	});
 
 	client.connect();

package/package.json

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