ESPHome Devices on a UniFi Network: Wi-Fi, VLANs, Discovery

ESPHome turns a few dollars of microcontroller into a sensor, a relay or a Bluetooth proxy that Home Assistant treats as a native device. The firmware holds open a persistent connection from Home Assistant and pushes every state change the moment it happens.

That design is also why these devices expose a network's rough edges. After all, a phone that drops off Wi-Fi for a second reconnects without anyone noticing, whereas an ESP32 that drops off is a temperature graph with holes in it.

UniFi's defaults are tuned for compatibility and roaming, and Ubiquiti says so: its SSID article calls them optimized for maximum client compatibility and roaming performance, with band steering and BSS transition on. Its own IoT troubleshooting list turns most of those roaming and steering features off again.

Accordingly, this guide works through the SSID, the addresses, discovery across VLANs, the ports, the reliability settings on both sides, and the wired boards that skip Wi-Fi entirely. The IoT VLAN guide explains the segmentation and the zone policies this layout assumes, and the PoE radios guide covers the Zigbee and Thread coordinators that often share a shelf with these boards.

First, the radio.

Start with the band. ESPHome's ESP32 platform page lists 2.4 GHz-only Wi-Fi for the ESP32, S2, S3, C2, C3, C6 and C61, with Wi-Fi 6 on the C6 and C61, and only the ESP32-C5 adds 5 GHz. That matches Ubiquiti's advice to limit IoT devices to a 2.4 GHz network when they struggle.

A dedicated SSID follows from that. Ubiquiti's SSID article notes that setting an SSID to WPA2 Personal disables 6 GHz for that SSID. The settings an ESP radio needs would therefore cost the household network its fastest band if they shared a name.

Security is where the two vendors meet in the middle. Ubiquiti's troubleshooting article recommends WPA2 for IoT devices and calls WPA3 not recommended on 2.4 GHz, while ESPHome's Wi-Fi component accepts WPA2 and WPA3 by default and offers WPA3-only on the ESP32 alone.

Protected Management Frames are the awkward case. Ubiquiti's troubleshooting article recommends disabling PMF for some IoT clients and says it cannot be disabled on WPA2/WPA3 or WPA3 networks. Its settings reference adds that Disabled is only recommended on a separate WPA2 SSID for legacy devices, so that SSID is the only place the lever exists.

Then the roaming features, which Ubiquiti's IoT list switches off as a set:

• Band steering nudges 2.4 GHz clients to 5 GHz with BSS transition frames, which is pointless on a 2.4 GHz-only SSID, and the IoT list turns it off.
• BSS transition and fast roaming help phones move between access points. ESPHome supports 802.11k and 802.11v on the ESP32 only, and only when enable_btm and enable_rrm are set, so leave both off unless every device is an ESP32 configured for them.
• Minimum data rate control can block legacy or low-speed IoT devices, in Ubiquiti's words, and its airtime article warns that 802.11b-based devices may lose connectivity when it is raised.
• UAPSD and multicast enhancement are power-save and conversion features that Ubiquiti lists as Off for troubleshooting IoT connections.

Ubiquiti also offers a toggle named Enhanced IoT Connectivity, which its settings reference describes as specialized access point functions for legacy or low-power devices that struggle to stay connected. The troubleshooting article's own opening advice, to create a dedicated SSID and enable IoT under WiFi Optimization, is the one instruction there that turns something on. Ubiquiti does not say whether that is the same toggle.

Keep in mind that hidden SSIDs cost ESPHome its strongest-signal pick. The Wi-Fi component says a hidden network needs hidden: true and skips the scan that picks the strongest access point, and Ubiquiti's list leaves Hide WiFi Name off as well.

The ESP8266, lastly, has a known 802.11n quirk. ESPHome documents a compatibility issue with some routers and a workaround that pins the radio to 802.11g, which is worth remembering if an older board connects to everything except a UniFi access point.

ESPHome's own pages settle this. Its Wi-Fi documentation says a static address can dramatically improve connection times, and its FAQ lists a static address second, after fast connect, among the fixes for a node that keeps reconnecting.

The in-firmware route is a manual_ip block with the address, gateway and subnet. The device then never negotiates with DHCP, and the documentation adds that the OTA process automatically targets that address.

The UniFi route is a reservation. Ubiquiti's DNS records article walks it through: open the client under Client Devices and enable Fixed IP Address to set a DHCP reservation. The gateway then hands the same lease every time, which is the step the IoT VLAN guide uses for Home Assistant itself.

Either works, and the difference, of course, is which record holds the address. A reservation survives a rebuilt configuration file, while a manual_ip block survives a replaced gateway. The same article's Local DNS Record setting can give either one a hostname, which resolves only for clients that use the gateway as their DNS server.

Names matter as much as addresses. Home Assistant's ESPHome documentation requires every device to have a unique name, because that name drives mDNS announcements, reconnection after deep sleep, and DHCP discovery when mDNS is unavailable.

Duplicate names, it says, lead to connection issues and failed discovery. What's more, the same page describes a name conflict resolution flow for replacing a dead board with a new one of the same name, which depends on the old one being offline.

In addition, ESPHome appends .local to the hostname for uploads by default, and a use_address option overrides the address the tools connect to when the hostname will not resolve. That option is the escape hatch for the discovery problems in the next section.

Home Assistant's ESPHome integration declares three discovery methods in its manifest: Zeroconf on _esphomelib._tcp.local., DHCP discovery of devices it has already registered, and an MQTT topic. The MQTT one only concerns nodes running the MQTT component instead of the native API. The first finds new devices, and the second recognizes a device Home Assistant already knows when it asks for an address.

The first two are link-local. The IoT VLAN guide explains why mDNS stops at a VLAN boundary and why Ubiquiti built a relay, and the relay's published list is the part that matters here.

Ubiquiti's switch settings reference lists the service types it says Auto mode commonly includes. It carries Apple, Google, Sonos, Roku, Bose, Philips Hue, Aqara, printers, scanners, file sharing and the Matter Network types. There is no entry for ESPHome, nor, as the IoT VLAN guide found, for Home Assistant's own announcement.

Three layouts handle that, in order of how little they ask of the gateway:

• Home Assistant on the IoT VLAN. Announcements arrive directly, nothing is relayed, and the gateway's relay limit of two networks on an Express or UXG Lite is never spent. This is the layout the VLAN guide recommends.
• Custom mode with the type added. Ubiquiti's mDNS proxy article says new services can be added in the form _service._protocol.local, so _esphomelib._tcp.local between the IoT and trusted networks is a one-line change.
• All mode. The switch reference says all mDNS traffic is forwarded by default, which works and relays everything else too, at the airtime cost the broadcast article describes.

Without any of those, ESPHome's FAQ spells out the fallback. Disable mDNS only with a static address in place, add the device to Home Assistant manually by that address, and expect the hostname to stop resolving unless regular DNS serves it.

The ESPHome Device Builder, in fact, behaves slightly better: its FAQ says status detection uses mDNS where available and a periodic ping sweep for every node regardless. A device whose address resolves another way, through use_address or a hostname regular DNS serves, therefore still shows online across a VLAN. Running the builder in Docker needs host networking for the same reason.

Be aware that two SSID settings also interfere, and both are on Ubiquiti's IoT list as Off. Multicast and Broadcast Control restricts multicast to approved clients and blocks cross-access-point discovery, while Client Device Isolation stops clients on one access point from reaching each other.

The native API is the only connection Home Assistant needs. ESPHome's API documentation gives it port 6053 by default and notes that only the ESPHome tools, Home Assistant and ioBroker speak it. Home Assistant's own page describes the persistent connection it maintains and reconnects.

Encrypt it. The API accepts a 32-byte base64 key, and Home Assistant asks for that key when a device is added. ESPHome's OTA platform reuses the same key to protect firmware uploads, the form its documentation recommends over the older password.

The OTA port is the second one to know. ESPHome lists 3232 for the ESP32, 8266 for the ESP8266, 2040 for the RP2040 and 8892 for Beken chips. The upload comes from wherever the Device Builder runs, which is Home Assistant itself when the builder is installed as its app.

Nothing here faces the internet. The remote access guide handles reaching Home Assistant from outside, and the devices themselves are only ever reached through it.

With the layout above, the firewall has nothing to do. Home Assistant and the devices share a VLAN, and the zone firewall guide explains that traffic inside one zone passes without a policy.

Split them across VLANs and two jobs appear. One is a policy letting the Home Assistant zone reach the IoT zone on the API and OTA ports. The other is the relay or manual addresses from the previous section, for discovery.

Moreover, a laptop that opens a device's web server needs the trusted-to-IoT allowance the VLAN guide already writes.

Remember what ESPHome does when a connection is blocked. The Wi-Fi component reboots the device after 15 minutes without a Wi-Fi connection, and the API component reboots it after 15 minutes without a client. A firewall rule that silently drops port 6053 therefore shows up as a device that restarts every quarter hour.

Finally, the fallback hotspot, which exists only when the configuration carries an ap: block. ESPHome's captive portal then starts an access point after a minute of failed connection attempts, reachable at 192.168.4.1, where the Wi-Fi settings can be changed and new firmware uploaded. The Wi-Fi component adds that credentials saved there survive later OTA updates as long as none are set in the configuration file.

ESPHome's FAQ says the reconnect problem is not fully understood. It suggests fast_connect, a static address and power_save_mode: light, then warns that the power-save change may make things worse in some situations.

The power-save default differs by chip. ESPHome's Wi-Fi component uses no power saving on the ESP8266 and light saving on the ESP32, and it says the highest mode brings frequent disconnections.

Two of the FAQ's causes are self-inflicted. Logging at the most verbose level can interfere with networking on single-core chips. Too many simultaneous clients on the native API, such as Home Assistant plus the Device Builder's log viewer, can produce the same reconnects.

Reducing the DTIM interval on the access point, the FAQ adds, may improve reliability for devices in power-save mode. Ubiquiti's settings reference agrees from the other side, saying a raised DTIM period may hurt battery life and connectivity for IoT devices. Its defaults are 1 on 2.4 GHz and 3 on 5 and 6 GHz.

Minimum RSSI is the setting that looks like a fix and behaves like a trap. Ubiquiti describes it as a hard kick for weak clients and warns that some devices may refuse to connect to an access point that has kicked them repeatedly. A stationary sensor in a far corner is precisely the device that will experience it.

Its Roaming Assistant, new in Network 9.2, is the softer alternative. Ubiquiti says it uses BSS transition frames to warn a client before dissociation, which modern clients tolerate. ESPHome's post-connect roaming does the client's half, rechecking for a better access point three times after connecting and moving on a 10 dB improvement.

For instance, a sensor that joined the wrong access point after a power cut can move itself within fifteen minutes under the default, without a kick. It needs a 10 dB better access point in range to do so. The roaming guide covers the cell sizing that keeps the choice easy in the first place.

Power, moreover, can masquerade as Wi-Fi trouble. ESPHome's FAQ ties the brownout detector to transmit bursts of several hundred milliamps. Its first fix is lowering output_power from the 20 dB default.

Every setting in the SSID section disappears, naturally, when the board has a cable. ESPHome's Ethernet component supports RMII and SPI controllers on the ESP32 and SPI and PIO controllers on the RP2040, and the device then joins whatever VLAN its switch port assigns.

The board list is a long one. ESPHome's documentation carries ready-made pin configurations for many of them, including the Olimex ESP32-POE, the Wireless Tag WT32-ETH01, the SMLIGHT SLZB-06 PoE Zigbee and the Silicognition wESP32. The LILYGO T-ETH-Lite, the Waveshare ESP32-S3-ETH PoE and the M5Stack PoESP32 are there too.

The SLZB-06 is the overlap with the PoE radios guide, which places it as a network Zigbee coordinator. Running ESPHome on the same hardware, which the Ethernet page covers with a ready-made pin configuration, makes it an ESPHome node on the same cable.

Power is modest: Ubiquiti's PoE reference lists up to 12.95 W delivered to a device on plain 802.3af PoE, the lowest of its four modes. That is far above the 120 mA active draw ESPHome's ESP8266 platform page lists for that chip. The PoE budget guide shows why the switch's total still needs checking.

Of course, the port needs a profile. The port profiles guide explains how a UniFi switch port is assigned to one VLAN, which is how a wired ESPHome board lands beside Home Assistant on the IoT network without touching Wi-Fi.

Note that mixing the two interfaces is an ESP32-only feature. ESPHome's documentation allows Wi-Fi and Ethernet in the same configuration on ESP32 boards with a network priority list, and on no other platform.

Discovery, meanwhile, works the same way over a cable. The device still announces itself over mDNS and still needs the API port reachable, so the previous sections apply unchanged. Improv over serial still reports the device online to the installer even when its configuration has no Wi-Fi at all.

Finally, these steps put the guide into the order a new device meets them:

1. Create a 2.4 GHz SSID on the IoT VLAN with WPA2/WPA3 or WPA2 security, PMF optional, and Ubiquiti's IoT list applied: band steering, BSS transition, fast roaming, UAPSD, multicast settings and minimum data rate all off or on Auto.
2. Put Home Assistant on that VLAN, or add _esphomelib._tcp.local to a Custom mDNS relay between the IoT and trusted networks.
3. Give every device a unique name, and either a manual_ip block or a Fixed IP reservation in UniFi Network.
4. Set an API encryption key and let OTA reuse it, with the device added to Home Assistant by discovery or by its fixed address.
5. Leave mDNS enabled and the log level below the most verbose setting, and keep the Device Builder's log viewer closed when you are not reading it.
6. Watch for the quarter-hour reboot. A device that restarts every fifteen minutes is telling you Home Assistant cannot reach it on port 6053, or that Wi-Fi itself is dropping.

Do the first step once and the rest become a template. After all, a second board on the same SSID inherits everything except its name and its address. When the next board is a Zigbee or Thread radio rather than a sensor, the PoE radios guide picks up where this checklist stops.