homebridge-ecobee-security 0.9.1 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 1.0.1
+
+- **Comfort Setting** is now one TV-style tile with an input per comfort setting, instead of a switch per
+  setting. Picking an input holds that setting, switching the tile off goes back to your schedule, and the
+  tile shows the scheduled setting while off. It is its own HomeKit accessory, added to the Home app with
+  the bridge's setup code, with a streaming-device icon; settings can be hidden in the Home app's input list
+  (remembered) and follow ecobee's order. Breaking: the old switches are removed, so automations built on them need
+  rebuilding with the tile (Home app scenes can set the input).
+- README: new Automation ideas section, and updated header and devices images.
+
+## 1.0.0
+
+- New setting **Quick Responses** (`quickResponses`, `quickResponseMessages`) in the Doorbell camera card:
+  short messages the doorbell plays on its speaker. They appear as one "Quick Responses" tile in the Home app
+  with a switch per message (open the tile to pick one; tapping the tile itself plays nothing), which you can
+  add to the live view's Nearby Accessories or use from Siri and automations. New setting
+  `quickResponseVolume` (default 40%) sets how loud they play. Three come built in (Leave
+  Delivery, Hang On, Not Home), each with a Preview button in the settings; remove the ones you don't want
+  (and add them back). With Piper installed you can also reword them and add your own.
+  The doorbell needs to accept audio from the plugin, as for two-way talk, but two-way talk doesn't have to be
+  on. If the doorbell connection is down, a message waits up to 20 seconds for it to come back; it doesn't
+  play while another message is playing or someone is talking in a live view, and the log says why.
+- The built-in messages come as recordings made with Piper's ryan voice (RyanSpeech, CC BY-NC-SA 4.0; see
+  `assets/quick-responses/LICENSE`). Changed or new wording needs [Piper](https://github.com/OHF-Voice/piper1-gpl)
+  on the Homebridge machine (`piperPath`, `piperVoice`; see "Custom wording with Piper" in the README).
+- Two-way talk is no longer a beta.
+- New **Doorbell Pressed** occupancy sensor on the video doorbell (with the doorbell link): Detected for 10
+  seconds after each press of any kind, for automations. It shows No Response while the link is down.
+
 ## 0.9.1
 
 - New setting **Add Comfort Setting switches** (`comfortSetting`, `comfortHoldType`): a Comfort Setting

package/README.md

@@ -38,6 +38,7 @@ GraphQL at `federated-api.prod.federated-graph.generacapis.com`), which ecobee c
 - **Vacation Mode** switch that follows, and starts, an ecobee vacation.
 - **Security holds** let other plugins, like a robot vacuum, keep the system from arming Away while they work.
 - **Doorbell camera** with HomeKit Secure Video, live view and snapshots; with the **doorbell link**, instant ring and motion, the sensors the doorbell bridges to HomeKit, and its Chime, Status Light and Night Vision switches.
+- **Quick Responses**: short messages the doorbell plays on its speaker ("Leave Delivery", "Hang On", "Not Home"), one Quick Responses tile in the Home app, plus a **Doorbell Pressed** sensor for automations.
 
 ## Contents
 
@@ -49,9 +50,11 @@ GraphQL at `federated-api.prod.federated-graph.generacapis.com`), which ecobee c
 - [Keypad unlock](#keypad-unlock)
 - [Security holds](#security-holds)
 - [Doorbell camera](#doorbell-camera)
+- [Quick Responses](#quick-responses)
 - [Home Occupied switch](#home-occupied-switch)
 - [Vacation Mode switch](#vacation-mode-switch)
 - [Smoke alarm and air quality](#smoke-alarm-and-air-quality)
+- [Automation ideas](#automation-ideas)
 - [Troubleshooting](#troubleshooting)
 - [API notes](#api-notes)
 - [License](#license)
@@ -150,8 +153,12 @@ Sign-in: see [Sign-in](#sign-in).
 | `doorbellCamera` | `false` | Adds the doorbell camera (beta). Restart the bridge after changing it. |
 | `motionGrace` | `15` | Seconds the motion sensor stays on after the doorbell's motion ends (6 to 120). |
 | `ffmpegPath` | `/usr/local/bin/ffmpeg` if it exists, else `ffmpeg` | The ffmpeg to use. |
-| `twoWayAudio` | `false` | Talk through the doorbell from the Home app's live view (beta; see [Two-way talk](#two-way-talk-beta)). |
+| `twoWayAudio` | `false` | Talk through the doorbell from the Home app's live view (see [Two-way talk](#two-way-talk)). |
 | `twoWayAudioTest` | `false` | With `twoWayAudio`: plays a 3-second tone on the doorbell when a live view starts (config file only). |
+| `quickResponses` | `false` | Adds a switch per message that plays it on the doorbell (see [Quick Responses](#quick-responses)). Restart the bridge after changing it. |
+| `quickResponseVolume` | `40` | How loud messages play at the door, in percent (5 to 100). Doesn't change two-way talk. |
+| `quickResponseMessages` | the three built-ins | The messages: a list of `{ "id", "name", "phrase" }`; a built-in with `"enabled": false` is removed but keeps its wording. `id` never changes (it is the switch's identity in the Home app), `name` is the tile name (14 characters at most), `phrase` is what is said. |
+| `piperPath`, `piperVoice` | none | Piper and its voice, only for changed or new wording (see [Custom wording with Piper](#custom-wording-with-piper)). |
 | `debugRecordings` | `false` | Keeps the last five recordings for troubleshooting (config file only; see [Troubleshooting](#troubleshooting)). |
 
 ### Switches and sensors settings
@@ -165,7 +172,7 @@ Sign-in: see [Sign-in](#sign-in).
 | `vacationSwitch` | `false` | Adds a **Vacation Mode** switch that is on while an ecobee vacation is running (see [Vacation Mode switch](#vacation-mode-switch)). |
 | `vacationWhenEmpty` | `false` | Starts a vacation when Home Occupied has been off for `vacationEmptyHours` (default 24; see [Vacations that follow Home Occupied](#vacations-that-follow-home-occupied)). |
 | `vacationEndOnArrival` | `false` | Ends running vacations when Home Occupied turns on. |
-| `comfortSetting` | `false` | Adds a **Comfort Setting** accessory with a switch per ecobee comfort setting (see [Comfort Setting](#comfort-setting)). |
+| `comfortSetting` | `false` | Adds a **Comfort Setting** accessory, a TV-style tile with an input per ecobee comfort setting (see [Comfort Setting](#comfort-setting)). |
 | `comfortHoldType` | `"nextTransition"` | How long a comfort setting turned on is held: `"nextTransition"` or `"indefinite"`. |
 | `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 "<thermostat> 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. |
@@ -348,7 +355,8 @@ the Home app. You get:
   occupancy and battery state;
 - the doorbell's own switches: **Chime Doorbell**, **Camera Status Light** and **Night Vision Light**.
   Changes in the Home app are sent to the doorbell, and changes made at the doorbell show up in the Home
-  app. While the link is down, setting one fails.
+  app. While the link is down, setting one fails;
+- a **Doorbell Pressed** sensor (see below).
 
 The pairing is kept in `ecobee-security/doorbell-pairing.json` in the Homebridge folder. **Unlink** in the
 settings removes it from the doorbell as well (restart the bridge afterwards). If the link drops, the
@@ -356,6 +364,13 @@ plugin looks for the doorbell again and reconnects by itself; the ring, motion,
 sensors show **No Response** while it has been down for a minute. The video still comes from the
 cloud session (the doorbell's own stream isn't used).
 
+### Doorbell Pressed sensor
+
+With the doorbell link, the video doorbell also has an occupancy sensor named **Doorbell Pressed**. Each press
+(single, double or long) sets it to Detected for 10 seconds; another press starts the 10 seconds again.
+The Home app can't start an automation from a video doorbell's ring, but it can from a sensor. It shows No
+Response while the doorbell link is down.
+
 ### HomeKit Secure Video
 
 The camera records for HomeKit Secure Video (a home hub and an iCloud+ plan are needed, as for any
@@ -378,11 +393,10 @@ person, animal and package detection, are then made by HomeKit.
 
 To inspect recordings, see [Troubleshooting](#troubleshooting).
 
-### Two-way talk (beta)
+### Two-way talk
 
 Turn on **Two-way talk** (`twoWayAudio`) and restart the bridge to talk through the doorbell from the Home app's
-live view (the microphone button). It is a beta: whether the doorbell accepts audio from the plugin isn't known for
-every firmware, and talking adds a little delay. The log says at start-up what the doorbell answered ("two-way
+live view (the microphone button). Whether the doorbell accepts audio from the plugin can depend on its firmware, and talking adds a little delay. The log says at start-up what the doorbell answered ("two-way
 talk: the camera answered audio sendrecv" is good; anything else means it can't take audio and the plugin carries
 on receive-only, as before). The live view's picture and sound are not affected.
 
@@ -390,6 +404,52 @@ To check that audio reaches the doorbell, set `"twoWayAudioTest": true` in the c
 switch), open the live view while standing at the door, and listen for a 3-second tone; the log says "test tone
 sent". Turn it off afterwards.
 
+## Quick Responses
+
+Quick Responses are short messages the doorbell plays on its speaker, for the person at your door: "You can just leave it", "We'll be right there". Turn on **Quick Responses** (`quickResponses`, in the **Doorbell camera** card, which needs the doorbell camera) and restart the bridge. It needs the doorbell to accept audio from the plugin, the same as [Two-way talk](#two-way-talk) (the log says what it answered), but **Two-way talk** itself doesn't have to be on.
+
+There are three built-in messages:
+
+| Tile | Says |
+|---|---|
+| Leave Delivery | "Hi there. You can just leave it. Thanks!" |
+| Hang On | "Just a sec, we'll be right there." |
+| Not Home | "Hi there, no one can answer the door right now, but we'll be notified that you stopped by." |
+
+The messages appear in the Home app as **one tile, "Quick Responses"**, which holds a switch per message. Tapping the tile itself turns all of them on at once, which the plugin recognises and ignores (it plays nothing and the switches turn back off; the log says so). **Open the tile** (long-press, or tap its settings) and pick one message instead. If you prefer a tile per message, turn on **Show as Separate Tiles** in the accessory's settings in the Home app. In the doorbell's live view, the group appears as one tile in **Nearby Accessories**: add it there and tap the message you want. Turning a message's switch on plays it and it turns itself off when the message ends. Siri works too ("Hey Siri, turn on Not Home"), and so do automations and scenes. Messages play at the volume you set (`quickResponseVolume`, 40% by default).
+
+In the settings, each message is a row: the **title** (the tile name, 14 characters at most), **what is said**, and **Preview**, which plays it in your browser. Without Piper, the three built-in messages are fixed: the rows show their title and wording as text, and you can preview them. Once [Piper](#custom-wording-with-piper) is installed, each built-in row has **Replace** (edit its title and wording; **Restore** goes back to the shipped wording and audio) and **Add a message** adds your own, with a remove button. The built-in messages can be removed (×) and added back from the line under the rows, with or without Piper; a removed message's switch leaves the Home app after a bridge restart, and returns with the same identity when added back. Changing a title or the wording takes effect after a bridge restart.
+
+An example automation: when someone rings and nobody is home, tell them so.
+
+1. **Trigger:** An Accessory is Controlled > **Doorbell Pressed** detects occupancy ([Doorbell Pressed sensor](#doorbell-pressed-sensor)).
+2. **Condition:** only if **Home Occupied** is off ([Home Occupied switch](#home-occupied-switch)).
+3. **Action:** turn on **Not Home**.
+
+How it works: the message is played into the plugin's session with the doorbell, so it can't play while the session is down, while the camera hasn't accepted audio from us, while another message is playing, or while someone is talking in a live view (the microphone has priority; a message that is playing stops when someone starts talking). The switch then turns itself back off after a second, and the log says why. One message plays at a time. The log line "Quick Response "<name>" played" shows how many audio packets were sent. Each switch's identity comes from the message's `id`, not its title or wording, so you can rename a message without breaking the automations that use it. Messages you remove from the settings disappear from the Home app after a restart.
+
+### Custom wording with Piper
+
+The three built-in messages come as recordings with the plugin. Anything else, meaning reworded built-ins and your own messages, is turned into speech on your Homebridge machine with [Piper](https://github.com/OHF-Voice/piper1-gpl), a local text-to-speech program that doesn't send your text anywhere. That is optional: without Piper the built-ins work as they are, and a message that needs it is left out, with a warning in the log.
+
+1. Install Piper into a folder the Homebridge user can read, for example a Python virtual environment:
+
+   ```sh
+   sudo -u homebridge python3 -m venv /var/lib/homebridge/piper
+   sudo -u homebridge /var/lib/homebridge/piper/bin/pip install piper-tts
+   ```
+
+2. Download a voice: an `.onnx` file and its `.onnx.json` file, side by side, from [rhasspy/piper-voices on Hugging Face](https://huggingface.co/rhasspy/piper-voices). The built-in messages use the English (US) **ryan**, **high** quality voice, which is a good place to start.
+3. In the settings, under **Piper settings** in the Quick Responses box, fill in **Piper path** (the `piper` program, for example `/var/lib/homebridge/piper/bin/piper`) and **Piper voice** (the `.onnx` file). The page says whether Piper was found. **Preview** then plays your wording.
+
+The plugin makes the audio for your messages when the bridge starts (one at a time, in the background) and keeps it in `ecobee-security/quick-responses` in the Homebridge folder, and removes it when no message uses it any more. A message shows up in the Home app once its audio is ready. All messages are spoken with the same speed and voice settings as the built-ins.
+
+Tips: a bare "Hi!" can come out as "Aye". Writing "Hi there" usually helps, or give Piper the exact sounds: text between `[[` and `]]` is read as phonemes, for example `[[ hˈaɪ ðɛɹ ]]`. Phonemes are passed through unchanged.
+
+### Voice licensing
+
+The recordings of the built-in messages (in `assets/quick-responses`) were made with Piper's **ryan** voice, whose training data (RyanSpeech) is licensed **CC BY-NC-SA 4.0**. The recordings are therefore licensed under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) too: free for non-commercial use, with attribution: "RyanSpeech (CC BY-NC-SA 4.0), synthesized with Piper". The rest of the plugin stays MIT licensed. A voice you use for your own wording has its own license; check it before sharing recordings made with it.
+
 ## Home Occupied switch
 
 Apple Home asks you to confirm (a notification you have to tap) whenever a people-arrive or
@@ -500,30 +560,48 @@ they forget, the Home app's security notification shows the disarm, and you can
 
 ## Comfort Setting
 
-Turn on **Add Comfort Setting switches** (`comfortSetting`) and the plugin adds one accessory,
-**Comfort Setting**, with a switch for each of your ecobee comfort settings (Home, Away, Sleep and your own,
-read from the thermostats' program; with several thermostats, a setting any of them has). It is for
-automations such as "Home Occupied off → Away on".
-
-- Turning a switch **on** holds that comfort setting on the thermostats that have it, and the others
-  turn off. How long: `comfortHoldType`, `"nextTransition"` (default, until the next scheduled change)
-  or `"indefinite"` (until you change it).
-- Turning the active switch **off** goes back to your schedule, so all off means following the schedule.
-- A hold set in the ecobee app or on the thermostat lights the matching switch (read every minute). A
-  temperature-only hold lights none.
-- During an ecobee vacation all switches are off and changes are refused (the log says so).
-- Like the other sensors, the switches show No Response while ecobee can't be reached. Restart the
-  bridge after changing the setting.
-
-> [!NOTE]
-> The Home app shows the switches as one tile, and tapping the tile toggles all of them. Open the tile
-> and pick one, or use **Show as Separate Tiles** in the accessory's settings.
+Turn on **Add Comfort Setting** (`comfortSetting`) and the plugin adds one accessory, **Comfort Setting**: a
+single tile in the Home app (a HomeKit television) with an input for each of your ecobee comfort settings
+(Home, Away, Sleep and your own, read from the thermostats' program; with several thermostats, a setting
+any of them has).
+
+- Picking a setting **holds** it on the thermostats that have it. How long: `comfortHoldType`,
+  `"nextTransition"` (default, until the next scheduled change) or `"indefinite"` (until you change it).
+- Switching the tile **off** goes back to your schedule. The tile is on while a comfort hold runs; while
+  the thermostats follow their schedule it is off and shows the setting the schedule is on now.
+  Switching it on holds the setting it shows.
+- A hold set in the ecobee app or on the thermostat shows on the tile (read every minute). A
+  temperature-only hold counts as following the schedule.
+- During an ecobee vacation the tile is off and changes are refused (the log says so).
+- Like the other sensors, the tile shows No Response while ecobee can't be reached.
+- HomeKit allows one television per bridge, so the tile is its own accessory: add it to the Home app
+  with the bridge's setup code (the log says so when it is published, once ecobee has been read).
+  Restart the bridge after changing the setting.
+- Home app scenes and automations can pick a comfort setting: add the tile and choose the setting
+  as its input.
+- The Home app can't start an automation when the comfort setting changes (TV tiles aren't offered as
+  triggers).
+- The tile appears with a streaming-device icon. In the Home app's
+  input list you can hide settings you don't use (remembered); the order follows the ecobee app.
+- It replaces the one-switch-per-setting accessory of earlier versions, which is removed from the Home
+  app at the next restart; automations built on those switches have to be rebuilt with the tile.
 
 ## Smoke alarm and air quality
 
 - **Smoke Alarm** (`smokeSensor`, on by default) is its own accessory, a Smoke Sensor that detects smoke while ecobee has a smoke-alarm incident open. It is separate from the security tile (the Home app would otherwise merge it into the tile with a cloud icon).
 - **Air quality** (`airQuality`, on by default) adds, for each thermostat with an air quality sensor (ecobee Premium), an Air Quality Sensor and a Carbon Dioxide Sensor, read every 5 minutes; `co2Alert` sets the CO2 level (ppm) that reports abnormal levels. Details are in the settings table above. Temperature and humidity come from ecobee's own HomeKit integration.
 
+## Automation ideas
+
+A few Home app automations built on this plugin's accessories:
+
+| When | Do |
+|---|---|
+| **Vacation Mode** turns on | Close the blinds |
+| **Doorbell** rings | Pause the Apple TV |
+| 6:00 AM every day, if someone is home | Set the **security system** to Off |
+| **Doorbell** detects motion, after sunset | Turn on the porch and entryway lights |
+
 ## Troubleshooting
 
 - **No Response** in the Home app: the security tile, Smoke Alarm and air quality sensors show it

package/assets/quick-responses/LICENSE

@@ -0,0 +1,19 @@
+The audio files in this folder (leave-delivery.wav, hang-on.wav, not-home.wav) are licensed under the
+Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International license (CC BY-NC-SA 4.0).
+
+  https://creativecommons.org/licenses/by-nc-sa/4.0/
+  Legal code: https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode
+
+You may copy and redistribute the recordings and adapt them, for non-commercial purposes only, if you give
+appropriate credit, indicate changes, and share your adaptations under the same license.
+
+Attribution:
+
+  RyanSpeech (CC BY-NC-SA 4.0), synthesized with Piper
+
+The recordings were synthesized with the Piper text-to-speech program (https://github.com/OHF-Voice/piper1-gpl)
+and its "ryan" voice (en_US-ryan-high), which was trained on the RyanSpeech dataset,
+licensed CC BY-NC-SA 4.0.
+
+The rest of this package is licensed under the MIT license (see the LICENSE file in the package root); this
+license applies only to the files in this folder.

package/config.schema.json

@@ -188,10 +188,10 @@
         }
       },
       "comfortSetting": {
-        "title": "Add Comfort Setting switches",
+        "title": "Add Comfort Setting",
         "type": "boolean",
         "default": false,
-        "description": "One switch per ecobee comfort setting (Home, Away, Sleep and your own). Turning one on holds it; turning it off goes back to your schedule. Restart the bridge after changing this."
+        "description": "One tile in the Home app with a picker for your ecobee comfort settings (Home, Away, Sleep and your own). Picking one holds it; switching the tile off goes back to your schedule. It is added to the Home app on its own with the bridge's setup code. Restart the bridge after changing this."
       },
       "comfortHoldType": {
         "title": "Comfort setting hold",
@@ -251,6 +251,79 @@
           "functionBody": "return model.doorbellCamera === true && model.twoWayAudio === true;"
         }
       },
+      "quickResponses": {
+        "title": "Quick Responses",
+        "type": "boolean",
+        "default": false,
+        "description": "Short messages the doorbell can play. They appear as one Quick Responses tile in the Home app, with a switch per message, which you can add to the live view's Nearby Accessories. Restart the bridge after changing this. See \"Quick Responses\" in the README.",
+        "condition": {
+          "functionBody": "return model.doorbellCamera === true;"
+        }
+      },
+      "quickResponseVolume": {
+        "title": "Quick Response volume (%)",
+        "type": "integer",
+        "default": 40,
+        "minimum": 5,
+        "maximum": 100,
+        "description": "How loud messages play at the door.",
+        "condition": {
+          "functionBody": "return model.doorbellCamera === true && model.quickResponses === true;"
+        }
+      },
+      "quickResponseMessages": {
+        "title": "Quick Response messages",
+        "type": "array",
+        "description": "The messages, each with an id that stays the same (it keeps the switch's identity in the Home app), a name of up to 14 characters, and what is said. With no list, the three built-in messages (Leave Delivery, Hang On, Not Home).",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "title": "Id",
+              "type": "string"
+            },
+            "name": {
+              "title": "Name",
+              "type": "string",
+              "maxLength": 14
+            },
+            "phrase": {
+              "title": "What is said",
+              "type": "string"
+            },
+            "enabled": {
+              "title": "Enabled",
+              "type": "boolean",
+              "default": true,
+              "description": "Only for the built-in messages: false removes the switch from the Home app and keeps the wording."
+            }
+          },
+          "required": [
+            "id",
+            "name",
+            "phrase"
+          ]
+        },
+        "condition": {
+          "functionBody": "return model.doorbellCamera === true && model.quickResponses === true;"
+        }
+      },
+      "piperPath": {
+        "title": "Piper path",
+        "type": "string",
+        "description": "Only for changed or new wording: the piper program you installed (see \"Custom wording with Piper\" in the README).",
+        "condition": {
+          "functionBody": "return model.doorbellCamera === true && model.quickResponses === true;"
+        }
+      },
+      "piperVoice": {
+        "title": "Piper voice",
+        "type": "string",
+        "description": "Path to the voice (.onnx) Piper speaks with.",
+        "condition": {
+          "functionBody": "return model.doorbellCamera === true && model.quickResponses === true;"
+        }
+      },
       "ffmpegPath": {
         "title": "ffmpeg path",
         "type": "string",