homebridge-ecobee-security 0.7.1 → 0.9.0

package/homebridge-ui/public/index.html

@@ -56,7 +56,6 @@
   </div>
 </div>
 
-
 <div class="card card-body mb-3" id="system-card" hidden>
   <h5 class="mb-3">Security system</h5>
   <div class="mb-3">
@@ -64,46 +63,23 @@
     <input class="form-control" type="text" id="s-name" data-key="name" data-type="text" data-default="Security System">
     <div class="hint mt-1">Name shown in the Home app.</div>
   </div>
-  <div class="mb-3">
-    <label for="s-homeId" class="form-label">Home ID</label>
-    <input class="form-control" type="text" id="s-homeId" data-key="homeId" data-type="text" data-default="">
-    <div class="hint mt-1">Only needed if your account has more than one home. The log lists your homes.</div>
+  <div class="mb-3" id="home-box" hidden>
+    <label for="s-homeId" class="form-label">Home</label>
+    <select class="form-select" id="s-homeId" data-key="homeId" data-type="select" data-default=""></select>
+    <div class="hint mt-1">Your ecobee account has more than one home. Pick the one whose security system to add.</div>
   </div>
   <div class="mb-3">
     <div class="form-check form-switch">
       <input class="form-check-input" type="checkbox" role="switch" id="s-offerNight" data-key="offerNight" data-type="bool" data-default="false">
-      <label class="form-check-label" for="s-offerNight">Offer Night</label>
+      <label class="form-check-label" for="s-offerNight">Enable Night</label>
     </div>
     <div class="hint">Adds a Night mode to use in automations. ecobee has no Night mode, so Night arms ecobee's Stay.</div>
     <div class="hint mt-1">Changing this recreates the security system in the Home app, so you need to set up its scenes and automations again.</div>
   </div>
   <div class="mb-0">
-    <label for="s-alarmTrigger" class="form-label">Enter Triggered State</label>
-    <select class="form-select" id="s-alarmTrigger" data-key="alarmTrigger" data-type="select" data-default="incident"><option value="incident">Immediately (mirror ecobee app)</option><option value="entryDelay">After the entry delay</option></select>
-    <div class="hint mt-1">Immediately: as soon as a door or sensor trips while armed, like the ecobee app. After the entry delay: only if no one disarms in time, so automations don't run while you walk in. Smoke alarms always trigger immediately.</div>
-  </div>
-</div>
-
-<div class="card card-body mb-3" id="sensors-card" hidden>
-  <h5 class="mb-3">Sensors</h5>
-  <div class="mb-3">
-    <div class="form-check form-switch">
-      <input class="form-check-input" type="checkbox" role="switch" id="s-smokeSensor" data-key="smokeSensor" data-type="bool" data-default="true">
-      <label class="form-check-label" for="s-smokeSensor">Smoke sensor</label>
-    </div>
-    <div class="hint">Adds a Smoke Alarm accessory that detects smoke when ecobee reports a smoke alarm. Use it for Home app notifications and automations.</div>
-  </div>
-  <div class="mb-3">
-    <div class="form-check form-switch">
-      <input class="form-check-input" type="checkbox" role="switch" id="s-airQuality" data-key="airQuality" data-type="bool" data-default="true">
-      <label class="form-check-label" for="s-airQuality">Air quality sensors</label>
-    </div>
-    <div class="hint">Adds 2 sensors for each ecobee Premium thermostat: air quality (with VOC) and CO2. ecobee's own HomeKit integration doesn't include them. Updates every 5 minutes.</div>
-  </div>
-  <div class="mb-0" id="co2-box">
-    <label for="s-co2Alert" class="form-label">CO2 alert level (ppm)</label>
-    <input class="form-control" type="number" step="1" min="400" id="s-co2Alert" data-key="co2Alert" data-type="int" data-default="1000">
-    <div class="hint mt-1">At or above this level, the CO2 sensor reports abnormal CO2. Use it for notifications and automations, like turning on ventilation.</div>
+    <label for="s-alarmTrigger" class="form-label">Home app alarm</label>
+    <select class="form-select" id="s-alarmTrigger" data-key="alarmTrigger" data-type="select" data-default="incident"><option value="incident">When a sensor is tripped (entry delay starts)</option><option value="entryDelay">When the siren goes off (entry delay ran out)</option></select>
+    <div class="hint mt-1">Sets when the Home app's security tile shows Triggered. Its critical alert and "security system triggered" automations follow it. ecobee's own alerts and professional monitoring don't change. "When a sensor is tripped" alerts every time someone comes in while it'sarmed, even if they disarm in time.</div>
   </div>
 </div>
 
@@ -148,6 +124,96 @@
   </div>
 </div>
 
+<div class="card card-body mb-3" id="camera-card" hidden>
+  <h5 class="mb-2">Doorbell camera</h5>
+  <div class="form-check form-switch mb-1">
+    <input class="form-check-input" type="checkbox" role="switch" id="s-doorbellCamera" data-key="doorbellCamera" data-type="bool" data-default="false">
+    <label class="form-check-label" for="s-doorbellCamera">Doorbell camera with HomeKit Secure Video</label>
+  </div>
+  <p class="hint mb-2">Recordings, activity zones and Apple's person and package detection in the Home app, plus live view. Restart the bridge after changing this.
+    <a href="https://github.com/seanfletchr/homebridge-ecobee-security#doorbell-camera" target="_blank" rel="noopener">Learn more…</a></p>
+  <div id="camera-box" hidden>
+    <div id="link-box" class="mb-2">
+      <div class="d-flex align-items-center gap-2 flex-wrap">
+        <span><strong>Doorbell link:</strong> <span id="link-status"></span></span>
+        <button type="button" class="btn btn-sm btn-secondary" id="link-unpair" hidden>Unlink</button>
+        <button type="button" class="btn btn-sm btn-secondary" id="link-open" hidden>Pair…</button>
+      </div>
+      <button type="button" class="btn btn-link btn-sm p-0" id="link-forget" hidden>Remove the link without asking the doorbell</button>
+      <div id="link-unpaired" hidden class="mt-2">
+        <p class="hint mb-2">First remove ecobee's own doorbell from the Home app: its automations and the sensors it connects go with it. Restart the bridge after linking.
+          <a href="https://github.com/seanfletchr/homebridge-ecobee-security#doorbell-link" target="_blank" rel="noopener">Learn more…</a></p>
+        <button type="button" class="btn btn-secondary mb-2" id="link-find">Find doorbells</button>
+        <div id="link-found" class="mb-2"></div>
+        <form id="link-form" class="d-flex gap-2" hidden>
+          <input type="text" class="form-control" id="link-code" inputmode="numeric" autocomplete="off" maxlength="13" placeholder="Setup code (8 digits)" required>
+          <button type="submit" class="btn btn-primary" id="link-pair">Pair</button>
+        </form>
+      </div>
+      <div id="link-error" class="alert alert-danger mt-2 mb-0" role="alert" hidden></div>
+    </div>
+    <details>
+      <summary>Advanced</summary>
+      <div class="mt-2">
+        <label for="s-motionGrace" class="form-label mb-1">Motion grace period (seconds)</label>
+        <input class="form-control mb-1" type="number" step="1" min="6" max="120" id="s-motionGrace" data-key="motionGrace" data-type="int" data-default="15">
+        <div class="hint mb-3">How long a clip keeps recording after motion stops. Someone back in view within this time stays in the same clip.</div>
+        <label for="s-ffmpegPath" class="form-label mb-1">ffmpeg path</label>
+        <input class="form-control" type="text" id="s-ffmpegPath" data-key="ffmpegPath" data-type="text" data-default="" placeholder="/usr/local/bin/ffmpeg">
+        <div class="hint mt-1">Only if the camera can't find ffmpeg. It needs libfdk_aac and libx264.</div>
+      </div>
+    </details>
+  </div>
+</div>
+
+<div class="card card-body mb-3" id="sensors-card" hidden>
+  <h5 class="mb-3">Switches and sensors</h5>
+
+  <div>
+    <h6 class="mb-1">Home Occupied</h6>
+    <div class="form-check form-switch mb-1">
+      <input class="form-check-input" type="checkbox" role="switch" id="s-occupancySwitch" data-key="occupancySwitch" data-type="bool" data-default="false">
+      <label class="form-check-label" for="s-occupancySwitch">Add a Home Occupied switch</label>
+    </div>
+    <p class="hint mb-2">Adds a switch to the Home app for your people-arrive and people-leave automations to set:
+      off (nobody home) arms Away, on (someone home) turns Away off. Switches don't ask for confirmation the way
+      automations that change the security system do. Restart the bridge after changing this.
+      <a href="https://github.com/seanfletchr/homebridge-ecobee-security#home-occupied-switch" target="_blank" rel="noopener">Learn more…</a></p>
+  </div>
+
+  <div class="mt-3">
+    <h6 class="mb-1">Vacation Mode</h6>
+    <div class="form-check form-switch mb-1">
+      <input class="form-check-input" type="checkbox" role="switch" id="s-vacationSwitch" data-key="vacationSwitch" data-type="bool" data-default="false">
+      <label class="form-check-label" for="s-vacationSwitch">Add a Vacation Mode switch</label>
+    </div>
+    <p class="hint mb-2">Shows when an ecobee vacation is on, for other accessories to follow. Turn it on to start a vacation now, until you turn it off; set dated vacations in the ecobee app. Restart the bridge after changing this.</p>
+  </div>
+
+  <div class="mt-3">
+    <h6 class="mb-1">Smoke Alarm</h6>
+    <div class="form-check form-switch">
+      <input class="form-check-input" type="checkbox" role="switch" id="s-smokeSensor" data-key="smokeSensor" data-type="bool" data-default="true">
+      <label class="form-check-label" for="s-smokeSensor">Add a Smoke Alarm sensor</label>
+    </div>
+    <div class="hint">Adds a Smoke Alarm accessory that detects smoke when ecobee reports a smoke alarm. Use it for Home app notifications and automations.</div>
+  </div>
+
+  <div class="mt-3">
+    <h6 class="mb-1">Air quality</h6>
+    <div class="form-check form-switch">
+      <input class="form-check-input" type="checkbox" role="switch" id="s-airQuality" data-key="airQuality" data-type="bool" data-default="true">
+      <label class="form-check-label" for="s-airQuality">Add air quality sensors</label>
+    </div>
+    <div class="hint">Adds 2 sensors for each ecobee Premium thermostat: air quality (with VOC) and CO2. ecobee's own HomeKit integration doesn't include them. Updates every 5 minutes.</div>
+    <div class="mt-3 mb-0" id="co2-box">
+      <label for="s-co2Alert" class="form-label">CO2 alert level (ppm)</label>
+      <input class="form-control" type="number" step="1" min="400" id="s-co2Alert" data-key="co2Alert" data-type="int" data-default="1000">
+      <div class="hint mt-1">At or above this level, the CO2 sensor reports abnormal CO2. Use it for notifications and automations, like turning on ventilation.</div>
+    </div>
+  </div>
+</div>
+
 <script>
 (async () => {
   const PLATFORM = 'EcobeeSecurityPlatform';
@@ -279,6 +345,9 @@
     const signedIn = Boolean(block?.refreshToken);
     $('system-card').hidden = !signedIn;
     $('sensors-card').hidden = !signedIn;
+    const link = signedIn ? await homebridge.request('/doorbell-link').catch(() => ({})) : {};
+    $('camera-card').hidden = !signedIn || link.hasDoorbell === false;
+    await showHomes(block);
     for (const input of controls) {
       const value = block?.[input.dataset.key];
       if (input.dataset.type === 'bool') {
@@ -288,6 +357,30 @@
       }
     }
     $('co2-box').hidden = block?.airQuality === false;
+    $('camera-box').hidden = block?.doorbellCamera !== true;
+    if (block?.doorbellCamera === true) {
+      await showLink();
+    }
+  }
+
+  /**
+   * The home list, from what the plugin last saw. Only offered when there's a choice: one home (or
+   * none seen yet) hides it, unless a home is already set.
+   */
+  async function showHomes(block) {
+    const homes = await homebridge.request('/homes').catch(() => []);
+    const select = $('s-homeId');
+    select.textContent = '';
+    const option = (value, text) => select.append(Object.assign(document.createElement('option'), { value, textContent: text }));
+    option('', 'Automatic (the first home with Smart Security)');
+    for (const home of homes) {
+      option(home.id, home.security ? home.name : `${home.name} (no Smart Security)`);
+    }
+    const set = block?.homeId;
+    if (set && !homes.some(h => h.id === set)) {
+      option(set, homes.length ? `${set} (not on this account)` : set);
+    }
+    $('home-box').hidden = homes.length < 2 && !set;
   }
 
   /** Write one setting. Top-level keys are cleared with undefined, never deleted (the UI merges shallowly). */
@@ -305,16 +398,21 @@
         await setSetting(key, input.checked);
         if (key === 'airQuality') {
           $('co2-box').hidden = !input.checked;
+        } else if (key === 'doorbellCamera') {
+          $('camera-box').hidden = !input.checked;
+          if (input.checked) {
+            await showLink();
+          }
         }
       } else if (type === 'int') {
         const number = input.value.trim() === '' ? undefined : Number(input.value);
-        const valid = number === undefined || (Number.isInteger(number) && number >= Number(input.min));
+        const valid = number === undefined || (Number.isInteger(number) && number >= Number(input.min) && (!input.max || number <= Number(input.max)));
         input.classList.toggle('is-invalid', !valid);
         if (valid) {
           await setSetting(key, number);
         }
       } else if (type === 'select') {
-        await setSetting(key, input.value);
+        await setSetting(key, input.value === '' ? undefined : input.value);
       } else {
         await setSetting(key, input.value.trim() === '' ? undefined : input.value.trim());
       }
@@ -439,6 +537,101 @@
     await showKeypad();
   });
 
+  // ── Doorbell link ──
+
+  let linkChoice;
+
+  function linkError(message) {
+    $('link-error').textContent = message ?? '';
+    $('link-error').hidden = !message;
+  }
+
+  async function showLink() {
+    const link = await homebridge.request('/doorbell-link').catch(() => ({ paired: false }));
+    $('link-unpaired').hidden = true;
+    $('link-open').hidden = link.paired;
+    $('link-unpair').hidden = !link.paired;
+    $('link-forget').hidden = true;
+    $('link-status').textContent = link.paired
+      ? (link.state === 'down' ? 'Linked, but the doorbell is not answering right now. ' : 'Linked · ')
+      : 'Not linked. Pair it for an instant ring and motion; it replaces ecobee\'s own doorbell in the Home app. ';
+  }
+
+  $('link-open').addEventListener('click', () => {
+    $('link-unpaired').hidden = !$('link-unpaired').hidden;
+  });
+
+  $('link-find').addEventListener('click', async () => {
+    linkError();
+    $('link-form').hidden = true;
+    const box = $('link-found');
+    box.textContent = 'Looking…';
+    try {
+      const doorbells = await homebridge.request('/doorbell-find');
+      box.textContent = '';
+      linkChoice = undefined;
+      if (!doorbells.length) {
+        box.textContent = 'No doorbell found. Is ecobee\'s own doorbell removed from the Home app?';
+        return;
+      }
+      for (const d of doorbells) {
+        const id = `doorbell-${d.id.replace(/[^a-z0-9]/gi, '-')}`;
+        const input = Object.assign(document.createElement('input'), { className: 'form-check-input', type: 'radio', name: 'doorbell', id, disabled: !d.availableToPair });
+        input.addEventListener('change', () => {
+          linkChoice = d.id;
+          $('link-form').hidden = false;
+        });
+        const label = Object.assign(document.createElement('label'), { className: 'form-check-label', htmlFor: id });
+        label.textContent = d.availableToPair ? d.name : `${d.name} (still paired: remove it from the Home app first)`;
+        const row = Object.assign(document.createElement('div'), { className: 'form-check' });
+        row.append(input, label);
+        box.append(row);
+      }
+      const only = doorbells.filter(d => d.availableToPair);
+      if (only.length === 1) {
+        box.querySelector('input:not(:disabled)').click();
+      }
+    } catch (error) {
+      box.textContent = '';
+      linkError(error.message);
+    }
+  });
+
+  $('link-form').addEventListener('submit', async (event) => {
+    event.preventDefault();
+    linkError();
+    homebridge.showSpinner();
+    try {
+      await homebridge.request('/doorbell-pair', { id: linkChoice, code: $('link-code').value });
+      $('link-code').value = '';
+      $('link-form').hidden = true;
+      $('link-found').textContent = '';
+      homebridge.toast.success('Linked. Restart the bridge to use it.');
+      await showLink();
+    } catch (error) {
+      linkError(error.message);
+    } finally {
+      homebridge.hideSpinner();
+    }
+  });
+
+  async function unlink(force) {
+    linkError();
+    homebridge.showSpinner();
+    try {
+      await homebridge.request('/doorbell-unpair', { force });
+      homebridge.toast.success('Unlinked. Restart the bridge to apply it.');
+      await showLink();
+    } catch (error) {
+      linkError(error.message);
+      $('link-forget').hidden = false;
+    } finally {
+      homebridge.hideSpinner();
+    }
+  }
+  $('link-unpair').addEventListener('click', () => unlink(false));
+  $('link-forget').addEventListener('click', () => unlink(true));
+
   await showStatus();
   await showSettings();
   await showKeypad();

package/homebridge-ui/server.js

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 
 import { HomebridgePluginUiServer, RequestError } from '@homebridge/plugin-ui-utils';
 
+import { findDoorbells, pairDoorbell, readPairing, unpairDoorbell } from '../lib/camera/hap-pairing.js';
 import { browserSignInLink, finishBrowserSignIn, finishMfa, passwordSignIn, SignInError } from '../lib/auth.js';
 
 class UiServer extends HomebridgePluginUiServer {
@@ -82,6 +83,56 @@ class UiServer extends HomebridgePluginUiServer {
       }
     });
 
+    // The homes on the account, as the plugin last saw them (only that list leaves state.json).
+    this.onRequest('/homes', async () => {
+      try {
+        const store = JSON.parse(await readFile(join(this.homebridgeStoragePath, 'ecobee-security', 'state.json'), 'utf8'));
+        return store.homes ?? [];
+      } catch {
+        return [];
+      }
+    });
+
+    // The doorbell link: pairing with the doorbell's own HomeKit server. The setup code is used once
+    // and neither logged nor kept.
+    const pairingPath = () => join(this.homebridgeStoragePath, 'ecobee-security', 'doorbell-pairing.json');
+
+    this.onRequest('/doorbell-link', async () => {
+      const pairing = readPairing(pairingPath());
+      let link;
+      let store = {};
+      try {
+        store = JSON.parse(await readFile(join(this.homebridgeStoragePath, 'ecobee-security', 'state.json'), 'utf8'));
+        link = store.doorbellLink;
+      } catch {
+        // not started yet
+      }
+      // hasDoorbell stays undefined until the plugin has looked at the account.
+      return { paired: Boolean(pairing), id: pairing?.id, state: pairing ? link?.state : undefined, hasDoorbell: store.hasDoorbell, name: store.doorbellName };
+    });
+
+    this.onRequest('/doorbell-find', () => findDoorbells(5).catch((error) => {
+      throw new RequestError(`Could not look for doorbells: ${error.message}`);
+    }));
+
+    this.onRequest('/doorbell-pair', async ({ id, code } = {}) => {
+      try {
+        await pairDoorbell({ id: String(id ?? ''), code, path: pairingPath() });
+        return { paired: true };
+      } catch (error) {
+        throw new RequestError(error.message);
+      }
+    });
+
+    this.onRequest('/doorbell-unpair', async ({ force } = {}) => {
+      try {
+        await unpairDoorbell({ path: pairingPath(), force: force === true });
+        return { paired: false };
+      } catch (error) {
+        throw new RequestError(`The doorbell could not be reached to remove the link (${error.message}).`, { code: 'unreachable' });
+      }
+    });
+
     this.ready();
   }
 

package/lib/airquality.js

@@ -26,6 +26,7 @@ export class AirQualitySensors {
     this.C = api.hap.Characteristic;
     this.sensors = new Map();      // thermostat id -> { accessory, air, co2 }
     this.failures = 0;
+    this.offline = false;          // after repeated failed reads the sensors show No Response
     this.stopped = false;
   }
 
@@ -97,21 +98,33 @@ export class AirQualitySensors {
         service.addCharacteristic(C.StatusFault);
       }
     }
-    return { accessory, air, co2, name: thermostat.name };
+    const sensor = { accessory, air, co2, name: thermostat.name, out: false };
+    for (const [service, characteristic] of this.readings(sensor)) {
+      service.getCharacteristic(characteristic).onGet(() => {
+        if (this.offline || sensor.out) {
+          throw this.noResponse();
+        }
+        return service.getCharacteristic(characteristic).value;
+      });
+    }
+    return sensor;
   }
 
   async poll() {
     try {
-      this.apply(await this.cloud.getAirQuality(this.homeId));
+      const thermostats = await this.cloud.getAirQuality(this.homeId);
       if (this.failures >= FAULT_AFTER) {
         this.log.info('Air quality readings are back.');
       }
       this.failures = 0;
       this.setFault(false);
+      this.setOffline(false);
+      this.apply(thermostats);
     } catch (error) {
       this.failures += 1;
       if (this.failures === FAULT_AFTER) {
         this.setFault(true);
+        this.setOffline(true);
       }
       if (!(error instanceof SignInRequiredError)) {
         this.log[this.failures >= FAULT_AFTER ? 'warn' : 'debug'](`Could not read air quality (${error.message}).`);
@@ -128,6 +141,37 @@ export class AirQualitySensors {
     }
   }
 
+  noResponse() {
+    return new this.api.hap.HapStatusError(this.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
+  }
+
+  /** The readings of one sensor accessory, as [service, characteristic] pairs. */
+  readings({ air, co2 }) {
+    const C = this.C;
+    return [[air, C.AirQuality], [air, C.VOCDensity], [co2, C.CarbonDioxideLevel], [co2, C.CarbonDioxideDetected]];
+  }
+
+  /**
+   * Stale readings show as No Response (like the security tile) once reads have failed for a while.
+   * Back online, the last values are put back until apply() brings the new ones.
+   */
+  setOffline(on) {
+    if (this.offline === on) {
+      return;
+    }
+    this.offline = on;
+    for (const sensor of this.sensors.values()) {
+      this.show(sensor, on || sensor.out);
+    }
+  }
+
+  /** No Response for one sensor accessory's readings, or their last values. */
+  show(sensor, noResponse) {
+    for (const [service, characteristic] of this.readings(sensor)) {
+      service.updateCharacteristic(characteristic, noResponse ? this.noResponse() : service.getCharacteristic(characteristic).value);
+    }
+  }
+
   apply(thermostats) {
     const { AirQuality, VOCDensity, CarbonDioxideLevel, CarbonDioxideDetected } = this.C;
     for (const t of thermostats) {
@@ -137,6 +181,16 @@ export class AirQualitySensors {
       }
       const aq = t.airQuality ?? {};
       const runtime = t.runtime ?? {};
+      // ecobee's cloud can't reach this thermostat: its readings are old.
+      const out = runtime.connected === false;
+      if (out !== sensor.out) {
+        sensor.out = out;
+        this.log.debug(`Air quality, ${sensor.name}: ${out ? "ecobee can't reach the thermostat" : 'thermostat reachable again'}.`);
+        this.show(sensor, out || this.offline);
+      }
+      if (out) {
+        continue;
+      }
       sensor.air.updateCharacteristic(AirQuality, aq.isCalibrating ? AirQuality.UNKNOWN : level(aq.airQualityScore, AirQuality));
       if (Number.isFinite(runtime.actualVOC) && runtime.actualVOC >= 0) {
         sensor.air.updateCharacteristic(VOCDensity, Math.min(runtime.actualVOC, 10000));

package/lib/camera/bridged.js

@@ -0,0 +1,171 @@
+// Sensors the doorbell bridges to HomeKit (an ecobee SmartSensor, say), re-published as platform
+// accessories on this bridge, with their values taken from the doorbell link.
+
+const OFFLINE_AFTER = 60 * 1000;
+const CHECK_EVERY = 5 * 1000;
+
+export const HAP_BRIDGED = 'hap-bridged';
+
+export class BridgedSensors {
+  /**
+   * @param {object} options
+   * @param {import('homebridge').API} options.api
+   * @param {import('homebridge').Logging} options.log
+   * @param {import('./hap-link.js').DoorbellHapLink} options.link
+   * @param {string} options.pluginName
+   * @param {string} options.platformName
+   * @param {import('homebridge').PlatformAccessory[]} options.cached
+   * @param {string} options.version
+   */
+  constructor({ api, log, link, pluginName, platformName, cached, version }) {
+    this.api = api;
+    this.log = log;
+    this.link = link;
+    this.pluginName = pluginName;
+    this.platformName = platformName;
+    this.version = version;
+    /** @type {Map<string, import('homebridge').PlatformAccessory>} */
+    this.accessories = new Map(cached.map(a => [a.UUID, a]));
+    /** key ("aid.iid") -> Characteristic */
+    this.characteristics = new Map();
+    this.offline = false;
+    const { Characteristic } = api.hap;
+    // The sensor characteristics worth mirroring, by short HAP UUID.
+    this.mirrored = new Map([
+      ['6A', Characteristic.ContactSensorState],
+      ['22', Characteristic.MotionDetected],
+      ['71', Characteristic.OccupancyDetected],
+      ['75', Characteristic.StatusActive],
+      ['79', Characteristic.StatusLowBattery],
+      ['68', Characteristic.BatteryLevel],
+      ['8F', Characteristic.ChargingState],
+    ]);
+    const { Service } = api.hap;
+    this.serviceTypes = new Map([
+      ['80', Service.ContactSensor],
+      ['85', Service.MotionSensor],
+      ['86', Service.OccupancySensor],
+      ['96', Service.Battery],
+    ]);
+    link.on('accessories', list => this.update(list));
+    link.on('characteristic', change => this.changed(change));
+    link.on('unpaired', () => this.removeAll());
+    this.timer = setInterval(() => this.checkOnline(), CHECK_EVERY);
+  }
+
+  stop() {
+    clearInterval(this.timer);
+  }
+
+  update(list) {
+    const { hap } = this.api;
+    const { Service, Characteristic } = hap;
+    const wanted = new Set();
+    this.characteristics.clear();
+    for (const info of list) {
+      const uuid = hap.uuid.generate(`ecobee-security:hap:${this.link.pairing?.id}:${info.aid}`);
+      wanted.add(uuid);
+      const name = info.name || 'Doorbell sensor';
+      let accessory = this.accessories.get(uuid);
+      const isNew = !accessory;
+      if (isNew) {
+        accessory = new this.api.platformAccessory(name, uuid);
+        accessory.context.kind = HAP_BRIDGED;
+        this.accessories.set(uuid, accessory);
+      }
+      accessory.displayName = name;
+      accessory.getService(Service.AccessoryInformation)
+        .setCharacteristic(Characteristic.Name, name)
+        .setCharacteristic(Characteristic.Manufacturer, info.manufacturer || 'ecobee')
+        .setCharacteristic(Characteristic.Model, info.model || 'Sensor')
+        .setCharacteristic(Characteristic.SerialNumber, info.serial || `${info.aid}`)
+        .setCharacteristic(Characteristic.FirmwareRevision, info.firmware || this.version);
+
+      const keep = new Set();
+      for (const svc of info.services) {
+        const Type = this.serviceTypes.get(svc.type);
+        if (!Type) {
+          continue;
+        }
+        const subtype = String(svc.iid);
+        const serviceName = svc.name || name;
+        const service = accessory.getServiceById(Type, subtype) ?? accessory.addService(Type, serviceName, subtype);
+        service.setCharacteristic(Characteristic.Name, serviceName);
+        keep.add(service);
+        for (const c of svc.characteristics) {
+          const Class = this.mirrored.get(c.type);
+          if (!Class || c.value === undefined || c.value === null) {
+            continue;
+          }
+          const characteristic = service.getCharacteristic(Class);
+          characteristic.updateValue(this.convert(Class, c.value));
+          this.characteristics.set(c.key, characteristic);
+        }
+      }
+      for (const stale of accessory.services.filter(s => s.UUID !== Service.AccessoryInformation.UUID && !keep.has(s))) {
+        accessory.removeService(stale);
+      }
+      if (isNew) {
+        this.api.registerPlatformAccessories(this.pluginName, this.platformName, [accessory]);
+        this.log.info(`"${name}" (bridged by the doorbell) added to HomeKit.`);
+      } else {
+        this.api.updatePlatformAccessories([accessory]);
+      }
+    }
+    const gone = [...this.accessories.entries()].filter(([uuid]) => !wanted.has(uuid));
+    if (gone.length) {
+      this.api.unregisterPlatformAccessories(this.pluginName, this.platformName, gone.map(([, a]) => a));
+      gone.forEach(([uuid, a]) => {
+        this.accessories.delete(uuid);
+        this.log.info(`"${a.displayName}" is no longer bridged by the doorbell; removed from HomeKit.`);
+      });
+    }
+    this.offline = false;
+  }
+
+  /** Without a pairing there is nothing to mirror: take the accessories out of HomeKit. */
+  removeAll() {
+    if (!this.accessories.size) {
+      return;
+    }
+    this.api.unregisterPlatformAccessories(this.pluginName, this.platformName, [...this.accessories.values()]);
+    this.log.info('The doorbell link was removed; the sensors it bridged are removed from HomeKit.');
+    this.accessories.clear();
+    this.characteristics.clear();
+  }
+
+  convert(Class, value) {
+    const { Characteristic } = this.api.hap;
+    return Class === Characteristic.MotionDetected || Class === Characteristic.StatusActive ? Boolean(value) : Number(value);
+  }
+
+  changed({ key, value, type }) {
+    const characteristic = this.characteristics.get(key);
+    if (!characteristic || value === null || value === undefined) {
+      return;
+    }
+    characteristic.updateValue(this.convert(this.mirrored.get(type), value));
+  }
+
+  /** Down for a minute: the sensors show No Response until the link is back (the next change or read). */
+  checkOnline() {
+    const offline = !this.link.up && this.link.paired && this.link.downFor() > OFFLINE_AFTER;
+    if (offline === this.offline) {
+      return;
+    }
+    this.offline = offline;
+    const error = new this.api.hap.HapStatusError(this.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
+    for (const accessory of this.accessories.values()) {
+      for (const service of accessory.services) {
+        for (const characteristic of service.characteristics) {
+          if ([...this.mirrored.values()].some(Class => characteristic.UUID === Class.UUID) && service.UUID !== this.api.hap.Service.AccessoryInformation.UUID) {
+            characteristic.updateValue(offline ? error : characteristic.value);
+          }
+        }
+      }
+    }
+    if (offline) {
+      this.log.warn('The doorbell link has been down for a minute; the sensors it bridges show No Response until it is back.');
+    }
+  }
+}