homebridge-ecobee-security 0.5.0 → 0.7.0

package/homebridge-ui/server.js

@@ -72,6 +72,16 @@ class UiServer extends HomebridgePluginUiServer {
       return [...plugins.values()];
     });
 
+    // Locks the plugin found that report keypad unlocks (only that list leaves state.json).
+    this.onRequest('/keypad-locks', async () => {
+      try {
+        const store = JSON.parse(await readFile(join(this.homebridgeStoragePath, 'ecobee-security', 'state.json'), 'utf8'));
+        return store.keypadLocks ?? [];
+      } catch {
+        return [];
+      }
+    });
+
     this.ready();
   }
 

package/lib/control.js

@@ -1,7 +1,11 @@
 // A local control socket so other Homebridge plugins (each child bridge is its own process)
 // can ask for a temporary Stay while they move around the house:
-//   POST /hold?by=<name>&plugin=<package>     -> { ok, held, state, reason? }
-//   POST /release?by=<name>&plugin=<package>  -> { released, state, waiting? }  (Away only once every holder has released)
+//   POST /hold?by=<name>&plugin=<package>[&halt=<endpoint>]  -> { ok, held, state, reason? }
+//     `halt`: a Unix socket path or http(s) URL where the plugin answers POST /halt?by=<name>; it's
+//     called when the system is armed Away while it's out (`&armAt=`: back at base or stopped by then;
+//     a robot that answers `returning` is waited for, see SecuritySystem.haltRobots).
+//   POST /release?by=<name>&plugin=<package>  -> { released, state, waiting? }  (Away only once every holder has released;
+//     also how a robot sent back to its base says it's in, or stopped, so an extended exit delay can end)
 // It's a Unix socket in the plugin's storage folder (mode 600), so only the homebridge user can use it.
 // Holds need `allowHolds` and the asking plugin ticked in the settings (`isAllowed`); otherwise it
 // answers 403 so the caller can log why. Every request is noted (`noteRequest`) so the settings page
@@ -23,6 +27,7 @@ export function startControlServer({ path, log, getSystem, isAllowed, noteReques
     // Requests are allowed per plugin; one that doesn't say which it is goes by its `by` name.
     const plugin = (url.searchParams.get('plugin') || '').slice(0, 100) || undefined;
     const key = plugin ?? by;
+    const halt = (url.searchParams.get('halt') || '').slice(0, 500) || undefined;
     const reply = (code, body) => {
       res.writeHead(code, { 'content-type': 'application/json' });
       res.end(JSON.stringify(body));
@@ -33,7 +38,7 @@ export function startControlServer({ path, log, getSystem, isAllowed, noteReques
     const system = getSystem();
     const releasing = url.pathname === '/release';
     noteRequest?.({ key, plugin, by });
-    if (!(releasing && system?.holders().includes(by))) {
+    if (!(releasing && (system?.holders().includes(by) || system?.returningNames().includes(by)))) {
       const allowed = isAllowed(key);
       if (allowed !== true) {
         const why = allowed === 'off'
@@ -47,7 +52,7 @@ export function startControlServer({ path, log, getSystem, isAllowed, noteReques
       return reply(503, { error: 'not connected to ecobee yet' });
     }
     try {
-      reply(200, url.pathname === '/hold' ? await system.hold(by) : await system.release(by));
+      reply(200, url.pathname === '/hold' ? await system.hold(by, { plugin, halt }) : await system.release(by));
     } catch (error) {
       reply(502, { error: error.message });
     }

package/lib/ecobee.js

@@ -163,10 +163,11 @@ export class EcobeeCloud {
    * @param {string} homeId
    * @param {string} armedState one of ArmedState
    * @param {number} exitDelay seconds; the app sends the exit delay as a timestamp
+   * @param {number} [until] the exit delay's end (ms) instead of `exitDelay`
    * @returns the home's monitoring state after the change
    */
-  async setArmedState(homeId, armedState, exitDelay = 0) {
-    const exitDelayUntil = new Date(Date.now() + exitDelay * 1000).toISOString().replace(/\.\d{3}Z$/, 'Z');
+  async setArmedState(homeId, armedState, exitDelay = 0, until = Date.now() + exitDelay * 1000) {
+    const exitDelayUntil = new Date(until).toISOString().replace(/\.\d{3}Z$/, 'Z');
     const data = await this.graphql('SetArmedStateForHome', SET_MUTATION, {
       input: { homeId, armedState, exitDelayUntil },
     });

package/lib/halt.js

@@ -0,0 +1,51 @@
+// Ask a plugin that's out working (a robot vacuum) to head back to its base or stop where it is,
+// because the system is being armed Away. Plugins give their halt endpoint with their hold request (`&halt=`): a Unix socket path,
+// or an http(s) URL. POST <endpoint>/halt?by=<name>&armAt=<ISO time> -> 2xx, optionally JSON
+// { halted, returning?, reason? }. `armAt` is when the motion sensors arm (the end of the exit delay),
+// so a robot can head back to its base in time; without it, it stops where it is.
+
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+
+const TIMEOUT = 5 * 1000;
+
+/** Resolves `{ halted, returning?, reason? }`; rejects if the plugin can't be reached. */
+export function sendHalt(endpoint, by, armAt) {
+  const query = `?by=${encodeURIComponent(by)}` + (armAt ? `&armAt=${encodeURIComponent(new Date(armAt).toISOString())}` : '');
+  const options = { method: 'POST', timeout: TIMEOUT };
+  let request = httpRequest;
+  if (/^https?:\/\//i.test(endpoint)) {
+    const url = new URL(endpoint);
+    Object.assign(options, {
+      protocol: url.protocol, hostname: url.hostname, port: url.port || undefined,
+      auth: url.username ? `${decodeURIComponent(url.username)}:${decodeURIComponent(url.password)}` : undefined,
+      path: `${url.pathname.replace(/\/$/, '')}/halt${query}`,
+    });
+    request = url.protocol === 'https:' ? httpsRequest : httpRequest;
+  } else {
+    Object.assign(options, { socketPath: endpoint, path: `/halt${query}` });
+  }
+  return new Promise((resolve, reject) => {
+    const req = request(options, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', chunk => { body += chunk; });
+      res.on('end', () => {
+        let json = {};
+        try {
+          json = body.trim() ? JSON.parse(body) : {};
+        } catch {
+          // The status code is what counts.
+        }
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          return reject(new Error(json.error ?? `answered ${res.statusCode}`));
+        }
+        resolve({ halted: json.halted ?? true, returning: json.returning === true, reason: json.reason });
+      });
+    });
+    req.on('timeout', () => req.destroy(new Error('no answer')));
+    req.on('error', error => reject(error.code === 'ENOENT' || error.code === 'ECONNREFUSED'
+      ? new Error('the plugin is not running') : error));
+    req.end();
+  });
+}

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 {
   /**
@@ -75,6 +77,7 @@ export class EcobeeSecurityPlatform {
       this.control?.close();
       this.system?.stop();
       this.airQuality?.stop();
+      this.keypad?.stop();
     });
   }
 
@@ -134,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);
     }
@@ -162,6 +168,7 @@ export class EcobeeSecurityPlatform {
       save: () => this.save(),
       offerNight: this.config.offerNight === true,
       alarmAfterEntryDelay: this.config.alarmTrigger === 'entryDelay',
+      returnWait: this.config.taskWaitSeconds ?? 120,
       smokeAccessory,
     });
     if (isNew) {
@@ -174,17 +181,97 @@ 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.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.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.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]);
+    }
   }
 
   /**