ESPHome WiFi: Secure Setup and Troubleshooting (2026)

Albert BarnosellEditor and publisher of Tecnoyfoto

Updated August 5, 2026 for ESPHome 2026.7.3.

ESPHome WiFi connects an ESP32 or ESP8266 to your network so it can communicate with Home Assistant, receive OTA updates, and resolve its hostname through mDNS. The minimum configuration takes only a few lines, but real-world reliability depends on how you handle credentials, coverage, power saving, access points, and IP addressing.

This guide starts with a secure baseline and explains when to use multiple networks, a manual IP, a fallback hotspot, 802.11k/v roaming, fast_connect, and diagnostic sensors. It also replaces old examples that exposed passwords or combined two incompatible wifi: sections.

Recommended ESPHome WiFi configuration

For most home installations, store the SSID and password in secrets.yaml. Since ESPHome 2026.6, WPA2 is the default minimum authentication mode on both ESP32 and ESP8266, while WPA3 networks are also accepted. You do not need to declare min_auth_mode to obtain this secure default.

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

Define those values in the ESPHome dashboard secrets file and never publish it. If a real key was already shared, removing it from YAML is not enough: change the network password and remove it from repository history.

# secrets.yaml — do not commit this file publicly
wifi_ssid: "YOUR_NETWORK_NAME"
wifi_password: "YOUR_LONG_NETWORK_PASSWORD"

Secrets prevent sensitive values from being repeated in every node. The official ESPHome security guide recommends WPA2 at minimum, WPA3 when the whole network supports it, strong passwords, and disabled WPS.

ESP32, ESP8266, and 2.4 GHz networks

Most ESP32 and ESP8266 boards used with ESPHome connect on 2.4 GHz. A router broadcasting one name for 2.4 and 5 GHz often works, but a dedicated 2.4 GHz IoT SSID can make troubleshooting easier when band steering or particular WiFi 6 settings cause unreliable association. Frequency is not a security setting: a 2.4 GHz network can and should use WPA2 or WPA3.

ESPHome requires a valid network interface and currently does not allow WiFi and Ethernet to be configured at the same time on one node. If you are still selecting hardware, read our ESP32 board and pinout guide.

Fallback AP and captive portal: useful, but protected

Fallback AP mode creates its own network when the device cannot join the router. With captive_portal, you can enter new credentials from a phone. The fallback hotspot starts after 90 seconds by default.

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "living-room-sensor-recovery"
    password: !secret fallback_ap_password

captive_portal:

Never leave this AP open. If the main network fails, anyone nearby could join the ESP and reach services exposed by the device. Use a long, unique password for each node, or omit the recovery AP from production installations that you can reflash over USB.

DHCP reservation or manual IP

A static IP is not mandatory. Reserving an address in the router’s DHCP server is usually the simplest approach: network settings remain centralized and address conflicts are less likely. A manual IP can slightly reduce connection time by skipping DHCP and can help when mDNS does not cross a VLAN, but you must supply the correct address, gateway, and subnet.

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  manual_ip:
    static_ip: 192.168.10.42
    gateway: 192.168.10.1
    subnet: 255.255.255.0
    dns1: 192.168.10.1

Make sure the address is outside the dynamic pool or reserved for that ESP. A wrong subnet, duplicate address, or gateway from another VLAN can make the node appear offline even though the firmware compiles successfully.

Changing an IP address or node name without losing OTA

During a migration, use_address temporarily tells ESPHome where to send the update using the old address. After the new firmware is installed and the new address works, remove the line. Leaving it in place makes later uploads continue targeting the old location.

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  use_address: 192.168.1.42  # Only for this migration

If wireless uploads rather than connectivity are failing, use our ESPHome OTA update and troubleshooting guide.

Connect ESPHome to multiple WiFi networks

For a primary and backup network, move credentials under networks:. Do not add another wifi: block or combine a top-level ssid with the list. ESPHome attempts to join the reachable network with the best signal; priority can influence that selection when needed.

wifi:
  networks:
    - ssid: !secret wifi_ssid_primary
      password: !secret wifi_password_primary
      priority: 10
    - ssid: !secret wifi_ssid_backup
      password: !secret wifi_password_backup
      priority: 0

A higher priority can make the node prefer a network even if its signal is slightly weaker. When replacing a router, keeping both networks temporarily is safer: update every node first, then retire the old SSID.

Automatic roaming since ESPHome 2026.1

ESPHome 2026.1 introduced post-connect roaming and enables it by default for visible networks. After joining, a node performs up to three checks at five-minute intervals and may switch to another access point with the same SSID when its signal is at least 10 dB better. This prevents devices from remaining attached to a weak AP after a router reboot or a simultaneous startup.

The handoff is not fully seamless: TCP connections, including the native API, may drop briefly during the switch. On ESP32 and a compatible network, you can enable 802.11k/v. ESPHome then disables its basic post-connect roaming automatically and lets the native mechanism handle AP selection.

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  enable_btm: true  # 802.11v, ESP32 only
  enable_rrm: true  # 802.11k, ESP32 only

Do not enable router fast-roaming options blindly. First confirm that your ESP32 variant, access-point firmware, and security mode are compatible. Keep the default basic roaming on ESP8266.

Hidden networks, fast_connect, and power saving

Hidden networks

Hiding an SSID does not provide meaningful security. If you still use one, set hidden: true inside the network entry. There is a significant trade-off in multi-AP homes: ESPHome cannot properly compare which access point offers the best signal for that hidden SSID.

wifi:
  networks:
    - ssid: !secret hidden_wifi_ssid
      password: !secret hidden_wifi_password
      hidden: true

fast_connect

fast_connect skips the initial scan and may reduce awake time for battery or deep-sleep sensors. It is off by default and often unsuitable for mesh networks because it can choose the first AP found instead of the best one. If the direct attempt fails, ESPHome scans normally.

power_save_mode

The default WiFi power-saving mode is LIGHT on ESP32 and NONE on ESP8266. HIGH saves more energy but may increase latency and disconnections. For a permanently powered node that loses its API connection despite good coverage, testing NONE is a reasonable diagnostic step—not a universal fix.

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

Measure signal, IP, channel, and access point

Publish diagnostic data before changing random settings. The wifi_signal sensor reports RSSI in dBm, while WiFi text sensors expose IP, SSID, BSSID, MAC, and scan results. About −50 dBm is excellent, roughly −67 dBm is generally usable, and below −75 dBm should prompt a review of placement, antenna, channel, and interference.

sensor:
  - platform: wifi_signal
    name: "WiFi Signal"
    update_interval: 60s

text_sensor:
  - platform: wifi_info
    ip_address:
      name: "IP Address"
    ssid:
      name: "Connected SSID"
    bssid:
      name: "Connected BSSID"
    mac_address:
      name: "WiFi MAC"

The BSSID identifies the specific access point. On a mesh network, it reveals whether a node joined the nearby AP or one across the building. The official WiFi component documentation lists all current options and limitations.

ESPHome WiFi troubleshooting

Dashboard says OFFLINE, but ping works: check mDNS, UDP port 5353, and VLAN boundaries. Try the IP address directly before altering firmware.
The node reboots every 15 minutes: reboot_timeout defaults to 15 minutes without WiFi. Find authentication, coverage, or DHCP errors first; setting it to 0s can hide the symptom and leave a stuck interface.
It joins a distant AP: inspect BSSID, avoid hidden SSIDs and fast_connect, and use default roaming or 802.11k/v on ESP32.
It fails after router security was tightened: confirm the IoT network offers WPA2/AES or WPA3. Do not downgrade to WPA/TKIP except as a temporary legacy-hardware test.
It compiles but never connects: validate the secret name, exact SSID, 2.4 GHz availability, subnet, and duplicate addresses.
The API drops with strong RSSI: inspect power supply, AP load, and power saving. Strong signal does not rule out packet loss or an unstable 5 V supply.

Use USB logs or the ESPHome dashboard before stacking options found in forum posts. Change one variable at a time and keep a known-good YAML backup.

Original video and later changes

The video below accompanied the original Spanish guide. Its discussion of secrets, IP addressing, and sensors remains useful, but it predates automatic roaming in 2026.1 and the shared WPA2 minimum in 2026.6. Use the updated code blocks in this article when building a configuration.

2:08 — Using secrets.
2:27 — Static IP.
4:45 — WiFi sensors.
6:32 — Multiple networks.
8:21 — Testing sensors.

A balanced final configuration

Begin with secrets and default settings. Add a protected fallback AP only if local recovery is genuinely useful; reserve an address in the router when you need a stable IP; measure RSSI and BSSID before adjusting radio or power-saving behavior. On multi-AP networks, roaming included since 2026.1 solves many cases without extra YAML.

The goal is not to collect every available option, but to keep the configuration small, secure, and observable. If you also expose a local interface, protect the ESPHome Web Server with current authentication and never expose the device directly to the internet.