homebridge-warmup4ie-v2 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -7,6 +7,54 @@ This package is a maintained fork of [`homebridge-warmup4ie`](https://github.com
 
 ---
 
+## [3.3.0] — 2026-05-05
+
+Roadmap [Milestone 6](ROADMAP.md) batch 1 — incremental polish. No GraphQL
+changes; everything uses data we already fetch. `config.json` unchanged.
+
+### Added
+- **`StatusFault` characteristic** on each Thermostat. Reads
+  `room.isFaultAir | isFaultFloor1 | isFaultFloor2` (data already in the
+  normalized room shape from v3.0). Surfaces sensor disconnects in
+  HomeKit's accessory diagnostics — better than mysterious wrong
+  readings. NO_FAULT (0) when clean, GENERAL_FAULT (1) when any flag set.
+- **`runMode` edge-case handling** in `state.js` for the rare modes the
+  GraphQL schema documents (`anti_frost`, `holiday`, `gradual`,
+  `fil_pilote`, `relay`, `previous`, `not_set`):
+  - `holiday` → `TargetHeatingCoolingState = OFF` (location-wide vacation
+    mode; user expectation = "off"). `Current` still tracks `currentTemp <
+    targetTemp` because heating to the holiday setpoint *is* heating.
+  - `anti_frost` → `Target = OFF` (frost protection is passive).
+    `Current` still tracks the temp delta.
+  - `gradual` (early-start ramp-up) → `Target = AUTO`.
+  - The four `not_set | fil_pilote | relay | previous` rare modes →
+    `Target = HEAT` (safe fallback; better than OFF when heating may be
+    happening).
+
+### Fixed
+- **Defensive guard against transient empty rooms.** If Warmup returns
+  `owned[0].rooms = []` (a transient API hiccup; the user almost
+  certainly didn't actually delete every thermostat in the seconds
+  between polls), `reconcileAccessories` now logs a warning and skips
+  the unregister-stale step. Without this guard, a single bad poll
+  would rip every cached accessory out of the user's HomeKit rooms /
+  scenes / automations.
+
+### Documentation
+- Per-thermostat metadata fields in `normalizeRoom` get inline comments
+  explaining what each is for and which roadmap milestone surfaces it.
+
+### Tests
+- 89 total, 86 offline + 2 live + 1 destructive (skipped). Up from 75
+  in 3.2.0. Notable additions:
+  - `state-derivers.test.js`: 8 new test cases covering every documented
+    `runMode` value (and a few unknown-mode fallbacks).
+  - `platform-state.test.js`: `StatusFault` flow (NO_FAULT initially,
+    GENERAL_FAULT after a sensor flag flips on the next poll); empty-rooms
+    defensive guard (cached accessory survives a 0-room poll response).
+
+---
+
 ## [3.2.0] — 2026-05-05
 
 Roadmap [Milestone 5](ROADMAP.md) — **Eve / fakegato history graphs.**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-warmup4ie-v2",
   "displayName": "Homebridge Warmup Wi-Fi Thermostats",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Homebridge plugin for Warmup Wi-Fi underfloor-heating thermostats (4iE, 6iE, 7iE, Element, Terra). Maintained fork of homebridge-warmup4ie with fixes for Homebridge 2.0 and the broken Off control in 0.1.0–0.1.1.",
   "main": "src/index.js",
   "scripts": {

package/src/index.js

@@ -123,6 +123,16 @@ warmup4iePlatform.prototype = {
   // register/unregister deltas to Homebridge so the on-disk cache + HomeKit
   // bridge match the Warmup account.
   reconcileAccessories: function (rooms) {
+    // Defensive: an empty rooms array is *probably* a transient Warmup
+    // hiccup (the user didn't actually delete every thermostat). Skip
+    // unregistering cached accessories — they'll show "Not Responding"
+    // until the next poll, but we don't rip their HomeKit tiles out of
+    // rooms / scenes / automations on a glitch.
+    if (rooms.length === 0 && this.accessories.size > 0) {
+      this.log.warn('Warmup returned 0 rooms but %s cached accessories exist — keeping cache untouched', this.accessories.size);
+      return;
+    }
+
     const seen = new Set();
     const toRegister = [];
 
@@ -298,6 +308,11 @@ function pushRoomState(accessory, room) {
     .updateValue(heatingState);
   thermo.getCharacteristic(Characteristic.TargetHeatingCoolingState)
     .updateValue(deriveTargetHeatingState(room));
+  // StatusFault: NO_FAULT (0) when sensors look fine, GENERAL_FAULT (1)
+  // when any of the per-thermostat fault flags is set. Calling
+  // .getCharacteristic on an optional characteristic auto-adds it.
+  thermo.getCharacteristic(Characteristic.StatusFault)
+    .updateValue(deriveStatusFault(room));
   temp.getCharacteristic(Characteristic.CurrentTemperature)
     .updateValue(Number(room.airTemp / 10));
 
@@ -410,6 +425,14 @@ function effectiveTargetTemp(room) {
   return room.targetTemp > room.minTemp ? room.targetTemp : room.minTemp;
 }
 
+// HAP StatusFault: NO_FAULT (0) | GENERAL_FAULT (1). Surfaces sensor
+// disconnects (air or floor probes) so the user gets a visible "fault" badge
+// in HomeKit's accessory diagnostics rather than mysterious wrong readings.
+function deriveStatusFault(room) {
+  const anyFault = room.isFaultAir || room.isFaultFloor1 || room.isFaultFloor2;
+  return anyFault ? Characteristic.StatusFault.GENERAL_FAULT : Characteristic.StatusFault.NO_FAULT;
+}
+
 function uuidForRoom(roomId) {
   return uuid.generate(`warmup4ie:${roomId}`);
 }

package/src/lib/state.js

@@ -5,19 +5,38 @@
 // HAP-NodeJS. Numeric values are HAP characteristic values:
 //   CurrentHeatingCoolingState: 0=OFF, 1=HEAT, 2=COOL  (we only emit 0 and 1)
 //   TargetHeatingCoolingState:  0=OFF, 1=HEAT, 2=COOL, 3=AUTO  (we only emit 0, 1, 3)
+//
+// `runMode` enum (per the GraphQL schema): not_set | off | schedule | override
+//                                          | fixed | anti_frost | holiday |
+//                                          | fil_pilote | gradual | relay | previous
 
 function deriveCurrentHeatingState(room) {
+  // OFF only when the device is genuinely off. For every other mode (including
+  // anti_frost and holiday — both still drive heating to a low setpoint) the
+  // signal is whether currentTemp is below targetTemp. Roadmap M6 will swap
+  // this for the more accurate `Thermostat4iE.parameters.outputStatus` relay
+  // signal once we re-add `parameters` to the GraphQL query.
   if (room.runMode === 'off') return 0;
   return room.currentTemp < room.targetTemp ? 1 : 0;
 }
 
 function deriveTargetHeatingState(room) {
   switch (room.runMode) {
-    case 'off': return 0;
+    case 'off':
+    case 'holiday':       // Location-wide vacation mode — user expectation: "off"
+    case 'anti_frost':    // Frost protection — passive, low setpoint
+      return 0;           // OFF
     case 'fixed':
-    case 'override': return 1;
-    case 'schedule': return 3;
-    default: return 1;
+    case 'override':
+      return 1;           // HEAT (user-set fixed temperature)
+    case 'schedule':
+    case 'gradual':       // Early-start ramp-up to the next scheduled slot
+      return 3;           // AUTO
+    default:
+      // Includes `not_set`, `fil_pilote`, `relay`, `previous` — rare modes
+      // we have no real signal on. HEAT is the safe fallback (better than
+      // showing OFF when heating is actually happening).
+      return 1;
   }
 }
 

package/src/lib/warmup4ie.js

@@ -270,9 +270,15 @@ function normalizeRoom(r) {
     fixedTemp: r.fixedTemp,
     energy: r.energy,
     cost: r.cost,
-    // Fields surfaced for future M5/M6 use (Eve energy graphs, StatusFault).
-    // M6 will additionally fetch `parameters { outputStatus }` for the
-    // real "is currently heating" relay signal — not in the query today.
+    // Per-thermostat metadata. Fault flags drive the platform's `StatusFault`
+    // characteristic (M6 batch 1). The rest are queued for follow-up:
+    //   - `floor1Temp`/`floor2Temp` — exposed as a separate sensor in M6+.
+    //   - `deviceSN` — could replace `warmup4ie-<roomId>` as SerialNumber, but
+    //     would force HomeKit to re-pair existing accessories. Not worth it.
+    //   - `lastPoll` — drives `StatusActive` (offline detection) in M6+.
+    //   - `parameters { outputStatus }` (relay state) is not in the GraphQL
+    //     query yet — re-adding caused a 409 during v3 development; M6 will
+    //     try again carefully and use it for `CurrentHeatingCoolingState`.
     floor1Temp: t.floor1Temp,
     floor2Temp: t.floor2Temp,
     isFaultAir: t.isFaultAir,