Build Your First ESPHome Device: Complete Beginner Walkthrough

1. What is ESPHome and Why Use It

ESPHome is a system that turns ESP8266 and ESP32 microcontrollers into smart home sensors and switches — configured entirely through YAML, with no programming knowledge required. You write a config file describing what your device does (read a temperature sensor, toggle a relay, blink an LED), and ESPHome compiles and flashes the firmware automatically.

The killer feature is native Home Assistant integration. Once your ESPHome device is on your Wi-Fi network, HA detects it automatically and imports all its sensors and switches as entities — no MQTT setup, no manual configuration. Everything stays local, so there's no cloud dependency or subscription fee.

Compared to flashing Tasmota or writing Arduino code, ESPHome is dramatically simpler. You describe what you want, not how to do it. It handles all the firmware details for you.

2. Installing the ESPHome Add-on in Home Assistant

If you're running Home Assistant OS or Supervised, installing ESPHome takes about two minutes:

1. In HA, go to Settings → Add-ons → Add-on Store
2. Search for ESPHome
3. Click it, then click Install
4. Once installed, enable Show in sidebar and click Start
5. Open the ESPHome dashboard from the sidebar

3. Creating Your First Device Config

In the ESPHome dashboard, click + New Device. Give it a name like my-sensor and choose ESP32 as the device type. ESPHome will generate a base config — but you'll replace it with the full config below.

Click Edit on your new device and paste this complete configuration:

esphome:
  name: my-sensor
  friendly_name: My Sensor

esp32:
  board: esp32dev
  framework:
    type: arduino

# Enable logging
logger:

# Enable Home Assistant API
api:
  encryption:
    key: "your-encryption-key-here"

ota:
  - platform: esphome
    password: "your-ota-password-here"

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

  # Enable fallback hotspot in case Wi-Fi fails
  ap:
    ssid: "My-Sensor Fallback"
    password: "fallback-password"

sensor:
  - platform: dht
    pin: GPIO4
    temperature:
      name: "Room Temperature"
    humidity:
      name: "Room Humidity"
    model: DHT22
    update_interval: 60s

Replace your-encryption-key-here with a random 32-character base64 string (ESPHome can generate one for you — click the key icon). Replace your-ota-password-here with any password you choose.

Setting up secrets

Notice that wifi_ssid and wifi_password use !secret. This keeps your credentials out of the device config. In ESPHome, click the Secrets button (or edit secrets.yaml in your ESPHome config folder) and add:

wifi_ssid: "YourWiFiName"
wifi_password: "YourWiFiPassword"

Wiring the DHT22

If you have a 3-pin DHT22 module (with the resistor already on the PCB): connect VCC → 3.3V, GND → GND, and DATA → GPIO4. That's the pin referenced in the YAML above. If you have a raw 4-pin DHT22 IC, you'll also need a 10kΩ pull-up resistor between DATA and VCC.

4. Flashing via Web Browser (ESPHome Web Flasher)

For the very first flash, you need a physical USB connection — over-the-air (OTA) updates only work after the device is already running ESPHome.

1. Connect your ESP32 to your computer via USB
2. In the ESPHome dashboard, click the three-dot menu on your device → Install
3. Choose Plug into this computer
4. ESPHome will compile the firmware (takes 1–3 minutes)
5. A browser dialog will ask you to select a serial port — choose the one that appears when your ESP32 is plugged in (usually COM3 on Windows or /dev/ttyUSB0 on Linux)
6. Click Connect and then Install

After flashing completes, your ESP32 will reboot and connect to your Wi-Fi. Watch the ESPHome logs — you should see Connected to WiFi within 30 seconds.

5. Adding to Home Assistant

Once your ESPHome device is online, Home Assistant auto-discovers it. You'll see a notification in HA under Settings → Devices & Services → Integrations showing a new ESPHome device. Click Configure and enter the encryption key you set in the YAML. That's it.

After adoption, navigate to the device page and you'll see two entities: Room Temperature (°C or °F) and Room Humidity (%). These update every 60 seconds as specified in your config. Add them to a dashboard card to start monitoring.

6. Expanding: Adding a Relay Output

Once your sensor is working, adding a relay output is just a few more lines of YAML. Many ESP32 dev boards have a built-in LED on GPIO2 you can test with, or wire a relay module to any GPIO pin.

Add this block to your existing config (below the sensor: section):

switch:
  - platform: gpio
    pin: GPIO26
    name: "Relay Output"
    id: relay_1
    restore_mode: RESTORE_DEFAULT_OFF

output:
  - platform: gpio
    pin: GPIO2
    id: onboard_led

light:
  - platform: binary
    name: "Onboard LED"
    output: onboard_led

After saving and clicking Install (this time it'll flash OTA wirelessly — no USB needed), a new Relay Output switch entity appears in HA. You can toggle it from the dashboard or use it in automations.

Wire your relay module: connect the relay's IN pin to GPIO26, VCC to the 5V pin on the ESP32, and GND to GND. The relay's NO/COM/NC terminals connect to whatever you want to control (a lamp, a water pump, etc.).

7. Troubleshooting

Device not appearing for adoption in HA

Check that your ESP32 and HA are on the same subnet. mDNS discovery (used by ESPHome) doesn't cross router boundaries. If you're on a VLAN setup, either move the ESP32 to the same VLAN as HA or enable mDNS repeating on your router.

DHT22 readings show "unavailable" or NaN

This usually means a wiring issue. Double-check that DATA is connected to GPIO4 (not GPIO5 or another pin). If you're using a raw DHT22 chip (not a module), ensure you have the 10kΩ pull-up resistor. Also try increasing update_interval to 30s minimum — DHT22 can't be polled faster than every 2 seconds, and ESPHome's default is 60s, but some faulty sensors need longer gaps.

OTA updates fail

If OTA flashing times out, the device may have lost Wi-Fi. Use the fallback hotspot: look for the "My-Sensor Fallback" Wi-Fi network on your phone, connect to it, and navigate to 192.168.4.1 to see the device's status and re-configure Wi-Fi.

Compilation errors

YAML is whitespace-sensitive. Use the ESPHome validator (the checkmark button) before flashing. Most errors are caused by incorrect indentation — use spaces, never tabs.

8. FAQ

SmartWired participates in the Amazon Associates Programme. We may earn a commission from qualifying purchases at no extra cost to you.