homebridge-philips-airplus-cloud 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 The Home Assistant integration in `custom_components/` is unchanged from upstream and keeps its own history.
 
+## 0.3.5 — 2026-10-11
+
+- Option `labelRefresh`: if the Home app does not show the labels under the purifier's components in its combined view, set any new value and restart. About 40 s after startup the plugin renames the components in two steps (long name, then short label), replaying the rename that made Home show the labels before. Names set in the Home app are replaced by the defaults.
+
+## 0.3.4 — 2026-10-11
+
+- Fix (0.3.3 regression): on Homebridge 2.x a newly created accessory could be left out of HomeKit ("has the same UUID as existing accessory … Skipping duplicate"), because its settings were saved before it was registered. Accessories are now only updated after registration.
+
 ## 0.3.3 — 2026-10-11
 
 - Fix: the plugin could stop updating when the cloud connection stayed open but stopped delivering data. If the purifier sends nothing for three status polls (at least 6 minutes), the connection is now rebuilt.

package/README.md

@@ -84,6 +84,7 @@ The refresh token rotates on every use; the plugin keeps the current one in `<ho
 | `displayLightProperty` | — | Property key of the display light, if it is not detected (see the `Status properties reported by the device` log line) |
 | `logDeviceData` | `false` | Diagnostics: at startup, log every port and the cloud shadow the purifier publishes |
 | `homekitIdentity` | — | Change to any new value to give the purifier a new HomeKit identity (use only if the Home app refuses to move or rename it; reassign the room afterwards) |
+| `labelRefresh` | — | Change to any new value if the Home app does not show the labels under the components; the plugin renames them in two steps ~40 s after startup (Home-app renames are replaced) |
 | `filterChangeThreshold` | `10` | Filter life (%) at or below which HomeKit shows "replace filter" |
 | `pollInterval` | `120` | Seconds between safety-net status polls |
 

package/config.schema.json

@@ -128,6 +128,12 @@
         "type": "string",
         "placeholder": "e.g. 2",
         "description": "Only if the Home app refuses to move or rename the purifier: type any new value (e.g. 2, then 3 next time) and restart. Home will see the purifier as a new accessory; reassign its room and check your scenes afterwards."
+      },
+      "labelRefresh": {
+        "title": "Refresh component labels (advanced)",
+        "type": "string",
+        "placeholder": "e.g. 1",
+        "description": "If the Home app does not show the labels under the purifier's components, type any new value and restart: about 40 seconds after startup the plugin renames the components in two steps so Home picks the labels up. Names you set in the Home app are replaced by the default ones."
       }
     }
   },
@@ -172,7 +178,8 @@
         "filterChangeThreshold",
         "pollInterval",
         "logDeviceData",
-        "homekitIdentity"
+        "homekitIdentity",
+        "labelRefresh"
       ]
     }
   ]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-philips-airplus-cloud",
   "displayName": "Philips Air+",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Homebridge plugin for Philips Air+ / PureProtect air purifiers via the Philips (Versuni) cloud — the same MQTT protocol used by the Air+ app and Google Home.",
   "main": "src/index.js",
   "license": "MIT",

package/src/accessory.js

@@ -90,6 +90,7 @@ class PurifierAccessory {
 
   start() {
     this.conn.start();
+    this._scheduleLabelRefresh();
     const pollS = Math.max(30, Number(this.platform.config.pollInterval) || C.STATUS_POLL_INTERVAL_S);
     // Watchdog: the cloud connection can stay open but stop delivering data.
     // Every poll asks the device for its status, so if nothing has arrived for
@@ -119,7 +120,44 @@ class PurifierAccessory {
     }, C.FILTER_POLL_INTERVAL_MS);
   }
 
+  /**
+   * labelRefresh: replays what made the Home app show labels under each
+   * component in the purifier's combined view — the plugin renaming the
+   * components while Home is connected (as the 0.2.1 update did, from
+   * "<purifier> Air Quality" to "Air Quality"). Runs once per new value.
+   * Names given in the Home app are replaced by the default labels.
+   */
+  _scheduleLabelRefresh() {
+    const want = String(this.platform.config.labelRefresh || '').trim();
+    if (!want || this.accessory.context.labelRefresh === want) return;
+    const { Characteristic } = this.hap;
+    const STEP_MS = 20000;
+    const targets = () => this.accessory.services.filter((x) => x.__label && x !== this.purifier);
+    const rename = (long) => {
+      for (const x of targets()) {
+        const name = long ? `${this.accessory.displayName} ${x.__label}` : x.__label;
+        x.updateCharacteristic(Characteristic.Name, name);
+        if (x.testCharacteristic(Characteristic.ConfiguredName)) x.updateCharacteristic(Characteristic.ConfiguredName, name);
+      }
+    };
+    this._labelTimers = [
+      setTimeout(() => {
+        if (!targets().length) return;
+        this.log.info('labelRefresh: renaming components in two steps so the Home app shows their labels');
+        rename(true);
+      }, STEP_MS),
+      setTimeout(() => {
+        if (!targets().length) return;
+        rename(false);
+        this.accessory.context.labelRefresh = want;
+        this.platform.updateAccessory(this.accessory);
+        this.log.info('labelRefresh: done');
+      }, 2 * STEP_MS),
+    ];
+  }
+
   stop() {
+    (this._labelTimers || []).forEach(clearTimeout);
     clearInterval(this.pollTimer);
     clearInterval(this.filterTimer);
     this.conn.stop();
@@ -189,6 +227,7 @@ class PurifierAccessory {
       ? this.accessory.getServiceById(type, subtype)
       : this.accessory.services.find((x) => x.UUID === type.UUID && !x.subtype);
     const s = existing || this.accessory.addService(type, label, subtype);
+    s.__label = label; // default label, used by labelRefresh (not persisted)
     // Set the label on new services, and once on services created by older
     // versions (which used long "<device> Sleep" names). Later user renames
     // made in the Home app are kept.

package/src/platform.js

@@ -37,7 +37,14 @@ class PhilipsAirPlusPlatform {
     this.cached.set(accessory.UUID, accessory);
   }
 
+  /**
+   * Persist context changes. Only for accessories Homebridge already knows:
+   * updating one that is not registered yet adds it to Homebridge's cache,
+   * and the registration that follows is then rejected as a duplicate
+   * (Homebridge 2.x), leaving the accessory out of HomeKit.
+   */
   updateAccessory(accessory) {
+    if (!this.cached.has(accessory.UUID)) return;
     this.api.updatePlatformAccessories([accessory]);
   }
 
@@ -89,6 +96,7 @@ class PhilipsAirPlusPlatform {
         const register = () => {
           this.log.info(`Adding ${dev.name}`);
           this.api.registerPlatformAccessories(C.PLUGIN_NAME, C.PLATFORM_NAME, [acc]);
+          this.cached.set(acc.UUID, acc);
         };
         if (handler.model) register();
         else handler.onModelReady = register;
@@ -103,6 +111,7 @@ class PhilipsAirPlusPlatform {
       if (stale.length) {
         this.log.info(`Removing ${stale.map((a) => a.displayName).join(', ')}`);
         this.api.unregisterPlatformAccessories(C.PLUGIN_NAME, C.PLATFORM_NAME, stale);
+        for (const a of stale) this.cached.delete(a.UUID);
       }
     }
   }