Important
This firmware is for the ratgdo32 and ratgdo32-disco series boards. It will not work with the ratgdo v2.5xi boards. HomeKit support for for the original v2.5xi devices can be found here
THIS IS EARLY FIRMWARE still under test. Future updates MAY include breaking changes requiring a flash erase and re-upload.
Firmware for the new DISCO device is under development. The following features, documented in this README, are not currently available in this version and may never be implemented
- Crashlog display and download.
- Locking WiFi to specific WiFi access point.
- Setting WiFi protocol version.
- Setting WiFi transmit power.
HomeKit-ratgdo32 is alternative firmware for the ratgdo32-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+, Security+ 2.0 and Dry Contact enabled garage door openers
- 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 or with the obstruction sensor
- Vehicle presence, arrival and departure sensing (ratgdo32-disco board only)
- Parking assist laser (ratgdo32-disco board only)
Check the GitHub Issues for planned features, or to suggest your own.
Connect your ratgdo to a computer with a USB cable and use the online browser-based flash tool to install the firmware.
Note
The browser must be able to access a USB serial device. Some browsers block USB access. The Google Chrome browser is known to work and is recommended.
After flashing the firmware, the browser-based tool will give you the option to provision WiFi network and password, and following that the option to connect to the ratgdo from where you can configure settings.
If you skip this step, then you can set the network and password later using a laptop, phone or tablet. Search for the WiFi network named Garage Door ABCDEF where the last six characters are a unique identifier. Once connected use a browser to access http://192.168.4.1 and wait for it to display a list of WiFi networks to join.
After selecting the WiFi network the device will reboot and you can connect to it using a browser on your network at the address http://Garage-Door-ABCDEF. Once the device is running you can change the name and add it to HomeKit by scanning the QR code.
The manual setup code is 2510-2023.
Warning
Only add one ratgdo device at a time. If you have multiple ratgdo devices, make sure that any not already paired to HomeKit are turned off... except the one that you want to add.
Note
If you experience very slow or poor connection accessing the ratgdo device web page then try moving the device further away from the garage door opener. Several users have reported that this can improve reliability of the connection. We do not know why this is the case but may suggest some RF interference between the door opener and the ratgdo device.
When you first add the device to HomeKit a number of accessories are added:
- HomeKit bridge to which all other accessories are attached
- garage door with door state, obstruction detection and lock. Lock not available with Dry Contact protocol
- light switch. Not available with Dry Contact protocol
- motion sensor. Automatically added for doors with wall panels that detect motion. Also can be optionally added and triggered by a button press on the wall panel and/or triggering the obstruction sensor.
- Vehicle arriving motion sensor. Only on ratgdo32-disco boards, triggers motion if it detects arrival of a vehicle.
- Vehicle departing motion sensor. Only on ratgdo32-disco boards, triggers motion if it detects departure of a vehicle.
- Vehicle presence occupancy sensor. Only on ratgdo32-disco boards, set if the distance sensor detects presence of a vehicle.
- Parking assist laser light switch. Only on ratgdo32-disco boards.
Vehicle arrival and departing sensors are only triggered if vehicle motion is detected within 5 minutes of door opening or closing. The parking assist laser is activated for one minute when vehicle arrival is detected.
See below for instructions on setting the distance threshold for triggering vehicle presence.
If you select Identify during the add accessory process then the blue LED and Laser will light and the beeper sound for 2 seconds.
Before pairing to HomeKit / Apple Home you should open up the ratgdo webpage and configure basic settings. Simply enter the local name or IP address of the ratgdo device to access the settings page 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.
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 if you wish to use it with another HomeKit home. A Reset or Un-pair HomeKit button is provided for this.
Note
If you will re-pair 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.
Note
If the word locked appears after the WiFi AP identifier then the ratgdo device will only connect to that WiFi Access Point. See warning in the Set WiFi SSID section below.
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).
For ratgdo32-disco boards, vehicle status is shown as Away, Parked, Arriving or Departing. A distance value in centimeters is also shown that represents the distance between the ratgdo board and either the garage floor (if no vehicle present) or the roof/hood of the vehicle. It is normal for this value to fluctuate. See section below on setting vehicle distance threshold.
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.
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 are protected with a username and 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 inadvertent 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 user name and password by clicking into the settings page:
The settings page allows you to input a new user name and password. 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).
When you save settings from this page the ratgdo device will either return immediately to the main page or, if required, reboot return to the main page and after a 30-second countdown.
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. The maximum length is 31 characters. For network hostname the length is truncated to 23 characters and all spaces are replaced with a hyphen.
You can select up-to 60 second delay before door starts closing. During the delay period the garage door lights will flash and you may hear the relay clicking. On ratgdo32-disco boards you will also hear an audible beep.
If selected then all the action buttons except reboot, and access to the settings page, will require authentication. Default is not required.
If selected On when idle, then the blue LED light on the ratgdo device will remain illuminated when the device is idle and flash off when there is activity. If you prefer the LED to remain off while idle then select Off when idle and the LED to flash on with activity. You can also Disable the blue LED. Note that the ratgdo32-disco boards also have a red power LED light. This cannot be controlled and is always on when power is connected.
This setting allows you to send the ratgdo logs to a syslog server. Enter the IP address of your syslog server. Uses UDP port 514 by default and logs to the LOCAL0 Facility.
Note
If your ratgdo is on an IoT VLAN or otherwise isolated VLAN, then you need to make sure it has access to your syslog server. If the syslog server is on a separate VLAN, you need to allow UDP port 514 through the firewall.
This allows you to select what causes the HomeKit motion sensor accessory to trigger. The default is to use the motion sensor built into the garage door opener, if it exists. This checkbox is not selectable because presence of the motion sensor is detected automatically... based on detecting motion in the garage. If your door opener does not have a motion sensor then the checkbox will show as un-checked.
Motion can also be triggered by the obstruction sensor and by pressing the door, light or lock buttons on the door opener wall panel. These are disabled by default but may be selected on the web page.
Ratgdo32-disco boards detect vehicle arrival, departure and presence based on distance measured from the ratgdo board. You should monitor the value reported in vehicle distance when there is no vehicle present (the approximate distance to the floor) and when the vehicle is parked (the approximate distance to the vehicle roof or hood). Set the vehicle distance slider to between these these two values. Measured distance can fluctuate so allow for this when setting the value.
Set the protocol for your model of garage door opener. This defaults to Security+ 2.0 and you should only change this if necessary. Note that the changing the door protocol also resets the door opener rolling codes and whether there is a motion sensor (this will be automatically detected after reset).
If the device fails 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.
You can set the WiFi transmit power to between 0 and 20 dBm. It defaults to the maximum (20.5 dBm, displayed as 20 dBm) but you may wish to fine tune this to control how the device connects to available WiFi access points.
Note
If the ratgdo device fails to connect to a WiFi access point by approximately 40 seconds after a reboot from a setting change, then the device will reset all the WiFi settings and will then attempt to reconnect to the server.
If selected then you can enter a static IP address, network mask, gateway IP and DNS server IP. Note that if the address changes, then after reboot the web page will not automatically reload from the new IP address... you will need to manually connect to the ratgdo device at its new address. Most users should NOT select static IP as it is far safer to use DHCP to automatically configure the device.
Ratgdo tests for network connection approximately 30 seconds after a reboot from a WiFi setting change. If this fails then the device will disable static IP and will attempt to reconnect to the network using DHCP.
Note
You must provide an IP address for DNS (Domain Name Service), this is required to set the clock on ratgdo with Network Time Protocol (NTP). Most household gateway routers act as DNS servers so you can use the same IP address as the gateway.
Warning
If you enter an IP address that is not valid on your network then you will not be able to access the device by web browser or from HomeKit. If the device fails to automatically recover by resetting to DHCP, then you can recover by using the soft AP mode described below in Set WiFi SSID (press light button 5 times). If this also fails then you will need to flash the ratgdo over the USB port using the web installer AND select the option to erase the device. This will factory reset the device and you will have to remove the garage door accessory from HomeKit and then add it again.
The ratgdo device will obtain current time from an NTP (Network Time Protocol) server. This requires internet access and the default setting is disabled.
When enabled, the lastDoorChange date and time (reported at the bottom of the web page) is saved across reboots and the actual time of log data is reported when viewed in the browser system logs page.
You can select time zone for your location. On fist boot, or after changing the WiFi network SSID, the ratgdo will reset to GMT/UTC and then attempt to obtain your time zone by geo-locating the external IP address of the network that ratgdo is connected to. The discovered time zone will take effect immediately after you view the ratgdo web page.
During early development there were several reports that the ratgdo device would reset itself and loose its pairing with HomeKit. To reduce the chance of this occurring 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.
This button resets the Sec+ 2.0 rolling codes and whether your door opener has a motion sensor. This may be necessary if the ratgdo device gets out-of-sync with what the door opener expects. Selecting this button requires the ratgdo to reboot and does not save any new settings.
This button enters the WiFi network selection page, similar to booting into Soft AP mode described below, but without the reboot. If you cancel from this page then you return to the main ratgdo page without a reboot or saving any changes. Selecting submit will save changes and reboot the device as described below.
This button will restart the ratgdo in soft Access Point (AP) mode from where you can set a new WiFi network SSID and password. You can connect to the ratgdo by connecting your laptop or mobile device to the ratgdo's WiFi SSID and pointing your browser to IP address 192.168.4.1. The SSID created is based on the device name, e.g. Garage-Door-ABCDEF.
If you are unable to connect to your ratgdo, or the old WiFi network is not available, you can force the device into soft Access Point mode by rapidly pressing the wall panel light button 5 times within 3 second. The ratgdo will respond by flashing the lights for 3 more seconds before rebooting into AP mode. Allow 15 to 20 seconds for the ratgdo to boot.
If you are preparing to move the ratgdo to a new location then, after the device has booted into soft AP mode, you can disconnect it (within 10 minutes). When it first boots in the new location it will start up in soft AP mode. In soft AP mode the ratgdo does not connect to the garage door opener or HomeKit.
On changing the WiFi network SSID you will have to un-pair and re-pair the ratgdo to Apple Home.
Note
If you do not set a new SSID and password within 10 minutes of booting into soft AP mode then the ratgdo will reboot as normal and connect to the previously set WiFi network SSID.
Note
On changing the SSID in soft AP mode the ratgdo attempts to connect to the new WiFi network. If that fails, then the ratgdo will reset to the old SSID and password, remove any Access Point lock, and reboot.
Warning
The soft AP page has an advanced mode. If you select this then the full list of discovered networks are shown, including same network SSID's broadcast by multiple access points. Selecting a WiFi network in advanced mode locks the device to a specific WiFi access point by its unique hardware BSSID. If that access point goes offline, or you replace it, then the device will NOT connect to WiFi. Use advanced mode with extreme caution. Not currently implemented on ratgdo32 boards.
This button erases all saved settings, including WiFi, HomeKit unique IDs. The device is reset to as-new state and must be reconfigured. HomeKit will no longer recognize the device and consider it all new.
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. Select the Include pre-releases box to include pre- or beta-release versions in the check. - If update is available, Click
Update.
- To check for updates, click
- Update from local file.
- Download the latest release, by download the
.binfile from the latest release page.
- Upload the firmware that was downloaded in step 1, by clicking
Choose FileunderUpdate from local file. - Click
Updateto 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.
- Download the latest release, by download the
Automatic updates are not supported (and probably will never be), so set a reminder to check back again in the future.
If the OTA firmware update fails the following message will be displayed and you are given the option to reboot or cancel. If you reboot, the device will reload the same firmware as previously installed. If you cancel then the device remains open, but the HomeKit service will be shutdown. This may be helpful for debugging, see Troubleshooting section below.
Espressif publishes esptool, a command line utility built with python. Esptool requires that you connect a USB serial cable to the ratgdo device.
Note
The ratgdo32 firmware comprises multiple files. It is strongly recommended to use the online browser-based flash tool described above rather than use this command directly
It is possible to query status, monitor and reboot/reset the ratgdo device from a command line. The following have been tested on Ubuntu Linux and Apple macOS.
curl -s http://<ip-address>/status.json
Status is returned as JSON formatted text.
curl -s -X POST http://<ip-address>/reboot
Allow 30 seconds for the device to reboot before attempting to reconnect.
curl -s -X POST http://<ip-address>/reset
Resets and reboots the device. This will delete HomeKit pairing.
Note
Will not work if device set to require authentication
curl -s http://<ip-address>/crashlog
Returns details of the last crash including stack trace and the message log leading up to the crash. Not currently implemented on ratgdo32 boards.
curl -s http://<ip-address>/clearcrashlog
Erase contents of the crash log.
curl -s http://<ip-address>/showlog
Returns recent history of message logs.
curl -s http://<ip-address>/showrebootlog
Returns log of messages that immediately preceded the last clean reboot (e.g. not a crash or power failure).
Note
This may be older than the most recent crash log.
The following script is available in this repository as viewlog.sh
UUID=$(uuidgen)
URL=$(curl -s "http://${1}/rest/events/subscribe?id=${UUID}&log")
curl -s "http://${1}/showlog"
curl -s -N "http://${1}${URL}?id=${UUID}" | sed -u -n '/event: logger/{n;p;}' | cut -c 7-
Run this script as <path>/viewlog.sh <ip-address>
Displays recent history of message log and remains connected to the device. Log messages are displayed as they occur. Use Ctrl-C keystroke to terminate and return to command line prompt. You will need to download this script file from github.
Warning
This should be used with extreme caution, updating from USB serial or web browser is strongly preferred. Before using this script you should check that embedded commands like md5 or md5sum and stat work correctly on your system. Monitoring the message log (see above) is recommended and no other browser should be connected to the ratgdo device.
<path>/upload_firmware.sh <ip-address> <firmware_file.bin>
Uploads a new firmware binary file to the device and reboots. It can take some time to complete the upload, you can monitor progress using the viewlog.sh script in a separate command line window. You will need to download this script file from github.
Note
Will not work if device set to require authentication
Connect a browser to your device at its IP address or host name (e.g. http://Garage-Door-ABCDEF). If you see a big QR code, the ratgdo is not paired.
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.
I get a message Unable to Add Accessory: The setup code is incorrect.
Warning
We have had a number of users that have encountered this error that was a result of running HomeBridge with the Bonjour-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.
From the ratgdo device home page click the Reset HomeKit or Un-pair HomeKit button, and then delete the garage door from within the HomeKit app (or vice versa, order does not matter). Resetting or Un-pairing HomeKit will cause the ratgdo device to reboot. You can then re-pair the device by adding it again as normal.
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 sign-up.
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.
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).
The lastDoorChange will show the date and time that the door was last opened or closed.
Clicking on the system logs link will open a new browser tab with details of current and saved logs. On this page you can select to view the current system log, the current system status in raw JSON format, the system log immediately before the last user requested reboot or reset, and the system log immediately before the last crash. If you open an issue on GitHub then please copy/paste the full crash log into the issue.
HomeKit-ratgdo32 uses PlatformIO for builds. You'll want to install PlatformIO first.
Check out this repo:
git clone --recurse-submodules https://github.com/ratgdo/homekit-ratgdo32.git
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.
This firmware was written by David Kerr, with lots of help from contributors: Jonathan Stroud and Donavan Becker
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
Copyright (c) 2023-24 HomeKit-ratgdo32 contributors.