homebridge-ecobee-security 0.2.0 → 0.4.0

package/lib/security.js

@@ -1,4 +1,5 @@
 import { ArmedState, SignInRequiredError } from './ecobee.js';
+import { VERSION } from './version.js';
 
 // HomeKit SecuritySystemCurrentState / TargetState values.
 const Hk = {
@@ -11,9 +12,11 @@ const Hk = {
 
 const HK_NAMES = ['Armed Stay', 'Armed Away', 'Armed Night', 'Disarmed', 'Alarm triggered'];
 
+// ecobee has no Night mode; with `offerNight`, Night arms Stay.
 const TO_ECOBEE = {
   [Hk.STAY]: ArmedState.STAY,
   [Hk.AWAY]: ArmedState.AWAY,
+  [Hk.NIGHT]: ArmedState.STAY,
   [Hk.DISARMED]: ArmedState.DISARMED,
 };
 
@@ -23,9 +26,12 @@ const FROM_ECOBEE = {
   [ArmedState.DISARMED]: Hk.DISARMED,
 };
 
-// Incident statuses that mean the alarm is over. Anything else counts as triggered.
+// Incident statuses that mean the alarm is over. Anything else counts as open.
 const CLOSED_INCIDENT = /RESOLV|CLOS|CANCEL|DISMISS|END|FALSE|COMPLETE|EXPIRE/i;
 
+// Entry delay (seconds) to assume when ecobee's settings don't say.
+const DEFAULT_ENTRY_DELAY = 30;
+
 const MAX_BACKOFF = 5 * 60 * 1000;
 const FAULT_AFTER = 3;
 
@@ -38,10 +44,15 @@ export class SecuritySystem {
    * @param {import('./ecobee.js').EcobeeCloud} options.cloud
    * @param {object} options.home first GraphQL home object
    * @param {number} options.pollInterval seconds
-   * @param {object} options.store persisted plugin state (`hold` lives here)
+   * @param {object} options.store persisted plugin state (`hold` and `night` live here)
    * @param {() => void} options.save persist `store`
+   * @param {boolean} [options.offerNight] offer HomeKit's Night, which arms ecobee's Stay
+   * @param {boolean} [options.alarmAfterEntryDelay] show Alarm triggered only once an intrusion
+   *   incident has outlasted the entry delay, instead of as soon as ecobee opens it
+   * @param {import('homebridge').PlatformAccessory} [options.smokeAccessory] separate accessory for a Smoke
+   *   Sensor that shows ecobee's smoke-alarm incidents (none: no smoke sensor)
    */
-  constructor({ api, log, accessory, cloud, home, pollInterval, store, save }) {
+  constructor({ api, log, accessory, cloud, home, pollInterval, store, save, offerNight = false, alarmAfterEntryDelay = false, smokeAccessory }) {
     this.api = api;
     this.store = store;
     this.save = save;
@@ -54,6 +65,10 @@ export class SecuritySystem {
     this.failures = 0;
     this.commandAt = 0;
     this.stopped = false;
+    this.offerNight = offerNight;
+    this.alarmAfterEntryDelay = alarmAfterEntryDelay;
+    this.incidents = [];
+    this.firstSeen = new Map();
 
     const { Service, Characteristic } = api.hap;
     this.C = Characteristic;
@@ -61,19 +76,49 @@ export class SecuritySystem {
     accessory.getService(Service.AccessoryInformation)
       .setCharacteristic(Characteristic.Manufacturer, 'ecobee')
       .setCharacteristic(Characteristic.Model, 'Smart Security')
-      .setCharacteristic(Characteristic.SerialNumber, home.id);
+      .setCharacteristic(Characteristic.SerialNumber, home.id)
+      .setCharacteristic(Characteristic.FirmwareRevision, VERSION);
 
-    this.service = accessory.getService(Service.SecuritySystem)
-      ?? accessory.addService(Service.SecuritySystem, accessory.displayName);
+    // HomeKit keeps a control's list of modes from when it was first published, so turning Night
+    // on or off only reaches the Home app as a new service (subtype 'night' or none). The old one
+    // is removed, which means scenes and automations that used it have to be set up again.
+    const subtype = offerNight ? 'night' : undefined;
+    const stale = accessory.services.filter(s => s.UUID === Service.SecuritySystem.UUID && s.subtype !== subtype);
+    if (stale.length) {
+      stale.forEach(s => accessory.removeService(s));
+      log.warn(`"Offer Night" was turned ${offerNight ? 'on' : 'off'}, so the security system was recreated in HomeKit `
+        + 'to show it. Set up again any Home app scenes and automations that use it.');
+    }
+    this.service = accessory.services.find(s => s.UUID === Service.SecuritySystem.UUID)
+      ?? accessory.addService(Service.SecuritySystem, accessory.displayName, subtype);
     this.service.getCharacteristic(Characteristic.SecuritySystemCurrentState)
-      .setProps({ validValues: [Hk.STAY, Hk.AWAY, Hk.DISARMED, Hk.TRIGGERED] });
+      .setProps({ validValues: offerNight ? [Hk.STAY, Hk.AWAY, Hk.NIGHT, Hk.DISARMED, Hk.TRIGGERED] : [Hk.STAY, Hk.AWAY, Hk.DISARMED, Hk.TRIGGERED] });
     this.service.getCharacteristic(Characteristic.SecuritySystemTargetState)
-      .setProps({ validValues: [Hk.STAY, Hk.AWAY, Hk.DISARMED] })
+      .setProps({ validValues: offerNight ? [Hk.STAY, Hk.AWAY, Hk.NIGHT, Hk.DISARMED] : [Hk.STAY, Hk.AWAY, Hk.DISARMED] })
       .onSet(value => this.setTarget(value));
     if (!this.service.testCharacteristic(Characteristic.StatusFault)) {
       this.service.addCharacteristic(Characteristic.StatusFault);
     }
 
+    // Smoke Sensor for ecobee's smoke-alarm detection, on its own accessory: on the security
+    // accessory the Home app merges it into the security tile. (0.4.0 test builds put it there.)
+    const merged = accessory.getService(Service.SmokeSensor);
+    if (merged) {
+      accessory.removeService(merged);
+    }
+    if (smokeAccessory) {
+      smokeAccessory.getService(Service.AccessoryInformation)
+        .setCharacteristic(Characteristic.Manufacturer, 'ecobee')
+        .setCharacteristic(Characteristic.Model, 'Smart Security smoke detection')
+        .setCharacteristic(Characteristic.SerialNumber, `${home.id}-smoke`)
+        .setCharacteristic(Characteristic.FirmwareRevision, VERSION);
+      this.smoke = smokeAccessory.getService(Service.SmokeSensor)
+        ?? smokeAccessory.addService(Service.SmokeSensor, smokeAccessory.displayName);
+      if (!this.smoke.testCharacteristic(Characteristic.StatusFault)) {
+        this.smoke.addCharacteristic(Characteristic.StatusFault);
+      }
+    }
+
     this.apply(home);
   }
 
@@ -84,6 +129,7 @@ export class SecuritySystem {
   stop() {
     this.stopped = true;
     clearTimeout(this.timer);
+    clearTimeout(this.alarmTimer);
   }
 
   schedule(delay) {
@@ -137,7 +183,9 @@ export class SecuritySystem {
 
   setFault(on) {
     const { StatusFault } = this.C;
-    this.service.updateCharacteristic(StatusFault, on ? StatusFault.GENERAL_FAULT : StatusFault.NO_FAULT);
+    const value = on ? StatusFault.GENERAL_FAULT : StatusFault.NO_FAULT;
+    this.service.updateCharacteristic(StatusFault, value);
+    this.smoke?.updateCharacteristic(StatusFault, value);
   }
 
   /** Apply a GraphQL home (or just its monitoring object) to HomeKit. */
@@ -156,10 +204,19 @@ export class SecuritySystem {
       return;
     }
 
-    const armed = FROM_ECOBEE[this.monitoring.armedState] ?? Hk.DISARMED;
+    let armed = FROM_ECOBEE[this.monitoring.armedState] ?? Hk.DISARMED;
     const desired = this.monitoring.delayedArmedState?.desiredArmedState;
-    const target = desired ? (FROM_ECOBEE[desired] ?? armed) : armed;
-    const current = this.triggered ? Hk.TRIGGERED : armed;
+    let target = desired ? (FROM_ECOBEE[desired] ?? armed) : armed;
+    // Stay that was armed as Night shows as Night until the state moves on.
+    if (this.store.night && (!this.offerNight || target !== Hk.STAY)) {
+      delete this.store.night;
+      this.save();
+    }
+    if (this.store.night) {
+      target = Hk.NIGHT;
+      armed = armed === Hk.STAY ? Hk.NIGHT : armed;
+    }
+    const current = this.alarmSounding() ? Hk.TRIGGERED : armed;
 
     const { SecuritySystemCurrentState, SecuritySystemTargetState } = this.C;
     const before = this.current;
@@ -169,17 +226,22 @@ export class SecuritySystem {
     }
     this.current = current;
     this.target = target;
-    if (this.store.hold && (target !== Hk.STAY || current === Hk.TRIGGERED)) {
-      this.log.info(`Security system changed to ${HK_NAMES[current === Hk.TRIGGERED ? current : target]} during the `
+    if (this.store.hold && (target !== Hk.STAY || this.incidents.length)) {
+      this.log.info(`Security system changed to ${HK_NAMES[this.incidents.length ? Hk.TRIGGERED : target]} during the `
         + `${this.store.hold.by} hold; it won't be put back to Away.`);
       this.dropHold();
     }
     this.service.updateCharacteristic(SecuritySystemTargetState, target);
     this.service.updateCharacteristic(SecuritySystemCurrentState, current);
+    if (this.smoke) {
+      const { SmokeDetected } = this.C;
+      const smoke = this.incidents.some(i => i.detectedSmokeAlarm);
+      this.smoke.updateCharacteristic(SmokeDetected, smoke ? SmokeDetected.SMOKE_DETECTED : SmokeDetected.SMOKE_NOT_DETECTED);
+    }
   }
 
   noteIncidents(incidents) {
-    const active = incidents.filter(i => !CLOSED_INCIDENT.test(i.status ?? ''));
+    this.incidents = incidents.filter(i => !CLOSED_INCIDENT.test(i.status ?? ''));
     const summary = JSON.stringify(incidents);
     if (summary !== this.incidentSummary) {
       if (incidents.length || this.incidentSummary !== undefined) {
@@ -187,7 +249,50 @@ export class SecuritySystem {
       }
       this.incidentSummary = summary;
     }
-    this.triggered = active.length > 0;
+    // ecobee's incidents carry no time we read, so the entry delay counts from when we first saw one.
+    const now = Date.now();
+    const ids = new Set(this.incidents.map(i => i.id));
+    this.incidents.forEach(i => this.firstSeen.has(i.id) || this.firstSeen.set(i.id, now));
+    [...this.firstSeen.keys()].filter(id => !ids.has(id)).forEach(id => this.firstSeen.delete(id));
+  }
+
+  /**
+   * Whether HomeKit should show Alarm triggered. By default any open incident counts (ecobee opens
+   * one as soon as a door opens while armed). With `alarmAfterEntryDelay` an intrusion only counts
+   * once it has outlasted the entry delay without a disarm; smoke counts at once.
+   */
+  alarmSounding() {
+    clearTimeout(this.alarmTimer);
+    if (!this.alarmAfterEntryDelay) {
+      return this.incidents.length > 0;
+    }
+    const now = Date.now();
+    const delay = this.entryDelay() * 1000;
+    let wait = Infinity;
+    for (const incident of this.incidents) {
+      const due = (incident.detectedSmokeAlarm ? 0 : this.firstSeen.get(incident.id) + delay) - now;
+      if (due <= 0) {
+        return true;
+      }
+      wait = Math.min(wait, due);
+    }
+    if (wait < Infinity && !this.stopped) {
+      // Re-check when the entry delay runs out, without waiting for the next poll.
+      this.alarmTimer = setTimeout(() => this.apply({}), wait + 100);
+    }
+    return false;
+  }
+
+  entryDelay() {
+    const settings = this.settings?.armedStateSettings;
+    const state = this.monitoring?.armedState;
+    if (state === ArmedState.AWAY) {
+      return settings?.armedAway?.entryDelayDuration ?? DEFAULT_ENTRY_DELAY;
+    }
+    if (state === ArmedState.STAY) {
+      return settings?.armedStay?.entryDelayDuration ?? DEFAULT_ENTRY_DELAY;
+    }
+    return 0;
   }
 
   exitDelay(value) {
@@ -195,14 +300,14 @@ export class SecuritySystem {
     if (value === Hk.AWAY) {
       return settings?.armedAway?.exitDelayDuration ?? 60;
     }
-    if (value === Hk.STAY) {
+    if (value === Hk.STAY || value === Hk.NIGHT) {
       return settings?.armedStay?.exitDelayDuration ?? 0;
     }
     return 0;
   }
 
   async setTarget(value) {
-    if (!TO_ECOBEE[value]) {
+    if (TO_ECOBEE[value] === undefined || (value === Hk.NIGHT && !this.offerNight)) {
       throw new this.api.hap.HapStatusError(this.api.hap.HAPStatus.INVALID_VALUE_IN_REQUEST);
     }
     if (this.store.hold) {
@@ -228,11 +333,20 @@ export class SecuritySystem {
   async arm(value, source) {
     const armedState = TO_ECOBEE[value];
     const delay = this.exitDelay(value);
-    this.log.info(`${source}: ${value === Hk.DISARMED ? 'disarm' : `arm ${armedState === ArmedState.STAY ? 'Stay' : 'Away'}`}`
+    const mode = { [Hk.STAY]: 'Stay', [Hk.AWAY]: 'Away', [Hk.NIGHT]: 'Night (ecobee Stay)' }[value];
+    this.log.info(`${source}: ${value === Hk.DISARMED ? 'disarm' : `arm ${mode}`}`
       + (delay ? ` (exit delay ${delay} s)` : ''));
     try {
       const monitoring = await this.cloud.setArmedState(this.homeId, armedState, delay);
       this.commandAt = Date.now();
+      if ((value === Hk.NIGHT) !== Boolean(this.store.night)) {
+        if (value === Hk.NIGHT) {
+          this.store.night = true;
+        } else {
+          delete this.store.night;
+        }
+        this.save();
+      }
       if (monitoring) {
         this.apply({ monitoring });
       }
@@ -252,16 +366,16 @@ export class SecuritySystem {
   /**
    * Another plugin (the robot vacuum) is about to move around the house. If the system is
    * armed Away (or arming Away), switch it to Stay and remember to put it back. Returns
-   * `{ ok, held, state }`: `ok` false means it isn't safe to start (alarm triggered, or the
-   * state isn't known yet).
+   * `{ ok, held, state }`: `ok` false means it isn't safe to start (an alarm incident is open,
+   * or the state isn't known yet).
    */
   hold(by) {
     return this.serial(async () => {
       if (!this.monitoring || this.failures >= FAULT_AFTER) {
         return { ok: false, held: false, state: 'unknown', reason: 'the security state is unknown' };
       }
-      if (this.current === Hk.TRIGGERED) {
-        return { ok: false, held: false, state: HK_NAMES[this.current], reason: 'the alarm is triggered' };
+      if (this.incidents.length) {
+        return { ok: false, held: false, state: HK_NAMES[this.current], reason: 'an alarm incident is open' };
       }
       if (this.store.hold) {
         return { ok: true, held: true, state: HK_NAMES[this.target] };
@@ -282,7 +396,7 @@ export class SecuritySystem {
       if (!this.store.hold) {
         return { released: false, state: HK_NAMES[this.target] };
       }
-      if (this.target !== Hk.STAY || this.current === Hk.TRIGGERED) {
+      if (this.target !== Hk.STAY || this.incidents.length) {
         this.log.info(`${by} is done, but the security system is ${HK_NAMES[this.current]}; leaving it.`);
         this.dropHold();
         return { released: false, state: HK_NAMES[this.target] };

package/lib/version.js

@@ -0,0 +1,4 @@
+import { readFileSync } from 'node:fs';
+
+/** The plugin version, reported to HomeKit as the accessories' firmware version. */
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-ecobee-security",
   "displayName": "ecobee Smart Security",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "ecobee Smart Security as a HomeKit security system: arm Stay / Away, disarm, alarm state (unofficial, ecobee cloud)",
   "type": "module",
   "main": "index.js",
@@ -32,9 +32,13 @@
     "index.js",
     "lib",
     "bin",
+    "homebridge-ui",
     "config.schema.json",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
-  ]
+  ],
+  "dependencies": {
+    "@homebridge/plugin-ui-utils": "^2.2.6"
+  }
 }