homebridge-ecobee-security 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.7.0
+
+- New setting **Disarm when a door is unlocked with its keypad** (`keypadDisarm`, off by default,
+  in a new **Door keypads** card): entering a code on a smart lock's keypad turns the security system
+  off, like Nest Guard with a Nest × Yale lock. Works with locks from the same Homebridge that report
+  keypad unlocks (HomeKit's Lock Last Known Action, read over HAP on 127.0.0.1; needs insecure mode).
+  The settings page lists the locks found (`keypadLocks`; no list = all).
+
+## 0.6.0
+
+- Security holds now keep Away off while a plugin (a robot vacuum) works, instead of just switching
+  Away to Home (ecobee's Stay). A plugin counts as out from its first hold until it releases, even if nothing was held.
+- Away from the Home app (a scene, automation, Siri or the tile) while a robot is out waits for it:
+  the hold is kept (or started), Home meanwhile, and the release arms Away; the tile shows Arming
+  Away while it waits. Home, Night and Off in the Home app, and an alarm, still cancel the hold
+  and the waiting Away.
+- New setting **Arm Away Now switch** (`armAwayNowSwitch`, in Security holds, off by default): adds
+  an Arm Away Now switch to the Home app that arms Away now and sends any robots that are out back to
+  their base.
+- Away armed in the ecobee app or at the keypad while a robot is out asks the robot to head back to
+  its base before the exit delay ends, or to stop where it is if it can't make it. Plugins give a halt
+  endpoint with their hold request (`&halt=`), and the request says when the exit delay ends
+  (`&armAt=`; left out for a keypad Away, which is only seen once armed: the robot stops at once). A
+  robot that moves again asks for a new hold.
+- New setting **Extra time for tasks to finish** (`taskWaitSeconds`, default 120, 0 = off):
+  when Away is armed from the ecobee app or the Arm Away Now switch while a task is running (like a
+  robot heading back to its base), the exit delay is extended by this much, and brought forward again
+  once the task is done (never earlier than it would have ended). A robot says it's docked, or stopped, with
+  `/release`; robots answer the halt with `returning: true` when they head back.
+
 ## 0.5.0
 
 - The `pollInterval` setting is gone: the security state is read every 10 s, as often as the ecobee
@@ -28,35 +58,7 @@
 
 ## 0.4.1
 
+First public release.
+
 - Plugin icon in the README.
 - Catch and log errors creating the storage folder or control socket instead of stopping the bridge.
-
-## 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
-  and MFA code. No terminal or browser developer tools needed; the website sign-in is still there
-  as a fallback.
-- `bin/ecobee-login.js` signs in with email and password by default; `--browser` for the old way.
-
-## 0.2.0
-
-- Control socket (`control.sock`) so other plugins can hold the system at Stay and release it to
-  Away afterwards (used by homebridge-narwal while the robot vacuum cleans).
-
-## 0.1.0
-
-- First release: arm Stay / Away, disarm and alarm state in Apple Home, browser sign-in script.

package/README.md

@@ -2,8 +2,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. It also adds
+Shows **ecobee Smart Security** in Apple Home as a security system: set it to **Home**, **Away** or
+**Off** (ecobee's Stay, Away and disarmed), and see **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
@@ -72,76 +73,127 @@ node <plugin folder>/bin/ecobee-login.js --browser  # website sign-in
 
 | 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. |
+| `offerNight` | `false` | Adds Night to the Home app. ecobee has no Night mode, so Night arms ecobee's Stay, and the tile keeps showing Night until the state changes (Stay armed in the ecobee app or at the keypad shows as Home). 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. |
-| `allowHolds` | `false` | Lets other Homebridge plugins ask for a **security hold** (see below), e.g. so a robot vacuum can clean while you're away without setting off the motion sensors. Off: hold requests are refused, and a hold left over from before is dropped without re-arming Away. |
+| `allowHolds` | `false` | Lets other plugins, like a robot vacuum, keep the system from arming Away while their task runs (see [Security holds](#security-holds)). |
+| `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). |
+| `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. |
 | `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
-  delay the Home app shows "Arming…" (current Disarmed, target Away). Stay uses the Stay exit delay
-  (0 by default). Disarm needs no PIN.
+  delay the Home app shows "Arming…" (current Off, target Away). Home and Night use ecobee's Stay
+  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.
-- **Siri:** the Home app calls Stay "Home". Asking Siri for Home or for Stay mode both arm Stay.
+- **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.
-- **Security holds** for other plugins, with `allowHolds`: see below.
+- **Keypad unlock:** unlocking a door with its keypad can turn the system off: see below.
+- **Security holds** let other plugins, like a robot vacuum, keep the system from arming Away while they work: see below.
+
+## Keypad unlock
+
+Turn on **Disarm when a door is unlocked with its keypad** (`keypadDisarm`) and entering a code on a
+smart lock's keypad turns the security system off, like Nest Guard did with a Nest × Yale lock.
+Family and guests use their lock codes; the lock's own app decides whose code works when (guest
+schedules, expiry), so the plugin needs no codes of its own.
+
+- **Which locks:** any lock in Apple Home from the same Homebridge whose plugin reports *how* it was
+  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 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
+  one from the Home app. How quickly the lock reports the unlock depends on the lock and its plugin. Unlock before you open the door: ecobee opens an incident
+  as soon as a door opens while armed, and the disarm clears it, as with the ecobee keypad.
+- **Locking** from the outside doesn't arm: most locks can't tell that from the thumb turn inside.
+- A disarm ends any [security hold](#security-holds), as a change from the Home app does.
+- Needs Homebridge's **insecure mode** (Homebridge Settings > Homebridge Insecure Mode / Accessory
+  Control; the Homebridge UI's accessory control uses it too): the plugin reads the locks over HAP on
+  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.
 
 ## Security holds
 
-A security hold lets another Homebridge plugin, such as a robot vacuum, keep the motion sensors from
-going off while it moves around the house when you're away. The plugin can only *ask*; this plugin
-decides, by four rules:
-
-1. **Hold:** if the system is armed Away (or arming Away), it's switched to Stay. If an alarm is in
-   progress, or ecobee can't be read, the hold is refused. Otherwise nothing changes.
-2. **Release:** once **every** plugin that asked is done, and the system is still in Stay, it's
-   armed Away again (with the normal exit delay).
-3. **Your change wins:** anything someone else does during a hold — disarm, arm Away, a change in
-   the Home app, an alarm — cancels it, and the system is left as it is.
-4. **No timers:** nothing changes unless a plugin asks or you act.
-
-Every decision uses ecobee's state read at that moment, not the last poll. Holds are off until you
-turn on **Allow security holds** in the settings' **Security holds** section and tick each plugin that
-may ask (`holdPlugins`): it lists installed plugins that declare they use holds, and any plugin that
-has asked. A plugin that isn't ticked is refused (it can still release a hold it already has).
-Turning holds off drops a hold left over from before (without arming Away).
-
-**Limits** that follow from these rules:
-
-- **Your own Stay looks like the hold's Stay.** If you disarm and re-arm Stay in the ecobee app or at
-  the keypad within a few seconds (between two reads), or while the bridge is restarting, the
-  release still arms Away: ecobee doesn't say who last changed the state. Changes in the Home app are
-  always seen.
-- **Your change wins even with a robot still out.** After you cancel a hold (say, disarm), arming
-  Away while the robot is still cleaning can set off the motion sensors: a plugin only asks for a
-  hold when it starts.
-- **Plugins identify themselves.** Any plugin running as the homebridge user can reach the socket,
-  and the plugin name it gives is its own claim: the list keeps honest plugins apart, it isn't a
-  lock. Two requests with the same name share one hold.
-- **A plugin that never releases leaves the system in Stay** until you change it.
-
-**API** (for plugin authors): a Unix socket at `<homebridge storage>/ecobee-security/control.sock`
-(mode 600, homebridge user only), declared in `package.json` as
-`"homebridge-security-hold": { "socket": "ecobee-security/control.sock" }` so plugins that support
-holds, like homebridge-narwal-freo, can list it. Plugins that ask for holds can declare
-`"homebridge-security-hold": { "client": true }` to show up in the list before their first request.
-The full API: [Security hold](https://github.com/seanfletchr/homebridge-narwal-freo/blob/main/docs/security-hold.md).
-
-- `POST /hold?by=<name>&plugin=<package>` → `{ "ok": true, "held": true|false, "state": "…" }`,
-  or `"ok": false` with a `"reason"`: don't start. `plugin` is optional; without it the plugin is
-  listed (and allowed) under its `by` name.
-- `POST /release?by=<name>&plugin=<package>` → `{ "released": true|false, "state": "…", "waiting": [names] }`;
-  `waiting` lists holders still out.
-- With `allowHolds` off or the plugin not ticked, both answer 403 (a release from a current holder
-  is always accepted); if ecobee can't be read (release) or isn't connected
-  yet, a 5xx with `"error"` — try again later. Holds survive restarts (in `state.json`).
+Things that move while you're out set off ecobee's motion sensors: a robot vacuum cleaning, or an AC
+blowing plants around in front of a sensor. **Security holds** let other Homebridge plugins keep the
+system from arming **Away** while their task runs. Instead the system is set to **Home** (Stay in the
+ecobee app): doors and windows stay armed, motion sensors don't.
+
+Plugins that support holds include
+[homebridge-narwal-freo](https://github.com/seanfletchr/homebridge-narwal-freo) (robot vacuum). Any
+plugin can add support; see [For plugin authors](#for-plugin-authors).
+
+### Turning it on
+
+1. In this plugin's settings, open **Security holds**, turn on **Allow security holds**, and tick the
+   plugins that may use them. (Plugins appear in the list once installed, or after they first ask.)
+2. Turn on the matching option in the other plugin's settings.
+
+### What happens
+
+Using a robot vacuum as the example:
+
+| Situation | What the security system does |
+|---|---|
+| The robot starts cleaning while the system is armed **Away** | Switches to Home, and goes back to Away when the robot is done. |
+| The robot starts while the system is set to **Home**, **Night** or **Off** | Nothing changes. |
+| You arm **Away in the Home app** while the robot is cleaning (the tile, a scene, an automation or Siri) | Stays in Home until the robot is done, then arms Away. The tile shows "Arming…" meanwhile. |
+| You want Away **now** | Turn on the **Arm Away Now** switch (see below). It arms Away right away and sends the robot home. |
+| You arm **Away in the ecobee app** while the robot is cleaning | Sends the robot home, and gives it up to 2 extra minutes on the countdown. It arms as soon as the robot is docked, but never earlier than your normal countdown. If the robot won't make it in time, it stops where it is before the sensors arm. |
+| You arm **Away at the keypad** while the robot is cleaning | Stops the robot where it is. ecobee doesn't report keypad countdowns, so this happens once Away is already armed: there's a window of up to 10 seconds in which a motion sensor could still catch the robot. |
+| You change the mode yourself while the robot is cleaning (in any app or at the keypad) | Your choice wins: when the robot is done, the system is left as you set it. |
+| An alarm is going off, or ecobee can't be reached | The robot isn't allowed to start. |
+
+Other plugins work the same way; what "stop" means is up to each one (a robot pauses or goes home,
+an AC turns off). Several at once are fine: Away comes back once all of them are done.
+
+### Settings
+
+In the **Security holds** section of the settings:
+
+- **Allow security holds** (`allowHolds`) and the list of plugins allowed to ask (`holdPlugins`).
+  Turning holds off cancels any hold in progress without re-arming Away.
+- **Arm Away Now switch** (`armAwayNowSwitch`): adds a switch to the Home app that arms Away
+  immediately, as from the ecobee app, asking any task in progress to stop (a robot goes home). Use it
+  from the Home app, a scene, or Siri ("turn on Arm Away Now").
+- **Extra time for tasks to finish** (`taskWaitSeconds`, default 120 seconds, 0 to turn it off): how
+  much longer the Away countdown may wait for a task to wrap up, e.g. a robot getting back to its
+  base. It arms as soon as the task is done.
+
+### Good to know
+
+- **Only Away is affected.** If your ecobee Stay mode also watches the motion sensors in question,
+  holds won't help there.
+- **A quick re-arm in the ecobee app can be missed.** If you disarm and re-arm Stay within a few
+  seconds in the ecobee app or at the keypad (or while Homebridge restarts), the plugin may not
+  notice, and will arm Away when the task is done. Changes in the Home app are always noticed.
+- **A plugin that can't be told to stop** keeps going when Away is armed at the keypad or in the
+  ecobee app. The log says so.
+- **A plugin that never reports it's done** leaves the system in Home until you change it.
+  (homebridge-narwal-freo also lets go if its robot hasn't moved for 10 minutes, e.g. when it's
+  stuck.)
+- **The allowed-plugins list is a courtesy, not a lock.** Any plugin running in your Homebridge can
+  reach the hold API and give any name.
+
+### For plugin authors
+
+Holds suit any plugin whose task could trip a motion sensor. Plugins ask over a Unix socket at `<homebridge storage>/ecobee-security/control.sock` (homebridge user
+only). This plugin declares it in `package.json` as
+`"homebridge-security-hold": { "socket": "ecobee-security/control.sock" }`; plugins that ask for holds
+can declare `"homebridge-security-hold": { "client": true }` to appear in the settings list. The API
+(hold, release, and being asked to stop or finish before Away arms) is documented in
+[Security hold](https://github.com/seanfletchr/homebridge-narwal-freo/blob/main/docs/security-hold.md).
 
 ## API notes
 

package/config.schema.json

@@ -3,7 +3,7 @@
   "pluginType": "platform",
   "singular": true,
   "customUi": true,
-  "headerDisplay": "Shows ecobee Smart Security as a security system in Apple Home (arm Stay / Away, disarm, alarm state). Unofficial: uses the same ecobee cloud as the app.",
+  "headerDisplay": "Adds ecobee Smart Security to Apple Home: set it to Home, Away or Off, and see alarms. Unofficial. It uses the same ecobee cloud as the ecobee app.",
   "schema": {
     "type": "object",
     "properties": {
@@ -19,18 +19,18 @@
         "x-schema-form": {
           "type": "password"
         },
-        "description": "Filled in when you sign in above. Only needed again if ecobee signs the plugin out (password change, 'sign out everywhere')."
+        "description": "Filled in when you sign in. You only need a new one if ecobee signs the plugin out, for example after a password change."
       },
       "homeId": {
         "title": "Home ID",
         "type": "string",
-        "description": "Only needed if the account has more than one home; the log lists them."
+        "description": "Only needed if your account has more than one home. The log lists your homes."
       },
       "offerNight": {
         "title": "Offer Night",
         "type": "boolean",
         "default": false,
-        "description": "Adds the Night setting for more specific automations. ecobee has no \"Night\" mode, so Night arms Stay. Changing this recreates the security system in the Home app; scenes and automations using it must be set up again."
+        "description": "Adds a Night mode to use in automations. ecobee has no Night mode, so Night arms ecobee's Stay. Changing this recreates the security system in the Home app, so you need to set up its scenes and automations again."
       },
       "alarmTrigger": {
         "title": "Enter Triggered State",
@@ -44,25 +44,25 @@
             ]
           },
           {
-            "title": "After the Entry/Disarm delay",
+            "title": "After the entry 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."
+        "description": "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."
       },
       "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."
+        "description": "Adds a Smoke Alarm accessory that detects smoke when ecobee reports a smoke alarm. Use it for Home app notifications and automations."
       },
       "allowHolds": {
         "title": "Allow security holds",
         "type": "boolean",
         "default": false,
-        "description": "Lets other Homebridge plugins (for example a robot vacuum, so it can clean while you're away) switch Away to Stay for a while and back to Away when they're done. Each plugin also has to be allowed in holdPlugins (the settings page lists the ones that asked). See \"Security holds\" in the README."
+        "description": "Lets other Homebridge plugins, like a robot vacuum, keep the system from arming Away while they work: if it's armed Away it's switched to Home (ecobee's Stay), and Away comes back when they're done. Away asked for in the Home app meanwhile waits until they're done. Each plugin also has to be allowed in holdPlugins (the settings page lists the ones that asked). See \"Security holds\" in the README."
       },
       "holdPlugins": {
         "title": "Plugins allowed to ask for holds",
@@ -70,20 +70,48 @@
         "items": {
           "type": "string"
         },
-        "description": "Package names (or, for a plugin that doesn't say, the name it asks with). Without this list, every plugin may ask once Allow security holds is on."
+        "description": "Package names of the plugins that may ask, or the name a plugin asks with if it gives no package. With no list, all plugins may ask while Allow security holds is on."
+      },
+      "armAwayNowSwitch": {
+        "title": "Arm Away Now switch",
+        "type": "boolean",
+        "default": false,
+        "description": "Adds an Arm Away Now switch to the Home app (with Allow security holds on). Turning it on arms Away now, with the normal exit delay, and asks any task that's running to stop (a robot goes back to its base, or stops where it is if it can't make it in time). Away from the security tile, scenes, automations and Siri waits until robots are done instead."
+      },
+      "taskWaitSeconds": {
+        "title": "Extra time for tasks to finish (seconds)",
+        "type": "integer",
+        "default": 120,
+        "minimum": 0,
+        "maximum": 300,
+        "description": "If Away is armed while a task is running, like a robot heading back to its base, the countdown waits up to this much longer, and arms as soon as it's done. 0: no waiting."
+      },
+      "keypadDisarm": {
+        "title": "Disarm when a door is unlocked with its keypad",
+        "type": "boolean",
+        "default": false,
+        "description": "Entering a code on a smart lock's keypad turns the security system off, so family and guests can use their lock codes. Works with locks in Apple Home from this Homebridge that report keypad unlocks. Needs Homebridge's insecure mode. See \"Keypad unlock\" in the README."
+      },
+      "keypadLocks": {
+        "title": "Locks that disarm",
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "Serial numbers of the locks that disarm (the settings page lists the ones found). With no list, every lock does."
       },
       "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."
+        "description": "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."
       },
       "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).",
+        "description": "At or above this level, the CO2 sensor reports abnormal CO2. Use it for notifications and automations, like turning on ventilation.",
         "condition": {
           "functionBody": "return model.airQuality !== false;"
         }

package/homebridge-ui/public/index.html

@@ -8,7 +8,7 @@
 
   <div id="signed-in" hidden>
     <div class="alert alert-success mb-2" role="status" id="signed-in-text">Signed in to ecobee.</div>
-    <p class="hint mb-2" id="signed-in-hint">You only need to sign in again if the log says ecobee signed the plugin out (for example after a password change).</p>
+    <p class="hint mb-2" id="signed-in-hint">Sign in again only if the log says ecobee signed the plugin out, for example after a password change.</p>
     <button type="button" class="btn btn-secondary" id="sign-in-again">Sign in again</button>
   </div>
 
@@ -22,7 +22,7 @@
     <div class="mb-2">
       <label for="password" class="form-label">Password</label>
       <input type="password" class="form-control" id="password" autocomplete="current-password" required>
-      <div class="hint mt-1">Sent only to ecobee to sign in. The plugin keeps a sign-in token, never your password.</div>
+      <div class="hint mt-1">Sent only to ecobee. The plugin saves a sign-in token, not your password.</div>
     </div>
     <button type="submit" class="btn btn-primary">Sign in</button>
     <button type="button" class="btn btn-link" id="sign-in-cancel" hidden>Cancel</button>
@@ -41,12 +41,12 @@
 
   <details class="mt-3" id="browser">
     <summary>Sign in on ecobee's website instead</summary>
-    <p class="hint mt-2 mb-2">Use this if signing in above keeps failing (for example if ecobee asks for a CAPTCHA). You'll need a desktop browser with developer tools.</p>
+    <p class="hint mt-2 mb-2">Use this if signing in above keeps failing, for example if ecobee asks for a CAPTCHA. You need a desktop browser with developer tools.</p>
     <ol class="small ps-3">
       <li>In Chrome, open a new tab, open DevTools (Option-Command-I or F12), go to <b>Network</b> and tick <b>Preserve log</b>.</li>
       <li>In that tab, open <a id="browser-link" href="#" target="_blank" rel="noopener">this sign-in link</a> and sign in.</li>
       <li>When the page goes blank, type <code>code=</code> in the Network filter, right-click the entry and choose <b>Copy &gt; Copy URL</b>. It starts with <code>com.ecobee.athenamobile://</code></li>
-      <li>Paste it here straight away (the code expires within a minute):</li>
+      <li>Paste it here within a minute, before it expires:</li>
     </ol>
     <form id="browser-form" class="d-flex gap-2">
       <input type="text" class="form-control" id="callback" placeholder="com.ecobee.athenamobile://…" required>
@@ -67,20 +67,20 @@
   <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 the account has more than one home; the log lists them.</div>
+    <div class="hint mt-1">Only needed if your account has more than one home. The log lists your homes.</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>
     </div>
-    <div class="hint">Adds the Night setting for more specific automations. ecobee has no "Night" mode, so Night arms Stay.</div>
-    <div class="hint mt-1">Changing this recreates the security system in the Home app; scenes and automations using it must be set up again.</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/Disarm delay</option></select>
-    <div class="hint mt-1">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.</div>
+    <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>
 
@@ -91,19 +91,34 @@
       <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 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.</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">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.</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">The Carbon Dioxide Sensor reports abnormal CO2 at or above this level, for Home app notifications and automations (for example, turning on ventilation).</div>
+    <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 class="card card-body mb-3" id="keypad-card" hidden>
+  <h5 class="mb-2">Door keypads</h5>
+  <div class="form-check form-switch mb-1">
+    <input class="form-check-input" type="checkbox" role="switch" id="keypad-disarm">
+    <label class="form-check-label" for="keypad-disarm">Disarm when a door is unlocked with its keypad</label>
+  </div>
+  <p class="hint mb-2">Entering a code on a smart lock's keypad turns the security system off, so family and guests
+    can use their lock codes. Restart the bridge after changing this.
+    <a href="https://github.com/seanfletchr/homebridge-ecobee-security#keypad-unlock" target="_blank" rel="noopener">Learn more…</a></p>
+  <div id="keypad-locks-box" hidden>
+    <div class="mb-1">Locks that disarm</div>
+    <div id="keypad-locks"></div>
   </div>
 </div>
 
@@ -113,12 +128,23 @@
     <input class="form-check-input" type="checkbox" role="switch" id="allow-holds">
     <label class="form-check-label" for="allow-holds">Allow security holds</label>
   </div>
-  <p class="hint mb-2">Lets supported plugins, like a robot vacuum, switch Away to Home while they work and back to
-    Away when they're done.
+  <p class="hint mb-2">Lets supported plugins, like a robot vacuum, keep the system from arming Away while they work:
+    Away is switched to Home, and comes back when they're done. Away asked for in the Home app meanwhile
+    waits until they're done.
     <a href="https://github.com/seanfletchr/homebridge-ecobee-security#security-holds" target="_blank" rel="noopener">Learn more…</a></p>
   <div id="hold-plugins-box" hidden>
     <div class="mb-1">Allowed plugins</div>
     <div id="hold-plugins"></div>
+    <div class="form-check form-switch mt-3 mb-1">
+      <input class="form-check-input" type="checkbox" role="switch" id="arm-away-now">
+      <label class="form-check-label" for="arm-away-now">Arm Away Now switch</label>
+    </div>
+    <div class="hint">Adds a switch to the Home app that arms Away now and asks any task that's running to stop (a robot goes back to its base). Restart the
+      bridge after changing this.</div>
+    <label for="s-taskWaitSeconds" class="form-label mt-3 mb-1">Extra time for tasks to finish (seconds)</label>
+    <input class="form-control" type="number" step="10" min="0" max="300" id="s-taskWaitSeconds" data-key="taskWaitSeconds" data-type="int" data-default="120">
+    <div class="hint mt-1">If Away is armed while a task is running, like a robot heading back to its base, the countdown
+      waits up to this much longer, and arms as soon as it's done. 0: no waiting.</div>
   </div>
 </div>
 
@@ -141,7 +167,7 @@
     $('signed-in').hidden = !signedIn;
     $('signin').hidden = signedIn;
     $('signed-in-text').textContent = justSignedIn
-      ? 'Signed in and saved. Restart the bridge this plugin runs on (or Homebridge) to use the new sign-in.'
+      ? 'Signed in and saved. Restart this plugin\'s bridge, or Homebridge, to use the new sign-in.'
       : 'Signed in to ecobee.';
     $('sign-in-cancel').hidden = !block?.refreshToken;
     $('signin-hint').textContent = block?.refreshToken
@@ -177,6 +203,7 @@
     homebridge.toast.success('Signed in to ecobee.');
     await showStatus({ justSignedIn: true });
     await showSettings();
+    await showKeypad();
     await showHolds();
   }
 
@@ -302,6 +329,7 @@
     $('holds-card').hidden = !block.refreshToken;
     $('allow-holds').checked = block.allowHolds === true;
     $('hold-plugins-box').hidden = block.allowHolds !== true;
+    $('arm-away-now').checked = block.armAwayNowSwitch === true;
     const plugins = await homebridge.request('/hold-plugins').catch(() => []);
     const box = $('hold-plugins');
     box.textContent = '';
@@ -350,8 +378,70 @@
     await homebridge.updatePluginConfig([block, ...blocks.slice(1)]);
   });
 
+  $('arm-away-now').addEventListener('change', async () => {
+    const blocks = await homebridge.getPluginConfig();
+    const block = blocks[0];
+    block.armAwayNowSwitch = $('arm-away-now').checked;
+    await homebridge.updatePluginConfig([block, ...blocks.slice(1)]);
+  });
+
+  // ── Door keypads ──
+
+  async function showKeypad() {
+    const [block = {}] = await homebridge.getPluginConfig();
+    $('keypad-card').hidden = !block.refreshToken;
+    $('keypad-disarm').checked = block.keypadDisarm === true;
+    $('keypad-locks-box').hidden = block.keypadDisarm !== true;
+    const locks = await homebridge.request('/keypad-locks').catch(() => []);
+    const box = $('keypad-locks');
+    box.textContent = '';
+    if (!locks.length) {
+      const p = document.createElement('p');
+      p.className = 'hint mb-0';
+      p.textContent = block.keypadDisarm === true
+        ? 'No lock found yet. Locks show up here a minute after the bridge restarts; the log says if none report keypad unlocks.'
+        : 'Turn this on and restart the bridge to find your locks.';
+      box.append(p);
+      return;
+    }
+    // Without a list, every lock disarms.
+    const allowed = Array.isArray(block.keypadLocks) ? block.keypadLocks : locks.map(l => l.key);
+    for (const lock of locks) {
+      const id = `lock-${lock.key.replace(/[^a-z0-9]/gi, '-')}`;
+      const input = Object.assign(document.createElement('input'), {
+        className: 'form-check-input', type: 'checkbox', id, checked: allowed.includes(lock.key),
+      });
+      input.addEventListener('change', () => setLock(locks, lock.key, input.checked));
+      const label = Object.assign(document.createElement('label'), { className: 'form-check-label', htmlFor: id });
+      label.textContent = lock.name;
+      const hint = Object.assign(document.createElement('div'), { className: 'hint' });
+      hint.textContent = lock.bridge;
+      const row = Object.assign(document.createElement('div'), { className: 'form-check mb-1' });
+      row.append(input, label, hint);
+      box.append(row);
+    }
+  }
+
+  async function setLock(locks, key, on) {
+    const blocks = await homebridge.getPluginConfig();
+    const block = blocks[0];
+    const current = Array.isArray(block.keypadLocks) ? block.keypadLocks : locks.map(l => l.key);
+    block.keypadLocks = on ? [...new Set([...current, key])] : current.filter(k => k !== key);
+    await homebridge.updatePluginConfig([block, ...blocks.slice(1)]);
+  }
+
+  $('keypad-disarm').addEventListener('change', async () => {
+    const blocks = await homebridge.getPluginConfig();
+    const block = blocks[0];
+    block.keypadDisarm = $('keypad-disarm').checked;
+    $('keypad-locks-box').hidden = !block.keypadDisarm;
+    await homebridge.updatePluginConfig([block, ...blocks.slice(1)]);
+    await showKeypad();
+  });
+
   await showStatus();
   await showSettings();
+  await showKeypad();
   await showHolds();
 })();
 </script>