From 59210aafe69db479020d3d4aad41d888aed3ce64 Mon Sep 17 00:00:00 2001 From: HJD Date: Sat, 19 Aug 2023 13:28:49 -0500 Subject: [PATCH] v3.0.0. --- README.md | 30 +- config.schema.json | 20 +- docs/AdvancedOptions.md | 4 +- docs/Changelog.md | 7 + docs/FeatureOptions.md | 80 +- homebridge-ui/public/index.html | 271 ++--- homebridge-ui/public/lib/featureoptions.mjs | 200 ++++ homebridge-ui/public/myq-featureoptions.mjs | 665 +++++++++++ homebridge-ui/public/ui.mjs | 144 +++ homebridge-ui/server.js | 97 +- package-lock.json | 1195 ++++++++++++------- package.json | 33 +- src/myq-accessory.ts | 110 -- src/myq-config.ts | 25 - src/myq-device.ts | 139 +++ src/myq-garagedoor.ts | 434 +++---- src/myq-lamp.ts | 86 +- src/myq-mqtt.ts | 41 +- src/myq-options.ts | 202 ++++ src/myq-platform.ts | 183 +-- tsconfig.json | 4 +- 21 files changed, 2716 insertions(+), 1254 deletions(-) create mode 100644 homebridge-ui/public/lib/featureoptions.mjs create mode 100644 homebridge-ui/public/myq-featureoptions.mjs create mode 100644 homebridge-ui/public/ui.mjs delete mode 100644 src/myq-accessory.ts delete mode 100644 src/myq-config.ts create mode 100644 src/myq-device.ts create mode 100644 src/myq-options.ts diff --git a/README.md b/README.md index d6b26bc..7d40f74 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ In a nutshell, the aim of this plugin for things to *just work* with minimal req What does *just work* mean in practice? It means that this plugin will discover all your myQ devices and poll at regular, reasonable intervals for changes in state of a garage door opener, lamp, or other myQ devices and inform HomeKit of those changes. By default. Without additional configuration beyond the login information required for myQ services. -`homebridge-myq` has been around a long time and is trusted by thousands of users. It's the first myQ [Homebridge](https://homebridge.io) plugin to provide comprehensive support for various myQ features such as obstruction detection, and the first to provide support for multiple myQ device types (currently, garage door openers and lamps). As more of the API can be decoded, my aim is to support as many device types as possible. I rely on this plugin every day and actively maintain and support it. +`homebridge-myq` has been around a long time and is trusted by thousands of users. It's the first myQ [Homebridge](https://homebridge.io) plugin to provide comprehensive support for various myQ features such as obstruction detection, and the first to provide support for multiple myQ device types. As more of the API can be decoded, my aim is to support as many device types as possible. I rely on this plugin every day and actively maintain and support it. ### Features - ***Easy* configuration - all you need is your myQ username and password to get started.** The defaults work for the vast majority of users. When you want more, there are [advanced options](#advanced-config) you can play with, if you choose. @@ -41,7 +41,7 @@ What does *just work* mean in practice? It means that this plugin will discover - **[Battery status detection](#battery-status) on supported myQ door position sensor devices.** If you have a myQ supported door position sensor, you'll see an alert raised in the Home app to inform you when the battery is running low. -- **The ability to [selectively hide and show](#feature-options) specific gateways (useful when you have multiple homes) or openers.** For those who only want to show particular devices in HomeKit, or particular homes, a flexible and intuitive way to configure device availability at a granular level is available. +- **The ability to [selectively hide and show](#feature-options) specific myQ devices.** For those who only want to show particular devices in HomeKit, or particular homes, a flexible and intuitive way to configure device availability at a granular level is available. - **Full MQTT support.** For those who use MQTT, this plugin provides full MQTT support with a rich set of options. [Read the MQTT documentation](https://github.com/hjdhjd/homebridge-myq/blob/master/docs/MQTT.md) for more details. @@ -50,19 +50,19 @@ The myQ API is undocumented and implementing a plugin like this one is the resul I would love to support more types of myQ devices. Currently `homebridge-myq` supports the following device types: -- Garage door openers +- Garage door and gate openers - Lamps and myQ switches Additional device types will be added as time allows. It's unlikely I will add support for myQ locks due to their deprecated protocol support. myQ cameras may be added at some point, but there are additional non-technical considerations related to the paid myQ product that I want to be mindful of. ## Documentation -* Getting going +* Getting Started * [Installation](#installation): installing this plugin, including system requirements. * [Plugin Configuration](#plugin-configuration): how to quickly get up and running. * [Additional Notes](#notes): some things you should be aware of, including myQ-specific quirks. * Advanced Topics - * [Feature Options](https://github.com/hjdhjd/homebridge-myq/blob/master/docs/FeatureOptions.md): granular options to allow you to show or hide specific garage door openers, gateways, and more. + * [Feature Options](https://github.com/hjdhjd/homebridge-myq/blob/master/docs/FeatureOptions.md): granular options to allow you to show or hide specific garage door openers and more. * [MQTT](https://github.com/hjdhjd/homebridge-myq/blob/master/docs/MQTT.md): how to configure MQTT support. * [Advanced Configuration](https://github.com/hjdhjd/homebridge-myq/blob/master/docs/AdvancedOptions.md): complete list of configuration options available in this plugin. * [Changelog](https://github.com/hjdhjd/homebridge-myq/blob/master/docs/Changelog.md): changes and release history of this plugin, starting with v2.0. @@ -70,32 +70,20 @@ Additional device types will be added as time allows. It's unlikely I will add s ## Installation If you are new to Homebridge, please first read the [Homebridge](https://homebridge.io) [documentation](https://github.com/homebridge/homebridge/wiki) and installation instructions before proceeding. -If you have installed the [Homebridge Config UI](https://github.com/oznu/homebridge-config-ui-x), you can intall this plugin by going to the `Plugins` tab and searching for `homebridge-myq` and installing it. - -If you prefer to install `homebridge-myq` from the command line, you can do so by executing: - -```sh -sudo npm install -g homebridge-myq -``` +If you have installed the [Homebridge Config UI](https://github.com/homebridge/homebridge-config-ui-x), you can intall this plugin by going to the `Plugins` tab and searching for `homebridge-myq` and installing it. ### Things To Be Aware Of -- The myQ API gets regularly updated and unfortunately this results in regularly breaking this and other myQ-related plugins. I've refactored this plugin in part to make it easier to maintain with future API changes that may come. Unfortunately, it's an ongoing challenge since API changes can be sudden and unpredictable. +- The myQ API has largely stabilized in recent years, particularly with the advent of the v6 version of the API. However, the myQ cloud can (and does) have occasional reliability challenges that can manifest through connectivity issues that you will see in the Homebridge logs related to this plugin. These are not bugs in `homebridge-myq` and there's not much we can do it aside from attempt to gracefully handle the errors when they occur. The myQ cloud is quite reliable the large majority (~93-95% by my estimate) of the time. Please do not open bug reports related to API issues - they'll be closed summarily unless it's a new API-specific issue that's emerged as a result of changes to the undocumented myQ API. These issues are largely harmless and resolve themselves on their own, usually in minutes, and occasionally in hours or days. - **As a result of the above you *will* see errors similar to this on an occasional basis in the Homebridge logs:** ``` myQ API: Unable to update device status from the myQ API. Acquiring a new access token. ``` - These messages can be safely ignored. myQ API errors *will* inevtiably happen. The myQ server-side infrastructure from Liftmaster / Chamberlain is not completely reliable and occasionally errors out due to server maintenance, network issues, or other infrastructure hiccups that occur on the myQ end of things. This plugin has no control over this, unfortunately, and all we can do is handle those errors gracefully, which is what I've attempted to do. The logging is informative and **not a cause for significant concern unless it is constant and ongoing**, which would be indicative of the larger API issues referenced above. When one of these errors is detected, we log back into the myQ infrastructure, obtain new API security credentials, and attempt refresh our status in the next scheduled update, which by is roughly [every 12 seconds by default](#advanced-config). + These messages can be safely ignored. myQ API errors *will* inevtiably happen. The myQ cloud infrastructure from Liftmaster / Chamberlain is not completely reliable and occasionally errors out due to infrastructure maintenance, network issues, or other infrastructure hiccups that occur on the myQ end of things. This plugin has no control over this. The logging is informative and **not a cause for significant concern unless it is constant and ongoing for multiple days**, which would be indicative of the larger API issues referenced above. When one of these errors is detected, we log back into the myQ infrastructure, obtain new API security credentials, and attempt refresh our status in the next scheduled update, which by is roughly [every 12 seconds by default](#advanced-config). - Obstruction detection in myQ is more nuanced than one might think at first glance. When myQ detects an obstruction, that obstruction is only visible in the API for a *very* small amount of time, typically no more than a few seconds. This presents a user experience problem - if you remain completely faithful to the myQ API and only show the user the obstruction for the very short amount of time that it actually occurs, the user might never notice it because the alert is not visible for more than a few seconds. Instead, the design decision I've chosen to make is to ensure that any detected obstruction is alerted in HomeKit for 30 seconds from the last time myQ detected that obstruction. This ensures that the user has a reasonable chance of noticing there was an obstruction at some point in the very recent past, without having to have the user stare at the Home app constantly to happen to catch an ephemeral state. -- If your myQ device has support for battery status, `homebridge-myq` will automatically detect and add support for it in HomeKit. However, you **will** see a warning message in the [Homebridge](https://homebridge.io) logs along the lines of: - ``` - HAP Warning: Characteristic 00000079-0000-1000-8000-0026BB765291 not in required or optional characteristics for service 00000041-0000-1000-8000-0026BB765291. Adding anyway. - ``` - This can be safely ignored. It's an error message indicating that, in HomeKit, the garage door opener accessory service doesn't normally support battery status. HomeKit will still report it correctly, and alert you accordingly. - ## Plugin Configuration If you choose to configure this plugin directly instead of using the [Homebridge Configuration web UI](https://github.com/oznu/homebridge-config-ui-x), you'll need to add the platform to your `config.json` in your home directory inside `.homebridge`. @@ -113,6 +101,6 @@ For most people, I recommend using [Homebridge Configuration web UI](https://git This is mostly of interest to the true developer nerds amongst us. [![License](https://img.shields.io/npm/l/homebridge-myq?color=%230559C9&logo=open%20source%20initiative&logoColor=%23FFFFFF&style=for-the-badge)](https://github.com/hjdhjd/homebridge-myq/blob/master/LICENSE.md) -[![Build Status](https://img.shields.io/github/workflow/status/hjdhjd/homebridge-myq/Continuous%20Integration?color=%230559C9&logo=github-actions&logoColor=%23FFFFFF&style=for-the-badge)](https://github.com/hjdhjd/homebridge-myq/actions?query=workflow%3A%22Continuous+Integration%22) +[![Build Status](https://img.shields.io/github/actions/workflow/status/hjdhjd/homebridge-myq/ci.yml?branch=main&color=%230559C9&logo=github-actions&logoColor=%23FFFFFF&style=for-the-badge)](https://github.com/hjdhjd/homebridge-myq/actions?query=workflow%3A%22Continuous+Integration%22) [![Dependencies](https://img.shields.io/librariesio/release/npm/homebridge-myq?color=%230559C9&logo=dependabot&style=for-the-badge)](https://libraries.io/npm/homebridge-myq) [![GitHub commits since latest release (by SemVer)](https://img.shields.io/github/commits-since/hjdhjd/homebridge-myq/latest?color=%230559C9&logo=github&sort=semver&style=for-the-badge)](https://github.com/hjdhjd/homebridge-myq/commits/master) diff --git a/config.schema.json b/config.schema.json index 3988ea0..b4f32ae 100644 --- a/config.schema.json +++ b/config.schema.json @@ -32,11 +32,11 @@ }, "name": { - "title": "Name", + "title": "Plugin Name", "type": "string", - "required": false, - "placeholder": "myQ", - "description": "The name to assign this plugin for logging purposes. Default: myQ." + "required": true, + "default": "myQ", + "description": "Name to use for Homebridge logging purposes. Default: myQ." }, "options": { @@ -47,8 +47,8 @@ "type": "string", "title": "Feature Option", "required": false, - "description": "Enter only one option per entry. See project page for the complete list of available options.", - "placeholder": "e.g. Disable.SerialNumber" + "description": "Enter only one option per entry. See the plugin documentation for the complete list of available options or use the feature options webUI tab above.", + "placeholder": "e.g. Disable.Device.SerialNumber" } }, @@ -56,7 +56,7 @@ "type": "string", "title": "MQTT Base Topic", "required": false, - "placeholder": "e.g. unifi/protect", + "placeholder": "e.g. myq", "description": "The base MQTT topic to publish to. Default: myq." }, @@ -74,7 +74,7 @@ "title": "myQ API Cloud Region", "required": false, "placeholder": "e.g. east", - "description": "The cloud geographic region to access the myQ API. Valid values are only east or west. Default: autoselected by the myQ API." + "description": "The cloud geographic region to access the myQ API. Valid values are only east or west. This option is provided with no support. Default: autoselected by the myQ API." }, "refreshInterval": { @@ -119,7 +119,7 @@ "type": "section", "title": "General Options", "expandable": true, - "expanded": true, + "expanded": false, "items": [ { "description": "Enter your myQ username and password below.", @@ -143,7 +143,7 @@ "type": "array", "orderable": true, "title": " ", - "description": "Feature options allow you to further customize the behavior of this plugin such as the ability to show or hide specific garage door openers.", + "description": "Use the feature options webUI tab above instead of manually configuring feature options here.", "buttonText": "Add Feature Option", "items": [ "options[]" diff --git a/docs/AdvancedOptions.md b/docs/AdvancedOptions.md index b33e4c8..5020433 100644 --- a/docs/AdvancedOptions.md +++ b/docs/AdvancedOptions.md @@ -29,8 +29,7 @@ This step is not required. The defaults should work well for almost everyone, bu "refreshInterval": 12, "activeRefreshInterval": 3, "activeRefreshDuration": 300, - "appId": "abcdefg", - "options": ["Hide.GW12345", "Show.CG6789"], + "options": ["Disable.Device.CG12345", "Enable.Device.CG6789"], "mqttUrl": "mqtt:1.2.3.4", "mqttTopic": "myq", "userAgent": "xyzxyz", @@ -48,7 +47,6 @@ This step is not required. The defaults should work well for almost everyone, bu | refreshInterval | Normal myQ device refresh interval in `seconds`. | 12 | No | | activeRefreshInterval | Refresh interval in `seconds` to use when myQ device state changes are detected. | 3 | No | | activeRefreshDuration | Duration in `seconds` to use `activeRefreshInterval` to refresh myQ device status. | 300 | No | -| appId | Override the builtin myQ appId to a user supplied one. **Use with extreme care.** | Builtin to `homebridge-myq` | No | | options | Configure plugin [feature options](https://github.com/hjdhjd/homebridge-myq/blob/master/docs/FeatureOptions.md). | [] | No | | mqttUrl | The URL of your MQTT broker. **This must be in URL form**, e.g.: `mqtt://user@password:1.2.3.4`. | | No | | mqttTopic | The base topic to use when publishing MQTT messages. | "myq" | No | diff --git a/docs/Changelog.md b/docs/Changelog.md index 9f9ebd7..d8e1ab9 100644 --- a/docs/Changelog.md +++ b/docs/Changelog.md @@ -2,6 +2,13 @@ All notable changes to this project will be documented in this file. This project uses [semantic versioning](https://semver.org/). +## 3.0.0 (2023-08-19) + * New feature: updated and modernized webUI to be inline with my other plugins. **Please note: there are several breaking changes to feature option names in this release. Please use the webUI to configure feature options.** For those familiar with one of my other plugins, `homebridge-unifi-protect` the webUI will look quite familiar to you. + * New feature: you can now synchronize names of your myQ devices with HomeKit. Synchronization is one-way and it will always view the myQ name as the source. The option is disabled by default. + * Improvement: further refinements to the myQ API to handle some of the more common errors gracefully and be more forgiving of issues on the myQ cloud end of the equation. + * **Note as of v3.0.0, Node 18 is the minimum required version of Node for `homebridge-myq`.** + * Housekeeping and documentation improvements. + ## 2.12.0 (2023-05-14) * Housekeeping. diff --git a/docs/FeatureOptions.md b/docs/FeatureOptions.md index 6a111bc..6bd149e 100644 --- a/docs/FeatureOptions.md +++ b/docs/FeatureOptions.md @@ -17,30 +17,76 @@ `homebridge-myq` is a [Homebridge](https://homebridge.io) plugin that makes myQ-enabled devices available to [Apple's](https://www.apple.com) [HomeKit](https://www.apple.com/ios/home) smart home platform. myQ-enabled devices include many smart garage door openers made primarily by Liftmaster, Chamberlain, and Craftsman, but includes other brands as well. You can determine if your garage door or other device is myQ-enabled by checking the [myQ compatibility check tool](https://www.myq.com/myq-compatibility) on the myQ website. ### Feature Options -Feature options allow you to enable or disable certain features in this plugin. -The `options` setting is an array of strings used to customize feature options. Available options: +Feature options allow you to enable or disable certain features in this plugin. These feature options provide unique flexibility by also allowing you to set a scope for each option that allows you more granular control in how this plugin makes features and capabilities available in HomeKit. -- `Disable.` - hide the opener or gateway identified by `` from HomeKit. -- `Enable.` (default) - show the opener or gateway identified by `` from HomeKit. +The priority given to these options works in the following order, from highest to lowest priority where settings that are higher in priority will override the ones below: -- `Disable.BatteryInfo` - disable low battery notification for battery-enabled door position sensors for myQ garage openers. -- `Enable.BatteryInfo` (default) - disable low battery notification for battery-enabled door position sensors for myQ garage openers. + * Device options that are enabled or disabled. + * Global options that are enabled or disabled. -- `Disable.ReadOnly` (default) - enable HomeKit commands to open and close myQ garage openers. -- `Enable.ReadOnly` - disable HomeKit commands from opening and closing myQ garage openers. +All feature options can be set at any scope level, or at multiple scope levels. If an option isn't applicable to a particular category of device, it is ignored. If you want to override a global feature option you've set, you can override the global feature option for the individual device, if you choose. -With both the `Disable` and `Enable` options, replace `` with the serial number for your specific device found within the device "Accessory Details" in the Home app. +**Note: it's strongly recommended that you use the Homebridge webUI](https://github.com/homebridge/homebridge-config-ui-x) to configure this plugin - it's easier to use for most people, and will ensure you always have a valid configuration.** -The plugin will log all devices it encounters and knows about, and you can use that to guide what you'd like to hide or show. +#### Specifying Scope +Scoping rules: -Before using these features, you should understand how gateways and openers work in myQ. Gateways are the devices in your home that actually communicate your status to myQ. Openers are attached to gateways. A typical home will have a single gateway and one, or more, openers. If you choose to hide a gateway, you will also hide all the openers associated with that gateway. + * If you don't use a scoping specifier, feature options will be applied globally for all devices and streaming clients. + * To use a device-specific feature option, append the option with `.serial`, where `serial` is the serial number of the myQ device, as shown in the `hombridge-myq` logs within Homebridge. -If you've hidden a gateway, and all it's openers with it, you can selectively enable a single opener associated with that gateway by explicitly setting a `Show.` feature option. This should give you a lot of richness in how you enable or disable devices for HomeKit use. +`homebridge-myq` will log all devices it discovers on startup, including serial numbers, which you can use to tailor the feature options you'd like to enable or disable on a per-device basis. -The priority given to these options works in this order, from highest to lowest priority where settings that are higher in priority can override lower ones: +### Getting Started +Before using these features, you should understand how feature options propagate to controllers and the devices attached to them. If you choose to disable a controller from being available to HomeKit, you will also disable all the cameras attached to that controller. If you've disabled a controller, you can selectively enable a single device associated with that controller by explicitly using the `Enable.` Feature Option with that device's serial number. This provides you a lot of richness in how you enable or disable devices for HomeKit use. -* Show any opener we've explicitly said to show. -* Show any gateway we've explicitly said to show. -* Hide any opener we've explicitly hidden. -* Hide any gateway we've explicitly hidden. +The `options` setting is an array of strings used to customize Feature Options in your `config.json`. I would encourage most users, however, to use the [Homebridge webUI](https://github.com/homebridge/homebridge-config-ui-x), to configure Feature Options as well as other options in this plugin. It contains additional validation checking of parameters to ensure the configuration is always valid. + +#### Example Configuration +An example `options` setting might look like this in your config.json: + +```js +"platforms": [ + { + "platform": "myQ", + + "options": [ + "Disable.Device.CG12345", + "Enable.Device.CG6789" + ], + + "email": "email@email.com", + "password": "password" + } +] +``` +In this example: + +* The first line `Disable.Device.CG12345` prevents the door opener with the serial number `CG12345` from appearing in HomeKit. +* The second line `Enable.Device.CG6789` shows the door opener with the serial number `CG6789` in HomeKit. In this instance, an option such as this one is unnecessary given that myQ devices are shown by default in `homebridge-myq` and is provided as an example only. + +### Feature Options Reference +Feature options provide a rich mechanism for tailoring your `homebridge-myq` experience. The reference below is divided into functional category groups: + +**Note: it's strongly recommended that you use the Homebridge webUI](https://github.com/homebridge/homebridge-config-ui-x) to configure this plugin - it's easier to use for most people, and will ensure you always have a valid configuration.** + + * [Device](#device): Device feature options. + * [Opener](#opener): Opener feature options. + +#### Device feature options. + +These option(s) apply to: all myQ devices + +| Option | Description +|--------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +| `Device` | Make this device available in HomeKit. **(default: enabled)**. +| `Device.SyncNames` | Synchronize the myQ name of this device with HomeKit. Synchronization is one-way only, syncing the device name from myQ to HomeKit. **(default: disabled)**. + +#### Opener feature options. + +These option(s) apply to: myQ garage door and gate openers + +| Option | Description +|--------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +| `Opener.ReadOnly` | Make this opener read-only by ignoring open and close requests from HomeKit. **(default: disabled)**. +| `Opener.BatteryInfo` | Display battery status information for myQ door position sensors. You may want to disable this if the myQ status information is incorrectly resulting in a potential notification annoyance in the Home app. **(default: enabled)**.
*Supported on myQ devices that have a door position sensor.* diff --git a/homebridge-ui/public/index.html b/homebridge-ui/public/index.html index b053b44..997b6b2 100644 --- a/homebridge-ui/public/index.html +++ b/homebridge-ui/public/index.html @@ -5,6 +5,8 @@ @@ -12,8 +14,8 @@ - -