homebridge-slwf-01pro 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -7,6 +7,66 @@ This package is a maintained fork of [`homebridge-esphome-ac`](https://github.co
 
 ---
 
+## [0.3.2] — 2026-05-06
+
+Config-schema polish + a regression-prevention test suite for the Homebridge UI form.
+
+### Fixed
+
+- **`config.schema.json` `name` default was stale** — `"ESPHomeAC"` left over from before the 0.2.0 platform rename to `SLWFOnePro`. New users adding the plugin via the Homebridge UI got a confusing log prefix that didn't match the platform identifier. Now defaults to `"SLWFOnePro"`.
+- **`headerDisplay` and `footerDisplay`** rewritten to mention the SLWF brand explicitly and link to the maintainer + upstream.
+
+### Added
+
+- **`test/unit/configSchema.test.js`** — 12 new tests (100 total now, up from 87) that automatically catch any future drift between the schema and the plugin code:
+  - Schema parses as valid JSON
+  - `pluginAlias` matches `PLATFORM_NAME` in `index.js` (won't silently rebrand the UI alias without rebranding the actual plugin)
+  - Every property in `schema.properties` is read by `index.js` (no dead schema fields the UI exposes but the plugin ignores)
+  - Per-device disable flags match platform-level disable flags 1:1 (so toggling a flag in the UI maps to a real code path)
+  - Layout references resolve to actual property keys (no typo'd field references in the form definition)
+  - `discoveryTimeout` condition references `autoDiscover` (so the field correctly hides when auto-discovery is off)
+  - All boolean disable flags default to `false`
+  - `name` default matches the platform identifier
+  - `discoveryTimeout` and `port` numeric constraints are sane
+
+### Why this matters
+
+The Homebridge UI form is rendered directly from `config.schema.json` by `homebridge-config-ui-x`. A typo, stale default, or unreferenced field shows up as a confused user not as a runtime error — the plugin still works, but the user's clicks don't end up where they think. The new tests fail CI if the schema drifts from the code, eliminating that whole class of silent UI bugs.
+
+### Verifying the UI is writing your config correctly
+
+After saving in the Homebridge UI, run:
+```bash
+sudo cat /var/lib/homebridge/config.json | jq '.platforms[] | select(.platform == "SLWFOnePro")'
+```
+You should see the JSON block matching what you toggled in the UI. If you toggled `disableHumiditySensor` ON for one device, expect `"disableHumiditySensor": true` under that device's block. If a UI toggle doesn't appear in this output, the UI didn't persist it.
+
+---
+
+## [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.

package/config.schema.json

@@ -2,15 +2,15 @@
   "pluginAlias": "SLWFOnePro",
   "pluginType": "platform",
   "singular": true,
-  "headerDisplay": "Homebridge plugin for ESPHome AC controllers (SLWF-01Pro Wi-Fi dongle and other ESPHome `Climate` entities). Supports auto-discovery, humidity / outdoor-temperature / power sensors, beeper / display switches, and DRY / FAN_ONLY mode tiles.",
-  "footerDisplay": "Original by @nitaybz; SLWF-01Pro fork by @nookied.",
+  "headerDisplay": "Homebridge plugin for the **SMLIGHT SLWF-01Pro** Wi-Fi dongle and other ESPHome `Climate` entities. Supports mDNS auto-discovery, multi-entity bundling (humidity / outdoor temperature / power sensors, Beeper / Display switches, DRY / FAN_ONLY mode tiles).",
+  "footerDisplay": "Maintained fork by [@nookied](https://github.com/nookied/homebridge-SLWF-01Pro). Based on `homebridge-esphome-ac` by [@nitaybz](https://github.com/nitaybz/homebridge-esphome-ac).",
   "schema": {
     "type": "object",
     "properties": {
       "name": {
         "title": "Plugin Name (for logs)",
         "type": "string",
-        "default": "ESPHomeAC",
+        "default": "SLWFOnePro",
         "required": false
       },
       "debug": {

package/lib/DeviceAccessory.js

@@ -43,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'];
 
@@ -77,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;
@@ -160,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);
@@ -178,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) {
@@ -207,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);
@@ -435,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);
@@ -450,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';
@@ -179,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.3.0",
+  "version": "0.3.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nookied/homebridge-SLWF-01Pro.git"