Home Assistant ESPHome Device — Complete Guide

In this tutorial, you'll learn about Home Assistant ESPHome Device. We cover key concepts, practical examples, and best practices.

Hook

Your ESPHome-powered sensor was working for months. Suddenly it goes "Offline" in Home Assistant. The ESP device LED is on, Wi-Fi is connected, but Home Assistant cannot reach it. OTA updates also fail: "Error: Connection refused."

The Wrong Way

Re-flashing the ESP firmware via USB fixes the immediate problem but does not address why the device keeps going offline. You will need to re-flash every time it happens.

# BAD: Re-flashing every time
esphome run sensor.yaml --device /dev/ttyUSB0

Uploading firmware...
Device rebooted — comes back online
But goes offline again after 3 days

Re-flashing is a temporary fix, not a solution.

The Right Way

Check the ESP device logs and Home Assistant connectivity to identify the root cause.

# 1. Check ESP device logs via serial
esphome logs sensor.yaml --device /dev/ttyUSB0

[WARNING] WiFi: Connection lost! Reason: 5 (Auth fail)
[INFO] WiFi: Reconnecting...
[WARNING] WiFi: Connection lost! Reason: 201 (No AP found)

The device is losing Wi-Fi due to authentication failure or signal loss.

# 2. In sensor.yaml, improve Wi-Fi configuration:

wifi:
  ssid: "MyNetwork"
  password: "password"
  fast_connect: true  # For 2.4 GHz only networks
  power_save_mode: none  # Prevent power-saving disconnects
  reboot_timeout: 15min  # Reboot if Wi-Fi lost for 15 min
  output_power: 20dB  # Max power for better range

# 3. Set a static IP for the ESP device:

wifi:
  manual_ip:
    static_ip: 192.168.1.200
    gateway: 192.168.1.1
    subnet: 255.255.255.0
    dns1: 192.168.1.1

# 4. Increase API keepalive:

api:
  encryption:
    key: "your-encryption-key"
  reboot_timeout: 30min
  keepalive: 30s  # Default is 15s — increase for flaky networks

# 5. Upload the fix via serial
esphome run sensor.yaml --device /dev/ttyUSB0

Upload complete — device online
Wi-Fi: Connected (RSSI: -45 dBm)
API: Connected to Home Assistant

Prevention

• Set power_save_mode: none in ESPHome Wi-Fi config.
• Use static IPs to avoid DHCP issues.
• Place ESP devices within range of a good Wi-Fi access point.
• Enable api.encryption for secure communication.
• Set reboot_timeout to 15min in both Wi-Fi and API configs for auto-recovery.

Common Mistakes with assistant esphome

1. Non-exhaustive pattern matches that compile with warnings then crash at runtime
2. Misunderstanding that String is [Char] with poor performance for large text operations
3. Using foldl instead of foldl' causing stack overflow on large lists

These mistakes appear frequently in real-world HOME code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

DodaTech — ESPHome devices that stay online.