A standalone ESPHome solution for Maxum JDHC commercial garage door openers using a D1 Mini (ESP8266) and a cheap 3- or 4-channel relay board. This replaces ratgdo, which has known issues with Maxum openers (door opening on power cycle, unreliable close commands).
Tested and running on two Maxum doors for several months.
- Full open / close / stop control from Home Assistant
- Real-time door state via physical limit switches (AUXREL boards)
Door Moving,Door Opening,Door Closingbinary sensors for automations- External operation detection - wall panel / remote operations update HA immediately (shows partial open with both up/down controls)
- Position tracking (time-interpolated with endstop correction)
- WiFi fallback AP + captive portal for recovery if WiFi credentials change
- Correct mid-travel state on boot (shows partial open, not stale closed/open)
| Component | Notes |
|---|---|
| D1 Mini (ESP8266) | Any ESP8266 dev board works. D1 Mini is compact and cheap. |
| 3- or 4-channel relay board | 5V coil, active-low input. The common cheapo boards on Amazon/AliExpress work fine. Only 3 relays are used (open, close, stop). |
| Maxum AUXREL boards (x2) | These are the auxiliary relay option boards that plug into the Maxum's control board. They provide dry-contact limit switch signals. Part numbers vary by Maxum model - check your manual. |
| 24V-to-5V buck converter | To power the D1 Mini and relay board from the Maxum's 24V supply (or use USB power). |
| Wire | 18-22 AWG for relay/limit connections. |
+----------------------------------+
| MAXUM CONTROL BOARD |
| |
| OPEN -------+ |
| CLOSE ------+ Low-voltage |
| STOP -------+ command inputs |
| COM --------+ (dry contact) |
| |
| AUXREL 1 slot <- plug in board |
| AUXREL 2 slot <- plug in board |
+----------------------------------+
| |
+-----------------+ +------------------+
| |
+--------+--------+ +---------+--------+
| AUXREL 1 | | AUXREL 2 |
| (Open Limit) | | (Closed Limit) |
| | | |
| COM -+ NC -+ | | COM -+ NO -+ |
+-------+------+--+ +-------+------+---+
| | | |
| +--> D7 (open limit input) | +--> D6 (closed limit input)
+---------> GND on D1 Mini +--------> GND on D1 Mini
+----------------------------------------------+
| D1 MINI (ESP8266) |
| |
| D1 --> Relay 1 IN (OPEN) |
| D2 --> Relay 2 IN (CLOSE) |
| D5 --> Relay 3 IN (STOP) |
| D6 <-- AUXREL 2 (closed limit) |
| D7 <-- AUXREL 1 (open limit) |
| GND -- AUXREL COMs + Relay GND |
| 5V --- Relay VCC + Buck converter |
+----------------------------------------------+
Relay outputs (NO contacts) -> Maxum command terminals:
Relay 1 NO --> OPEN on Maxum
Relay 2 NO --> CLOSE on Maxum
Relay 3 NO --> STOP on Maxum
Relay COMs --> COM on Maxum
Refer to your Maxum manual (page 57+ in newer manuals) for the AUXREL DIP switch settings:
| Board | DIP Switches | Behavior | Wiring |
|---|---|---|---|
| AUXREL 1 | OFF ON OFF | Energizes at open limit | Use NC (normally closed) contact - ON = door fully open |
| AUXREL 2 | OFF OFF ON | Energizes when not at close limit | Use NO (normally open) contact - ON = door fully closed |
The key insight: AUXREL 2's "energizes when not at close limit" with a NO contact and INPUT_PULLUP means: when the door IS at the close limit, the relay is de-energized, the NO contact is open, and the pullup holds the pin HIGH (sensor ON). When the door is NOT at the close limit, the relay energizes, the NO contact closes to GND, and the pin reads LOW (sensor OFF).
Pin inversion note: Whether you need inverted: true on the limit switch GPIO pins depends on your AUXREL wiring (NO vs NC contacts) and DIP switch config. With the wiring described above, no inversion is needed. If your limit reads backwards (shows closed when open), add inverted: true under the pin config.
| Pin | Direction | Function |
|---|---|---|
| D1 | Output | OPEN relay (active low) |
| D2 | Output | CLOSE relay (active low) |
| D5 | Output | STOP relay (active low) |
| D6 | Input (pullup) | Closed limit switch (from AUXREL 2) |
| D7 | Input (pullup) | Open limit switch (from AUXREL 1) |
- HA sends open/close/stop command
- ESPHome pulses the corresponding relay for 200ms
- The
cover: endstopplatform starts time-based position tracking - When the physical limit switch triggers, position snaps to 0% or 100%
- Door starts moving from wall panel or remote
- The limit switch releases (e.g., closed limit goes OFF)
- ESPHome detects the cover was idle when the limit released - this means the movement was external
- Cover position is set to 50% (partial open) and stays idle - HA shows the door as "open" with both up/down controls available
- If the door reaches the opposite limit, position snaps to 0% or 100% as normal
- If the door stops mid-travel (wall panel stop), it stays at 50% showing "Stopped Mid-Travel"
Why idle instead of opening/closing? The previous approach set the cover to OPENING/CLOSING on external limit release, which started the endstop platform's timing engine. This caused incorrect position interpolation since we don't know when external movement will stop. Keeping IDLE with a 50% position gives HA the correct controls without the timing engine drifting to a wrong position.
On boot, ESPHome reads the physical limit switches and snaps the cover to the correct state:
- Closed limit active - position 0% (closed)
- Open limit active - position 100% (open)
- Neither limit active - position 50% (partial open, "Stopped Mid-Travel")
This ensures the door always shows the correct state after a reboot or power cycle, even if the door was manually moved while the ESP was offline. No errant door movement - the relay outputs use restore_mode: ALWAYS_OFF and the GPIO pins are held via inverted: true (active-low relays stay de-energized on boot).
- Position accuracy during external operations: For wall panel/remote operations, the position shows as 50% (partial) until a limit switch is reached, rather than smoothly interpolating. The final position (0% or 100%) is always accurate once a limit is hit.
- Mid-travel stop for external ops: If someone opens via wall panel then stops mid-travel, HA correctly shows "Stopped Mid-Travel" at 50%. The exact position is unknown but both open/close controls are available.
- No obstruction sensor: The Maxum's obstruction sensor circuit isn't tapped. It could potentially be wired through the ESP (like ratgdo does) but I haven't tested this to avoid introducing a failure point in a safety circuit.
- Copy
maxum-esphome-garage-door.yamlto your ESPHome config directory - Create or update your
secrets.yamlwithapi_key,ota_password,wifi_ssid,wifi_password,fallback_ap_password - Update the
substitutionsblock with your door's name and measured travel times - Flash via USB the first time, then OTA for updates
- The device will appear in Home Assistant's ESPHome integration automatically
For multiple Maxum doors, copy the YAML and change only the substitutions block (name, friendly_name, travel times). Each door gets its own D1 Mini + relay board + AUXREL pair. The GPIO pin assignments stay the same.