homebridge-slwf-01pro 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,57 @@ This package is a maintained fork of [`homebridge-esphome-ac`](https://github.co
 
 ---
 
+## [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,7 @@
 const ESPHome = require('./lib/esphome');
 
 const PLUGIN_NAME = 'homebridge-slwf-01pro';
-const PLATFORM_NAME = 'ESPHomeAC';
+const PLATFORM_NAME = 'SLWFOnePro';
 
 class ESPHomeAC {
 	constructor(log, config, api) {

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,13 +8,61 @@ 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}`);
+	}
+}
+
 async function init() {
 	const platform = this;
+	detectOrphanedAccessories(platform);
 	platform._clients = [];
 
 	const manualDevices = (platform.devices || []).map(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.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nookied/homebridge-SLWF-01Pro.git"