Control a relay over WiFi with ESPHome

ESPHome turns an ESP32 into a smart-home device using just a YAML file. It integrates directly with Home Assistant and supports over-the-air (OTA) firmware updates.

Parts

• ESP32 DevKit
• 1-channel relay module (3.3V-compatible or opto-isolated; many 5V modules still work with a 3.3V signal, but verify)
• Push button, 5V supply

Wiring

ESPHome configuration

esphome:
  name: living-room-light

esp32:
  board: esp32dev
  framework:
    type: esp-idf

logger:

api:
  encryption:
    key: !secret api_key

ota:
  - platform: esphome
    password: !secret ota_password

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:                       # fallback hotspot if WiFi is lost
    ssid: "Living-Room-Light"
    password: !secret ap_password

captive_portal:

switch:
  - platform: gpio
    id: relay1
    name: "Living room light"
    pin: GPIO26
    restore_mode: RESTORE_DEFAULT_OFF

binary_sensor:
  - platform: gpio
    pin:
      number: GPIO27
      mode: INPUT_PULLUP
      inverted: true
    name: "Light button"
    filters:
      - delayed_on: 50ms     # debounce
    on_press:
      - switch.toggle: relay1

Steps

1. Install ESPHome (the Home Assistant add-on, or pip install esphome).
2. Create a secrets.yaml with wifi_ssid, wifi_password, api_key, ota_password and ap_password. The api_key is a random 32-byte base64 string; the ESPHome dashboard can generate one for you.
3. Flash the first time over USB: esphome run living-room-light.yaml.
4. Later updates go over WiFi (OTA). Home Assistant will discover the device automatically.

Notes

• Avoid strapping pins (0, 2, 5, 12, 15) for the relay, because their state at boot can make the relay click. See GPIO pins to avoid.
• Some relay modules are active-low (LOW = on). If it's inverted, add inverted: true to the switch pin.
• Pick a suitable restore_mode: after a power cut, should the light come back off or keep its previous state?