homebridge-philips-airplus-cloud 0.3.8 → 0.3.9

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 The Home Assistant integration in `custom_components/` is unchanged from upstream and keeps its own history.
 
+## 0.3.9 — 2026-10-11
+
+- New **Allergens** sensor on models that report the Philips allergen index (AC0651/10, AC1715/11, AC3221). HomeKit has no allergen reading, so the index (1–12) is shown as a second air quality sensor: 1 Excellent, 2–3 Good, 4–6 Fair, 7–9 Inferior, 10–12 Poor. Option `allergenSensor` (default on).
+
 ## 0.3.8 — 2026-10-11
 
 - Homebridge verification: `supports-hap` keyword; config schema uses object-level `required` arrays instead of per-field `required: true`. No functional changes.

package/README.md

@@ -18,6 +18,7 @@ One accessory per purifier with:
 - **Sleep switch** — turns Sleep mode on; turning it off returns to Auto.
 - **Display light** — the purifier's display/LED as a dimmable light. It appears after the purifier first reports its light setting (property `D03104`, `D03105` or `D0312D`); devices with three light levels are detected automatically.
 - **Air Quality Sensor** — PM2.5 (µg/m³) and a HomeKit air-quality level derived from it.
+- **Allergens** — on models that report the Philips allergen index (1–12): a second air quality sensor whose level follows the index (1 Excellent, 2–3 Good, 4–6 Fair, 7–9 Inferior, 10–12 Poor). HomeKit has no allergen or pollen reading of its own.
 - **Filter Maintenance** — main filter and pre-filter (cleaning), with life level, change alert (below 10% by default) and reset from the Home app. The reset writes the same value the official app does.
 
 State changes arrive in real time over MQTT; a status poll runs every 120 s as a safety net.
@@ -77,6 +78,7 @@ The refresh token rotates on every use; the plugin keeps the current one in `<ho
 |---|---|---|
 | `devices` | all | `[{ "uuid": "…", "name": "…", "model": "AC0651/10" }]` — pick/rename devices; `model` is only needed if auto-detection fails |
 | `airQualitySensor` | `true` | Show the PM2.5 sensor |
+| `allergenSensor` | `true` | Show the allergen index as a second air quality sensor (models that report it) |
 | `filterSensors` | `true` | Show filter and pre-filter status |
 | `sleepSwitch` | `true` | Show the Sleep mode switch |
 | `sleepSwitchStyle` | `switch` | `purifier` shows the Sleep control as a second air purifier (purifier icon in Home) that only turns Sleep on/off |

package/config.schema.json

@@ -62,6 +62,12 @@
         "type": "boolean",
         "default": true
       },
+      "allergenSensor": {
+        "title": "Show allergen sensor",
+        "type": "boolean",
+        "default": true,
+        "description": "HomeKit has no allergen reading: the Philips allergen index (1–12) is shown as a second air quality sensor, 'Allergens'. Only on models that report it."
+      },
       "filterSensors": {
         "title": "Show filter and pre-filter status",
         "type": "boolean",
@@ -174,6 +180,7 @@
       "expanded": false,
       "items": [
         "airQualitySensor",
+        "allergenSensor",
         "filterSensors",
         "sleepSwitch",
         "sleepSwitchStyle",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-philips-airplus-cloud",
   "displayName": "Philips Air+",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "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

@@ -35,6 +35,19 @@ const LIGHT_KEYS = ['D03104', 'D03105', 'D0312D'];
 // Bump to re-apply default service labels once on existing accessories.
 const NAMES_VERSION = 2;
 
+/**
+ * Philips allergen index (IAI, 1-12) to a HomeKit air quality level.
+ * Philips bands: 1-3 good, 4-6 fair, 7-9 poor, 10-12 very poor.
+ */
+function allergenToAirQuality(idx) {
+  if (idx == null || Number.isNaN(idx) || idx <= 0) return 0; // UNKNOWN
+  if (idx <= 1) return 1; // EXCELLENT
+  if (idx <= 3) return 2; // GOOD
+  if (idx <= 6) return 3; // FAIR
+  if (idx <= 9) return 4; // INFERIOR
+  return 5; // POOR
+}
+
 function pm25ToAirQuality(pm) {
   if (pm == null || Number.isNaN(pm)) return 0; // UNKNOWN
   if (pm <= 12) return 1; // EXCELLENT
@@ -212,7 +225,9 @@ class PurifierAccessory {
   }
 
   _remove(type, subtype) {
-    const s = subtype ? this.accessory.getServiceById(type, subtype) : this.accessory.getService(type);
+    const s = subtype
+      ? this.accessory.getServiceById(type, subtype)
+      : this.accessory.services.find((x) => x.UUID === type.UUID && !x.subtype);
     if (s) this.accessory.removeService(s);
   }
 
@@ -263,6 +278,18 @@ class PurifierAccessory {
       this.aq = null;
     }
 
+    // --- Allergen index (HomeKit has no allergen characteristic: shown as
+    // a second air quality sensor whose level follows the Philips index)
+    if (this._prop('allergen_index') && cfg.allergenSensor !== false) {
+      const al = this._service(Service.AirQualitySensor, 'Allergens', 'allergen');
+      this.allergen = al;
+      al.getCharacteristic(Characteristic.AirQuality).onGet(() => allergenToAirQuality(this._num('allergen_index')));
+      al.getCharacteristic(Characteristic.StatusActive).onGet(() => this.conn.connected);
+    } else {
+      this._remove(Service.AirQualitySensor, 'allergen');
+      this.allergen = null;
+    }
+
     // --- Filters
     this.filters = {};
     const filterDefs = [
@@ -669,6 +696,11 @@ class PurifierAccessory {
       }
       this.aq.updateCharacteristic(Characteristic.StatusActive, this.conn.connected);
     }
+    if (this.allergen) {
+      const idx = this._num('allergen_index');
+      if (idx !== null) this.allergen.updateCharacteristic(Characteristic.AirQuality, allergenToAirQuality(idx));
+      this.allergen.updateCharacteristic(Characteristic.StatusActive, this.conn.connected);
+    }
     if (this.sleepSwitch) this.sleepSwitch.updateCharacteristic(Characteristic.On, this._isSleep());
     if (this.sleepPurifier) {
       this.sleepPurifier.updateCharacteristic(Characteristic.Active, this._isSleep() ? 1 : 0);
@@ -687,4 +719,4 @@ class PurifierAccessory {
   }
 }
 
-module.exports = { PurifierAccessory, pm25ToAirQuality, FALLBACK_MODEL };
+module.exports = { PurifierAccessory, pm25ToAirQuality, allergenToAirQuality, FALLBACK_MODEL };