ESPHome Beginner Guide: Build Local Smart Devices with YAML

What ESPHome Is

ESPHome is a framework that compiles YAML configuration files into C++ firmware for ESP microcontrollers. Instead of writing code, you describe what hardware is connected and what it should do — ESPHome handles the rest.

Once flashed, an ESPHome device connects to your Wi-Fi, exposes its sensors and controls via the ESPHome API (or optionally MQTT), and auto-discovers itself in Home Assistant. Updates are wireless — you never need to plug the USB cable in again after the first flash.

ESPHome is ideal for:

• Temperature, humidity, CO2, and motion sensors
• Relay-controlled switches and lights
• Garage door controllers
• LED strip controllers (WLED alternative)
• Custom presence detection (mmWave radar sensors)

Installing the ESPHome Add-on

1. Go to Settings → Add-ons → Add-on Store
2. Search for ESPHome and click Install
3. Enable Start on boot and Show in sidebar
4. Click Start, then Open Web UI

The ESPHome dashboard shows all your configured devices. Click New Device to create your first one.

First YAML Config: DHT22 Temperature Sensor

Connect your DHT22 sensor to the ESP32: VCC → 3.3V, GND → GND, DATA → GPIO4 (with a 10kΩ pull-up resistor to 3.3V, or use GPIO's internal pull-up).

Here's the complete, working YAML config for an ESP32 with a DHT22 sensor:

esphome:
  name: bedroom-sensor
  friendly_name: Bedroom Sensor

esp32:
  board: esp32dev
  framework:
    type: arduino

# Enable logging
logger:

# Enable Home Assistant API
api:
  encryption:
    key: !secret esphome_api_key

ota:
  - platform: esphome
    password: !secret ota_password

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Fallback hotspot if WiFi fails
  ap:
    ssid: "Bedroom-Sensor Fallback"
    password: "fallback123"

captive_portal:

sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    temperature:
      name: "Bedroom Temperature"
      unit_of_measurement: "°C"
      accuracy_decimals: 1
    humidity:
      name: "Bedroom Humidity"
      unit_of_measurement: "%"
      accuracy_decimals: 1
    update_interval: 60s

The !secret references load from a secrets.yaml file in your ESPHome config directory. Create it with:

wifi_ssid: "YourNetworkName"
wifi_password: "YourWiFiPassword"
esphome_api_key: "your_32_char_base64_key_here"
ota_password: "your_ota_password"

Flashing Your Device

The first flash must be done via USB. After that, all updates are wireless (OTA).

1. Click your device in the ESPHome dashboard
2. Click Install → Plug into this computer
3. Your browser opens the Web Serial flasher — select your ESP32's COM/ttyUSB port
4. Click Connect and wait for the firmware to compile and flash (~2-3 minutes)
5. Watch the logs — you should see "Connected to WiFi" and "API connected"

Adding to Home Assistant

Once your device connects to Wi-Fi, Home Assistant discovers it automatically (within ~30 seconds):

1. A notification appears: "ESPHome node discovered"
2. Go to Settings → Integrations → ESPHome
3. Click Configure on your new device
4. Enter the API encryption key from your secrets.yaml
5. Click Submit — the device and its sensors appear in HA

Your temperature and humidity sensors now appear as HA entities and update every 60 seconds.

Adding a Relay Output

To control a relay (for switching lights, fans, or any AC device), add this to your YAML config:

switch:
  - platform: gpio
    pin: GPIO26
    name: "Bedroom Fan"
    id: bedroom_fan
    restore_mode: RESTORE_DEFAULT_OFF
    icon: "mdi:fan"

binary_sensor:
  - platform: gpio
    pin:
      number: GPIO0
      mode:
        input: true
        pullup: true
      inverted: true
    name: "Bedroom Fan Button"
    on_press:
      then:
        - switch.toggle: bedroom_fan

This creates a switch entity in HA for the relay, plus a physical button on GPIO0 that toggles it locally — even without internet. Connect a 5V relay module's IN pin to GPIO26, COM to your load's live wire, and NO (normally open) to complete the circuit.

Troubleshooting

• Entities don’t appear in Home Assistant: Confirm the integration is loaded correctly and double-check that the device is supported by the platform you chose.
• Commands feel delayed: This is usually caused by cloud polling, weak Wi-Fi, or a slow Zigbee mesh rather than Home Assistant itself.
• Things work in the vendor app but not in HA: Re-check credentials, local API permissions, and whether the device is using the correct network path.
• Automations misfire: Open the automation trace in Home Assistant and verify the exact entity IDs and state changes being used.

FAQ

SmartWired uses affiliate links. If you buy through our links, we may earn a commission at no extra cost to you. See our Affiliate Disclosure.