homebridge-ecobee-security 0.4.2 → 0.7.0

package/lib/security.js

@@ -1,4 +1,5 @@
 import { ArmedState, SignInRequiredError } from './ecobee.js';
+import { sendHalt } from './halt.js';
 import { VERSION } from './version.js';
 
 // HomeKit SecuritySystemCurrentState / TargetState values.
@@ -33,6 +34,8 @@ const CLOSED_INCIDENT = /RESOLV|CLOS|CANCEL|DISMISS|END|FALSE|COMPLETE|EXPIRE/i;
 const DEFAULT_ENTRY_DELAY = 30;
 
 const MAX_BACKOFF = 5 * 60 * 1000;
+// Robots back (or stopped) before an extended exit delay ends: arm this long after, at the earliest.
+const ARM_AFTER_RETURN = 10 * 1000;
 const FAULT_AFTER = 3;
 
 export class SecuritySystem {
@@ -44,7 +47,7 @@ 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` and `night` live here)
+   * @param {object} options.store persisted plugin state (`hold`, `out` 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
@@ -52,7 +55,8 @@ export class SecuritySystem {
    * @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, offerNight = false, alarmAfterEntryDelay = false, smokeAccessory }) {
+  constructor({ api, log, accessory, cloud, home, pollInterval, store, save, offerNight = false, alarmAfterEntryDelay = false,
+    returnWait = 120, smokeAccessory }) {
     this.api = api;
     this.store = store;
     this.save = save;
@@ -67,6 +71,8 @@ export class SecuritySystem {
     this.stopped = false;
     this.offerNight = offerNight;
     this.alarmAfterEntryDelay = alarmAfterEntryDelay;
+    // Extra exit-delay time for robots heading back to their base when Away is armed (ms).
+    this.returnWait = Math.max(0, returnWait) * 1000;
     this.incidents = [];
     this.firstSeen = new Map();
 
@@ -228,10 +234,23 @@ export class SecuritySystem {
     this.target = target;
     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.holders().join(' and ')} hold; it won't be put back to Away.`);
       this.dropHold();
     }
-    this.service.updateCharacteristic(SecuritySystemTargetState, target);
+    // Armed Away some other way (the ecobee app, the keypad, Arm Away Now) with robots out: send them
+    // back before the exit delay ends (a keypad's is only seen once armed: stop them now).
+    if (target === Hk.AWAY && this.outNames().length) {
+      const until = Date.parse(this.monitoring.delayedArmedState?.delayedUntil ?? '');
+      const why = `The security system ${until > Date.now() ? 'is arming' : 'was armed'} Away`;
+      this.serial(() => this.haltRobots(why, until > Date.now() ? until : undefined)).catch(() => {});
+    }
+    // Waiting for robots on their way back: over once Away is armed or no longer asked for.
+    if (this.store.returning && (target !== Hk.AWAY || armed === Hk.AWAY)) {
+      delete this.store.returning;
+      this.save();
+    }
+    // Away asked for in the Home app during a hold waits for the release: show it as arming Away.
+    this.service.updateCharacteristic(SecuritySystemTargetState, this.store.hold?.away ? Hk.AWAY : target);
     this.service.updateCharacteristic(SecuritySystemCurrentState, current);
     if (this.smoke) {
       const { SmokeDetected } = this.C;
@@ -310,8 +329,13 @@ export class SecuritySystem {
     if (TO_ECOBEE[value] === undefined || (value === Hk.NIGHT && !this.offerNight)) {
       throw new this.api.hap.HapStatusError(this.api.hap.HAPStatus.INVALID_VALUE_IN_REQUEST);
     }
+    // HomeKit can't say who asked (requests come through the home hub), so Away always waits for
+    // robots that are out; the Arm Away Now switch is the way to stop them and arm now.
+    if (value === Hk.AWAY && this.outNames().length && await this.serial(() => this.deferAway())) {
+      return;
+    }
     if (this.store.hold) {
-      this.log.info(`Home app changed the security system during the ${this.store.hold.by} hold; it won't be put back to Away.`);
+      this.log.info(`Home app changed the security system during the ${this.holders().join(' and ')} hold; it won't be put back to Away.`);
       this.dropHold();
     }
     try {
@@ -323,6 +347,166 @@ export class SecuritySystem {
     }
   }
 
+
+  /**
+   * Away from the Home app while robots are out (say, a scene run from far away while one cleans):
+   * the release arms Away anyway, so keep (or start) the hold and let it; Stay meanwhile. Returns
+   * true if Away now waits.
+   */
+  async deferAway() {
+    const out = this.outNames();
+    if (!out.length || this.incidents.length || (this.store.hold && this.target !== Hk.STAY)) {
+      return false;
+    }
+    if (!this.store.hold) {
+      // The robots started while the system wasn't Away, so nothing holds Stay for them yet.
+      if (this.target !== Hk.STAY || this.store.night) {
+        await this.arm(Hk.STAY, `${out.join(' and ')} out`);
+      }
+      this.store.hold = { by: out, since: new Date().toISOString() };
+    }
+    this.store.hold = { ...this.store.hold, away: true };
+    this.save();
+    this.log.info(`Home app: arm Away — waiting until ${this.holders().join(' and ')} ${this.holders().length > 1 ? 'are' : 'is'} done (security hold). `
+      + 'Use the Arm Away Now switch to stop and arm now.');
+    this.service.updateCharacteristic(this.C.SecuritySystemTargetState, Hk.AWAY);
+    return true;
+  }
+
+  /**
+   * The Arm Away Now switch: drop the hold and arm Away (normal exit delay); apply() then sends
+   * robots that are out back to their base (or stops them), as for Away from the ecobee app.
+   */
+  armAwayNow() {
+    return this.serial(async () => {
+      if (this.store.hold) {
+        this.dropHold();
+      }
+      await this.arm(Hk.AWAY, 'Arm Away Now');
+    });
+  }
+
+
+  /**
+   * A door was unlocked with its keypad: disarm, like Nest Guard with a Nest × Yale lock. Always sent,
+   * even if the last poll said Off: it may be up to 10 s old, and disarming twice does no harm.
+   * Retried once, since a missed disarm means an alarm.
+   */
+  keypadDisarm(lock) {
+    return this.serial(async () => {
+      if (this.store.hold) {
+        this.log.info(`${lock} was unlocked during the ${this.holders().join(' and ')} hold; it won't be put back to Away.`);
+        this.dropHold();
+      }
+      try {
+        await this.arm(Hk.DISARMED, `${lock} unlocked with its keypad`);
+      } catch {
+        await new Promise(resolve => setTimeout(resolve, 2000));
+        await this.arm(Hk.DISARMED, `${lock} unlocked with its keypad (retry)`);
+      }
+    });
+  }
+
+  /** Robots (or other plugins) that asked for a hold and haven't released yet, held or not. */
+  outNames() {
+    return Object.keys(this.store.out ?? {});
+  }
+
+  /**
+   * The system is being armed Away with robots out. With `armAt` (when the motion sensors arm, the
+   * end of the exit delay), each robot heads back to its base if it can make it and stops where it
+   * is if it doesn't; without it, it stops now (pause, not dock). They're forgotten and the hold
+   * dropped right away; a robot that moves again asks for a new hold.
+   *
+   * Wait for them: ecobee accepts a later end for an exit delay that's counting down, so it's pushed
+   * back by `returnWait`, and brought forward again (never before `armAt`) once every robot that
+   * headed back has said it's in, or stopped (`/release`).
+   */
+  async haltRobots(reason, armAt) {
+    const out = Object.entries(this.store.out ?? {});
+    if (!out.length) {
+      return;
+    }
+    delete this.store.out;
+    if (this.store.hold) {
+      this.dropHold();
+    }
+    this.save();
+    if (armAt && this.returnWait > 0 && out.some(([, robot]) => robot.halt)) {
+      try {
+        await this.setExitDelayEnd(armAt + this.returnWait);
+        this.log.info(`Exit delay extended by ${Math.round(this.returnWait / 1000)} s so robots can get back to their base.`);
+        armAt += this.returnWait;
+        this.store.returning = { armAt: armAt - this.returnWait, names: [] };
+        this.save();
+      } catch (error) {
+        this.log.warn(`Could not extend the exit delay (${error.message}); robots have until it ends as usual.`);
+      }
+    }
+    const names = out.map(([by]) => by).join(' and ');
+    this.log.info(armAt ? `${reason}: asking ${names} to be back at base or stopped by ${new Date(armAt).toLocaleTimeString()}.`
+      : `${reason}: asking ${names} to stop.`);
+    await Promise.all(out.map(async ([by, robot]) => {
+      if (!robot.halt) {
+        this.log.warn(`${by} can't be asked to stop (${robot.plugin ?? 'its plugin'} doesn't support it); it may set off the motion sensors.`);
+        return;
+      }
+      try {
+        const result = await sendHalt(robot.halt, by, armAt);
+        const what = result.returning ? 'heading back to its base' : result.halted ? 'stopped' : `not stopped (${result.reason ?? 'no reason given'})`;
+        this.log[result.halted ? 'info' : 'warn'](`${by}: ${what}.`);
+        if (result.returning && this.store.returning) {
+          this.store.returning.names.push(by);
+          this.save();
+        }
+      } catch (error) {
+        this.log.warn(`Could not ask ${by} to stop (${error.message}); it may set off the motion sensors.`);
+      }
+    }));
+    if (this.store.returning && !this.store.returning.names.length) {
+      await this.armWhenBack('No robot is heading back');
+    }
+  }
+
+  /** Robots that were sent back to their base and haven't said they're in yet. */
+  returningNames() {
+    return this.store.returning?.names ?? [];
+  }
+
+  /**
+   * Every robot that headed back is in (or stopped): bring the end of the extended exit delay forward
+   * again, to its original end, or a few seconds from now if that has passed.
+   */
+  async armWhenBack(why) {
+    const { armAt } = this.store.returning;
+    delete this.store.returning;
+    this.save();
+    const delayed = this.monitoring?.delayedArmedState;
+    if (this.monitoring?.armedState === ArmedState.AWAY || delayed?.desiredArmedState !== ArmedState.AWAY) {
+      return;
+    }
+    const until = Math.max(armAt, Date.now() + ARM_AFTER_RETURN);
+    if (until >= Date.parse(delayed.delayedUntil ?? '')) {
+      return;
+    }
+    this.log.info(`${why}: arming Away at ${new Date(until).toLocaleTimeString()}.`);
+    try {
+      await this.setExitDelayEnd(until);
+    } catch (error) {
+      this.log.warn(`Could not bring the exit delay forward (${error.message}); it ends as extended.`);
+    }
+  }
+
+  /** Move the end of an Away exit delay (ecobee takes a new end while it counts down). */
+  async setExitDelayEnd(until) {
+    const monitoring = await this.cloud.setArmedState(this.homeId, ArmedState.AWAY, 0, until);
+    this.commandAt = Date.now();
+    if (monitoring) {
+      this.apply({ monitoring });
+    }
+    this.schedule(2000);
+  }
+
   /** Run hold/release/Home app commands one at a time. */
   serial(fn) {
     const run = this.queue.then(fn, fn);
@@ -358,34 +542,69 @@ export class SecuritySystem {
     }
   }
 
+  /** Read the state now (for hold decisions). Resolves false if ecobee can't be read. */
+  async refresh() {
+    try {
+      const home = (await this.cloud.getHomes()).find(h => h.id === this.homeId);
+      if (!home) {
+        throw new Error('the home is no longer on this ecobee account');
+      }
+      this.apply(home);
+      return true;
+    } catch (error) {
+      this.log.warn(`Could not read the security state for a hold (${error.message}).`);
+      return false;
+    }
+  }
+
   dropHold() {
     delete this.store.hold;
     this.save();
   }
 
+  /** Who is holding Stay (several robots can be out at once). Up to 0.4.x `by` was a single name. */
+  holders() {
+    const by = this.store.hold?.by;
+    return Array.isArray(by) ? by : by ? [by] : [];
+  }
+
   /**
    * 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 (an alarm incident is open,
    * or the state isn't known yet).
    */
-  hold(by) {
+  hold(by, { plugin, halt } = {}) {
     return this.serial(async () => {
-      if (!this.monitoring || this.failures >= FAULT_AFTER) {
+      // Decide on ecobee's live state, not the last poll: a disarm moments ago must not become a Stay.
+      if (!(await this.refresh()) || !this.monitoring) {
         return { ok: false, held: false, state: 'unknown', reason: 'the security state is unknown' };
       }
       if (this.incidents.length) {
         return { ok: false, held: false, state: HK_NAMES[this.current], reason: 'an alarm incident is open' };
       }
+      // Remember who's out (and how to stop them) until they release, held or not. Only once Stay is
+      // decided: a poll seeing Away in between would otherwise stop this very robot.
+      const noteOut = () => {
+        this.store.out = { ...this.store.out, [by]: { plugin, halt, since: this.store.out?.[by]?.since ?? new Date().toISOString() } };
+        this.save();
+      };
       if (this.store.hold) {
+        if (!this.holders().includes(by)) {
+          this.store.hold = { ...this.store.hold, by: [...this.holders(), by] };
+          this.save();
+          this.log.info(`${by} joined the hold; Away comes back once ${this.holders().join(' and ')} are done.`);
+        }
+        noteOut();
         return { ok: true, held: true, state: HK_NAMES[this.target] };
       }
       if (this.target !== Hk.AWAY) {
+        noteOut();
         return { ok: true, held: false, state: HK_NAMES[this.target] };
       }
       await this.arm(Hk.STAY, `${by} hold`);
-      this.store.hold = { by, since: new Date().toISOString() };
-      this.save();
+      this.store.hold = { by: [by], since: new Date().toISOString() };
+      noteOut();
       return { ok: true, held: true, state: HK_NAMES[this.target] };
     });
   }
@@ -393,9 +612,37 @@ export class SecuritySystem {
   /** The vacuum is back: put the system back to Away if we moved it and nobody has changed it since. */
   release(by) {
     return this.serial(async () => {
+      // A change since the last poll (say, a disarm in the ecobee app) drops the hold in apply(),
+      // so a fresh read is what keeps us from arming Away over it. Can't read it: don't arm.
+      if (!(await this.refresh())) {
+        throw new Error('could not read the security state; not arming Away');
+      }
+      if (this.store.out?.[by]) {
+        delete this.store.out[by];
+        this.save();
+      }
+      if (this.returningNames().includes(by)) {
+        this.store.returning.names = this.returningNames().filter(name => name !== by);
+        this.save();
+        const others = this.returningNames();
+        if (others.length) {
+          this.log.info(`${by} is back; still waiting for ${others.join(' and ')}.`);
+        } else {
+          await this.armWhenBack(`${by} is back`);
+        }
+        return { released: true, state: HK_NAMES[this.target] };
+      }
       if (!this.store.hold) {
         return { released: false, state: HK_NAMES[this.target] };
       }
+      const others = this.holders().filter(name => name !== by);
+      if (others.length) {
+        // Someone else is still out: keep Stay until the last one is done.
+        this.store.hold = { ...this.store.hold, by: others };
+        this.save();
+        this.log.info(`${by} is done; staying in Stay for ${others.join(' and ')}.`);
+        return { released: false, state: HK_NAMES[this.target], waiting: others };
+      }
       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();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-ecobee-security",
   "displayName": "ecobee Smart Security",
-  "version": "0.4.2",
+  "version": "0.7.0",
   "description": "ecobee Smart Security as a HomeKit security system: arm Stay / Away, disarm, alarm state (unofficial, ecobee cloud)",
   "type": "module",
   "main": "index.js",
@@ -41,5 +41,8 @@
   ],
   "dependencies": {
     "@homebridge/plugin-ui-utils": "^2.2.6"
+  },
+  "homebridge-security-hold": {
+    "socket": "ecobee-security/control.sock"
   }
 }