This GDO setup guide provides two methods to add the GRGDO1 to an ESPHome/Home Assistant instance. You can add a new device and flash the firmware with a physical device connection via USB serial or you can add it using the pre installed GRGDO1 WIFI Captive portal and upload the firmware via OTA. The WIFI Captive portal method is by far a more convenient method since we only need a cell phone to establish your local WIFI connection. If the method chosen is the captive portal then you can install GRGDO1 physically and proceed to configure it remotely using your phone and ESPHome/Home Assistant after approximately one minute of power on time.
For Secplus GDO firmware see https://github.com/GelidusResearch/device.docs
Important information:
- If you are not familiar with AC mains safety please consult with or hire an electrician to connect the GRGDO1.
- You should NEVER connect to a live AC mains supply during the install or while the case is open.
- Always use an non-metallic fire safe enclosure to house the GRGDO1, (Included with the GRGDO1-KIT)
- The ESPhome Home Assistant Add-on is required – see: https://esphome.io/guides/getting_started_hassio.html
GDO Setup Guide – ESPHome Device Preparation
To start we create a unique device name like gdo1 since the preloaded firmware contains it it will speed up the editing later, once created we can edit the config to host the GRGDO1 pin set.
Since we are appending to the YAML config we can skip this step. We need to add a full configuration from the content in this guide.
The GRGDO1 is powered with an ESP32 as shown we need to set it and skip the next prompt.
Skip this step and note the generated unique key, this must be preserved in the config going forward.
GDO Setup Guide – YAML Configuration
Now we can edit the newly created device named gdo1, preserving the API key and add the example GRGDO1 code after the captive portal line, as shown. Note: the secplusv2 protocol selection default, older units may need secplusv1. You can also set the source to the RATGDO Github URL. We provide an alternate here to ensure upstream changes are well tested for good code quality.
#GDO setup guide
external_components:
- source: github://descipher/esphome-ratgdo/components/ratgdo
components: [ ratgdo ]
refresh: 0s
esphome:
name: gdo1
friendly_name: gdo1
esp32:
board: esp32dev
framework:
type: arduino
# Enable logging
logger:
# Enable Home Assistant API
api:
encryption:
key: "<your key>"
ota:
# - platform: esphome # post 2024.5.x
password: "<your password>"
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
ap:
ssid: "gdo1"
password: !secret iot_captive_password
captive_portal:
web_server:
preferences:
flash_write_interval: 600s
substitutions:
id_prefix: gdo1
friendly_name: "GDO"
uart_tx_pin: GPIO22 # J4 Pin 1 Red or 3 Blue to Opener Red CTRL terminal
uart_rx_pin: GPIO21 # J4 Pin 1 Red or 3 Blue to Opener Red CTRL terminal
input_obst_pin: GPIO23 # J4 Pin 4 Grey OBST
dry_contact_open_pin: GPIO17 # J4 Pin 6 Green
dry_contact_close_pin: GPIO19 # J4 Pin 7 Blue
dry_contact_light_pin: GPIO18 # J4 Pin 8 Orange
ratgdo:
id: ${id_prefix}
input_gdo_pin: ${uart_rx_pin}
output_gdo_pin: ${uart_tx_pin}
input_obst_pin: ${input_obst_pin}
protocol: secplusv2
sensor:
- platform: ratgdo
id: ${id_prefix}_openings
type: openings
entity_category: diagnostic
ratgdo_id: ${id_prefix}
name: "Openings"
unit_of_measurement: "openings"
icon: mdi:open-in-app
# - platform: dht #Optional Add-on DHT22
# model: DHT22
# pin: GPIO3
# temperature:
# name: "Temperature"
# accuracy_decimals: 1
# humidity:
# name: "Humidity"
# accuracy_decimals: 1
# update_interval: 60s
binary_sensor:
- platform: ratgdo
type: motion
id: ${id_prefix}_motion
ratgdo_id: ${id_prefix}
name: "Motion"
device_class: motion
- platform: ratgdo
type: obstruction
id: ${id_prefix}_obstruction
ratgdo_id: ${id_prefix}
name: "Obstruction"
device_class: problem
- platform: ratgdo
type: button
id: ${id_prefix}_button
ratgdo_id: ${id_prefix}
name: "Button"
entity_category: diagnostic
- platform: ratgdo
type: motor
id: ${id_prefix}_motor
ratgdo_id: ${id_prefix}
name: "Motor"
device_class: running
entity_category: diagnostic
- platform: gpio
id: "${id_prefix}_dry_contact_open"
pin:
number: ${dry_contact_open_pin} # dry contact for opening door
inverted: true
mode:
input: true
pullup: true
name: "Dry contact open"
entity_category: diagnostic
on_press:
- if:
condition:
binary_sensor.is_off: ${id_prefix}_dry_contact_close
then:
- cover.open: ${id_prefix}_garage_door
- platform: gpio
id: "${id_prefix}_dry_contact_close"
pin:
number: ${dry_contact_close_pin} # dry contact for closing door
inverted: true
mode:
input: true
pullup: true
name: "Dry contact close"
entity_category: diagnostic
on_press:
- if:
condition:
binary_sensor.is_off: ${id_prefix}_dry_contact_open
then:
- cover.close: ${id_prefix}_garage_door
- platform: gpio
id: "${id_prefix}_dry_contact_light"
pin:
number: ${dry_contact_light_pin} # dry contact for triggering light
inverted: true
mode:
input: true
pullup: true
name: "Dry contact light"
entity_category: diagnostic
on_press:
- light.toggle: ${id_prefix}_light
number:
- platform: ratgdo
id: ${id_prefix}_rolling_code_counter
type: rolling_code_counter
entity_category: config
ratgdo_id: ${id_prefix}
name: "Rolling code counter"
mode: box
unit_of_measurement: "codes"
- platform: ratgdo
id: ${id_prefix}_opening_duration
type: opening_duration
entity_category: config
ratgdo_id: ${id_prefix}
name: "Opening duration"
unit_of_measurement: "s"
- platform: ratgdo
id: ${id_prefix}_closing_duration
type: closing_duration
entity_category: config
ratgdo_id: ${id_prefix}
name: "Closing duration"
unit_of_measurement: "s"
- platform: ratgdo
id: ${id_prefix}_client_id
type: client_id
entity_category: config
ratgdo_id: ${id_prefix}
name: "Client ID"
mode: box
cover:
- platform: ratgdo
id: ${id_prefix}_garage_door
device_class: garage
name: "Door"
ratgdo_id: ${id_prefix}
light:
- platform: ratgdo
id: ${id_prefix}_light
name: "Light"
ratgdo_id: ${id_prefix}
button:
- platform: restart
name: "Restart"
- platform: safe_mode
name: "Safe mode boot"
entity_category: diagnostic
- platform: template
id: ${id_prefix}_query_status
entity_category: diagnostic
name: "Query status"
on_press:
then:
lambda: !lambda |-
id($id_prefix).query_status();
- platform: template
id: ${id_prefix}_query_openings
name: "Query openings"
entity_category: diagnostic
on_press:
then:
lambda: !lambda |-
id($id_prefix).query_openings();
- platform: template
id: ${id_prefix}_sync
name: "Sync"
entity_category: diagnostic
on_press:
then:
lambda: !lambda |-
id($id_prefix).sync();
- platform: template
id: ${id_prefix}_toggle_door
name: "Toggle door"
on_press:
then:
lambda: !lambda |-
id($id_prefix).door_toggle();
status_led:
pin: GPIO4
GDO Setup Guide – Captive Portal Method
With the GRGDO1 already powered up for at least 1 minute use a phone or other capable device connect to the GRGDO1 default preinstalled captive portal AP SSID named gdo1
Set your SSID and Password .
Note: Depending on the version of ESPHome you may need to manually open a browser to reach the captive portal.
After a minute or so visit the GRGDO1 WEB portal using its mDNS address to verify it’s ready. Power cycle it if required.
http://gdo1.local
Prepare the firmware by selecting INSTALL on the top right of the ESPHome edit screen.
We need to select manual download since the the factory setting will not have an OTA password set, as a result we use the WEB UI to update the firmware with the registered device firmware build.
Be sure to generate the Legacy format and then proceed to selecting the file for the OTA upload.
We can now use the factory set WEB UI to upload the newly created firmware named gdo1.bin which is based on the device name.
GRGDO1 will now come online and you can add it to Home Assistant with the configured API encryption key.
GDO Setup Guide – Physical USB Serial Method
To enable flash mode on the GRGDO1 you need to depress and hold SW1 then connect your USB to serial adapter to the UART flashing connector as shown here. Once power is applied the button can be released and GRGDO1 will be in flash mode. (Pre-connecting J1 and then plugging in the USB end is usually easier)
Serial TX and RX pins should be crossed e.g.
J1 GRGDO1 : USB Adapter
TX -> RX
RX <- TX
3.3v - 3.5v Max
GND - GND
Prepare the firmware by selecting install on the top right of the ESPHome edit screen.
Select Plug into this computer.
GRGDO1 will now come online and you can add it to Home Assistant with the configured key.
MQTT option
You have the option to run the GRGDO1 with MQTT. MQTT can be used for Home Assistant and a variety of other home automation systems such as HomeKit. Configuring and flashing the GRGDO1 would require compiling ESPHome using a docker environment in either a Home Assistant ESPHome integration or a standalone instance which is not detailed here and can be setup referencing this documentation https://esphome.io/guides/getting_started_command_line.html
An MQTT implementation method grants access to the full of ESPHome RATGDO component features. This is a significant enhancement over using a RATGDO MQTT or Native RATGDO HomeKit firmware images.
Enabling MQTT requires that a Home Assistant API is disabled, comment out the following api entry as show.
# Enable Home Assistant API
# api:
# encryption:
# key: "<your key>"
This minimum set of MQTT YAML entries must be added to your YAML config. Notice the improv_serial: entry, this is optional and is handy for setting or changing WiFi SSID and password up serially using a USB UART adapter. You will also be able to open any web server that is enabled for it via ESP WEB Tools.
We have included this example YAML, if you need more options see the full set at https://esphome.io/components/mqtt.html
improv_serial:
mqtt:
id: mqtt_client
client_id: GRGDO1
broker: <mqtt_ip>
username: <mqtt_username>
password: <mqtt_password>
discover_prefix: <your systems prefix> # Defauts to homeassistant
birth_message:
topic: availability
payload: online
will_message:
topic: availability
payload: offline
Connecting the GRGDO1 Module
J4 Pinouts
Pins 1 or 3 (CTRL) connects to the RED door opener terminal, this is the wired rolling code control signal. It can also connect to the door control button panel. Two terminals are provided to allow for a secondary feed.
Pins 2 or 5 (GND) connect to one of the WHITE door opener terminals, this is the system GND. Two terminals are provided to allow for a secondary feed.
Pins 6,7 and 8 are the dry contact inputs. This is the default config from the YAML file. These inputs can be used for other purposes such as a door status switch. They are voltage clamped to protect the ESP inputs from over voltages.
Example Wired Connection
This example is a basic config and is the most common way to connect up the GRGDO1 hardware
Connecting an optional DHT22
The DHT22 should align as shown.
Home Assistant Dashboard Examples
Button Card
Our GDO setup guide includes this custom button card which provides a compact simple interface for quick ops on a phone. This example assumes you have a HACS frontend installed with button-card and card-mod setup.
Compact Button Card – Closed State
Compact Button Card – Transition State
Compact Button Card – Open State
# HA Button Card YAML Example
# Button part
type: custom:button-card
template: garage-door-button-card
entity: cover.gdo1_door
name: Garage Door
tap_action:
action: toggle
variables:
icon_open: mdi:garage-open
icon_closed: mdi:garage
icon_cached: mdi:cached
# Template part
garage-door-button-card:
variables:
- icon_on: ''
- icon_off: ''
- icon_locked: ''
icon: |
[[[ if (entity.state == "open") return variables.icon_open;
if (entity.state == "closed") return variables.icon_closed;
else return variables.icon_cached;
]]]
size: 40px
action: toggle
hold_action:
action: more-info
styles:
card:
- aspect_ratio: 1/1
- padding: 5px 5px
- border-radius: 2
- border-color: var(--primary-color)
icon:
- color: |
[[[ if (entity.state == "closed") return 'var(--state-icon-color)' ;
else return 'var(--state-icon-active-color)';
]]]
Entity Card
In this GDO setup guide example we use the default entity card with a custom card-mod to high light it’s border, in this case the custom card-mod is optional.
Entity Card – Closed
Entity Card – Transition
Entity Card – Open
# Entities example
type: entities
entities:
- entity: cover.gdo1_door
name: Garage Door Opener
title: Garage Door
card_mod:
style: |
ha-card {
border-color: var(--primary-color);
}
This completes the GDO Setup Guide. For addition help please join the ESPhome discord site and ping @descipher