homebridge-ecobee-security 0.4.2 → 0.7.0

package/lib/keypad.js

@@ -0,0 +1,240 @@
+// Disarm on a keypad unlock: watch the locks on the other bridges of this Homebridge for an unlock
+// that the lock says was done with its keypad (HomeKit's Lock Last Known Action). Child bridges run
+// in their own processes, so the locks are read over HAP on 127.0.0.1, which Homebridge allows with
+// just the bridge's PIN in insecure mode (the Homebridge UI's accessory control uses the same).
+// HAP events need a paired session, so the locks are polled; reading a few values locally every
+// second costs next to nothing.
+
+import { readFileSync } from 'node:fs';
+
+const POLL = 1000;
+// No locks found (or a bridge went away): look again this often.
+const RESCAN = 10 * 60 * 1000;
+// Other child bridges may still be starting: rescan every 30 s for this long.
+const GRACE = 3 * 60 * 1000;
+const GRACE_RESCAN = 30 * 1000;
+const TIMEOUT = 3000;
+// An unlock whose "by keypad" comes in a later update than the state still counts within this.
+const LABEL_LAG = 5000;
+
+const INFO = '3E';
+const LOCK = '45';
+const NAME = '23';
+const CONFIGURED_NAME = 'E3';
+const SERIAL = '30';
+const CURRENT = '1D';
+const LAST_ACTION = '1C';
+
+const UNSECURED = 0;
+const UNSECURED_BY_KEYPAD = 5;
+
+/** Apple's HAP types come as "45" or "00000045-0000-1000-8000-0026BB765291". */
+function shortType(type) {
+  const t = String(type).toUpperCase();
+  if (t.includes('-') && !t.endsWith('-0000-1000-8000-0026BB765291')) {
+    return t;
+  }
+  return t.split('-')[0].replace(/^0+/, '');
+}
+
+export class KeypadLocks {
+  /**
+   * @param {object} opts
+   * @param {string} opts.configPath Homebridge's config.json (bridge ports and PINs)
+   * @param {string} opts.ownPlatform this plugin's platform name (its own bridge is skipped)
+   * @param {(lock: {key: string, name: string, bridge: string}) => void} opts.onKeypadUnlock
+   * @param {(locks: {key: string, name: string, bridge: string}[]) => void} [opts.onLocks] the locks found, after each scan
+   */
+  constructor({ configPath, ownPlatform, log, onKeypadUnlock, onLocks }) {
+    this.configPath = configPath;
+    this.ownPlatform = ownPlatform;
+    this.log = log;
+    this.onKeypadUnlock = onKeypadUnlock;
+    this.onLocks = onLocks;
+    /** @type {Map<string, object>} key → lock: { key, name, bridge, aid, current, last, state, lastAction, pendingUntil } */
+    this.locks = new Map();
+    this.scannedAt = 0;
+    this.warned = new Set();
+  }
+
+  start() {
+    this.startedAt = Date.now();
+    this.timer = setInterval(() => this.poll(), POLL);
+    this.poll();
+  }
+
+  stop() {
+    clearInterval(this.timer);
+  }
+
+  /** Every bridge in config.json with a fixed port, except this plugin's own. */
+  bridges() {
+    const config = JSON.parse(readFileSync(this.configPath, 'utf8'));
+    const main = config.bridge ?? {};
+    const list = [{ name: main.name ?? 'Homebridge', port: main.port, pin: main.pin }];
+    for (const block of [...(config.platforms ?? []), ...(config.accessories ?? [])]) {
+      const child = block?._bridge;
+      if (child?.port && block.platform !== this.ownPlatform) {
+        list.push({ name: child.name ?? block.platform ?? block.accessory, port: child.port, pin: child.pin ?? main.pin });
+      }
+    }
+    return list.filter(b => b.port && b.pin);
+  }
+
+  async request(bridge, path) {
+    const response = await fetch(`http://127.0.0.1:${bridge.port}${path}`, {
+      headers: { Authorization: bridge.pin },
+      signal: AbortSignal.timeout(TIMEOUT),
+    });
+    if (response.status === 401 || response.status === 470) {
+      const error = new Error('not allowed');
+      error.auth = true;
+      throw error;
+    }
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    return response.json();
+  }
+
+  /** Find every lock that reports how it was last locked or unlocked. */
+  async scan() {
+    this.scannedAt = Date.now();
+    let bridges;
+    try {
+      bridges = this.bridges();
+    } catch (error) {
+      this.warnOnce('config', `Keypad unlock: could not read the Homebridge config (${error.message}).`);
+      return;
+    }
+    const found = new Map();
+    let denied = 0;
+    for (const bridge of bridges) {
+      let data;
+      try {
+        data = await this.request(bridge, '/accessories');
+      } catch (error) {
+        denied += error.auth ? 1 : 0;
+        continue;
+      }
+      for (const accessory of data.accessories ?? []) {
+        const services = accessory.services ?? [];
+        const lock = services.find(s => shortType(s.type) === LOCK);
+        const all = services.flatMap(s => s.characteristics ?? []);
+        const current = lock?.characteristics?.find(c => shortType(c.type) === CURRENT);
+        const last = all.find(c => shortType(c.type) === LAST_ACTION);
+        if (!current || !last) {
+          continue;
+        }
+        const info = services.find(s => shortType(s.type) === INFO)?.characteristics ?? [];
+        const nameOf = chars => chars.find(c => shortType(c.type) === CONFIGURED_NAME)?.value
+          || chars.find(c => shortType(c.type) === NAME)?.value;
+        const name = nameOf(lock.characteristics) || nameOf(info) || `Lock ${accessory.aid}`;
+        const serial = info.find(c => shortType(c.type) === SERIAL)?.value;
+        const key = serial ? String(serial) : `${bridge.name}/${name}`;
+        const known = this.locks.get(key);
+        found.set(key, {
+          key, name, bridge, aid: accessory.aid, current: current.iid, last: last.iid,
+          // Keep what we knew if it's the same lock on the same bridge; otherwise start from its first read.
+          ...(known?.bridge.port === bridge.port && known.aid === accessory.aid
+            ? { state: known.state, lastAction: known.lastAction, pendingUntil: known.pendingUntil } : {}),
+        });
+      }
+    }
+    if (denied && denied === bridges.length) {
+      this.warnOnce('denied', 'Keypad unlock: Homebridge didn\'t let the plugin read the other bridges. Turn on insecure mode '
+        + '(Homebridge Settings > Homebridge Insecure Mode / Accessory Control) and restart Homebridge.');
+    }
+    const before = [...this.locks.keys()].sort().join();
+    this.locks = found;
+    if ([...found.keys()].sort().join() !== before) {
+      if (found.size) {
+        this.log.info(`Keypad unlock: watching ${[...found.values()].map(l => `"${l.name}" (${l.bridge.name})`).join(', ')}.`);
+        this.warned.delete('none');
+      }
+      this.onLocks?.([...found.values()].map(({ key, name, bridge }) => ({ key, name, bridge: bridge.name })));
+    }
+    if (!found.size && !this.starting()) {
+      this.warnOnce('none', 'Keypad unlock: no lock on this Homebridge reports keypad unlocks; checking again every 10 minutes.');
+    }
+  }
+
+  async poll() {
+    if (this.polling) {
+      return;
+    }
+    this.polling = true;
+    try {
+      const every = this.starting() ? GRACE_RESCAN : RESCAN;
+      if (this.rescan || (!this.locks.size && Date.now() - this.scannedAt >= every)) {
+        this.rescan = false;
+        await this.scan();
+      }
+      const byBridge = new Map();
+      for (const lock of this.locks.values()) {
+        byBridge.set(lock.bridge.port, [...(byBridge.get(lock.bridge.port) ?? []), lock]);
+      }
+      await Promise.all([...byBridge.values()].map(locks => this.read(locks)));
+    } finally {
+      this.polling = false;
+    }
+  }
+
+  async read(locks) {
+    const ids = locks.flatMap(l => [`${l.aid}.${l.current}`, `${l.aid}.${l.last}`]).join(',');
+    let values;
+    try {
+      const data = await this.request(locks[0].bridge, `/characteristics?id=${ids}`);
+      values = new Map((data.characteristics ?? []).map(c => [`${c.aid}.${c.iid}`, c.value]));
+    } catch {
+      // Bridge restarting (or the lock moved): forget the states, so an unlock isn't seen in
+      // whatever it reports when it's back, and look for the locks again (at most every 30 s).
+      locks.forEach(l => Object.assign(l, { state: undefined, lastAction: undefined, pendingUntil: undefined }));
+      if (Date.now() - this.scannedAt >= GRACE_RESCAN) {
+        this.rescan = true;
+      }
+      return;
+    }
+    for (const lock of locks) {
+      this.update(lock, values.get(`${lock.aid}.${lock.current}`), values.get(`${lock.aid}.${lock.last}`));
+    }
+  }
+
+  /**
+   * Only an unlock counts, never a label: the lock must go to unlocked while saying it was unlocked
+   * with its keypad (in the same update, or within a few seconds after). An app unlock passes through
+   * other labels, and a label left from an earlier keypad unlock has no state change to go with it.
+   */
+  update(lock, state, lastAction) {
+    if (state === undefined || lastAction === undefined) {
+      return;
+    }
+    const first = lock.state === undefined;
+    const unlocked = !first && state === UNSECURED && lock.state !== UNSECURED;
+    const now = Date.now();
+    if (state !== lock.state) {
+      lock.pendingUntil = unlocked ? now + LABEL_LAG : undefined;
+    }
+    lock.state = state;
+    lock.lastAction = lastAction;
+    if (lock.pendingUntil && now > lock.pendingUntil) {
+      lock.pendingUntil = undefined;
+    }
+    if (lock.pendingUntil && lastAction === UNSECURED_BY_KEYPAD) {
+      lock.pendingUntil = undefined;
+      this.onKeypadUnlock({ key: lock.key, name: lock.name, bridge: lock.bridge.name });
+    }
+  }
+
+  /** Within the start-up grace period, when other bridges may not be up yet. */
+  starting() {
+    return Date.now() - this.startedAt < GRACE;
+  }
+
+  warnOnce(key, message) {
+    if (!this.warned.has(key)) {
+      this.warned.add(key);
+      this.log.warn(message);
+    }
+  }
+}

package/lib/platform.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { EcobeeCloud, SignInRequiredError } from './ecobee.js';
 import { startControlServer } from './control.js';
 import { AirQualitySensors } from './airquality.js';
+import { KeypadLocks } from './keypad.js';
 import { SecuritySystem } from './security.js';
 import { VERSION } from './version.js';
 
@@ -14,6 +15,7 @@ const RETRY_START = 60 * 1000;
 const AIR_QUALITY_RETRY = 10 * 60 * 1000;
 const AIR_QUALITY = 'airQuality';
 const SMOKE = 'smoke';
+const ARM_NOW = 'armAwayNow';
 
 export class EcobeeSecurityPlatform {
   /**
@@ -60,7 +62,13 @@ export class EcobeeSecurityPlatform {
     });
 
     api.on('didFinishLaunching', () => {
-      this.control = startControlServer({ path: join(dir, 'control.sock'), log, getSystem: () => this.system });
+      this.control = startControlServer({
+        path: join(dir, 'control.sock'),
+        log,
+        getSystem: () => this.system,
+        isAllowed: key => this.holdAllowed(key),
+        noteRequest: request => this.noteHoldRequest(request),
+      });
       this.launch();
     });
     api.on('shutdown', () => {
@@ -69,6 +77,7 @@ export class EcobeeSecurityPlatform {
       this.control?.close();
       this.system?.stop();
       this.airQuality?.stop();
+      this.keypad?.stop();
     });
   }
 
@@ -128,7 +137,10 @@ export class EcobeeSecurityPlatform {
     const uuid = this.api.hap.uuid.generate(`ecobee-security:${home.id}`);
     const smokeUuid = this.api.hap.uuid.generate(`ecobee-security:smoke:${home.id}`);
     const wantSmoke = this.config.smokeSensor !== false;
-    const stale = this.cached.filter(a => a.UUID !== uuid && a.context.kind !== AIR_QUALITY && !(wantSmoke && a.UUID === smokeUuid));
+    const armNowUuid = this.api.hap.uuid.generate(`ecobee-security:arm-away-now:${home.id}`);
+    const wantArmNow = this.config.allowHolds === true && this.config.armAwayNowSwitch === true;
+    const stale = this.cached.filter(a => a.UUID !== uuid && a.context.kind !== AIR_QUALITY
+      && !(wantSmoke && a.UUID === smokeUuid) && !(wantArmNow && a.UUID === armNowUuid));
     if (stale.length) {
       this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, stale);
     }
@@ -150,11 +162,13 @@ export class EcobeeSecurityPlatform {
       accessory,
       cloud: this.cloud,
       home,
-      pollInterval: Math.max(5, Number(this.config.pollInterval) || 10),
+      // The ecobee app reads the security state about every 10 s; polling faster would stand out.
+      pollInterval: 10,
       store: this.store,
       save: () => this.save(),
       offerNight: this.config.offerNight === true,
       alarmAfterEntryDelay: this.config.alarmTrigger === 'entryDelay',
+      returnWait: this.config.taskWaitSeconds ?? 120,
       smokeAccessory,
     });
     if (isNew) {
@@ -167,14 +181,123 @@ export class EcobeeSecurityPlatform {
     } else if (smokeAccessory) {
       this.api.updatePlatformAccessories([smokeAccessory]);
     }
+    if (wantArmNow) {
+      this.setupArmNow(armNowUuid, home.id);
+    }
     this.system.start();
     const m = home.monitoring;
     this.log.info(`Connected to "${home.name}" (${m.armedState}; professional monitoring `
       + `${m.homeMonitoringSettings?.isProfessionalMonitoringEnabled ? 'on' : 'off'}).`);
-    if (this.store.hold) {
-      this.log.info(`Still holding Stay for ${this.store.hold.by} (since ${this.store.hold.since}).`);
+    if (this.store.out && this.config.allowHolds !== true) {
+      delete this.store.out;
+      this.save();
+    }
+    if (this.store.hold && this.config.allowHolds !== true) {
+      this.log.info(`Security holds are off; dropping the hold for ${this.system.holders().join(' and ')} without re-arming Away`
+        + (this.store.hold.away ? ' (the Home app\'s Away request is dropped too; arm Away again if you still want it).' : '.'));
+      this.system.dropHold();
+    } else if (this.store.hold) {
+      this.log.info(`Still holding Stay for ${this.system.holders().join(' and ')} (since ${this.store.hold.since})`
+        + (this.store.hold.away ? '; the Home app asked for Away, which follows the release.' : '.'));
     }
     this.startAirQuality(home.id);
+    this.startKeypad();
+  }
+
+  /**
+   * Disarm when a lock on another bridge is unlocked with its keypad (`keypadDisarm`), for the locks
+   * ticked in `keypadLocks` (no list: every lock). The locks found go into state.json for the
+   * settings page.
+   */
+  startKeypad() {
+    if (this.config.keypadDisarm !== true) {
+      return;
+    }
+    const allowed = this.config.keypadLocks;
+    this.keypad = new KeypadLocks({
+      configPath: this.api.user.configPath(),
+      ownPlatform: PLATFORM_NAME,
+      log: this.log,
+      onKeypadUnlock: ({ key, name }) => {
+        if (Array.isArray(allowed) && !allowed.includes(key)) {
+          this.log.info(`"${name}" was unlocked with its keypad; it isn't ticked in the settings, so the security system is left as it is.`);
+          return;
+        }
+        this.system.keypadDisarm(`"${name}"`).catch(() => {});
+      },
+      onLocks: locks => {
+        this.store.keypadLocks = locks;
+        this.save();
+      },
+    });
+    this.keypad.start();
+  }
+
+  /**
+   * The Arm Away Now switch (its own accessory, so the Home app doesn't fold it into the security
+   * tile): sends robots that are out back to their base (or stops them) and arms Away now, then turns itself off. Away from the
+   * security tile waits for robots instead, because HomeKit can't tell who asked.
+   */
+  setupArmNow(uuid, homeId) {
+    const { Service, Characteristic, HapStatusError, HAPStatus } = this.api.hap;
+    let accessory = this.cached.find(a => a.UUID === uuid);
+    const isNew = !accessory;
+    if (isNew) {
+      accessory = new this.api.platformAccessory('Arm Away Now', uuid);
+      accessory.context.kind = ARM_NOW;
+    }
+    accessory.getService(Service.AccessoryInformation)
+      .setCharacteristic(Characteristic.Manufacturer, 'ecobee')
+      .setCharacteristic(Characteristic.Model, 'Smart Security: Arm Away Now')
+      .setCharacteristic(Characteristic.SerialNumber, `${homeId}-arm-away-now`)
+      .setCharacteristic(Characteristic.FirmwareRevision, VERSION);
+    const sw = accessory.getService(Service.Switch) ?? accessory.addService(Service.Switch, accessory.displayName);
+    const off = () => setTimeout(() => sw.updateCharacteristic(Characteristic.On, false), 1000);
+    sw.getCharacteristic(Characteristic.On)
+      .onGet(() => false)
+      .onSet(async (on) => {
+        if (!on) {
+          return;
+        }
+        try {
+          await this.system.armAwayNow();
+        } catch {
+          throw new HapStatusError(HAPStatus.SERVICE_COMMUNICATION_FAILURE);
+        } finally {
+          off();
+        }
+      });
+    if (isNew) {
+      this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
+    } else {
+      this.api.updatePlatformAccessories([accessory]);
+    }
+  }
+
+  /**
+   * May this plugin (or, if it doesn't say, this name) ask for a hold? `true`, `'off'` (holds are off),
+   * or `'not allowed'`. Without a `holdPlugins` list (settings from before it), every plugin may.
+   */
+  holdAllowed(key) {
+    if (this.config.allowHolds !== true) {
+      return 'off';
+    }
+    const list = this.config.holdPlugins;
+    return !Array.isArray(list) || list.includes(key) ? true : 'not allowed';
+  }
+
+  /** Remember who asked, for the settings page's list of plugins. */
+  noteHoldRequest({ key, plugin, by }) {
+    const requesters = this.store.holdRequesters ??= {};
+    const entry = requesters[key] ??= { names: [] };
+    if (plugin) {
+      entry.plugin = plugin;
+    }
+    if (!entry.names.includes(by)) {
+      entry.names = [...entry.names, by].slice(-10);
+    }
+    entry.lastAsked = new Date().toISOString();
+    this.save();
   }
 
   /** Air quality sensors for thermostats that have them; failures here never affect the security system. */