homebridge-slwf-01pro 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,51 @@ This package is a maintained fork of [`homebridge-esphome-ac`](https://github.co
 
 ---
 
+## [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;
@@ -84,12 +87,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 +101,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;

package/lib/esphome.js

@@ -60,10 +60,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,

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.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nookied/homebridge-SLWF-01Pro.git"