v1.2.0.

.eslintrc.json

@@ -13,6 +13,7 @@
     "sourceType": "module"
   },
   "plugins": [ "@stylistic" ],
+  "root": true,
   "rules": {
     "camelcase": [ "warn" ],
     "curly": [ "warn", "all" ],

README.md

@@ -31,17 +31,23 @@ In the interest of the community seeking a solution outside of myQ, I've develop
   * Obstruction detection.
   * Occupancy sensor support.
   * Read-only garage door opener support.
-  * Automation switch support.
+  * Automation switch and dimmer support, allowing you to set the garage door to any position.
   * A rich webUI for configuration.
 
 ## Getting Started
 To get started with `homebridge-ratgdo`:
 
   * Install `homebridge-ratgdo` using the Homebridge webUI. Make sure you make `homebridge-ratgdo` a child bridge for the best performance.
+  * Install the [ESPHome Ratgdo firmware](https://ratgdo.github.io/esphome-ratgdo/). You'll need to use Chrome for this as Safari doesn't support installing firmware through a USB serial port.
+  * That's it. Ensure `homebridge-ratgdo` is running and it will autodiscover your Ratgdo devices and make them available in HomeKit.
+
+Deprecated instructions:
+  * Install the [MQTT Ratgdo firmware](https://paulwieland.github.io/ratgdo/flash.html). You'll need to use Chrome for this as Safari doesn't support installing firmware through a USB serial port.
   * [Carefully](#known-caveats) edit the MQTT server and port on your Ratgdo device to the IP address of your Homebridge server, and port 18830 (unless you've changed the default port in `homebridge-ratgdo`).
+  * **Please note, MQTT Ratgdo firmware support in `homebridge-ratgdo` is now considered deprecated and will be removed in an upcoming release. I encourage everyone to upgrade to the [ESPHome Ratgdo firmware](https://ratgdo.github.io/esphome-ratgdo/) as soon as they can.
 
 ## Known Caveats
-Ratgdo is a terrific solution that solves a problem for many stranded former myQ users and others. There are some quirks and caveats to note, however. As of Ratgdo firmware v2.57:
+Ratgdo is a terrific solution that solves a problem for many stranded former myQ users and others. There are some quirks and caveats to note, however. As of MQTT Ratgdo firmware v2.57:
 
   * Misconfiguring your MQTT server IP or port number in any way **will** lock up / brick the Ratgdo. The only fix for this I've discovered is to reflash the Ratgdo and don't misconfigure it the next time around.
   * Ratgdo currently has no useful way to query it's state over MQTT. That means that on startup, the state of the garage door opener in Homebridge / HomeKit will be unknowable. Given that challenge, `homebridge-ratgdo` will assume the garage door opener is closed on startup. Once an action is taken, the state of the garage door opener will be accurately reflected in Homebridge / HomeKit. There is technically a *query* command available through the MQTT interface to Ratgdo, but all that currently does is to set the Ratgdo state information to an unknown state, awaiting the next state update from the garage door opener, rather than actually publish the current state, which is really what we need.

config.schema.json

@@ -69,7 +69,7 @@
   "layout": [
     {
       "type": "section",
-      "title": "Settings",
+      "title": "Ratgdo Settings (MQTT Firmware)",
       "expandable": true,
       "expanded": false,
       "items": [

docs/Changelog.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file. This project uses [semantic versioning](https://semver.org/).
 
+## 1.2.0 (2024-04-14)
+  * New feature: ESPHome firmware support. homebridge-ratgdo now supports both the MQTT and ESPHome firmwares. **A future release of homebridge-ratgdo will remove support for using the Ratgdo MQTT firmware. I encourage everyone to upgrade to the ESPHome firmware sooner than later.** The ESPHome firmware appears to be far better maintained and issue-free than the MQTT firmware. It's been far more stable and reliable in my extensive testing. In addition, it enables some new functionality, particularly for certain automation scenarios. ESPHome firmware support "just works": homebridge-ratgdo will autodetect it's presence and configure it accordingly. There is nothing you need to do beyond installing the Ratgdo ESPHome firmware - the devices will be autodiscovered and autoconfigured by homebridge-ratgdo. You also do not need to remove your prior accessories. homebridge-ratgdo will gracefully handle things.
+  * New feature: automation dimmer support. You can now set automations to open and close yoru garage door opener to specific percentage levels, if you choose to do so. This feature is only available when using the ESPHome Ratgdo firmware.
+  * Improvement: enhanced MQTT support for opening and closing, allowing you to specify where you want the door to be opened to, if using the ESPHome Ratgdo firmware.
+  * Housekeeping.
+
 ## 1.1.0 (2024-02-29)
   * Improvement: when tapping on the garage door opener while an open or close event is inflight and has not yet completed, the garage door opener will now stop.
   * Fix: accessory names were being overwritten when the user has not requested them to be.

docs/FeatureOptions.md

@@ -44,13 +44,14 @@ Feature options provide a rich mechanism for tailoring your `homebridge-ratgdo`
 | Option                                           | Description
 |--------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 | `Device`                                         | Make this device available in HomeKit. **(default: enabled)**.
-| `Device.SyncName`                                | Synchronize the Ratgdo name of this device with HomeKit. Synchronization is one-way only, syncing the device name from Ratgdo to HomeKit. **(default: disabled)**.
+| `Device.SyncName`                                | Synchronize the Ratgdo name of this device with HomeKit. Synchronization is one-way only, syncing the device name from Ratgdo to HomeKit. This option is only available on Ratgdo devices running MQTT firmware versions. **(default: disabled)**.
 
 #### <A NAME="opener"></A>Opener feature options.
 
 | Option                                           | Description
 |--------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 | `Opener.ReadOnly`                                | Make this opener read-only by ignoring open and close requests from HomeKit. **(default: disabled)**.
+| `Opener.Dimmer`                                  | Add a dimmer accessory to control the opener. This can be useful in automation scenarios where you want to set the door to a specific percentage. This option is only available on Ratgdo devices running ESPHome firmware versions. **(default: disabled)**.
 | `Opener.Switch`                                  | Add a switch accessory to control the opener. This can be useful in automation scenarios where you want to work around HomeKit's security restrictions for controlling garage door openers. **(default: disabled)**.
 | `Opener.OccupancySensor`                         | Add an occupancy sensor accessory using the open state of the opener to determine occupancy. This can be useful in automation scenarios where you want to trigger an action based on the opener being open for an extended period of time. **(default: disabled)**.
 | `Opener.OccupancySensor.Duration<I>.Value</I>`   | Duration, in seconds, to wait once the opener has reached the open state before indicating occupancy. **(default: 300)**.

docs/MQTT.md

@@ -69,7 +69,7 @@ The topics that `homebridge-ratgdo` subscribes to are:
 |-------------------------|----------------------------------
 | `dooropenoccupancy/get` | `true` will trigger a publish event of the current garage door opener door open indicator occupancy status.
 | `garagedoor/get`        | `true` will trigger a publish event of the current garage door opener state.
-| `garagedoor/set`        | One of `close` or `open`. This will send the respective command to the garage door opener.
+| `garagedoor/set`        | One of `close` or `open`. This will send the respective command to the garage door opener. When using the ESPHome firmware, `open` takes an optional parameter between 0 and 100 to set the door position appropriately: `open 50` will set the garage door to the 50% open position.
 | `light/get`             | `true` will trigger a publish event of the current garage door opener light.
 | `motion/get`            | `true` will trigger a publish event of the current garage door opener motion sensor.
 | `obstruction/get`       | `true` will trigger a publish event of the current garage door opener obstruction sensor.

homebridge-ui/public/index.html

@@ -5,8 +5,7 @@
   <div class="text-left">
     <p>Welcome to <strong>homebridge-ratgdo</strong>. To get started:
       <ol>
-        <li>Ensure you're running the latest <a href="https://paulwieland.github.io/ratgdo/flash.html">Ratgdo MQTT firmware</a>.</li>
-        <li>Edit the MQTT server and port configuration using the webUI on your Ratgdo devices to the IP address of this Homebridge server and port <code id="serverPortInfo" class="font-weight-bold"></code>.</li>
+        <li>Ensure you're running the latest <a href="https://ratgdo.github.io/esphome-ratgdo/">Ratgdo ESPHome firmware</a>.</li>
       </ol>
     </p>
   </div>
@@ -70,6 +69,7 @@ <h5>Introduction</h5>
       Other plugins by <a target="_blank" href="https://github.com/hjdhjd">HJD</a>:
 
       <ul dir="auto">
+        <li><a target="_blank" href="https://github.com/hjdhjd/homebridge-unifi-access">homebridge-unifi-access: HomeKit integration for the UniFi Access ecosystem</a></li>
         <li><a target="_blank" href="https://github.com/hjdhjd/homebridge-unifi-protect">homebridge-unifi-protect: Complete HomeKit integration for the entire UniFi Protect ecosystem</a></li>
       </ul>
     </div>