fix(homebridge): surface terminal stream health instead of staying silently stale (#116)

* fix(homebridge): surface terminal stream health instead of staying silently stale

Handle stream_error and terminal auth_failure from the account SSE stream:
correct the disconnect log (it no longer claims a reconnect is coming, since
after two consecutive auth failures the SDK stops for good), mark every
contact sensor that supports a HomeKit fault state (doors, TPMS, grid
outage, storm watch active) as faulted on terminal failure, and clear it on
the next successful connect. Core service types without an honest fault
characteristic (Lock, Switch, Thermostat, Battery) are left alone rather
than forcing an out-of-spec characteristic onto them.

* fix(homebridge): clear stream fault per-service on real data, not on bare connect

TeslemetryStream emits "connect" before consuming any SSE event, so clearing
StatusFault there showed last-known (possibly stale/default) sensor state as
healthy again with no proof fresh data had actually arrived. Each faulted
service now clears its own StatusFault only when it receives a real reading,
matching the existing "unknown/faulted until a real payload lands" pattern
already used for TPMS/grid-outage/storm-watch. DoorService didn't touch
StatusFault on data at all; it now does.

* fix(homebridge): fault lazily-created Wall Connector sensors on terminal stream failure

WallConnectorService doesn't extend BaseEnergyService (its per-DIN sensors
are created lazily), so it had no setStreamFault() and EnergyAccessory's
duck-typed fault fan-out silently skipped it - already-discovered Wall
Connector sensors kept their last cable/fault state forever instead of
reporting GENERAL_FAULT like the other stream-backed contact sensors.
Adds setStreamFault(), clearing each DIN's fault only when a fresh
live_status reading for that DIN actually arrives.

* fix(homebridge): clear StatusFault generically wherever subscribeSignal delivers real data

RearDefrostService is a ContactSensor driven entirely through the generic
subscribeSignal() path, which only ever updated the mapped characteristic -
unlike Door/TPMS/GridOutage/StormWatch, nothing cleared its StatusFault, so
once a terminal auth failure faulted it, it would stay GENERAL_FAULT forever
even after receiving current data. Clearing the fault inside subscribeSignal
itself (a no-op for service types without StatusFault) fixes this for
RearDefrost and any future ContactSensor service that uses the generic path.

Author: Bre77

.changeset/hb-stream-health.md

@@ -0,0 +1,5 @@
+---
+"homebridge-teslemetry": patch
+---
+
+Handle `stream_error` and terminal `auth_failure` from the account stream: a stream disconnect no longer logs a blanket "will attempt to reconnect" (it may be terminal), and two consecutive auth failures now mark every contact sensor that supports a HomeKit fault state (doors, TPMS, grid outage, storm watch active) as faulted instead of leaving them on their last cached value forever. A later reconnect clears the fault. See the README's Streaming Connection Issues section for recovery steps.

AGENTS.md

@@ -149,6 +149,8 @@ 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`.
+
 ### 5. `iobroker.teslemetry` - ioBroker Adapter
 
 **Location**: `packages/iobroker.teslemetry/`

packages/homebridge-teslemetry/README.md

@@ -146,6 +146,11 @@ Each energy site appears as its own set of accessories:
 3. Restart Homebridge
 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.
+
 ### Accessories Not Responding
 
 1. Check if vehicle is asleep (may take a moment to wake)

packages/homebridge-teslemetry/src/energy-services/base.ts

@@ -142,6 +142,28 @@ export abstract class BaseEnergyService {
       });
   }
 
+  /**
+   * Reflect terminal stream health as StatusFault. Only sensor-type HomeKit
+   * services (e.g. ContactSensor) declare StatusFault as optional; forcing it
+   * onto a service type that doesn't would add an out-of-spec characteristic,
+   * so those are left untouched rather than given a misleading fault signal.
+   */
+  setStreamFault(faulted: boolean): void {
+    this.applyStreamFault(this.service, faulted);
+  }
+
+  protected applyStreamFault(service: Service, faulted: boolean): void {
+    const { StatusFault } = this.platform.Characteristic;
+    // testCharacteristic() only reports characteristics already added, not
+    // ones the service type merely permits - check the declared optional
+    // list instead so a not-yet-added StatusFault still gets recognized.
+    const supportsStatusFault = service.optionalCharacteristics.some(
+      (characteristic) => characteristic.UUID === StatusFault.UUID,
+    );
+    if (!supportsStatusFault) return;
+    service.updateCharacteristic(StatusFault, faulted ? StatusFault.GENERAL_FAULT : StatusFault.NO_FAULT);
+  }
+
   /**
    * Cleanup all subscriptions
    * Should be called when the service is being removed

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

@@ -69,6 +69,29 @@ export class WallConnectorService {
       ContactSensorState,
       isConnected ? ContactSensorState.CONTACT_DETECTED : ContactSensorState.CONTACT_NOT_DETECTED,
     );
+
+    // A real reading just arrived for this DIN - clear any fault a prior
+    // terminal stream failure left set (see setStreamFault()).
+    this.applyStreamFault(services, false);
+  }
+
+  /**
+   * Reflect terminal stream health. Only DINs already discovered (i.e. with
+   * services created) can be marked - a DIN never seen has no sensors to
+   * fault yet, matching the same lazy-creation contract as everything else
+   * here.
+   */
+  setStreamFault(faulted: boolean): void {
+    for (const services of this.connectors.values()) {
+      this.applyStreamFault(services, faulted);
+    }
+  }
+
+  private applyStreamFault(services: ConnectorServices, faulted: boolean): void {
+    const { StatusFault } = this.platform.Characteristic;
+    const value = faulted ? StatusFault.GENERAL_FAULT : StatusFault.NO_FAULT;
+    services.fault.updateCharacteristic(StatusFault, value);
+    services.connected.updateCharacteristic(StatusFault, value);
   }
 
   private createConnectorServices(din: string): ConnectorServices {

packages/homebridge-teslemetry/src/energy.ts

@@ -153,6 +153,19 @@ export class EnergyAccessory {
     this.platform.log.debug(`Started stream listeners for ${this.site.name}`);
   }
 
+  /**
+   * 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).
+   */
+  setStreamFault(faulted: boolean): void {
+    for (const service of this.services) {
+      if ("setStreamFault" in service) {
+        service.setStreamFault(faulted);
+      }
+    }
+  }
+
   /**
    * Cleanup all services and stop polling/streaming
    */

packages/homebridge-teslemetry/src/platform.ts

@@ -33,6 +33,11 @@ export class TeslemetryPlatform implements DynamicPlatformPlugin {
   private teslemetry?: Teslemetry;
   private products?: Products;
 
+  // True once the stream has stopped permanently (two consecutive auth
+  // failures); cleared only by a subsequent "connect", since the SDK never
+  // reconnects on its own from this state.
+  private streamFaulted = false;
+
   // Accessory management
   private readonly accessories: PlatformAccessory[] = [];
   private readonly vehicleAccessories: Map<string, VehicleAccessory> = new Map();
@@ -152,15 +157,60 @@ export class TeslemetryPlatform implements DynamicPlatformPlugin {
       return;
     }
 
+    // "connect" fires as soon as the SSE handshake completes, before any
+    // event is consumed - clearing StatusFault here would show last-known
+    // (possibly stale/default) sensor state as healthy again with no proof
+    // fresh data has actually arrived. Each faulted service instead clears
+    // its own StatusFault the next time it receives a real payload (the
+    // same "unknown/faulted until a real reading lands" convention already
+    // used for TPMS/grid-outage/storm-watch at startup).
     this.teslemetry.sse.on("connect", () => {
-      this.log.info("✓ Streaming API connected");
+      if (this.streamFaulted) {
+        this.log.info("✓ Streaming API reconnected");
+        this.streamFaulted = false;
+      } else {
+        this.log.info("✓ Streaming API connected");
+      }
     });
 
+    // A disconnect on its own doesn't say whether the SDK will retry or has
+    // stopped for good - that distinction only arrives via stream_error/
+    // auth_failure below, so this log makes no promise either way.
     this.teslemetry.sse.on("disconnect", () => {
-      this.log.warn("✗ Streaming API disconnected - will attempt to reconnect");
+      this.log.warn("✗ Streaming API disconnected");
+    });
+
+    this.teslemetry.sse.on("stream_error", ({ error, status, retries }) => {
+      const message = error instanceof Error ? error.message : String(error);
+      this.log.warn(
+        `Streaming API error (status ${status ?? "unknown"}, attempt ${retries}): ${message}`,
+      );
+    });
+
+    this.teslemetry.sse.on("auth_failure", (error) => {
+      this.log.error(
+        "Streaming API authentication failed twice in a row and has stopped permanently - " +
+          "characteristics will no longer update. Fix the access token in this plugin's " +
+          "config and restart Homebridge to resume streaming.",
+        error,
+      );
+      this.streamFaulted = true;
+      this.markStreamFault(true);
     });
   }
 
+  /**
+   * Reflect terminal stream health on every registered vehicle/energy site.
+   */
+  private markStreamFault(faulted: boolean): void {
+    for (const vehicleAccessory of this.vehicleAccessories.values()) {
+      vehicleAccessory.setStreamFault(faulted);
+    }
+    for (const energyAccessory of this.energyAccessories.values()) {
+      energyAccessory.setStreamFault(faulted);
+    }
+  }
+
   /**
    * Register a vehicle as a HomeKit accessory
    */

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

@@ -99,6 +99,10 @@ export abstract class BaseService {
           characteristic,
           mappedValue as Nullable<CharacteristicValue>,
         );
+        // A real reading just arrived - clear any fault a prior terminal
+        // stream failure left set (see setStreamFault()). A no-op for
+        // service types that don't support StatusFault.
+        this.applyStreamFault(this.service, false);
       } catch (error) {
         this.platform.log.error(
           `Error updating characteristic for signal ${signal}:`,
@@ -158,6 +162,30 @@ export abstract class BaseService {
       });
   }
 
+  /**
+   * Reflect terminal stream health as StatusFault. Only sensor-type HomeKit
+   * services (e.g. ContactSensor) declare StatusFault as optional; forcing it
+   * onto a service type that doesn't (Lock, Switch, Thermostat, Battery)
+   * would add an out-of-spec characteristic, so those are left untouched
+   * rather than given a misleading fault signal.
+   */
+  setStreamFault(faulted: boolean): void {
+    this.applyStreamFault(this.service, faulted);
+  }
+
+  protected applyStreamFault(service: Service, faulted: boolean): void {
+    const { StatusFault } = this.platform.Characteristic;
+    // testCharacteristic() only reports characteristics already added, not
+    // ones the service type merely permits - check the declared optional
+    // list instead so a not-yet-added StatusFault (e.g. Door, which never
+    // touches it during normal operation) still gets recognized.
+    const supportsStatusFault = service.optionalCharacteristics.some(
+      (characteristic) => characteristic.UUID === StatusFault.UUID,
+    );
+    if (!supportsStatusFault) return;
+    service.updateCharacteristic(StatusFault, faulted ? StatusFault.GENERAL_FAULT : StatusFault.NO_FAULT);
+  }
+
   /**
    * Cleanup all subscriptions
    * Should be called when the service is being removed

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

@@ -95,10 +95,19 @@ export class DoorService extends BaseService {
             ? ContactSensorState.CONTACT_NOT_DETECTED // Door open
             : ContactSensorState.CONTACT_DETECTED, // Door closed
         );
+        // A real reading just arrived for this door - clear any fault a
+        // prior terminal stream failure left set (see setStreamFault()).
+        this.applyStreamFault(service, false);
       }
     }
   }
 
+  setStreamFault(faulted: boolean): void {
+    for (const service of this.doorServices.values()) {
+      this.applyStreamFault(service, faulted);
+    }
+  }
+
   /**
    * Override destroy to clean up all door services
    */

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

@@ -112,6 +112,13 @@ export class TpmsService extends BaseService {
     }
   }
 
+  setStreamFault(faulted: boolean): void {
+    super.setStreamFault(faulted);
+    for (const service of this.softWarningServices.values()) {
+      this.applyStreamFault(service, faulted);
+    }
+  }
+
   destroy(): void {
     super.destroy();
     this.softWarningServices.clear();