GarHAge

a Home-Automation-friendly ESP8266-based MQTT Garage Door Controller

GarHAge allows two "dumb" garage door openers to be controlled (open/close) and report garage door status (open/closed) via MQTT.

GarHAge is almost completely compatible with Home Assistant's "MQTT Cover" platform. It responds to HASS's open and close commands and reports door status to keep HASS's GUI in sync with the door state. GarHAge does not implement HASS's "stop" command (as this functionality varies between garage door openers) or "tilt" functionality. Sample HASS configuration snippets are provided in this repository to get your garage door openers connected to HASS as quickly and painlessly as possible.

GarHAge should be controllable via any home automation software that can configure an MQTT cover, rollershutter, garage door, or send commands over MQTT, including OpenHAB.

GarHAge has both hardware and software components. The required hardware components include an ESP8266-based microcontroller (such as the NodeMCU), a relay module, and reed/magnetic switches. The software component is found in this repo.

Best of all, if you select the proper parts, building and installing a GarHAge requires no soldering!

Table of Contents

• GarHAge
  • a Home-Automation-friendly ESP8266-based MQTT Garage Door Controller
  • How GarHAge works...
  • Hardware
    • Bill of Materials
    • Detailed Bill of Materials
      • 1. ESP8266-based microcontroller
      • 2. Dual 5v relay module with active-high inputs
      • 3. Reed/magnetic door switches
      • 4. 5v MicroUSB power supply
      • 5. Mini solderless breadboard (170 tie-point)
      • 6. - 8. Miscellaneous parts
    • Building GarHAge
  • Software
    • 1. Set up the Arduino IDE
    • 2. Load the sketch in the Arduino IDE and modify the user parameters in config.h
      • Wifi Parameters
      • Static IP Parameters
      • MQTT Parameters
      • Door 1 Parameters
      • Door 2 Parameters
    • 3. Upload the sketch to your NodeMCU / microcontroller
    • 4. Check the Arduino IDE Serial Monitor
  • Installing GarHAge
  • Configuring Home Assistant
    • HASS Automation Workaround
    • MQTT Cover: Basic configuration
    • MQTT Cover: Complete configuration
    • MQTT Binary Sensor
    • HASS Example Automations
  • Configuring OpenHAB
  • Contributing
  • Issues/Bug Reports/Feature Requests

How GarHAge works...

GarHAge subscribes to a configurable MQTT topic for each of two garage doors (by default, garage/door/1/action and garage/door/2/action).

When the OPEN payload is received on either of these topics, GarHAge momentarily activates a relay connected to the relevant garage door opener to cause the door to open.

When the CLOSE payload is received on either of these topics, GarHAge momentarily activates a relay connected to the relevant garage door opener to cause the door to close. By default, GarHAge is configured to activate the same relay for the OPEN and CLOSE payloads, as most (if not all) garage door openers operate manually by momentarily closing the same circuit to both open and close.

When the STATE payload is received on either of these topics, GarHAge publishes the status (open or closed) of the relevant garage door to the configurable topic garage/door/1/status or garage/door/2/status. These messages are published with the "retain" flag set. (Note: To address a current issue in Home Assistant that may result in MQTT platforms not showing the correct garage door status (open/closed) after a HASS restart, I recommend creating an automation in Home Assistant that publishes the STATE payload for each door on HASS start. An example is provided in the Configuring Home Assistant section of this documentation.)

When the state of a garage door changes (either because GarHAge has triggered the door to open or close, or because the door has been opened or closed via a remote, pushbutton switch, or manually), GarHAge publishes the status (open or closed) of the relevant garage door to garage/door/1/status or garage/door/2/status. These messages are published with the "retain" flag set.

GarHAge also publishes a "birth" message on connection to your MQTT broker, and a "last-will-and-testament" message on disconnection from the broker, so that your home automation software can respond appropriately to GarHAge being online or offline.

Hardware

Bill of Materials

Building GarHAge to control two garage door openers requires:

| No. | Qty | Part | Link | Approx Price | | --- | --- | ---- | ---- | ------------ | | 1. | 1 | ESP8266-based microcontroller (e.g. NodeMCU) | Link | $ 7.00 | | 2. | 1 | Dual-relay module | Link | $ 4.00 | | 3. | 2 | Reed/Magnetic door switches | Link | $ 12.00 | | 4. | 1 | 5v MicroUSB power supply | Link | $ 6.00 | | 5. | 1 | Mini solderless breadboard (170 tie-point) | Link | $ 4.00 | | 6. | | Bell/low voltage two-conductor wire | | | | 7. | | Male-to-female breadboard jumper wires | | | | 8. | | Project box or case | | |

Approximate total cost for major components: $ 33.00, even less if you don't mind a long lead time and source your components from AliExpress/BangGood.

Note: If you are building GarHAge to control only one garage door opener, you will only require a single-relay module, and a single reed switch.

Detailed Bill of Materials

1. ESP8266-based microcontroller

I recommend the NodeMCU as GarHAge was developed and is tested on it. Its advantages are:

• it comes with header pins already soldered so that it can plug directly into a mini solderless breadboard;
• its VIN (or VU on the LoLin variant) port can power the 5v relay module;
• it can be powered and programmed via MicroUSB;
• it has Reset and Flash buttons, making programming easy.

Accordingly, this guide is written with the NodeMCU in mind.

But, Garhage should also work with the Adafruit HUZZAH, Wemos D1, or similar, though you may need to adjust the GPIO ports used by the sketch to match the ESP8266 ports that your microcontroller makes available.

2. Dual 5v relay module

A dual 5v relay module (as opposed to individual 5v relays) makes setup easy: just plug jumper wires from the module's VCC, CH1, CH2, and GND pins to the NodeMCU. These relay modules generally also include LEDs to ease troubleshooting.

Most importantly, because the relay module is powered by 5v, its inputs can be triggered by the NodeMCU's GPIOs.

GarHAge will work with relay modules that are active-high or active-low; if using an active-low relay, be sure to set the relevant configuration parameter in config.h, described below, and test thoroughly to be sure that your garage door opener(s) are not inadvertently triggered after a momentary power-loss.

3. Reed/magnetic door switches

GarHAge will work with both normally-open and normally-closed reed switches; if using a normally-closed switch, be sure to set the relevant configuration parameter in config.h, described below, to match the type of switch in use. Many switches with screw terminals are available, making placement and wiring easy.

4. 5v MicroUSB power supply

Power your NodeMCU via the same type of power supply used to charge Android phones or power a RaspberryPi. Powering the NodeMCU via MicroUSB is important since the relay module can then be powered via the NodeMCU VIN (or VU on the LoLin variant) port.

5. Mini solderless breadboard (170 tie-point)

The NodeMCU mounts to this breadboard nicely, leaving one female port next to each NodeMCU port and making it easy to use male-to-female jumper wires to make connections from the NodeMCU to the relay module. The bell wire attached to the reed switches will also plug into the breadboard ports, making for a clean and solderless installation. Finally, these mini breadboards often also have an adhesive backing, making mounting in your project box easy.

6. - 8. Miscellaneous parts

To install GarHAge, you will also require:

• Enough bell/low voltage two-conductor wire to make connections from each reed/magnetic switch at your garage doors to where GarHAge is mounted and to make connections from GarHAge to each garage door opener.
• Male-to-female breadboard jumper wires to make connections from the NodeMCU to the dual-relay module (4 jumper wires required).
• a project box to hold both the NodeMCU and dual-relay module.

Building GarHAge

1. Attach your NodeMCU to the middle of the mini solderless breadboard, leaving one fema