@mp-consulting/homebridge-unifi-access 1.0.0

package/docs/FeatureOptions.md

@@ -0,0 +1,120 @@
+<div align="center">
+
+![homebridge-unifi-access: Native HomeKit support for UniFi Access](media/homebridge-unifi-access.svg)
+
+# Homebridge UniFi Access
+
+[![Downloads](https://img.shields.io/npm/dt/@mp-consulting/homebridge-unifi-access?color=%230559C9&logo=icloud&logoColor=%23FFFFFF&style=for-the-badge)](https://www.npmjs.com/package/@mp-consulting/homebridge-unifi-access)
+[![Version](https://img.shields.io/npm/v/@mp-consulting/homebridge-unifi-access?color=%230559C9&label=Latest%20Version&logo=ubiquiti&logoColor=%23FFFFFF&style=for-the-badge)](https://www.npmjs.com/package/@mp-consulting/homebridge-unifi-access)
+[![verified-by-homebridge](https://img.shields.io/badge/homebridge-verified-blueviolet?color=%23491F59&style=for-the-badge&logoColor=%23FFFFFF&logo=homebridge)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)
+[![License](https://img.shields.io/npm/l/@mp-consulting/homebridge-unifi-access?color=%230559C9&logo=open%20source%20initiative&logoColor=%23FFFFFF&style=for-the-badge)](../LICENSE.md)
+
+Complete HomeKit support for the [UniFi Access](https://ui.com/door-access) ecosystem using [Homebridge](https://homebridge.io).
+
+</div>
+
+`@mp-consulting/homebridge-unifi-access` is a [Homebridge](https://homebridge.io) plugin that provides HomeKit support to the [UniFi Access](https://ui.com/door-access) device ecosystem. [UniFi Access](https://ui.com/door-access) is [Ubiquiti's](https://www.ui.com) door access security platform, with doorbell, reader, lock, and controller hardware options for you to choose from, as well as an app which you can use to view, configure and manage your door access security.
+
+### Feature 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.
+
+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:
+
+  * Device options that are enabled or disabled.
+  * Controller options that are enabled or disabled.
+  * Global options that are enabled or disabled.
+
+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. For example, if you have two doorbells in your environment, and want to enable the same feature options on both, you can enable the doorbell-related feature options globally rather than specifying them for each individual doorbell. If you want to override a global feature option you've set, you can override the global feature option for the individual doorbell in this example.
+
+**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.**
+
+#### Specifying Scope
+There are two types of scope specifiers that you can use with feature options - MAC addresses.
+
+Scoping rules:
+
+  * If you don't use a scoping specifier, feature options will be applied globally for all devices.
+  * To use a device or controller-specific feature option, append the option with `.MAC`, where `MAC` is the MAC address of either a UniFi Access controller or a hub.
+
+`@mp-consulting/homebridge-unifi-access` will log all devices it discovers on startup, including MAC addresses, which you can use to tailor the feature options you'd like to enable or disable on a per-device basis.
+
+### 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 devices 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 MAC address. This provides you a lot of richness in how you enable or disable devices for HomeKit use.
+
+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.
+
+### <A NAME="reference"></A>Feature Options Reference
+Feature options provide a rich mechanism for tailoring your `@mp-consulting/homebridge-unifi-access` experience. The reference below is divided into functional category groups:
+
+ * [Device](#device): Device feature options.
+ * [Controller](#controller): Controller feature options.
+ * [Hub](#hub): Hub feature options.
+ * [AccessMethod](#accessmethod): Access method feature options.
+ * [Log](#log): Logging feature options.
+
+#### <A NAME="device"></A>Device feature options.
+
+These option(s) apply to: all Access device types.
+
+| Option                                                                              | Description
+|-------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------
+| <A NAME="Device"></A>`Device`                                                       | Make this device available in HomeKit. **(default: enabled)**.
+| <A NAME="Device.SyncName"></A>`Device.SyncName`                                     | Synchronize the UniFi Access name of this device with HomeKit. Synchronization is one-way only, syncing the device name from UniFi Access to HomeKit. **(default: disabled)**.
+
+#### <A NAME="controller"></A>Controller feature options.
+
+These option(s) apply to: Access controllers.
+
+| Option                                                                              | Description
+|-------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------
+| <A NAME="Controller.DelayDeviceRemoval"></A><CODE>Controller.DelayDeviceRemoval<I>.Value</I></CODE>  | Delay, in seconds, before removing devices that are no longer detected on the Access controller. By default, devices are added and removed in realtime. **(default: 60)**.
+| <A NAME="Controller.Publish.Telemetry"></A>`Controller.Publish.Telemetry`           | Publish all the realtime telemetry received from the Access controller to MQTT. **(default: disabled)**.
+
+#### <A NAME="hub"></A>Hub feature options.
+
+These option(s) apply to: all Access device types.
+
+| Option                                                                              | Description
+|-------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------
+| <A NAME="Hub.Door.UseLock"></A>`Hub.Door.UseLock`                                   | Use a lock accessory instead of a garage door opener accessory for the gate. **(default: disabled)**. <BR>*Supported on UniFi Access Gate.*
+| <A NAME="Hub.Door.UseGarageOpener"></A>`Hub.Door.UseGarageOpener`                   | Use a garage door opener accessory instead of a lock accessory. This is a visual preference only within HomeKit; the underlying lock behavior and feature options remain the same. **(default: disabled)**. <BR>*Supported on UniFi Access Ultra.*
+| <A NAME="Hub.LockDelayInterval"></A><CODE>Hub.LockDelayInterval<I>.Value</I></CODE>  | Delay, in minutes, before locking the door lock relay once it's been unlocked by HomeKit. If set to 0, it will remain unlocked indefinitely. This applies regardless of whether you use a lock or garage door opener accessory. By default, the door lock relay will lock five seconds after unlocking. **(default: 0)**.
+| <A NAME="Hub.Lock.Trigger"></A>`Hub.Lock.Trigger`                                   | Add a switch accessory to control the door lock relay. This can be useful in automation scenarios where you want to work around HomeKit's security restrictions and trigger events when a lock or unlock event occurs. This works with both lock and garage door opener accessories. **(default: disabled)**.
+| <A NAME="Hub.Doorbell"></A>`Hub.Doorbell`                                           | Add a doorbell accessory to handle doorbell ring events in HomeKit. **(default: enabled)**. <BR>*Supported on UniFi Access hubs that have a doorbell.*
+| <A NAME="Hub.Doorbell.Trigger"></A>`Hub.Doorbell.Trigger`                           | Add a switch accessory for automation scenarios to reflect (but not trigger) doorbell ring events on an Access doorbell. **(default: disabled)**. <BR>*Supported on UniFi Access hubs that have a doorbell.*
+| <A NAME="Hub.DPS"></A>`Hub.DPS`                                                     | Add a contact sensor accessory for the door position sensor. **(default: enabled)**. <BR>*Supported on UniFi Access Ultra.*
+| <A NAME="Hub.REL"></A>`Hub.REL`                                                     | Add a contact sensor accessory for the remote release. **(default: enabled)**. <BR>*Supported on UniFi Access Hub.*
+| <A NAME="Hub.REN"></A>`Hub.REN`                                                     | Add a contact sensor accessory for the request to enter sensor. **(default: enabled)**. <BR>*Supported on UniFi Access Hub.*
+| <A NAME="Hub.REX"></A>`Hub.REX`                                                     | Add a contact sensor accessory for the request to exit sensor. **(default: enabled)**. <BR>*Supported on UniFi Access Ultra.*
+| <A NAME="Hub.SideDoor"></A>`Hub.SideDoor`                                           | Add a lock accessory for the side door (pedestrian gate) on UniFi Access Gate Hub devices. **(default: enabled)**. <BR>*Supported on UniFi Access Gate.*
+| <A NAME="Hub.SideDoor.DPS"></A>`Hub.SideDoor.DPS`                                   | Add a contact sensor accessory for the side door position sensor. **(default: enabled)**. <BR>*Supported on UniFi Access Gate.*
+| <A NAME="Hub.SideDoor.Lock.Trigger"></A>`Hub.SideDoor.Lock.Trigger`                 | Add a switch accessory to control the side door lock. This can be useful in automation scenarios where you want to work around HomeKit's security restrictions for controlling locks. **(default: disabled)**. <BR>*Supported on UniFi Access Gate.*
+
+#### <A NAME="accessmethod"></A>Access method feature options.
+
+These option(s) apply to: all Access device types.
+
+| Option                                                                              | Description
+|-------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------
+| <A NAME="AccessMethod.Face"></A>`AccessMethod.Face`                                 | Add a switch accessory to control the face unlock access method. **(default: enabled)**. <BR>*Supported on UniFi Access readers that support face unlock authentication.*
+| <A NAME="AccessMethod.Hand"></A>`AccessMethod.Hand`                                 | Add a switch accessory to control the hand wave unlock access method. **(default: enabled)**. <BR>*Supported on UniFi Access readers that support hand wave authentication.*
+| <A NAME="AccessMethod.Mobile"></A>`AccessMethod.Mobile`                             | Add a switch accessory to control the mobile unlock access method. **(default: enabled)**. <BR>*Supported on UniFi Access readers that support mobile authentication.*
+| <A NAME="AccessMethod.NFC"></A>`AccessMethod.NFC`                                   | Add a switch accessory to control the NFC card access method. **(default: enabled)**. <BR>*Supported on UniFi Access readers that support NFC authentication.*
+| <A NAME="AccessMethod.PIN"></A>`AccessMethod.PIN`                                   | Add a switch accessory to control the PIN unlock access method. **(default: enabled)**. <BR>*Supported on UniFi Access readers that support PIN authentication.*
+| <A NAME="AccessMethod.QR"></A>`AccessMethod.QR`                                     | Add a switch accessory to control the QR unlock access method. **(default: enabled)**. <BR>*Supported on UniFi Access readers that support QR code authentication.*
+| <A NAME="AccessMethod.TouchPass"></A>`AccessMethod.TouchPass`                       | Add a switch accessory to control the Touch Pass access method. **(default: enabled)**. <BR>*Supported on UniFi Access readers that support Touch Pass.*
+
+#### <A NAME="log"></A>Logging feature options.
+
+These option(s) apply to: all Access device types.
+
+| Option                                                                              | Description
+|-------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------
+| <A NAME="Log.Doorbell"></A>`Log.Doorbell`                                           | Log doorbell ring events in Homebridge. **(default: enabled)**. <BR>*Supported on UniFi Access hubs that have a doorbell.*
+| <A NAME="Log.DPS"></A>`Log.DPS`                                                     | Log door position sensor events in Homebridge. **(default: enabled)**. <BR>*Supported on UniFi Access Ultra.*
+| <A NAME="Log.REL"></A>`Log.REL`                                                     | Log door remote release events in Homebridge. **(default: enabled)**. <BR>*Supported on UniFi Access Hub.*
+| <A NAME="Log.REN"></A>`Log.REN`                                                     | Log door request to enter events in Homebridge. **(default: enabled)**. <BR>*Supported on UniFi Access Hub.*
+| <A NAME="Log.REX"></A>`Log.REX`                                                     | Log door request to exit events in Homebridge. **(default: enabled)**. <BR>*Supported on UniFi Access Ultra.*
+| <A NAME="Log.Lock"></A>`Log.Lock`                                                   | Log lock events in Homebridge. **(default: enabled)**. <BR>*Supported on UniFi Access hubs.*
+

package/docs/MQTT.md

@@ -0,0 +1,116 @@
+<div align="center">
+
+![homebridge-unifi-access: Native HomeKit support for UniFi Access](media/homebridge-unifi-access.svg)
+
+# Homebridge UniFi Access
+
+[![Downloads](https://img.shields.io/npm/dt/@mp-consulting/homebridge-unifi-access?color=%230559C9&logo=icloud&logoColor=%23FFFFFF&style=for-the-badge)](https://www.npmjs.com/package/@mp-consulting/homebridge-unifi-access)
+[![Version](https://img.shields.io/npm/v/@mp-consulting/homebridge-unifi-access?color=%230559C9&label=Latest%20Version&logo=ubiquiti&logoColor=%23FFFFFF&style=for-the-badge)](https://www.npmjs.com/package/@mp-consulting/homebridge-unifi-access)
+[![verified-by-homebridge](https://img.shields.io/badge/homebridge-verified-blueviolet?color=%23491F59&style=for-the-badge&logoColor=%23FFFFFF&logo=homebridge)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)
+[![License](https://img.shields.io/npm/l/@mp-consulting/homebridge-unifi-access?color=%230559C9&logo=open%20source%20initiative&logoColor=%23FFFFFF&style=for-the-badge)](../LICENSE.md)
+
+Complete HomeKit support for the [UniFi Access](https://ui.com/door-access) ecosystem using [Homebridge](https://homebridge.io).
+
+</div>
+
+`@mp-consulting/homebridge-unifi-access` is a [Homebridge](https://homebridge.io) plugin that provides HomeKit support to the [UniFi Access](https://ui.com/door-access) device ecosystem. [UniFi Access](https://ui.com/door-access) is [Ubiquiti's](https://www.ui.com) door access security platform, with doorbell, reader, lock, and controller hardware options for you to choose from, as well as an app which you can use to view, configure and manage your door access security.
+
+### MQTT Support
+
+[MQTT](https://mqtt.org) is a popular Internet of Things (IoT) messaging protocol that can be used to weave together different smart devices and orchestrate or instrument them in an infinite number of ways. In short - it lets things that might not normally be able to talk to each other communicate across ecosystems, provided they can support MQTT.
+
+`@mp-consulting/homebridge-unifi-access` will publish MQTT events if you've configured a broker in the controller-specific settings. The plugin supports a rich set of capabilities over MQTT, including:
+
+  * Doorbell ring events.
+  * Lock events, including triggering locks via MQTT.
+  * Door position sensor (DPS) events.
+  * Terminal input events (REL, REN, REX).
+  * Motion detection events, including triggering motion via MQTT.
+  * Side door events for UA Gate devices.
+  * Raw telemetry publishing.
+
+### How to configure and use this feature
+
+This documentation assumes you know what MQTT is, what an MQTT broker does, and how to configure it. Setting up an MQTT broker is beyond the scope of this documentation. There are plenty of guides available on how to do so just a search away.
+
+You configure MQTT settings within a `controller` configuration block. The settings are:
+
+| Configuration Setting | Description
+|-----------------------|----------------------------------
+| `mqttUrl`             | The URL of your MQTT broker. **This must be in URL form**, e.g.: `mqtt://user:password@1.2.3.4`.
+| `mqttTopic`           | The base topic to publish to. The default is: `unifi/access`.
+
+To reemphasize the above: **mqttUrl** must be a valid URL. Simply entering in a hostname without specifying it in URL form will result in an error. The URL can use any of these protocols: `mqtt`, `mqtts`, `tcp`, `tls`, `ws`, `wss`.
+
+When events are published, by default, the topics look like:
+
+```sh
+unifi/access/1234567890AB/lock
+unifi/access/ABCDEF123456/doorbell
+```
+
+In the above example, `1234567890AB` and `ABCDEF123456` are the MAC addresses of your Access hub or other devices. We use MAC addresses as an easy way to guarantee unique identifiers that won't change. `@mp-consulting/homebridge-unifi-access` provides you information about your devices and their respective MAC addresses in the homebridge log on startup. Additionally, you can use the UniFi Access app or webUI to lookup what the MAC addresses are of your devices, should you need to do so.
+
+### <A NAME="publish"></A>Topics Published
+
+The topics and messages that `@mp-consulting/homebridge-unifi-access` publishes are:
+
+#### Door and Lock Topics
+
+| Topic                 | Message Published                | Device Scope
+|-----------------------|----------------------------------|----------------------------------
+| `doorbell`            | `true` when ringing, `false` when ring ends. | Hubs with doorbells.
+| `dps`                 | `true` when open, `false` when closed, `unknown` if not wired. | UA Ultra, UA Hub, UA Hub Door Mini, UA Gate.
+| `lock`                | `true` when locked, `false` when unlocked. | All hubs.
+| `rel`                 | `true` when open, `false` when closed. | UA Hub (remote release sensor).
+| `ren`                 | `true` when open, `false` when closed. | UA Hub (request to enter sensor).
+| `rex`                 | `true` when open, `false` when closed. | UA Ultra, UA Hub, UA Hub Door Mini (request to exit sensor).
+
+#### Side Door Topics (UA Gate Only)
+
+| Topic                 | Message Published                | Description
+|-----------------------|----------------------------------|----------------------------------
+| `sidedoor/dps`        | `true` when open, `false` when closed, `unknown` if not wired. | Side door (pedestrian gate) position sensor.
+| `sidedoor/lock`       | `true` when locked, `false` when unlocked. | Side door (pedestrian gate) lock state.
+
+#### Motion and Telemetry Topics
+
+| Topic                 | Message Published                | Description
+|-----------------------|----------------------------------|----------------------------------
+| `motion`              | `true` when motion detected, `false` when motion ends. | Motion detection events.
+| `telemetry`           | JSON payload of raw event data. | Published when `Controller.Publish.Telemetry` is enabled.
+
+Messages are published to MQTT when an action occurs on an Access device that triggers the respective event, or when an MQTT message is received for one of the topics `@mp-consulting/homebridge-unifi-access` subscribes to.
+
+### <A NAME="subscribe"></A>Topics Subscribed
+
+The topics that `@mp-consulting/homebridge-unifi-access` subscribes to are:
+
+#### Door and Lock Topics
+
+| Topic                   | Message Expected                 | Description
+|-------------------------|----------------------------------|----------------------------------
+| `doorbell/get`          | `true` | Triggers a publish of the current doorbell ring status.
+| `dps/get`               | `true` | Triggers a publish of the current door position sensor state.
+| `lock/get`              | `true` | Triggers a publish of the current lock state.
+| `lock/set`              | `true` to unlock momentarily (auto-relocks based on configured delay), `false` to unlock indefinitely. | Controls the door lock relay.
+
+#### Side Door Topics (UA Gate Only)
+
+| Topic                   | Message Expected                 | Description
+|-------------------------|----------------------------------|----------------------------------
+| `sidedoor/dps/get`      | `true` | Triggers a publish of the current side door position sensor state.
+| `sidedoor/lock/get`     | `true` | Triggers a publish of the current side door lock state.
+| `sidedoor/lock/set`     | `true` to lock, `false` to unlock. | Controls the side door lock relay.
+
+#### Motion Topics
+
+| Topic                   | Message Expected                 | Description
+|-------------------------|----------------------------------|----------------------------------
+| `motion/trigger`        | `true` | Triggers a motion event on the device.
+
+### Some Fun Facts
+  * MQTT support is disabled by default. It's enabled when an MQTT broker is specified in the configuration.
+  * MQTT is configured per-controller. This allows you to have different MQTT brokers for different Access controllers, if needed.
+  * If connectivity to the broker is lost, it will perpetually retry to connect in one-minute intervals.
+  * If a bad URL is provided, MQTT support will not be enabled.