homebridge-ecobee-security 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.8.0
+
+- While the plugin can't reach ecobee (three failed reads in a row, or signed out), the security
+  tile, the Smoke Alarm and the air quality sensors show **No Response** in the Home app instead of
+  their last state. They come back with the next successful read.
+- The security tile and Smoke Alarm also show **No Response** when ecobee's cloud can't reach the
+  thermostats Smart Security runs on: every thermostat unreachable for a minute. One dropping out
+  briefly doesn't count, and it comes back as soon as one is connected. A thermostat's air quality
+  sensors show No Response while ecobee can't reach it. Security holds are refused meanwhile.
+- New setting **Home Occupied switch** (`occupancySwitch`, off by default; `occupancyName`): a switch
+  for your Home app people-arrive and people-leave automations. Off arms Away like the Home app tile
+  does (waiting for robots that are out), on turns Away off (never Home, Night or Off). Switches
+  don't need the confirmation that automations controlling a security system do.
+- Settings page: the Home ID field is now a list of the homes on your ecobee account, shown only
+  when there's more than one (the list fills in once the plugin has started).
+
+## 0.7.1
+
+- Keypad unlock: the plugin now reads ecobee's current state first and only disarms when the system
+  is armed, arming or alarming. A disarm sent while it was already off was followed by ecobee camera
+  activity alerts.
+- An intrusion incident only shows as **Alarm triggered** while the system is armed. ecobee also
+  opens one for a camera activity alert while the system is off, which briefly showed as an alarm in
+  the Home app (and counted as one for security holds). Smoke alarms still show at any time.
+
 ## 0.7.0
 
 - New setting **Disarm when a door is unlocked with its keypad** (`keypadDisarm`, off by default,

package/README.md

@@ -69,7 +69,7 @@ node <plugin folder>/bin/ecobee-login.js --browser  # website sign-in
 }
 ```
 
-`homeId` is only needed if the account has several homes (the log lists them).
+`homeId` is only needed if the account has several homes (the settings page lists them).
 
 | Setting | Default | |
 |---|---|---|
@@ -80,6 +80,8 @@ node <plugin folder>/bin/ecobee-login.js --browser  # website sign-in
 | `holdPlugins` | all | The plugins allowed to do that; the settings page lists them. |
 | `armAwayNowSwitch` | `false` | Adds an **Arm Away Now** switch: arms Away immediately and asks any task in progress to stop (a robot goes home). |
 | `taskWaitSeconds` | `120` | How much longer the Away countdown may wait for a task to finish, e.g. a robot getting home (0: don't wait). |
+| `occupancySwitch` | `false` | Adds a **Home Occupied** switch for your presence automations (see [Home Occupied switch](#home-occupied-switch)). |
+| `occupancyName` | `"Home Occupied"` | The switch's name in the Home app. |
 | `keypadDisarm` | `false` | Turns the security system off when a door is unlocked with a code on its keypad (see [Keypad unlock](#keypad-unlock)). |
 | `keypadLocks` | all | The locks that do that, by serial number; the settings page lists the ones found. |
 | `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. |
@@ -92,12 +94,18 @@ node <plugin folder>/bin/ecobee-login.js --browser  # website sign-in
   exit delay (0 by default). Off needs no PIN.
 - **Changes from elsewhere** (ecobee app, keypad, ecobee automations) show up within 10 s, about
   as fast as in the ecobee app (it polls too), and quickly after an exit delay ends.
-- **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.
+- **Alarm triggered** while ecobee lists an open incident: a smoke alarm at any time, an intrusion
+  only while armed (ecobee also opens one for a camera activity alert while the system is off; that
+  isn't shown as an alarm). See `alarmTrigger` above for when it starts showing. Disarming clears it. Every change in the incident list is logged.
 - **Siri:** asking for Home or for Stay mode both set Home (ecobee's 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.
+- After three failed reads in a row the accessory shows a fault, and the security tile, Smoke Alarm and air
+  quality sensors show **No Response** instead of their last state until ecobee answers again; reads back off up to 5 minutes.
+  The security tile and Smoke Alarm also show No Response when ecobee can't reach your thermostats, which run
+  Smart Security, for a minute (all of them; one dropping out briefly doesn't count), and an air quality sensor
+  does when ecobee can't reach its thermostat.
 - **Keypad unlock:** unlocking a door with its keypad can turn the system off: see below.
+- **Home Occupied switch:** your arrive and leave automations can arm and disarm Away without a confirmation prompt: see below.
 - **Security holds** let other plugins, like a robot vacuum, keep the system from arming Away while they work: see below.
 
 ## Keypad unlock
@@ -111,6 +119,8 @@ schedules, expiry), so the plugin needs no codes of its own.
   unlocked (HomeKit's Lock Last Known Action), for example homebridge-nest-accfactory's Nest × Yale
   locks. The settings page lists the locks found; untick the ones that shouldn't disarm. Locks
   paired to Apple Home directly (not through Homebridge) can't be seen.
+- **Only when armed:** the plugin checks ecobee's current state first and sends nothing if the system
+  is already off.
 - **Only keypad unlocks** count: not the app, Siri, automations, a key or the thumb turn. Any code
   that opens the lock disarms, yours included.
 - **Speed:** the plugin checks the locks every second; the disarm reaches ecobee about as fast as
@@ -123,6 +133,39 @@ schedules, expiry), so the plugin needs no codes of its own.
   127.0.0.1 with the bridge PIN, since each child bridge runs in its own process. The log says if
   it isn't on.
 
+## Home Occupied switch
+
+Apple Home asks you to confirm (a notification you have to tap) whenever a people-arrive or
+people-leave automation changes a security system. Automations that flip an ordinary switch don't
+ask. Turn on **Home Occupied switch** (`occupancySwitch`) and the plugin adds a **Home Occupied**
+switch (named by `occupancyName`) that those automations set instead; the plugin then changes the
+security system itself.
+
+In the Home app, create two automations:
+
+1. **When the last person leaves** (People > Leave, "Everyone leaves") > turn **Home Occupied** off.
+2. **When the first person arrives** (People > Arrive, "Anyone arrives") > turn **Home Occupied** on.
+
+What each direction does:
+
+- **Off (nobody home)** arms **Away** exactly as Away from the Home app does: the normal exit delay,
+  and if a robot or other task is out it [waits for it](#security-holds). Home, Night and Off are all
+  switched to Away; if it is already Away, or waiting to be, nothing happens.
+- **On (someone home)** turns the system **off, but only if it is Away** (armed, arming, or waiting for
+  a task to finish). Home and Night, and a system that is already off, are left as they are, so
+  arriving never cancels the Home you set before bed.
+- Only a real change counts: setting the switch to the value it already has does nothing. It starts as
+  on and is remembered across restarts; restarting the plugin never arms or disarms anything.
+- The switch is your presence signal, not a mirror of the security system: arming or disarming
+  elsewhere doesn't move it.
+- If ecobee can't be reached, the switch still keeps its new value; the log says the security system
+  was left as it was (disarming is retried once).
+
+> [!CAUTION]
+> HomeKit doesn't ask for authorisation to use a switch. Turning Home Occupied on, by hand, with Siri
+> or from a shared home member's phone, turns off an Away system, so treat it as as sensitive as the
+> security tile itself.
+
 ## Security holds
 
 Things that move while you're out set off ecobee's motion sensors: a robot vacuum cleaning, or an AC

package/config.schema.json

@@ -24,7 +24,7 @@
       "homeId": {
         "title": "Home ID",
         "type": "string",
-        "description": "Only needed if your account has more than one home. The log lists your homes."
+        "description": "Only needed if your ecobee account has more than one home. The settings page lists them."
       },
       "offerNight": {
         "title": "Offer Night",
@@ -100,6 +100,21 @@
         },
         "description": "Serial numbers of the locks that disarm (the settings page lists the ones found). With no list, every lock does."
       },
+      "occupancySwitch": {
+        "title": "Home Occupied switch",
+        "type": "boolean",
+        "default": false,
+        "description": "Adds a Home Occupied switch to the Home app. Your own people-arrive and people-leave automations set it, and it does the rest: 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. See \"Home Occupied switch\" in the README."
+      },
+      "occupancyName": {
+        "title": "Home Occupied switch name",
+        "type": "string",
+        "default": "Home Occupied",
+        "description": "Name shown in the Home app.",
+        "condition": {
+          "functionBody": "return model.occupancySwitch === true;"
+        }
+      },
       "airQuality": {
         "title": "Air quality sensors",
         "type": "boolean",

package/homebridge-ui/public/index.html

@@ -64,10 +64,10 @@
     <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">
@@ -122,6 +122,23 @@
   </div>
 </div>
 
+<div class="card card-body mb-3" id="occupancy-card" hidden>
+  <h5 class="mb-2">Home Occupied switch</h5>
+  <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">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 id="occupancy-box" hidden>
+    <label for="s-occupancyName" class="form-label mb-1">Name</label>
+    <input class="form-control" type="text" id="s-occupancyName" data-key="occupancyName" data-type="text" data-default="Home Occupied">
+    <div class="hint mt-1">Name shown in the Home app.</div>
+  </div>
+</div>
+
 <div class="card card-body mb-3" id="holds-card" hidden>
   <h5 class="mb-2">Security holds</h5>
   <div class="form-check form-switch mb-1">
@@ -279,6 +296,8 @@
     const signedIn = Boolean(block?.refreshToken);
     $('system-card').hidden = !signedIn;
     $('sensors-card').hidden = !signedIn;
+    $('occupancy-card').hidden = !signedIn;
+    await showHomes(block);
     for (const input of controls) {
       const value = block?.[input.dataset.key];
       if (input.dataset.type === 'bool') {
@@ -288,6 +307,27 @@
       }
     }
     $('co2-box').hidden = block?.airQuality === false;
+    $('occupancy-box').hidden = block?.occupancySwitch !== true;
+  }
+
+  /**
+   * 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,6 +345,8 @@
         await setSetting(key, input.checked);
         if (key === 'airQuality') {
           $('co2-box').hidden = !input.checked;
+        } else if (key === 'occupancySwitch') {
+          $('occupancy-box').hidden = !input.checked;
         }
       } else if (type === 'int') {
         const number = input.value.trim() === '' ? undefined : Number(input.value);
@@ -314,7 +356,7 @@
           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());
       }

package/homebridge-ui/server.js

@@ -82,6 +82,16 @@ 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 [];
+      }
+    });
+
     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/ecobee.js

@@ -21,7 +21,11 @@ export const ArmedState = {
 
 const MONITORING_FIELDS = 'armedState delayedArmedState { desiredArmedState delayedUntil }';
 
-const STATE_QUERY = `query HomesSecurity { homes { id name capabilities monitoring { ${MONITORING_FIELDS} `
+// Smart Security runs on the thermostats; `connected` is false while ecobee's cloud can't reach one.
+const DEVICE_FIELDS = 'devices { thermostats { id name legacyRuntime { connected } } } ';
+
+const stateQuery = withDevices => `query HomesSecurity { homes { id name capabilities ${withDevices ? DEVICE_FIELDS : ''}`
+  + `monitoring { ${MONITORING_FIELDS} `
   + 'incidents { id status detectedIntrusion detectedSmokeAlarm } '
   + 'homeMonitoringSettings { isProfessionalMonitoringEnabled armedStateSettings { '
   + 'armedAway { entryDelayDuration exitDelayDuration } armedStay { entryDelayDuration exitDelayDuration } } } } } }';
@@ -110,7 +114,11 @@ export class EcobeeCloud {
         this.accessToken = undefined;
         return this.graphql(operationName, query, variables, false);
       }
-      throw new Error(`${operationName}: ${message}`);
+      const error = new Error(`${operationName}: ${message}`);
+      // The query itself was rejected (a field ecobee doesn't have), not the request.
+      error.validation = json.errors.some(e => e.extensions?.code === 'GRAPHQL_VALIDATION_FAILED'
+        || /cannot query field|unknown (field|type)/i.test(e.message));
+      throw error;
     }
     if (!res.ok) {
       throw new Error(`${operationName}: HTTP ${res.status}`);
@@ -118,10 +126,25 @@ export class EcobeeCloud {
     return json.data;
   }
 
-  /** All homes on the account with their security state. */
+  /**
+   * All homes on the account with their security state and thermostat connectivity. If ecobee
+   * rejects the connectivity fields, they're dropped for good (logged once) and the security state
+   * is read without them.
+   */
   async getHomes() {
-    const data = await this.graphql('HomesSecurity', STATE_QUERY);
-    return data.homes ?? [];
+    if (!this.withoutDevices) {
+      try {
+        return (await this.graphql('HomesSecurity', stateQuery(true))).homes ?? [];
+      } catch (error) {
+        if (!error.validation) {
+          throw error;
+        }
+        this.withoutDevices = true;
+        this.log.warn(`ecobee doesn't accept the thermostat connectivity check (${error.message}); `
+          + 'carrying on without it.');
+      }
+    }
+    return (await this.graphql('HomesSecurity', stateQuery(false))).homes ?? [];
   }
 
   /**

package/lib/platform.js

@@ -16,6 +16,7 @@ const AIR_QUALITY_RETRY = 10 * 60 * 1000;
 const AIR_QUALITY = 'airQuality';
 const SMOKE = 'smoke';
 const ARM_NOW = 'armAwayNow';
+const OCCUPANCY = 'occupancy';
 
 export class EcobeeSecurityPlatform {
   /**
@@ -119,6 +120,9 @@ export class EcobeeSecurityPlatform {
 
   async setup() {
     const homes = await this.cloud.getHomes();
+    // For the settings page's home list (it only offers a choice when there's more than one).
+    this.store.homes = homes.map(h => ({ id: h.id, name: h.name, security: Boolean(h.monitoring) }));
+    this.save();
     const wanted = this.config.homeId?.trim();
     const home = wanted
       ? homes.find(h => h.id === wanted)
@@ -139,8 +143,11 @@ export class EcobeeSecurityPlatform {
     const wantSmoke = this.config.smokeSensor !== false;
     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 occupancyUuid = this.api.hap.uuid.generate(`ecobee-security:occupancy:${home.id}`);
+    const wantOccupancy = this.config.occupancySwitch === true;
     const stale = this.cached.filter(a => a.UUID !== uuid && a.context.kind !== AIR_QUALITY
-      && !(wantSmoke && a.UUID === smokeUuid) && !(wantArmNow && a.UUID === armNowUuid));
+      && !(wantSmoke && a.UUID === smokeUuid) && !(wantArmNow && a.UUID === armNowUuid)
+      && !(wantOccupancy && a.UUID === occupancyUuid));
     if (stale.length) {
       this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, stale);
     }
@@ -184,6 +191,13 @@ export class EcobeeSecurityPlatform {
     if (wantArmNow) {
       this.setupArmNow(armNowUuid, home.id);
     }
+    if (wantOccupancy) {
+      this.setupOccupancy(occupancyUuid, home.id);
+    } else if (this.store.occupied !== undefined) {
+      // Not kept while the switch is off: it would be stale when the switch comes back.
+      delete this.store.occupied;
+      this.save();
+    }
     this.system.start();
     const m = home.monitoring;
     this.log.info(`Connected to "${home.name}" (${m.armedState}; professional monitoring `
@@ -274,6 +288,58 @@ export class EcobeeSecurityPlatform {
     }
   }
 
+  /**
+   * The Home Occupied switch (its own accessory): the Home app's people-arrive and people-leave
+   * automations can set an ordinary switch without the confirmation prompt they need for a security
+   * system. Off (nobody home) arms Away like the tile does; on (someone home) disarms Away only. It
+   * is the user's presence signal, so it never follows the security system. The state is kept in
+   * the store (on until told otherwise); starting up does nothing.
+   */
+  setupOccupancy(uuid, homeId) {
+    const { Service, Characteristic } = this.api.hap;
+    const name = this.config.occupancyName?.trim() || 'Home Occupied';
+    let accessory = this.cached.find(a => a.UUID === uuid);
+    const isNew = !accessory;
+    if (isNew) {
+      accessory = new this.api.platformAccessory(name, uuid);
+      accessory.context.kind = OCCUPANCY;
+    }
+    accessory.displayName = name;
+    accessory.getService(Service.AccessoryInformation)
+      .setCharacteristic(Characteristic.Manufacturer, 'ecobee')
+      .setCharacteristic(Characteristic.Model, 'Smart Security: Home Occupied')
+      .setCharacteristic(Characteristic.SerialNumber, `${homeId}-occupancy`)
+      .setCharacteristic(Characteristic.FirmwareRevision, VERSION);
+    this.occupancy = accessory.getService(Service.Switch) ?? accessory.addService(Service.Switch, name);
+    this.occupancy.setCharacteristic(Characteristic.Name, name);
+    this.occupancy.getCharacteristic(Characteristic.On)
+      .onGet(() => this.store.occupied !== false)
+      .onSet(on => this.setOccupied(Boolean(on), 'Home Occupied'));
+    if (isNew) {
+      this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
+    } else {
+      this.api.updatePlatformAccessories([accessory]);
+    }
+  }
+
+  /**
+   * Someone is home or nobody is. Only a real change does anything. `source` is who says so: the
+   * switch today; another source (say, ecobee's own location sensing) would call this too and the
+   * switch follows it.
+   */
+  setOccupied(occupied, source) {
+    if (occupied === (this.store.occupied !== false)) {
+      return;
+    }
+    this.store.occupied = occupied;
+    this.save();
+    this.occupancy?.updateCharacteristic(this.api.hap.Characteristic.On, occupied);
+    this.log.info(`${source}: ${occupied ? 'someone is home' : 'nobody is home'}.`);
+    // Not awaited: Home app automations don't wait on the cloud, and a failure doesn't change the
+    // fact that was reported (the system logs it).
+    this.system.occupancyChanged(occupied, source).catch(() => {});
+  }
+
   /**
    * May this plugin (or, if it doesn't say, this name) ask for a hold? `true`, `'off'` (holds are off),
    * or `'not allowed'`. Without a `holdPlugins` list (settings from before it), every plugin may.

package/lib/security.js

@@ -37,6 +37,8 @@ const MAX_BACKOFF = 5 * 60 * 1000;
 // Robots back (or stopped) before an extended exit delay ends: arm this long after, at the earliest.
 const ARM_AFTER_RETURN = 10 * 1000;
 const FAULT_AFTER = 3;
+// Every thermostat unreachable for this long (ms): the security system counts as offline.
+const OFFLINE_AFTER = 60 * 1000;
 
 export class SecuritySystem {
   /**
@@ -67,13 +69,19 @@ export class SecuritySystem {
     this.homeId = home.id;
     this.pollInterval = pollInterval * 1000;
     this.failures = 0;
+    // The tiles show No Response instead of the last state when either holds: the plugin can't reach
+    // ecobee (or is signed out), or ecobee's cloud can't reach the thermostats Smart Security runs on.
+    this.cloudDown = false;
+    this.thermostatsDown = false;
+    this.outSince = undefined;
+    this.outKey = '';
     this.commandAt = 0;
     this.stopped = false;
     this.offerNight = offerNight;
     this.alarmAfterEntryDelay = alarmAfterEntryDelay;
     // Extra exit-delay time for robots heading back to their base when Away is armed (ms).
     this.returnWait = Math.max(0, returnWait) * 1000;
-    this.incidents = [];
+    this.openIncidents = [];
     this.firstSeen = new Map();
 
     const { Service, Characteristic } = api.hap;
@@ -98,9 +106,11 @@ export class SecuritySystem {
     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: offerNight ? [Hk.STAY, Hk.AWAY, Hk.NIGHT, Hk.DISARMED, Hk.TRIGGERED] : [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] })
+      .onGet(() => this.read(this.current, Characteristic.SecuritySystemCurrentState));
     this.service.getCharacteristic(Characteristic.SecuritySystemTargetState)
       .setProps({ validValues: offerNight ? [Hk.STAY, Hk.AWAY, Hk.NIGHT, Hk.DISARMED] : [Hk.STAY, Hk.AWAY, Hk.DISARMED] })
+      .onGet(() => this.read(this.shownTarget, Characteristic.SecuritySystemTargetState))
       .onSet(value => this.setTarget(value));
     if (!this.service.testCharacteristic(Characteristic.StatusFault)) {
       this.service.addCharacteristic(Characteristic.StatusFault);
@@ -120,6 +130,8 @@ export class SecuritySystem {
         .setCharacteristic(Characteristic.FirmwareRevision, VERSION);
       this.smoke = smokeAccessory.getService(Service.SmokeSensor)
         ?? smokeAccessory.addService(Service.SmokeSensor, smokeAccessory.displayName);
+      this.smoke.getCharacteristic(Characteristic.SmokeDetected)
+        .onGet(() => this.read(this.smokeShown, Characteristic.SmokeDetected, this.smoke));
       if (!this.smoke.testCharacteristic(Characteristic.StatusFault)) {
         this.smoke.addCharacteristic(Characteristic.StatusFault);
       }
@@ -155,15 +167,15 @@ export class SecuritySystem {
       if (!home) {
         throw new Error('the home is no longer on this ecobee account');
       }
+      const wasOffline = this.offline;
+      this.reachable();
+      this.noteThermostats(home.devices?.thermostats);
       // A command that finished while this poll was running is newer than what we just read.
       if (startedAt >= this.commandAt) {
         this.apply(home);
+      } else if (wasOffline && !this.offline) {
+        this.apply({});
       }
-      if (this.failures >= FAULT_AFTER) {
-        this.log.info('ecobee is reachable again.');
-      }
-      this.failures = 0;
-      this.setFault(false);
       const until = Date.parse(home.monitoring?.delayedArmedState?.delayedUntil ?? '');
       if (until > Date.now()) {
         // Catch the end of an exit delay promptly.
@@ -172,14 +184,14 @@ export class SecuritySystem {
     } catch (error) {
       this.failures += 1;
       if (error instanceof SignInRequiredError) {
-        this.setFault(true);
+        this.setOffline();
         this.log.error(`${error.message}. Sign in again: run bin/ecobee-login.js (see the plugin README), `
           + 'paste the new refresh token into the plugin settings and restart the bridge.');
         return;
       }
       next = Math.min(this.pollInterval * 2 ** this.failures, MAX_BACKOFF);
       if (this.failures === FAULT_AFTER) {
-        this.setFault(true);
+        this.setOffline();
       }
       const say = this.failures >= FAULT_AFTER ? 'warn' : 'debug';
       this.log[say](`Could not read the security state (${error.message}); retrying in ${Math.round(next / 1000)} s.`);
@@ -194,6 +206,95 @@ export class SecuritySystem {
     this.smoke?.updateCharacteristic(StatusFault, value);
   }
 
+  /** Offline for either reason; the tiles show No Response. */
+  get offline() {
+    return this.cloudDown || this.thermostatsDown;
+  }
+
+  /** The plugin can't reach ecobee: the tiles show No Response. The fault stays set for as long. */
+  setOffline() {
+    const wasOffline = this.offline;
+    this.cloudDown = true;
+    this.setFault(true);
+    if (!wasOffline) {
+      this.pushNoResponse();
+    }
+  }
+
+  /** A read or command got through: ecobee is reachable (apply() then puts the real state back on the tiles). */
+  reachable() {
+    if (this.cloudDown) {
+      this.log.info('ecobee is reachable again.');
+    }
+    this.cloudDown = false;
+    this.failures = 0;
+    this.setFault(this.offline);
+  }
+
+  /** Pushed at once, so the tile changes without waiting for the Home app to read it. */
+  pushNoResponse() {
+    const { SecuritySystemCurrentState, SecuritySystemTargetState, SmokeDetected } = this.C;
+    this.service.updateCharacteristic(SecuritySystemCurrentState, this.noResponse());
+    this.service.updateCharacteristic(SecuritySystemTargetState, this.noResponse());
+    this.smoke?.updateCharacteristic(SmokeDetected, this.noResponse());
+  }
+
+  /**
+   * ecobee's view of the thermostats (their `connected` flags). The system counts as offline once
+   * every thermostat that reports a flag has been unreachable for OFFLINE_AFTER, without a break; a
+   * single thermostat dropping out for a moment is normal (debug log only). Back as soon as one is
+   * connected. Without the data (ecobee rejected the fields), there is no check. The next apply()
+   * puts the real state back on the tiles.
+   */
+  noteThermostats(thermostats = []) {
+    const known = thermostats.filter(t => typeof t.legacyRuntime?.connected === 'boolean');
+    const out = known.filter(t => !t.legacyRuntime.connected).map(t => t.name ?? t.id);
+    const key = out.join(', ');
+    if (key !== this.outKey) {
+      this.outKey = key;
+      this.log.debug(out.length ? `ecobee can't reach: ${key}.` : 'ecobee reaches all thermostats.');
+    }
+    if (!known.length || out.length < known.length) {
+      this.outSince = undefined;
+      if (this.thermostatsDown) {
+        this.thermostatsDown = false;
+        this.log.info('Smart Security is back online.');
+        this.setFault(this.offline);
+      }
+      return;
+    }
+    this.outSince ??= Date.now();
+    if (!this.thermostatsDown && Date.now() - this.outSince >= OFFLINE_AFTER) {
+      const wasOffline = this.offline;
+      this.thermostatsDown = true;
+      this.log.warn(`Smart Security is offline: ecobee can't reach the thermostats (${key}).`);
+      this.setFault(true);
+      if (!wasOffline) {
+        this.pushNoResponse();
+      }
+    }
+  }
+
+  noResponse() {
+    return new this.api.hap.HapStatusError(this.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
+  }
+
+  /** A Home app read: the last known value, or No Response while ecobee can't be reached. */
+  read(value, characteristic, service = this.service) {
+    if (this.offline) {
+      throw this.noResponse();
+    }
+    return value ?? service.getCharacteristic(characteristic).value;
+  }
+
+  /** What the Home app shows as the target, unless ecobee can't be reached. */
+  showTarget(value) {
+    this.shownTarget = value;
+    if (!this.offline) {
+      this.service.updateCharacteristic(this.C.SecuritySystemTargetState, value);
+    }
+  }
+
   /** Apply a GraphQL home (or just its monitoring object) to HomeKit. */
   apply(home) {
     const monitoring = home.monitoring ?? {};
@@ -250,17 +351,33 @@ export class SecuritySystem {
       this.save();
     }
     // Away asked for in the Home app during a hold waits for the release: show it as arming Away.
-    this.service.updateCharacteristic(SecuritySystemTargetState, this.store.hold?.away ? Hk.AWAY : target);
-    this.service.updateCharacteristic(SecuritySystemCurrentState, current);
+    this.shownTarget = this.store.hold?.away ? Hk.AWAY : target;
     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);
+      this.smokeShown = smoke ? SmokeDetected.SMOKE_DETECTED : SmokeDetected.SMOKE_NOT_DETECTED;
+    }
+    // Pushed whether it changed or not, so the tiles come back from No Response. Not while offline:
+    // an alarm timer or a late command must not hide it.
+    if (this.offline) {
+      return;
     }
+    this.service.updateCharacteristic(SecuritySystemTargetState, this.shownTarget);
+    this.service.updateCharacteristic(SecuritySystemCurrentState, current);
+    this.smoke?.updateCharacteristic(this.C.SmokeDetected, this.smokeShown);
+  }
+
+  /**
+   * Open incidents that are alarms: smoke always, intrusions only while armed. ecobee also opens an
+   * intrusion incident for a camera activity alert while the system is off; that isn't an alarm.
+   */
+  get incidents() {
+    const armed = [ArmedState.STAY, ArmedState.AWAY].includes(this.monitoring?.armedState);
+    return this.openIncidents.filter(i => i.detectedSmokeAlarm || armed);
   }
 
   noteIncidents(incidents) {
-    this.incidents = incidents.filter(i => !CLOSED_INCIDENT.test(i.status ?? ''));
+    this.openIncidents = incidents.filter(i => !CLOSED_INCIDENT.test(i.status ?? ''));
     const summary = JSON.stringify(incidents);
     if (summary !== this.incidentSummary) {
       if (incidents.length || this.incidentSummary !== undefined) {
@@ -270,8 +387,8 @@ export class SecuritySystem {
     }
     // 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));
+    const ids = new Set(this.openIncidents.map(i => i.id));
+    this.openIncidents.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));
   }
 
@@ -325,24 +442,25 @@ export class SecuritySystem {
     return 0;
   }
 
-  async setTarget(value) {
+  /** @param {string} [source] who asked, for the log (the Home Occupied switch asks too) */
+  async setTarget(value, source = 'Home app') {
     if (TO_ECOBEE[value] === undefined || (value === Hk.NIGHT && !this.offerNight)) {
       throw new this.api.hap.HapStatusError(this.api.hap.HAPStatus.INVALID_VALUE_IN_REQUEST);
     }
     // HomeKit can't say who asked (requests come through the home hub), so Away always waits for
     // robots that are out; the Arm Away Now switch is the way to stop them and arm now.
-    if (value === Hk.AWAY && this.outNames().length && await this.serial(() => this.deferAway())) {
+    if (value === Hk.AWAY && this.outNames().length && await this.serial(() => this.deferAway(source))) {
       return;
     }
     if (this.store.hold) {
-      this.log.info(`Home app changed the security system during the ${this.holders().join(' and ')} hold; it won't be put back to Away.`);
+      this.log.info(`${source} changed the security system during the ${this.holders().join(' and ')} hold; it won't be put back to Away.`);
       this.dropHold();
     }
     try {
-      await this.serial(() => this.arm(value, 'Home app'));
+      await this.serial(() => this.arm(value, source));
     } catch (error) {
       // Put the Home app's target back to what ecobee really has.
-      setTimeout(() => this.service.updateCharacteristic(this.C.SecuritySystemTargetState, this.target ?? Hk.DISARMED), 500);
+      setTimeout(() => this.showTarget(this.target ?? Hk.DISARMED), 500);
       throw new this.api.hap.HapStatusError(this.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
     }
   }
@@ -353,7 +471,7 @@ export class SecuritySystem {
    * the release arms Away anyway, so keep (or start) the hold and let it; Stay meanwhile. Returns
    * true if Away now waits.
    */
-  async deferAway() {
+  async deferAway(source = 'Home app') {
     const out = this.outNames();
     if (!out.length || this.incidents.length || (this.store.hold && this.target !== Hk.STAY)) {
       return false;
@@ -367,9 +485,9 @@ export class SecuritySystem {
     }
     this.store.hold = { ...this.store.hold, away: true };
     this.save();
-    this.log.info(`Home app: arm Away — waiting until ${this.holders().join(' and ')} ${this.holders().length > 1 ? 'are' : 'is'} done (security hold). `
+    this.log.info(`${source}: arm Away — waiting until ${this.holders().join(' and ')} ${this.holders().length > 1 ? 'are' : 'is'} done (security hold). `
       + 'Use the Arm Away Now switch to stop and arm now.');
-    this.service.updateCharacteristic(this.C.SecuritySystemTargetState, Hk.AWAY);
+    this.showTarget(Hk.AWAY);
     return true;
   }
 
@@ -388,9 +506,8 @@ export class SecuritySystem {
 
 
   /**
-   * A door was unlocked with its keypad: disarm, like Nest Guard with a Nest × Yale lock. Always sent,
-   * even if the last poll said Off: it may be up to 10 s old, and disarming twice does no harm.
-   * Retried once, since a missed disarm means an alarm.
+   * A door was unlocked with its keypad: disarm, like Nest Guard with a Nest × Yale lock. Retried
+   * once, since a missed disarm means an alarm.
    */
   keypadDisarm(lock) {
     return this.serial(async () => {
@@ -398,6 +515,13 @@ export class SecuritySystem {
         this.log.info(`${lock} was unlocked during the ${this.holders().join(' and ')} hold; it won't be put back to Away.`);
         this.dropHold();
       }
+      // Only disarm what's armed: a disarm sent while ecobee is already off isn't a no-op for ecobee
+      // (camera activity alerts followed it), so read the live state first. Can't read it: disarm anyway.
+      if (await this.refresh() && this.monitoring?.armedState === ArmedState.DISARMED
+        && !this.monitoring.delayedArmedState?.desiredArmedState) {
+        this.log.info(`${lock} was unlocked with its keypad; the security system is already off.`);
+        return;
+      }
       try {
         await this.arm(Hk.DISARMED, `${lock} unlocked with its keypad`);
       } catch {
@@ -407,6 +531,64 @@ export class SecuritySystem {
     });
   }
 
+  /**
+   * The Home Occupied switch (or another source of presence) changed. Empty arms Away the way Away
+   * from the Home app does: waiting for robots that are out, with the normal exit delay. Occupied
+   * disarms an Away system only (armed, arming, or waiting on a hold), never Home, Night or Off.
+   * Failures are logged, not thrown: the presence fact stays true either way.
+   * @param {boolean} occupied
+   * @param {string} [source] who says so, for the log
+   */
+  async occupancyChanged(occupied, source = 'Home Occupied') {
+    try {
+      if (occupied) {
+        await this.serial(() => this.disarmAway(source));
+      } else {
+        await this.armAwayEmpty(source);
+      }
+    } catch (error) {
+      this.log.warn(`${source}: could not ${occupied ? 'disarm' : 'arm Away'} (${error.message}). `
+        + 'The security system is left as it is.');
+    }
+  }
+
+  async armAwayEmpty(source) {
+    // The live state, not the last poll: Away arrived by another route a moment ago must not restart.
+    await this.refresh();
+    // Under a hold the system shows Home, but Away is on its way back (or asked for).
+    if (this.target === Hk.AWAY || this.store.hold) {
+      this.log.info(`${source}: nobody home; the security system is already Away, or waiting to be.`);
+      return;
+    }
+    this.log.info(`${source}: nobody home; arming Away.`);
+    await this.setTarget(Hk.AWAY, source);
+  }
+
+  /**
+   * Someone is home: turn Away off. A held system (a robot is out) counts as Away, since the release
+   * would arm it again. Like keypadDisarm: decide on the live state and retry once.
+   */
+  async disarmAway(source) {
+    const live = await this.refresh();
+    const away = this.target === Hk.AWAY || Boolean(this.store.hold);
+    if (!away) {
+      // Can't read ecobee: only the last state we saw can say, and that's no Away.
+      this.log.info(`${source}: someone is home; the security system is ${HK_NAMES[this.current]}`
+        + `${live ? '' : ' (as last seen; ecobee could not be read)'}, so it is left as it is.`);
+      return;
+    }
+    if (this.store.hold) {
+      this.log.info(`${source}: someone is home during the ${this.holders().join(' and ')} hold; it won't be put back to Away.`);
+      this.dropHold();
+    }
+    try {
+      await this.arm(Hk.DISARMED, `${source}: someone is home`);
+    } catch {
+      await new Promise(resolve => setTimeout(resolve, 2000));
+      await this.arm(Hk.DISARMED, `${source}: someone is home (retry)`);
+    }
+  }
+
   /** Robots (or other plugins) that asked for a hold and haven't released yet, held or not. */
   outNames() {
     return Object.keys(this.store.out ?? {});
@@ -501,6 +683,7 @@ export class SecuritySystem {
   async setExitDelayEnd(until) {
     const monitoring = await this.cloud.setArmedState(this.homeId, ArmedState.AWAY, 0, until);
     this.commandAt = Date.now();
+    this.reachable();
     if (monitoring) {
       this.apply({ monitoring });
     }
@@ -523,6 +706,7 @@ export class SecuritySystem {
     try {
       const monitoring = await this.cloud.setArmedState(this.homeId, armedState, delay);
       this.commandAt = Date.now();
+      this.reachable();
       if ((value === Hk.NIGHT) !== Boolean(this.store.night)) {
         if (value === Hk.NIGHT) {
           this.store.night = true;
@@ -549,10 +733,12 @@ export class SecuritySystem {
       if (!home) {
         throw new Error('the home is no longer on this ecobee account');
       }
+      this.reachable();
+      this.noteThermostats(home.devices?.thermostats);
       this.apply(home);
       return true;
     } catch (error) {
-      this.log.warn(`Could not read the security state for a hold (${error.message}).`);
+      this.log.warn(`Could not read the security state (${error.message}).`);
       return false;
     }
   }
@@ -580,6 +766,9 @@ export class SecuritySystem {
       if (!(await this.refresh()) || !this.monitoring) {
         return { ok: false, held: false, state: 'unknown', reason: 'the security state is unknown' };
       }
+      if (this.offline) {
+        return { ok: false, held: false, state: 'offline', reason: 'the security system is offline' };
+      }
       if (this.incidents.length) {
         return { ok: false, held: false, state: HK_NAMES[this.current], reason: 'an alarm incident is open' };
       }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-ecobee-security",
   "displayName": "ecobee Smart Security",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "ecobee Smart Security as a HomeKit security system: arm Stay / Away, disarm, alarm state (unofficial, ecobee cloud)",
   "type": "module",
   "main": "index.js",