homebridge-ecobee-security 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.4.0
+
+- `offerNight`: adds Night to the Home app; it arms ecobee's Stay and keeps showing Night. Changing
+  the setting recreates the security system in HomeKit (the Home app doesn't pick up new modes on an
+  existing control).
+- `alarmTrigger: "entryDelay"`: show Alarm triggered only once an intrusion has outlasted the entry
+  delay without a disarm, instead of as soon as ecobee opens the incident. Smoke still shows at once.
+- `smokeSensor` (on by default): a separate Smoke Alarm accessory that detects smoke while ecobee has a smoke-alarm
+  incident open.
+- Air quality (`airQuality`, on by default): for ecobee thermostats with an air quality sensor, an
+  Air Quality Sensor (level, VOC) and a Carbon Dioxide Sensor (ppm, alert at `co2Alert`, 1000 ppm).
+- The accessory reports the plugin version as its firmware version.
+- The hold API refuses a hold while any alarm incident is open, whichever `alarmTrigger` is set.
+
 ## 0.3.0
 
 - Sign in from the plugin's settings page in the Homebridge UI with your ecobee email, password

package/README.md

@@ -1,7 +1,9 @@
 # homebridge-ecobee-security
 
 Shows **ecobee Smart Security** in Apple Home as a security system: arm **Stay**, arm **Away**,
-**disarm**, and **Alarm triggered** when ecobee has an open intrusion or smoke incident. Works with
+**disarm**, and **Alarm triggered** when ecobee has an open intrusion or smoke incident. It also adds
+**air quality** sensors for ecobee thermostats that have one (ecobee Premium), which ecobee's own
+HomeKit integration leaves out. Works with
 Siri ("set the security system to away") and Home automations. ecobee removed Smart Security from
 its HomeKit integration; this brings it back.
 
@@ -55,12 +57,25 @@ node <plugin folder>/bin/ecobee-login.js --browser  # website sign-in
   "name": "Security System",
   "refreshToken": "…",
   "pollInterval": 10,
+  "offerNight": false,
+  "alarmTrigger": "incident",
+  "smokeSensor": true,
+  "airQuality": true,
+  "co2Alert": 1000,
   "_bridge": { "username": "…", "port": 51926, "name": "Ecobee Security Bridge" }
 }
 ```
 
 `homeId` is only needed if the account has several homes (the log lists them).
 
+| Setting | Default | |
+|---|---|---|
+| `offerNight` | `false` | Adds Night to the Home app. ecobee has no Night mode, so Night arms Stay and the tile keeps showing Night until the state changes (a Stay armed elsewhere shows as Stay). HomeKit only picks up a changed list of modes on a new control, so changing this setting recreates the security system in the Home app: set up scenes and automations that use it again. |
+| `alarmTrigger` | `"incident"` | When the tile enters **Triggered**: `"incident"` immediately, when ecobee opens an incident as a door or sensor trips while armed (mirrors the ecobee app); `"entryDelay"` only after the entry (disarm) delay runs out without a disarm. Smoke alarms always trigger immediately. |
+| `smokeSensor` | `true` | Adds a separate **Smoke Alarm** accessory (a Smoke Sensor) that detects smoke while ecobee has a smoke-alarm incident open, for automations and Home app smoke notifications. Set to `false` to remove it. |
+| `airQuality` | `true` | For each thermostat with an air quality sensor: an accessory "&lt;thermostat&gt; Air Quality" with an **Air Quality Sensor** (overall level; VOC as ecobee reports it, in ppb, which the Home app labels µg/m³) and a **Carbon Dioxide Sensor** (ppm). Read every 5 minutes. The level follows the ecobee app's Clean–Poor bar: its first two segments are Excellent, then Good, Fair, Inferior, Poor; Unknown while the sensor calibrates. |
+| `co2Alert` | `1000` | CO2 (ppm) at or above which the Carbon Dioxide Sensor reports abnormal levels. |
+
 ## How it behaves
 
 - **Arm Away** uses ecobee's Away exit delay (60 s by default), just like the app. During the
@@ -68,13 +83,10 @@ node <plugin folder>/bin/ecobee-login.js --browser  # website sign-in
   (0 by default). Disarm needs no PIN.
 - **Changes from elsewhere** (ecobee app, keypad, ecobee automations) show up within the poll
   interval (10 s by default), and quickly after an exit delay ends.
-- **Alarm triggered** while ecobee lists an incident whose status isn't resolved/closed/cancelled.
-  ecobee opens an incident as soon as a door opens while armed, during the entry delay, so the
-  tile shows Alarm triggered from that moment, as the ecobee app does; disarming clears it.
-  Every change in the incident list is logged.
-- **Siri** calls Stay "Home": "set the security system to Home". Saying "arm … for stay" makes
-  Siri pick Away.
-- **Night** isn't offered; ecobee has no Night mode.
+- **Alarm triggered** while ecobee lists an open incident (see `alarmTrigger` above for when it
+  starts showing). Disarming clears it. Every change in the incident list is logged.
+- **Siri:** the Home app calls Stay "Home". Asking Siri for Home or for Stay mode both arm Stay.
+- **Night** is only offered with `offerNight`; ecobee has no Night mode of its own.
 - After three failed reads in a row the accessory shows a fault; reads back off up to 5 minutes.
 - **Hold for other plugins:** a Unix socket at `<homebridge storage>/ecobee-security/control.sock`
   (mode 600, homebridge user only) lets another plugin, e.g. homebridge-narwal, ask for a temporary

package/config.schema.json

@@ -32,6 +32,54 @@
         "default": 10,
         "minimum": 5,
         "description": "How often to read the armed state, so changes made in the ecobee app or at the keypad show up in Apple Home."
+      },
+      "offerNight": {
+        "title": "Offer Night",
+        "type": "boolean",
+        "default": false,
+        "description": "Adds Night to the Home app, for automations or Siri that use it. ecobee has no Night mode, so Night arms Stay; the Home app keeps showing Night until the state changes. Changing this setting recreates the security system in the Home app, so scenes and automations that use it have to be set up again."
+      },
+      "alarmTrigger": {
+        "title": "Enter Triggered State",
+        "type": "string",
+        "default": "incident",
+        "oneOf": [
+          {
+            "title": "Immediately (mirror ecobee app)",
+            "enum": [
+              "incident"
+            ]
+          },
+          {
+            "title": "After the Entry/Disarm delay",
+            "enum": [
+              "entryDelay"
+            ]
+          }
+        ],
+        "description": "ecobee opens an incident as soon as a door or sensor trips while armed. \"After the Entry/Disarm delay\" waits until that delay runs out without a disarm, so automations on Triggered don't fire while you're walking in to disarm. Smoke alarms always trigger immediately."
+      },
+      "smokeSensor": {
+        "title": "Smoke sensor",
+        "type": "boolean",
+        "default": true,
+        "description": "Adds a separate \"Smoke Alarm\" accessory to the Home app that detects smoke whenever ecobee reports a smoke-alarm incident, so you can use it in automations and get Home app smoke notifications."
+      },
+      "airQuality": {
+        "title": "Air quality sensors",
+        "type": "boolean",
+        "default": true,
+        "description": "For ecobee thermostats with an air quality sensor (ecobee Premium): adds an Air Quality Sensor (overall level and VOC) and a Carbon Dioxide Sensor (CO2 in ppm) per thermostat. ecobee's own HomeKit integration doesn't show these. Updated every 5 minutes."
+      },
+      "co2Alert": {
+        "title": "CO2 alert level (ppm)",
+        "type": "integer",
+        "default": 1000,
+        "minimum": 400,
+        "description": "The Carbon Dioxide Sensor reports abnormal CO2 at or above this level, for Home app notifications and automations (for example, turning on ventilation).",
+        "condition": {
+          "functionBody": "return model.airQuality !== false;"
+        }
       }
     }
   }

package/lib/airquality.js

@@ -0,0 +1,186 @@
+// Air quality from ecobee thermostats with the sensor (ecobee Premium): one accessory per thermostat
+// with an Air Quality Sensor (overall level, VOC) and a Carbon Dioxide Sensor (ppm, high-CO2 alert).
+// ecobee's own HomeKit integration doesn't expose these readings.
+import { SignInRequiredError } from './ecobee.js';
+
+const POLL = 5 * 60 * 1000;        // ecobee updates thermostat runtime every few minutes
+const FAULT_AFTER = 3;
+
+export class AirQualitySensors {
+  /**
+   * @param {object} options
+   * @param {import('homebridge').API} options.api
+   * @param {import('homebridge').Logging} options.log
+   * @param {import('./ecobee.js').EcobeeCloud} options.cloud
+   * @param {string} options.homeId
+   * @param {import('homebridge').PlatformAccessory[]} options.cached accessories restored by Homebridge
+   * @param {(uuid: string, name: string) => import('homebridge').PlatformAccessory} options.create new, unregistered accessory
+   * @param {(accessories: import('homebridge').PlatformAccessory[]) => void} options.register
+   * @param {(accessories: import('homebridge').PlatformAccessory[]) => void} options.update
+   * @param {(accessories: import('homebridge').PlatformAccessory[]) => void} options.unregister
+   * @param {number} options.co2Alert ppm at or above which the CO2 sensor reports abnormal levels
+   * @param {string} options.version plugin version, shown as firmware
+   */
+  constructor({ api, log, cloud, homeId, cached, create, register, update, unregister, co2Alert, version }) {
+    Object.assign(this, { api, log, cloud, homeId, cached, create, register, update, unregister, co2Alert, version });
+    this.C = api.hap.Characteristic;
+    this.sensors = new Map();      // thermostat id -> { accessory, air, co2 }
+    this.failures = 0;
+    this.stopped = false;
+  }
+
+  uuid(thermostatId) {
+    return this.api.hap.uuid.generate(`ecobee-security:air-quality:${thermostatId}`);
+  }
+
+  /** First read: create, keep or remove accessories to match the thermostats with air quality. */
+  async start() {
+    const thermostats = (await this.cloud.getAirQuality(this.homeId))
+      .filter(t => t.airQuality?.hasAirQualityEnabled);
+    const wanted = new Set(thermostats.map(t => this.uuid(t.id)));
+    const stale = this.cached.filter(a => !wanted.has(a.UUID));
+    if (stale.length) {
+      this.unregister(stale);
+    }
+    // Build each accessory completely (services and first readings) before it's published.
+    const added = [];
+    const kept = [];
+    for (const t of thermostats) {
+      const uuid = this.uuid(t.id);
+      const cached = this.cached.find(a => a.UUID === uuid);
+      const accessory = cached ?? this.create(uuid, `${t.name} Air Quality`);
+      (cached ? kept : added).push(accessory);
+      this.sensors.set(t.id, this.setUp(accessory, t));
+    }
+    this.apply(thermostats);
+    if (added.length) {
+      this.register(added);
+    }
+    if (kept.length) {
+      this.update(kept);
+    }
+    for (const t of thermostats) {
+      this.log.info(`Air quality, ${t.name}: ${describe(t)}.`);
+    }
+    this.schedule(POLL);
+  }
+
+  stop() {
+    this.stopped = true;
+    clearTimeout(this.timer);
+  }
+
+  schedule(delay) {
+    if (!this.stopped && this.sensors.size) {
+      clearTimeout(this.timer);
+      this.timer = setTimeout(() => this.poll(), delay);
+    }
+  }
+
+  setUp(accessory, thermostat) {
+    const { Service } = this.api.hap;
+    const C = this.C;
+    accessory.getService(Service.AccessoryInformation)
+      .setCharacteristic(C.Manufacturer, 'ecobee')
+      .setCharacteristic(C.Model, 'Thermostat air quality')
+      .setCharacteristic(C.SerialNumber, thermostat.id)
+      .setCharacteristic(C.FirmwareRevision, this.version);
+    const air = accessory.getService(Service.AirQualitySensor)
+      ?? accessory.addService(Service.AirQualitySensor, `${thermostat.name} Air Quality`);
+    // ecobee reports VOC in ppb, often above HomeKit's default 1000 limit.
+    air.getCharacteristic(C.VOCDensity).setProps({ maxValue: 10000 });
+    const co2 = accessory.getService(Service.CarbonDioxideSensor)
+      ?? accessory.addService(Service.CarbonDioxideSensor, `${thermostat.name} CO2`);
+    co2.getCharacteristic(C.CarbonDioxideLevel);
+    for (const service of [air, co2]) {
+      if (!service.testCharacteristic(C.StatusFault)) {
+        service.addCharacteristic(C.StatusFault);
+      }
+    }
+    return { accessory, air, co2, name: thermostat.name };
+  }
+
+  async poll() {
+    try {
+      this.apply(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);
+    } catch (error) {
+      this.failures += 1;
+      if (this.failures === FAULT_AFTER) {
+        this.setFault(true);
+      }
+      if (!(error instanceof SignInRequiredError)) {
+        this.log[this.failures >= FAULT_AFTER ? 'warn' : 'debug'](`Could not read air quality (${error.message}).`);
+      }
+    }
+    this.schedule(POLL);
+  }
+
+  setFault(on) {
+    const { StatusFault } = this.C;
+    for (const { air, co2 } of this.sensors.values()) {
+      air.updateCharacteristic(StatusFault, on ? StatusFault.GENERAL_FAULT : StatusFault.NO_FAULT);
+      co2.updateCharacteristic(StatusFault, on ? StatusFault.GENERAL_FAULT : StatusFault.NO_FAULT);
+    }
+  }
+
+  apply(thermostats) {
+    const { AirQuality, VOCDensity, CarbonDioxideLevel, CarbonDioxideDetected } = this.C;
+    for (const t of thermostats) {
+      const sensor = this.sensors.get(t.id);
+      if (!sensor) {
+        continue;
+      }
+      const aq = t.airQuality ?? {};
+      const runtime = t.runtime ?? {};
+      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));
+      }
+      if (Number.isFinite(runtime.actualCO2) && runtime.actualCO2 >= 0) {
+        sensor.co2.updateCharacteristic(CarbonDioxideLevel, Math.min(runtime.actualCO2, 100000));
+        sensor.co2.updateCharacteristic(CarbonDioxideDetected, runtime.actualCO2 >= this.co2Alert
+          ? CarbonDioxideDetected.CO2_LEVELS_ABNORMAL : CarbonDioxideDetected.CO2_LEVELS_NORMAL);
+      }
+      this.log.debug(`Air quality, ${sensor.name}: ${describe(t)}.`);
+    }
+  }
+}
+
+const LEVEL_NAMES = ['unknown', 'excellent', 'good', 'fair', 'inferior', 'poor'];
+
+function describe(t) {
+  const aq = t.airQuality ?? {};
+  const r = t.runtime ?? {};
+  const name = aq.isCalibrating ? 'calibrating' : LEVEL_NAMES[level(aq.airQualityScore, { UNKNOWN: 0, EXCELLENT: 1, GOOD: 2, FAIR: 3, INFERIOR: 4, POOR: 5 })];
+  return `${name} (score ${Number.isFinite(aq.airQualityScore) ? aq.airQualityScore.toFixed(2) : '?'}), `
+    + `CO2 ${r.actualCO2 ?? '?'} ppm, VOC ${r.actualVOC ?? '?'} ppb`;
+}
+
+/**
+ * ecobee's 0 (clean) … 1 (poor) score onto HomeKit's five levels, following the eight segments of
+ * the ecobee app's bar: 1–2 Excellent (the app calls 0.21 "Clean"), 3–4 Good, 5 Fair, 6 Inferior,
+ * 7–8 Poor.
+ */
+export function level(score, AirQuality) {
+  if (!Number.isFinite(score)) {
+    return AirQuality.UNKNOWN;
+  }
+  if (score < 0.25) {
+    return AirQuality.EXCELLENT;
+  }
+  if (score < 0.5) {
+    return AirQuality.GOOD;
+  }
+  if (score < 0.625) {
+    return AirQuality.FAIR;
+  }
+  if (score < 0.75) {
+    return AirQuality.INFERIOR;
+  }
+  return AirQuality.POOR;
+}

package/lib/ecobee.js

@@ -2,6 +2,8 @@
 
 export const AUTH = 'https://auth.ecobee.com';
 export const GRAPHQL = 'https://federated-api.prod.federated-graph.generacapis.com/graphql';
+// ecobee's older REST API; the app still reads thermostat runtime (CO2 ppm, VOC) from it.
+export const REST = 'https://api.ecobee.com/1';
 export const CLIENT_ID = 'CuGkX8Ai7OWD2V1F32rFa7UJGRVRsnbv';
 export const REDIRECT_URI = 'com.ecobee.athenamobile://auth.ecobee.com/ios/com.ecobee.athenamobile/callback';
 export const AUDIENCE = 'https://prod.ecobee.com/api/v1';
@@ -24,6 +26,9 @@ const STATE_QUERY = `query HomesSecurity { homes { id name capabilities monitori
   + 'homeMonitoringSettings { isProfessionalMonitoringEnabled armedStateSettings { '
   + 'armedAway { entryDelayDuration exitDelayDuration } armedStay { entryDelayDuration exitDelayDuration } } } } } }';
 
+const AIR_QUALITY_QUERY = 'query ThermostatsAirQuality($homeID: ID!) { homes(id: $homeID) { id devices { id '
+  + 'thermostats { id name airQuality { hasAirQualityEnabled carbonDioxideScore vocScore airQualityScore isCalibrating } } } } }';
+
 const SET_MUTATION = 'mutation SetArmedStateForHome($input: SetArmedStateForHomeInput!) { '
   + `setArmedStateForHome(input: $input) { home { id monitoring { ${MONITORING_FIELDS} } } success } }`;
 
@@ -119,6 +124,41 @@ export class EcobeeCloud {
     return data.homes ?? [];
   }
 
+  /**
+   * The home's thermostats with ecobee's air quality scores (0 = clean … 1 = poor), plus the
+   * runtime readings (`actualCO2` ppm, `actualVOC` ppb, `actualAQScore`) from the REST API.
+   */
+  async getAirQuality(homeId) {
+    const data = await this.graphql('ThermostatsAirQuality', AIR_QUALITY_QUERY, { homeID: homeId });
+    const thermostats = data.homes?.[0]?.devices?.thermostats ?? [];
+    if (!thermostats.length) {
+      return [];
+    }
+    const json = await this.rest('/thermostat', {
+      selectionType: 'thermostats', selectionMatch: thermostats.map(t => t.id).join(','), includeRuntime: true,
+    });
+    const runtime = new Map((json.thermostatList ?? []).map(t => [t.identifier, t.runtime ?? {}]));
+    return thermostats.map(t => ({ ...t, runtime: runtime.get(t.id) ?? {} }));
+  }
+
+  async rest(path, selection, retry = true) {
+    const token = await this.token();
+    const url = `${REST}${path}?json=${encodeURIComponent(JSON.stringify({ selection }))}`;
+    const res = await fetch(url, {
+      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json;charset=UTF-8', 'user-agent': USER_AGENT },
+      signal: AbortSignal.timeout(TIMEOUT),
+    });
+    if (res.status === 401 && retry) {
+      this.accessToken = undefined;
+      return this.rest(path, selection, false);
+    }
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok || (json.status?.code ?? 0) !== 0) {
+      throw new Error(`${path}: HTTP ${res.status} ${json.status?.message ?? ''}`.trim());
+    }
+    return json;
+  }
+
   /**
    * @param {string} homeId
    * @param {string} armedState one of ArmedState

package/lib/platform.js

@@ -3,12 +3,17 @@ import { join } from 'node:path';
 
 import { EcobeeCloud, SignInRequiredError } from './ecobee.js';
 import { startControlServer } from './control.js';
+import { AirQualitySensors } from './airquality.js';
 import { SecuritySystem } from './security.js';
+import { VERSION } from './version.js';
 
 export const PLUGIN_NAME = 'homebridge-ecobee-security';
 export const PLATFORM_NAME = 'EcobeeSecurityPlatform';
 
 const RETRY_START = 60 * 1000;
+const AIR_QUALITY_RETRY = 10 * 60 * 1000;
+const AIR_QUALITY = 'airQuality';
+const SMOKE = 'smoke';
 
 export class EcobeeSecurityPlatform {
   /**
@@ -56,8 +61,10 @@ export class EcobeeSecurityPlatform {
     });
     api.on('shutdown', () => {
       clearTimeout(this.retryTimer);
+      clearTimeout(this.airQualityRetry);
       this.control?.close();
       this.system?.stop();
+      this.airQuality?.stop();
     });
   }
 
@@ -115,7 +122,9 @@ export class EcobeeSecurityPlatform {
     }
 
     const uuid = this.api.hap.uuid.generate(`ecobee-security:${home.id}`);
-    const stale = this.cached.filter(a => a.UUID !== uuid);
+    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));
     if (stale.length) {
       this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, stale);
     }
@@ -124,6 +133,12 @@ export class EcobeeSecurityPlatform {
     if (isNew) {
       accessory = new this.api.platformAccessory(this.config.name || 'Security System', uuid);
     }
+    let smokeAccessory = wantSmoke ? this.cached.find(a => a.UUID === smokeUuid) : undefined;
+    const smokeIsNew = wantSmoke && !smokeAccessory;
+    if (smokeIsNew) {
+      smokeAccessory = new this.api.platformAccessory('Smoke Alarm', smokeUuid);
+      smokeAccessory.context.kind = SMOKE;
+    }
 
     this.system = new SecuritySystem({
       api: this.api,
@@ -134,12 +149,20 @@ export class EcobeeSecurityPlatform {
       pollInterval: Math.max(5, Number(this.config.pollInterval) || 10),
       store: this.store,
       save: () => this.save(),
+      offerNight: this.config.offerNight === true,
+      alarmAfterEntryDelay: this.config.alarmTrigger === 'entryDelay',
+      smokeAccessory,
     });
     if (isNew) {
       this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
     } else {
       this.api.updatePlatformAccessories([accessory]);
     }
+    if (smokeIsNew) {
+      this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [smokeAccessory]);
+    } else if (smokeAccessory) {
+      this.api.updatePlatformAccessories([smokeAccessory]);
+    }
     this.system.start();
     const m = home.monitoring;
     this.log.info(`Connected to "${home.name}" (${m.armedState}; professional monitoring `
@@ -147,5 +170,42 @@ export class EcobeeSecurityPlatform {
     if (this.store.hold) {
       this.log.info(`Still holding Stay for ${this.store.hold.by} (since ${this.store.hold.since}).`);
     }
+    this.startAirQuality(home.id);
+  }
+
+  /** Air quality sensors for thermostats that have them; failures here never affect the security system. */
+  async startAirQuality(homeId) {
+    const cached = this.cached.filter(a => a.context.kind === AIR_QUALITY);
+    if (this.config.airQuality === false) {
+      if (cached.length) {
+        this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, cached);
+      }
+      return;
+    }
+    const sensors = new AirQualitySensors({
+      api: this.api,
+      log: this.log,
+      cloud: this.cloud,
+      homeId,
+      cached,
+      co2Alert: Math.max(400, Number(this.config.co2Alert) || 1000),
+      version: VERSION,
+      create: (uuid, name) => {
+        const accessory = new this.api.platformAccessory(name, uuid);
+        accessory.context.kind = AIR_QUALITY;
+        return accessory;
+      },
+      register: accessories => this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, accessories),
+      update: accessories => this.api.updatePlatformAccessories(accessories),
+      unregister: accessories => this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, accessories),
+    });
+    try {
+      await sensors.start();
+      this.airQuality = sensors;
+    } catch (error) {
+      sensors.stop();
+      this.log.warn(`Could not set up air quality (${error.message}); trying again in 10 minutes.`);
+      this.airQualityRetry = setTimeout(() => this.startAirQuality(homeId), AIR_QUALITY_RETRY);
+    }
   }
 }

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.3.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",