Garage door opener on an ESP32-C3
A relay that presses the opener’s wall button for half a second and two reed switches that say closed, opening, open, closing or stopped, from a button or the Web tab. The whole build, an ESP32-C3 and 5 more parts, runs here in your browser on the firmware below; open it in the editor to change the wiring or the code and run it again.
Teaching? Assign it to your class in one click.
Intermediate About 30 minutes to build and run. Runs in your browser. Free, and no account needed.
The parts retail for about $15.50. On Mokxi they're free.
What you'll learn
- Switching a low-voltage wall button with a relay
- Reading a reed switch with
INPUT_PULLUP - Tracking a door's state from two sensors
- Serving JSON from an ESP32 web server
- Making a relay boot off and never stay on
- Difficulty: Intermediate
- Time: About 30 minutes
- Board: ESP32-C3-DevKitM-1
- Parts: 7
How it works
The relay on pin 18 is wired across the opener's wall button. When it closes for half a second, it does exactly what a finger press would do. The opener still moves the door and keeps its own safety features.
Two reed switches tell the sketch where the door really is. The one on pin 3 closes when the door is down, and the one on pin 2 when it is fully up. Neither one means the door is between. The sketch reports closed, opening, open, closing or stopped.
You can press the door from the local button on pin 9 or from the network. The sketch serves its state as JSON at /state and presses the button at /toggle. It prints what it would publish instead of using MQTT, since Mokxi has no broker.
Parts list
7 parts, plus the jumper wires. They retail for about $15.50; on Mokxi they're free.
- 1 × ESP32-C3-DevKitM-1In Handheld Console Kit, Desk Buddy Kit, ESP32-C3 Starter Kit.
- 1 × Full-size breadboard
- 2 × Reed switchIn Escape Box Kit.
- 2 × PushbuttonIn Starter Kit, Christmas Lights Kit, Logic Lab Kit.
- 1 × Relay moduleIn Halloween Prop Kit, Water Level and Pump Kit.
Wiring table
Every connection, pin by pin, read from the circuit itself. Each row joins the pin on the left to the pin on the right, by a jumper wire or a breadboard strip.
| Part and pin | Connects to |
|---|---|
| Reed switch (1) pin 2 | ESP32-C3-DevKitM-1 pin GND |
| Reed switch (2) pin 2 | ESP32-C3-DevKitM-1 pin GND |
| Reed switch (2) pin 1 | ESP32-C3-DevKitM-1 pin 2 |
| Reed switch (1) pin 1 | ESP32-C3-DevKitM-1 pin 3 |
| Relay module pin VCC | ESP32-C3-DevKitM-1 pin 5V |
| Pushbutton (1) pin 2a | ESP32-C3-DevKitM-1 pin GND |
| Pushbutton (1) pin 2b | ESP32-C3-DevKitM-1 pin GND |
| Relay module pin GND | ESP32-C3-DevKitM-1 pin GND |
| Pushbutton (1) pin 1a | ESP32-C3-DevKitM-1 pin 9 |
| Pushbutton (1) pin 1b | ESP32-C3-DevKitM-1 pin 9 |
| Relay module pin IN | ESP32-C3-DevKitM-1 pin 18 |
| Pushbutton (2) pin 2a | Relay module pin NO |
| Pushbutton (2) pin 2b | Relay module pin NO |
| Pushbutton (2) pin 1a | Relay module pin COM |
| Pushbutton (2) pin 1b | Relay module pin COM |
The code
The firmware exactly as the editor opens it. Change a line there and press Run: it compiles in the browser.
// Home Assistant garage door: a relay that presses the button, two reed switches that tell the truth.
//
// relay on GPIO 18 wired across the opener's wall-button terminals
// reed, closed, GPIO 3 the magnet on the door meets it when the door is down
// reed, open, GPIO 2 and this one when the door is all the way up
// button on GPIO 9 a local button (the BOOT pin), so the door works offline
//
// The opener already knows how to move the door, stop at its limits and back
// off when it hits something. This device never replaces any of that. It does
// what the wall button does, a short press, and it reads two reed switches so
// it knows where the door really is instead of guessing from the last command.
//
// SAFETY, for the real thing: connect only to the opener's low-voltage wall
// button terminals, never to mains or the motor. The relay must boot OFF and
// never stay on. Do not defeat the photo-eyes or the opener's obstruction
// reversal, and only trigger the door remotely when you can see it or the
// opener's own safety features are working. Test the reversal after installing.
//
// The door is not simulated: drag the magnet on each reed switch to move it.
// Mokxi has no MQTT broker, so the sketch prints what it would publish and serves
// its state as JSON at /state. Send /toggle from the Web tab to press the button.
#include <WebServer.h>
#include <WiFi.h>
const int RELAY_PIN = 18;
const int CLOSED_REED_PIN = 3;
const int OPEN_REED_PIN = 2;
const int BUTTON_PIN = 9;
const unsigned long PRESS_MS = 500; // how long the relay holds the button
const unsigned long LOCKOUT_MS = 1500; // no second press straight after one
const unsigned long TRAVEL_MS = 15000; // longer than a full run means something is wrong
enum DoorState { CLOSED, OPENING, OPEN, CLOSING, STOPPED };
const char *const STATE_NAMES[] = {"closed", "opening", "open", "closing", "stopped"};
WebServer server(80);
DoorState state = STOPPED;
DoorState lastSent = OPEN;
bool travelWarned = false;
unsigned long movedAt = 0;
unsigned long pressedAt = 0;
bool pressing = false;
bool buttonWas = false;
void publish(const char *topic, const char *payload) {
Serial.print("publish home/garage/");
Serial.print(topic);
Serial.print(' ');
Serial.println(payload);
}
// A reed switch with a pull-up reads LOW when the magnet is close.
bool atClosed() { return digitalRead(CLOSED_REED_PIN) == LOW; }
bool atOpen() { return digitalRead(OPEN_REED_PIN) == LOW; }
// One press of the wall button: the relay closes for PRESS_MS, then lets go.
void pressButton(const char *why) {
unsigned long now = millis();
if (pressing || now - pressedAt < LOCKOUT_MS) {
Serial.println("press ignored: too soon after the last one");
return;
}
pressing = true;
pressedAt = now;
digitalWrite(RELAY_PIN, HIGH);
Serial.print("relay pressed (");
Serial.print(why);
Serial.println(")");
// What the opener will do next, judged from where the door is now.
if (state == CLOSED || state == STOPPED) state = atOpen() ? CLOSING : OPENING;
else if (state == OPEN) state = CLOSING;
else state = STOPPED; // a press mid-travel stops most openers
movedAt = now;
travelWarned = false;
}
void updateState() {
if (atClosed()) state = CLOSED;
else if (atOpen()) state = OPEN;
else if (state == CLOSED) state = OPENING; // it left the closed switch on its own
else if (state == OPEN) state = CLOSING;
if ((state == OPENING || state == CLOSING) && !travelWarned &&
millis() - movedAt > TRAVEL_MS) {
travelWarned = true;
publish("problem", "ON");
Serial.println("the door has not reached a switch in time: check it");
}
if (state != lastSent) {
lastSent = state;
movedAt = millis();
publish("state", STATE_NAMES[state]);
}
}
void sendState() {
String json = "{\"state\":\"";
json += STATE_NAMES[state];
json += "\",\"closed_switch\":";
json += atClosed() ? "true" : "false";
json += ",\"open_switch\":";
json += atOpen() ? "true" : "false";
json += "}";
server.send(200, "application/json", json);
}
void handleToggle() {
pressButton("from the network");
sendState();
}
void setup() {
// The relay pin is written LOW before it becomes an output, so it boots off.
digitalWrite(RELAY_PIN, LOW);
pinMode(RELAY_PIN, OUTPUT);
pinMode(CLOSED_REED_PIN, INPUT_PULLUP);
pinMode(OPEN_REED_PIN, INPUT_PULLUP);
pinMode(BUTTON_PIN, INPUT_PULLUP);
Serial.begin(115200);
Serial.println("Garage door: simulated WiFi, no MQTT broker in Mokxi.");
WiFi.begin("Mokxi-Lab", "breadboard");
while (WiFi.status() != WL_CONNECTED) {
delay(250);
}
Serial.print("online at http://");
Serial.print(WiFi.localIP());
Serial.println("/state, press with /toggle");
server.on("/", sendState);
server.on("/state", sendState);
server.on("/toggle", handleToggle);
server.begin();
updateState();
}
void loop() {
server.handleClient();
unsigned long now = millis();
if (pressing && now - pressedAt >= PRESS_MS) {
pressing = false;
digitalWrite(RELAY_PIN, LOW);
}
bool button = digitalRead(BUTTON_PIN) == LOW;
if (button && !buttonWas) pressButton("local button");
buttonWas = button;
updateState();
delay(10);
}
Code walkthrough
The key functions of the sketch, and what each one does.
pressButton sketch.ino
Closes the relay for PRESS_MS (500 ms) and sets the state to what the opener will probably do next. It refuses a second press within LOCKOUT_MS (1500 ms). The loop lets go of the relay when the time is up, so it never stays on.
// One press of the wall button: the relay closes for PRESS_MS, then lets go.
void pressButton(const char *why) {
unsigned long now = millis();
if (pressing || now - pressedAt < LOCKOUT_MS) {
Serial.println("press ignored: too soon after the last one");
return;
}
pressing = true;
pressedAt = now;
digitalWrite(RELAY_PIN, HIGH);
Serial.print("relay pressed (");
Serial.print(why);
Serial.println(")");
// What the opener will do next, judged from where the door is now.
if (state == CLOSED || state == STOPPED) state = atOpen() ? CLOSING : OPENING;
else if (state == OPEN) state = CLOSING;
else state = STOPPED; // a press mid-travel stops most openers
movedAt = now;
travelWarned = false;
}updateState sketch.ino
Checks the reed switches each pass. Closed switch means CLOSED, open switch means OPEN. If the door leaves a switch, it becomes OPENING or CLOSING. It warns if the door takes longer than TRAVEL_MS, and publishes the state whenever it changes.
void updateState() {
if (atClosed()) state = CLOSED;
else if (atOpen()) state = OPEN;
else if (state == CLOSED) state = OPENING; // it left the closed switch on its own
else if (state == OPEN) state = CLOSING;
if ((state == OPENING || state == CLOSING) && !travelWarned &&
millis() - movedAt > TRAVEL_MS) {
travelWarned = true;
publish("problem", "ON");
Serial.println("the door has not reached a switch in time: check it");
}
if (state != lastSent) {
lastSent = state;
movedAt = millis();
publish("state", STATE_NAMES[state]);
}
}sendState sketch.ino
Builds a small JSON string with the state name and whether each reed switch is closed, then sends it as the web response. It is used for /, /state and after /toggle.
void sendState() {
String json = "{\"state\":\"";
json += STATE_NAMES[state];
json += "\",\"closed_switch\":";
json += atClosed() ? "true" : "false";
json += ",\"open_switch\":";
json += atOpen() ? "true" : "false";
json += "}";
server.send(200, "application/json", json);
}Troubleshooting
The usual mistakes with this circuit, and the fix for each.
- The door state never leaves stopped. This project
The state only settles when a reed switch triggers. Drag the magnet to the closed switch on pin 3 or the open switch on pin 2. - The reed switches seem backwards. This project
Each reed is wired between its pin and ground with a pull-up, so it reads LOW when the magnet is near. Check the pins inCLOSED_REED_PINandOPEN_REED_PIN. - A second press seems ignored. This project
That is the lockout. Wait 1.5 seconds between presses. - The input reads random values. Reed switch
A reed switch is just two contacts. Use INPUT_PULLUP and wire one side to the pin and the other to GND, so closed reads LOW. - It triggers several times or never closes. Reed switch
Contacts bounce, so debounce in code. The switch is most sensitive along its length, so move the magnet along the blades, not straight at the end. - The input reads random HIGH and LOW when the button is not pressed. Pushbutton
A floating pin picks up noise. Add a 10 k pull-down or pull-up resistor, or use INPUT_PULLUP and wire the button between the pin and GND. Then pressed reads LOW. - The button seems always pressed, or never changes. Pushbutton
A 4-leg tactile switch has legs joined in pairs. Place it across the breadboard center gap so the pairs sit on different rows. Wired along one side, the legs are already connected. - The relay does not click, or the board resets when it switches. Relay module
A relay coil needs more current than a pin can give. Use a module with a transistor driver, and power VCC from 5 V. Share ground between the module and the Arduino.
Change it and keep it
Open it in the editor, change the circuit or the code, and keep your version in a free account.