GDO Setup Guide

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: GPIO18  # J4 Pin 6 Green
  dry_contact_close_pin: GPIO19 # J4 Pin 7 Blue
  dry_contact_light_pin: GPIO17 # 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

GDO Flashing Header — GRGDO1 Flashing Header

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

Return to the main page.