fix(homebridge): propagate terminal stream faults to Presence and cached Wall Connector sensors (#118)

Closes the two P2 gaps deferred from PR #116: PresenceService's
OccupancySensor services now honestly fault via setStreamFault (HAP
declares StatusFault optional on OccupancySensor, so this is not a
misleading signal), and WallConnectorService now hydrates its per-DIN
connectors map from Homebridge's persisted accessory cache at
construction so already-restored sensors are fault-checked immediately,
including a fault already raised before the accessory was constructed.

Author: Bre77

.changeset/hb-fault-followup.md

@@ -0,0 +1,5 @@
+---
+"homebridge-teslemetry": patch
+---
+
+Close two gaps left by the terminal stream health fault propagation: PresenceService's occupancy sensors now fault on a terminal stream failure and clear again once their signal reports a fresh value, and WallConnectorService's per-DIN sensors restored from Homebridge's accessory cache (before any `live_status` has arrived this run) are now hydrated and fault-checked immediately instead of being invisible to `setStreamFault()` until their first reading.

AGENTS.md

@@ -150,7 +150,9 @@ pnpm link --global n8n-nodes-teslemetry
 
 **Gotcha**: not every feature can be gated ahead of time (model/config are known synchronously; whether a given vehicle *reports* a signal at all often isn't). `PresenceService` (`vehicle-services/presence.ts`) and `WallConnectorService` (`energy-services/wall-connector.ts`) don't extend `BaseService`/`BaseEnergyService` and create zero HAP services at construction time - each sub-sensor (per presence field, per Wall Connector DIN) is created lazily the first time its signal/live_status entry actually arrives, since a field withheld by scope or simply absent hardware may never fire. Contrast this with `TpmsService`, `GridOutageService`, and `StormWatchActiveService`, which construct their `ContactSensor`s eagerly (virtually every vehicle/site has the underlying hardware) but hold `StatusFault` at `GENERAL_FAULT` until the first real payload lands, clearing it only then - never default a not-yet-received reading to "safe" by leaving a fresh `ContactSensorState` at its HAP default. Both new and existing contact-sensor mappings in this package (`DoorService`, the TPMS/grid/storm/wall-connector services above) follow one polarity convention: `CONTACT_DETECTED` = normal/quiescent (door closed, no fault, cable seated, grid up), `CONTACT_NOT_DETECTED` = triggered/abnormal (door open, fault active, cable unseated, grid down) - keep new contact sensors on this convention rather than picking polarity per-service.
 
-**Gotcha**: `BaseService`/`BaseEnergyService.setStreamFault()` (called from `VehicleAccessory`/`EnergyAccessory`/`TeslemetryPlatform` to reflect terminal account-stream health) only marks a service's `StatusFault` when that HomeKit service type actually declares it as an optional characteristic (checked via `service.optionalCharacteristics`, not `service.testCharacteristic()` - the latter only reports characteristics already added, which excludes `StatusFault` on a service like `DoorService` that never touches it during normal operation). Only sensor-type services (`ContactSensor` and similar) declare `StatusFault` at all; core control services (`LockMechanism`, `Switch`, `Thermostat`, `Battery`) don't, and forcing it onto them via `getCharacteristic()` would silently add an out-of-spec characteristic with a HAP warning - `setStreamFault()` is a no-op for those rather than inventing a misleading fault signal. Services owning more than one HAP `Service` instance (`TpmsService`, `DoorService`) override `setStreamFault()` to loop over all of them, not just the primary `this.service`.
+**Gotcha**: `BaseService`/`BaseEnergyService.setStreamFault()` (called from `VehicleAccessory`/`EnergyAccessory`/`TeslemetryPlatform` to reflect terminal account-stream health) only marks a service's `StatusFault` when that HomeKit service type actually declares it as an optional characteristic (checked via `service.optionalCharacteristics`, not `service.testCharacteristic()` - the latter only reports characteristics already added, which excludes `StatusFault` on a service like `DoorService` that never touches it during normal operation). Only sensor-type services (`ContactSensor`, `OccupancySensor`, and similar) declare `StatusFault` at all; core control services (`LockMechanism`, `Switch`, `Thermostat`, `Battery`) don't, and forcing it onto them via `getCharacteristic()` would silently add an out-of-spec characteristic with a HAP warning - `setStreamFault()` is a no-op for those rather than inventing a misleading fault signal. Services owning more than one HAP `Service` instance (`TpmsService`, `DoorService`) override `setStreamFault()` to loop over all of them, not just the primary `this.service`. `PresenceService`/`WallConnectorService` don't extend `BaseService`/`BaseEnergyService` (see above) but hand-implement the same `setStreamFault()` contract over their own lazily-created sensor maps, clearing a sensor's fault the moment its own signal/DIN reading arrives - independent of any debounce applied to the reading's *value*.
+
+**Gotcha**: `WallConnectorService`'s `connectors` map is otherwise only populated by `live_status`, so per-DIN sensors that already exist in Homebridge's persisted accessory cache from a prior run are invisible to `setStreamFault()` until this run's first `live_status` - its constructor hydrates `connectors` from any matching cached `ContactSensor` services up front (parsed off their `wall-connector-{fault,connected}-<din>` subtype) and immediately applies `TeslemetryPlatform.streamFault` (a public getter over the platform's private terminal-fault flag), so a fault already raised before this accessory was constructed still reaches them. Any other lazily-hydrated per-entity service map should follow the same hydrate-from-cache-at-construction pattern rather than assuming the live stream is the only source of a map's keys.
 
 ### 5. `iobroker.teslemetry` - ioBroker Adapter
 

packages/homebridge-teslemetry/README.md

@@ -147,9 +147,9 @@ Each energy site appears as its own set of accessories:
 4. Check firewall settings (SSE requires persistent connections)
 
 If the log shows streaming authentication failed twice in a row, the stream has stopped
-permanently (contact sensors that support a fault state, e.g. doors and TPMS, will show
-faulted). Fix the access token in your config and restart Homebridge - the plugin does not
-retry a dead token on its own.
+permanently (contact sensors and occupancy sensors that support a fault state, e.g. doors,
+TPMS, wall connectors, and presence, will show faulted). Fix the access token in your config
+and restart Homebridge - the plugin does not retry a dead token on its own.
 
 ### Accessories Not Responding
 

packages/homebridge-teslemetry/src/energy-services/wall-connector.ts

@@ -31,11 +31,41 @@ export class WallConnectorService {
     private readonly accessory: PlatformAccessory,
     private readonly site: EnergyDetails,
   ) {
+    // Per-DIN services from a prior run persist in Homebridge's accessory
+    // cache, but `connectors` was otherwise only ever populated by
+    // live_status - hydrate it from any already-cached services up front so
+    // a setStreamFault() call this run (including one that already happened
+    // before this accessory was constructed) reaches them too.
+    this.hydrateFromCache();
+    if (this.platform.streamFault) {
+      this.setStreamFault(true);
+    }
+
     const listener = (data: any) => this.handleLiveStatus(data);
     this.site.api.on("liveStatus", listener);
     this.cleanupFunctions.push(() => this.site.api.off("liveStatus", listener));
   }
 
+  private hydrateFromCache(): void {
+    const faultPrefix = "wall-connector-fault-";
+    const connectedPrefix = "wall-connector-connected-";
+
+    for (const service of this.accessory.services) {
+      if (service.UUID !== this.platform.Service.ContactSensor.UUID) continue;
+      const subtype = service.subtype;
+      if (!subtype) continue;
+
+      const din = subtype.startsWith(faultPrefix)
+        ? subtype.slice(faultPrefix.length)
+        : subtype.startsWith(connectedPrefix)
+          ? subtype.slice(connectedPrefix.length)
+          : undefined;
+      if (din === undefined || this.connectors.has(din)) continue;
+
+      this.connectors.set(din, this.createConnectorServices(din));
+    }
+  }
+
   private handleLiveStatus(data: any): void {
     const connectors = data?.response?.wall_connectors;
     if (!Array.isArray(connectors)) return;

packages/homebridge-teslemetry/src/energy.ts

@@ -155,8 +155,7 @@ export class EnergyAccessory {
 
   /**
    * Reflect terminal stream health across every service that has an honest
-   * HomeKit fault characteristic (WallConnectorService's lazily-created
-   * sensors don't implement this and are skipped).
+   * HomeKit fault characteristic.
    */
   setStreamFault(faulted: boolean): void {
     for (const service of this.services) {

packages/homebridge-teslemetry/src/platform.ts

@@ -38,6 +38,14 @@ export class TeslemetryPlatform implements DynamicPlatformPlugin {
   // reconnects on its own from this state.
   private streamFaulted = false;
 
+  /** Current terminal-stream-fault state, so a service constructed after the
+   *  fault was raised (e.g. hydrating services from Homebridge's persisted
+   *  accessory cache) can apply it immediately instead of waiting for the
+   *  next markStreamFault() call that will never come until reconnect. */
+  get streamFault(): boolean {
+    return this.streamFaulted;
+  }
+
   // Accessory management
   private readonly accessories: PlatformAccessory[] = [];
   private readonly vehicleAccessories: Map<string, VehicleAccessory> = new Map();

packages/homebridge-teslemetry/src/vehicle-services/presence.ts

@@ -75,6 +75,11 @@ export class PresenceService {
 
     const service = this.services.get(definition.field)!;
 
+    // The signal just arrived, proving the stream is alive right now -
+    // clear any fault independent of the debounced occupancy transition
+    // below, which only governs when the *value* change is applied.
+    this.applyStreamFault(service, false);
+
     const existingTimer = this.pendingTimers.get(definition.field);
     if (existingTimer) clearTimeout(existingTimer);
 
@@ -97,6 +102,7 @@ export class PresenceService {
 
     service.setCharacteristic(this.platform.Characteristic.Name, displayName);
     this.applyOccupancy(service, initialValue);
+    this.applyStreamFault(service, false);
     return service;
   }
 
@@ -108,6 +114,25 @@ export class PresenceService {
     );
   }
 
+  /**
+   * Reflect terminal stream health on every occupancy sensor created so far.
+   * OccupancySensor declares StatusFault as an optional characteristic, so
+   * this is an honest signal (same convention as the contact-sensor-backed
+   * services) - a sensor not yet created (its field has never reported a
+   * value) has nothing to fault and is simply skipped, the same as every
+   * other lazily-created sensor in this package.
+   */
+  setStreamFault(faulted: boolean): void {
+    for (const service of this.services.values()) {
+      this.applyStreamFault(service, faulted);
+    }
+  }
+
+  private applyStreamFault(service: Service, faulted: boolean): void {
+    const { StatusFault } = this.platform.Characteristic;
+    service.updateCharacteristic(StatusFault, faulted ? StatusFault.GENERAL_FAULT : StatusFault.NO_FAULT);
+  }
+
   private getDisplayName(serviceName: string): string {
     if (this.platform.config.prefixName !== false) {
       return `${this.vehicle.name} ${serviceName}`;

packages/homebridge-teslemetry/src/vehicle.ts

@@ -138,8 +138,7 @@ export class VehicleAccessory {
 
   /**
    * Reflect terminal stream health across every service that has an honest
-   * HomeKit fault characteristic (PresenceService's lazily-created sensors
-   * don't implement this and are skipped).
+   * HomeKit fault characteristic.
    */
   setStreamFault(faulted: boolean): void {
     for (const service of this.services) {

packages/homebridge-teslemetry/test/fakePlatform.ts

@@ -18,7 +18,10 @@ export function createFakeAccessory(displayName = "Test Vehicle"): PlatformAcces
 	return accessory as unknown as PlatformAccessory;
 }
 
-export function createFakePlatform(config: Record<string, unknown> = {}): {
+export function createFakePlatform(
+	config: Record<string, unknown> = {},
+	options: { streamFault?: boolean } = {},
+): {
 	platform: TeslemetryPlatform;
 	logs: LogEntry[];
 } {
@@ -31,6 +34,7 @@ export function createFakePlatform(config: Record<string, unknown> = {}): {
 		Service,
 		Characteristic,
 		config,
+		streamFault: options.streamFault ?? false,
 		log: {
 			info: log("info"),
 			warn: log("warn"),

packages/homebridge-teslemetry/test/presence.test.ts

@@ -85,6 +85,30 @@ test("a non-boolean signal value is ignored without throwing", () => {
 	assert.doesNotThrow(() => sse.emitSignal("LocatedAtHome", null));
 });
 
+test("setStreamFault(true) faults every discovered sensor; a fresh signal for it clears it", () => {
+	const { accessory, sse, presence } = setup();
+	sse.emitSignal("LocatedAtHome", true);
+	const home = accessory.getServiceById(Service.OccupancySensor, "presence-home")!;
+
+	presence.setStreamFault(true);
+	assert.equal(
+		home.getCharacteristic(Characteristic.StatusFault).value,
+		Characteristic.StatusFault.GENERAL_FAULT,
+	);
+
+	sse.emitSignal("LocatedAtHome", true);
+	assert.equal(
+		home.getCharacteristic(Characteristic.StatusFault).value,
+		Characteristic.StatusFault.NO_FAULT,
+	);
+});
+
+test("setStreamFault(true) has nothing to fault before any signal has been discovered", () => {
+	const { accessory, presence } = setup();
+	assert.doesNotThrow(() => presence.setStreamFault(true));
+	assert.equal(accessory.services.filter((s) => s.UUID === Service.OccupancySensor.UUID).length, 0);
+});
+
 test("destroy() detaches signal subscriptions and clears pending debounce timers", (t) => {
 	t.mock.timers.enable({ apis: ["setTimeout"] });
 	const { sse, presence } = setup();