homebridge-slwf-01pro 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,102 @@ 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.
+
+### ⚠️ Breaking — config.json edit required
+
+The Homebridge platform identifier has been renamed from `"ESPHomeAC"` (shared with upstream) to **`"SLWFOnePro"`** (ours alone). Update your `config.json`:
+
+```diff
+- "platform": "ESPHomeAC",
++ "platform": "SLWFOnePro",
+```
+
+Restart Homebridge after the edit. The plugin detects orphaned cached accessories from the old identifier and logs a clear warning with cleanup instructions on first start.
+
+### Why
+
+Before 0.2.0, the platform identifier was shared with upstream `homebridge-esphome-ac` for "drop-in migration" compatibility. In practice this caused two real problems:
+
+1. **Cache collisions** — when both plugins were ever installed in the same Homebridge (even temporarily during a migration), accessories cached under upstream's plugin name became orphans that no live plugin claims, but the platform identifier overlap made it ambiguous which plugin "owned" them.
+2. **Confusing logs** — Homebridge's startup log lists all installed platforms by `<plugin>.<platformName>`. Both plugins claiming `ESPHomeAC` made the dependency graph unreadable.
+
+After 0.2.0, the two plugins are completely independent: separate npm names, separate platform identifiers, no shared state. Both can coexist on the same Homebridge without interfering.
+
+### Added
+
+- **`detectOrphanedAccessories(platform)` in `lib/esphome.js`.** Best-effort scan of the bridge's `cachedAccessories.<bridgeId>` files at startup. Warns about:
+  - Accessories cached under upstream `homebridge-esphome-ac`
+  - Accessories cached under our plugin name but the **legacy** `ESPHomeAC` platform identifier (i.e. pre-0.2.0 entries left after the rename)
+  Both warnings include explicit cleanup paths (Homebridge UI step + filesystem path). Best-effort — wrapped in try/catch, never throws, falls through silently if the cache directory doesn't exist or files are malformed.
+
+### Changed
+
+- **Platform identifier `ESPHomeAC` → `SLWFOnePro`** in `index.js` `PLATFORM_NAME`, `config.schema.json` `pluginAlias`, `config-sample.json`, README, CLAUDE.md, QA_TESTS.md.
+- **Upstream git remote removed** (`git remote remove upstream`). The fork is intentionally divergent. CLAUDE.md fork rules updated; if anyone needs upstream history they can re-add the remote ad-hoc.
+
+### Migration
+
+For anyone on `homebridge-slwf-01pro@0.1.x`:
+1. `sudo npm install -g homebridge-slwf-01pro@latest`
+2. Edit `config.json`: `"platform": "ESPHomeAC"` → `"platform": "SLWFOnePro"` (and the `name` field if you used the default).
+3. Restart Homebridge.
+4. Log will warn about the orphaned 0.1.x cached accessories. Clean via Homebridge UI → Settings → Remove Single Cached Accessory.
+
+For anyone migrating from upstream `homebridge-esphome-ac`:
+1. `sudo npm uninstall -g homebridge-esphome-ac && sudo npm install -g homebridge-slwf-01pro`
+2. Same `config.json` edit as above.
+3. Restart. Log warns about upstream's orphaned cache entries. Clean via UI.
+
+---
+
 ## [0.1.2] — 2026-05-06
 
 Critical bug fix surfaced by the first real-hardware test of 0.1.0/0.1.1.

package/README.md

@@ -56,8 +56,8 @@ The simplest config — auto-discover everything on the local network:
 {
   "platforms": [
     {
-      "platform": "ESPHomeAC",
-      "name": "ESPHomeAC",
+      "platform": "SLWFOnePro",
+      "name": "SLWFOnePro",
       "autoDiscover": true
     }
   ]
@@ -70,8 +70,8 @@ Or fully manual (required for encrypted devices and any device not on the same b
 {
   "platforms": [
     {
-      "platform": "ESPHomeAC",
-      "name": "ESPHomeAC",
+      "platform": "SLWFOnePro",
+      "name": "SLWFOnePro",
       "debug": false,
       "devices": [
         {
@@ -93,8 +93,8 @@ You can mix both — listed devices in `devices[]` take precedence; auto-discove
 
 | Key | Required | Default | Notes |
 |---|---|---|---|
-| `platform` | yes | — | Must be exactly `"ESPHomeAC"` (the platform identifier — same as the upstream plugin so existing configs migrate without edits) |
-| `name` | no | `ESPHomeAC` | Display name in Homebridge logs |
+| `platform` | yes | — | Must be exactly `"SLWFOnePro"` (the platform identifier — distinct from upstream `homebridge-esphome-ac`'s `"ESPHomeAC"` to guarantee no namespace collision when both plugins are installed). Pre-0.2.0 configs using `"ESPHomeAC"` need a one-line edit. |
+| `name` | no | `SLWFOnePro` | Display name in Homebridge logs |
 | `debug` | no | `false` | Surface ESPHome state-change chatter to the main log instead of `log.debug` |
 | `autoDiscover` | no | `false` | mDNS-browse for ESPHome devices on the local network and create accessories automatically. Encrypted devices still need a manual `devices[]` entry — the Noise key is not broadcast. |
 | `discoveryTimeout` | no | `5` | Seconds to wait for mDNS responses before continuing. |
@@ -184,17 +184,37 @@ If the device advertises any swing mode beyond OFF, a HomeKit Swing toggle is ex
 
 ## Migration
 
-If you're moving from the upstream `homebridge-esphome-ac`:
+### From upstream `homebridge-esphome-ac`
 
-```bash
-sudo npm uninstall -g homebridge-esphome-ac
-sudo npm install -g homebridge-slwf-01pro
-sudo systemctl restart homebridge   # or: hb-service restart
-```
+Both the npm package name AND the Homebridge platform identifier are different from upstream — that's deliberate, and it means the two plugins never share cache or namespace. Migration is two short steps:
+
+1. **Replace the package**:
+   ```bash
+   sudo npm uninstall -g homebridge-esphome-ac
+   sudo npm install -g homebridge-slwf-01pro
+   ```
+
+2. **Edit `config.json`** — change `"platform": "ESPHomeAC"` to `"platform": "SLWFOnePro"`:
+   ```jsonc
+   {
+     "platforms": [
+       {
+         "platform": "SLWFOnePro",   // ← was "ESPHomeAC"
+         "name": "SLWFOnePro",       // ← rename to match (or keep your custom name)
+         "autoDiscover": true,
+         "devices": [ /* ...same as before... */ ]
+       }
+     ]
+   }
+   ```
+
+3. **Restart Homebridge**: `sudo systemctl restart homebridge` (or via UI).
+
+The plugin will detect any cached accessories left over from upstream and **log a warning** with cleanup instructions on startup. Clean them via Homebridge UI → Settings → Remove Single Cached Accessory, or stop the (child) bridge and delete the relevant `cachedAccessories.<bridgeId>` file. The new accessories from this plugin will re-pair automatically on the next restart with stable UUIDs derived from each device's ESPHome `unique_id` (or from the MAC + `object_id` when `unique_id` isn't set).
 
-**Your `config.json` does not need changes.** The platform identifier (`"platform": "ESPHomeAC"`) is unchanged for compatibility — only the npm package name differs.
+### From a pre-0.2.0 release of this plugin
 
-If accessories appear duplicated after the migration, clear Homebridge's cached accessories from the UI (Settings → Remove Single Cached Accessory) for the orphaned ones from the old plugin. The new plugin will re-pair them automatically on the next restart with stable UUIDs derived from each device's ESPHome `entity.config.uniqueId`.
+If you upgraded from `homebridge-slwf-01pro@0.1.x`, the platform identifier rename is the only change you need to apply (step 2 above). The plugin will detect old `"ESPHomeAC"` cached entries and log a warning the same way.
 
 ## Known SLWF-01Pro quirks
 

package/config-sample.json

@@ -9,8 +9,8 @@
   "description": "Sample config for the homebridge-SLWF-01Pro fork. Pick auto-discovery OR manual devices, or both.",
   "platforms": [
     {
-      "platform": "ESPHomeAC",
-      "name": "ESPHomeAC",
+      "platform": "SLWFOnePro",
+      "name": "SLWFOnePro",
       "debug": false,
       "autoDiscover": true,
       "discoveryTimeout": 5,

package/config.schema.json

@@ -1,5 +1,5 @@
 {
-  "pluginAlias": "ESPHomeAC",
+  "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.",

package/index.js

@@ -1,7 +1,8 @@
 const ESPHome = require('./lib/esphome');
 
 const PLUGIN_NAME = 'homebridge-slwf-01pro';
-const PLATFORM_NAME = 'ESPHomeAC';
+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

@@ -1,3 +1,5 @@
+const fs = require('fs');
+const path = require('path');
 const { Client } = require('@2colors/esphome-native-api');
 const DeviceAccessory = require('./DeviceAccessory');
 const { discoverDevices } = require('./discovery');
@@ -6,14 +8,75 @@ const { bundleEntities } = require('./classifyEntity');
 const RECONNECT_INTERVAL_MS = 5000;
 const DEFAULT_DISCOVERY_TIMEOUT_S = 5;
 
+const UPSTREAM_PLUGIN_NAME = 'homebridge-esphome-ac';
+const LEGACY_PLATFORM_NAME = 'ESPHomeAC';
+
 function normalizeHost(value) {
 	if (!value) return '';
 	return value.toString().toLowerCase().replace(/\.local\.?$/, '').replace(/\.$/, '');
 }
 
+function detectOrphanedAccessories(platform) {
+	try {
+		const cacheDir = path.join(platform.api.user.persistPath(), 'accessories');
+		if (!fs.existsSync(cacheDir)) return;
+
+		const files = fs.readdirSync(cacheDir).filter(f => f.startsWith('cachedAccessories.'));
+		let upstreamCount = 0;
+		let legacyPlatformCount = 0;
+
+		for (const file of files) {
+			let content;
+			try {
+				content = JSON.parse(fs.readFileSync(path.join(cacheDir, file), 'utf8'));
+			} catch (_e) {
+				continue;
+			}
+			if (!Array.isArray(content)) continue;
+			for (const acc of content) {
+				if (!acc) continue;
+				if (acc.plugin === UPSTREAM_PLUGIN_NAME) upstreamCount++;
+				else if (acc.plugin === platform.PLUGIN_NAME && acc.platform === LEGACY_PLATFORM_NAME) legacyPlatformCount++;
+			}
+		}
+
+		if (upstreamCount > 0) {
+			platform.log.warn(
+				`Detected ${upstreamCount} cached accessor${upstreamCount === 1 ? 'y' : 'ies'} from upstream "${UPSTREAM_PLUGIN_NAME}". ` +
+				`These are orphans (this plugin is "${platform.PLUGIN_NAME}", different name). ` +
+				`Clean up via Homebridge UI → Settings → Remove Single Cached Accessory, ` +
+				`or stop Homebridge and delete cachedAccessories.* in ${cacheDir}, then restart.`
+			);
+		}
+		if (legacyPlatformCount > 0) {
+			platform.log.warn(
+				`Detected ${legacyPlatformCount} cached accessor${legacyPlatformCount === 1 ? 'y' : 'ies'} using the legacy "${LEGACY_PLATFORM_NAME}" platform identifier (pre-0.2.0). ` +
+				`The platform was renamed to "SLWFOnePro" in v0.2.0; the old entries are orphans. ` +
+				`Update your config.json (\`"platform": "SLWFOnePro"\`) and clean up via Homebridge UI → Settings → Remove Single Cached Accessory.`
+			);
+		}
+	} catch (err) {
+		platform.log.easyDebug(`Orphan detection failed (non-fatal): ${err.message || err}`);
+	}
+}
+
+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;
 	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.1.2",
+  "version": "0.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nookied/homebridge-SLWF-01Pro.git"