What is HomeKit-RATGDO?

HomeKit-RATGDO is an alternative firmware for the RATGDO v2.5-series WiFi control boards that works over your local network using HomeKit, or over the internet using your Apple HomeKit home hubs, to control your garage door opener. It requires no supporting infrastructure such as Home Assistant, Homebridge, MQTT, etc, and connects to your garage door opener with as few as three wires.

This firmware supports Security+ and Security+ 2.0 enabled garage door openers and RATGDO v2.5-series ESP8266-based hardware.

[!IMPORTANT] As of release v1.0.0, we believe this code is stable enough to call this a release build. You may still encounter issues. Please review the Issues and open a new one if necessary.

See the section below on where to get help.

[!WARNING] This firmware does not currently provide support the delayed close feature while warning users with flashing lights and beeping. When you ask it to close, it closes. If this is a concern for you, then you may want to go with another solution until this feature can be implemented. See Issue #60

[!NOTE] Many thanks to the original author @thenewwazoo. Why I'm leaving.

What does this firmware support?

• Opening and closing multiple garage doors independently in the same HomeKit home.
• Light Control and Status
• Obstruction sensor reporting
• Motion sensor reporting, if you have a "smart" wall-mounted control panel.

That's it, for now. Check the GitHub Issues for planned features, or to suggest your own.

How do I install it?

[!NOTE] The installation process is still being improved. You may need to reload the flasher tool page after each of the following steps in order to proceed.

For each of the following steps, use the online browser-based flash tool:

• Install the HomeKit-RATGDO firmware, and then wait 20 seconds.
• Connect the RATGDO to WiFi
• Click "Visit Device", and then begin the process of adding a device to HomeKit. Scan the QR code, or manually enter the setup code 2510-2023.

That's it!

Using ratgdo Webpage

Before pairing to HomeKit / Apple Home you should open up the ratgdo webpage and configure basic settings. Simply enter the local IP address of the ratgdo device to access the page. While this is optional, it is a good idea to set a more appropriate device name and check that your door protocol is correct.

The webpage comprises three sections, HomeKit and ratgdo device status, garage door opener status, and an information and diagnostic section.

HomeKit and ratgdo status

If you ratgdo device is not yet paired to HomeKit then a QR code is displayed for you to scan and add the garage door to HomeKit. If the device is already paired then this is replaced with a statement that you must first un-pair the device. A Reset or Un-pair HomeKit button is provided for this. Note: if you will repair to the same HomeKit home you must also delete the accessory from HomeKit as well as un-pairing at the ratgdo device.

This section also displays the current firmware version, with a statement on whether an update is available, the uptime of the device in days/hours/minutes/seconds and WiFi connection status.

Garage door opener status

Status of the garage door along with action buttons are shown in this section. The status values are updated in real time whether triggered by one of the action buttons or an external action (motion in the garage, someone using a door remote).

Information section

The final section provides useful links to documentation and legal/license information. At the very bottom of the page is diagnostic information, see Troubleshooting section below.

Authentication

By default authentication is not required for any action on this web page. However it is strongly recommended that you enable the setting to require a password and change the default. If authentication is enabled then all buttons except Reboot and entering the settings page are protected with a username and password

Default Username/Password: admin/password

[!NOTE] The device uses Digest Authentication supported in all web browsers, this is not cryptographically secure but is sufficient to protect against unauthorized or inadvertant access. Note that web browsers remember the username and password for a period of time so you will not be prompted to authenticate for every access.

You can change the default password by clicking into the settings gear:

Settings Webpage

The settings page allows you to input a new password (but username cannot be changed, it is always admin). Saving a new password will return you to the main webpage from which point you will have to authenticate with the new password to access the settings page or any of the action buttons (except for reboot).

If you save any settings from this page the ratgdo device will reboot and after a 30-second countdown you will return to the main webpage.

Name

This updates the name reported to HomeKit and for mDNS device discovery. The default name is Garage Door ABCDEF where the last 6 characters are set to the MAC address of the ratgdo device. Changing the name after pairing with HomeKit does not change the name within HomeKit or Apple Home.

Door Protocol

Set the protocol for your model of garage door opener. This defaults to Security+ 2.0 and you should only change this if necessary.

Require Password

If selected then all the action buttons except reboot, and access to the settings page, will require authentication. Default is not required.

Reboot Every

During early devlopment there were several reports that the ratgdo device would reset itself and loose its pairing with HomeKit. To reduce the chance of this occuring a regular (e.g. daily) reboot of the device provided a work-around. The firmware is far more stable now and it is hoped that this is no longer required. This setting may be removed in future versions.

WiFi Version

If the device faile to connect reliably and consistently to your WiFi network it may help to lock it to a specific WiFi version. The ratgdo supports 802.11b, 802.11g and 802.11n on the 2.4GHz WiFi band and by default will auto-select. If it helps in your network, select the specific version you wish to use. Note: If you select a version that your network does not support then the ratgdo will revert to auto-select and reboot itself after 30 seconds.

How do I upgrade?

Over-the-Air (OTA) updates are supported, either directly from GitHub or by selecting a firmware binary file on your computer. Follow the steps below to update:

• Navigate to your ratgdo's ip address where you will see the devices webpage, Click Firmware Update
• Update from Github
  • To check for updates, click Check for update
  • If update is available, Click Update
• Update from local file
  • Download the latest release, by download the .bin file on the latest release
  • Upload the firmware that was downloaded in step 1, by clicking Choose File under Update from local file.
  • Click Update to proceed with upgrading
  • Once the update is Successful, ratgdo will now Reboot
  • After a firmware update, you may have to go through the process of re-pairing your device to HomeKit. If your device is showing up as unresponsive in HomeKit, please try un-pairing, reboot, and re-pairing.

Automatic updates are not supported (and probably will never be), so set a reminder to check back again in the future.

Help! aka the FAQs

How can I tell if the ratgdo is paired to HomeKit?

Use the online browser-based flash tool, and follow the "Visit Device" link. If you see a big QR code, the ratgdo is not paired.

I added my garage door in the Home app but can't find it

This is a common problem. Be sure to check all of the "rooms" in the Home app. If you really can't find it, you can try un-pairing and re-pairing the device, paying close attention to the room you select after adding it.

Unable to Pair

I get a message Unable to Add Accessory: The setup code is incorrect.

We have had a number of users that have encountered this error that was a result of running HomeBrdige with the Bounjour-HAP mDNS backend. You can find more details in the issue thread, but the short story is to consider changing that backend to Avahi or Ciao.

How do I re-pair my ratgdo?

Use the online browser-based flash tool, and follow the "Visit Device" link. If you see a big QR code, the ratgdo is not paired. Click the "Un-pair HomeKit" button, and then delete the garage door from within the HomeKit app (or vice versa, order does not matter). It is also recommended that you reboot the RATGDO after un-pairing. You can then re-pair the device by adding it again as normal.

Where can I get help?

If your question has not been answered here, you can try the Discord chat.

Click this link to follow an invite to the server. Server rules require a 10 minute wait after signup.

Now that you've signed up, go here to join the discussion:

.

Please also feel free to open a GitHub Issue if you don't already see your concern listed. Don't forget to check the closed issues to see if someone has already found a fix.

Troubleshooting

Great reliability improvements have been made in recent versions of the firmware, but it is possible that things can still go wrong. As noted above you should check that the door protocol is correctly set and if WiFi connection stability is suspected then you select a specific WiFi version.

The footer of the webpage displays useful information that can help project contributors assist with diagnosing a problem. The ESP8266 is a low-memory device so monitoring actual memory usage is first place to start. Whenever you connect to the webpage, the firmware reports memory utilization every second... current available free heap, the lowest value that free heap has reached since last reboot, and the minimum available stack reached since last reboot.

In addition the last reboot date and time is reported (calculated by subtracting up-time from current time). If the last reboot was caused by a system crash then an additonal line will display the number of times it crashed with options to display the crash log, and to clear the crash log.

Display log

If this appears then please click on the link. A new browser tab will open with details of the crash. If you open an issue on GitHub then please copy/paste this into the issue.

Clear log

Once you have made a copy of the crash log, you should clear it so there is sufficient space to capture future crashes. Clearing the log requires authentication (only if require password selected) but will not reboot the device.

How can I contribute?

HomeKit-RATGDO uses PlatformIO for builds. You'll want to install PlatformIO first.

After you've checked out this repo:

git clone [email protected]:ratgdo/homekit-ratgdo.git

Initialize the submodules from the root of the repo:

cd homekit-ratgdo
git submodule init lib/secplus/
git submodule update

The x.sh script is my lazy way of not having to remember PlatformIO-specific pio commands. The important ones are run, upload, and monitor.

Who wrote this?

This firmware was written by Brandon Matthews, with lots of inspiration from the esphome-ratgdo project and critical dependence on the secplus decoder library.

Ongoing reliability improvements by Jonathan Stroud, and webpage design and implementation by David Kerr

Special credit goes to the Chamberlain Group, without whose irredeemably stupid decision to close their API to third parties, this firmware would never have been necessary.

Garage icons created by Creative Squad - Flaticon