How does the ESPHome Dashboard determine if a node is online?

I’m running ESPHome in a Docker container on my Windows computer, and I plan to integrate the nodes in a different system than Home Assistant (HomeSeer, to be precise). I’m compiling the binary files just fine, and I’m able to upload them to a node using OTA, since I’ve set the node up with a static IP address. But the node is still offline in the ESPHome Dashboard.

I’m trying to understand why this is, but I haven’t found any information on this in the documentation. I believe it might be related to port forwarding between my Windows host computer and the Docker container running the ESPHome Dashboard. Since setting --net=host isn’t really doing anything (at least not forwarding port 6052 for the Dashboard), I instead have to forward the port manually.

So how does the ESPHome Dashboard determine if a node is online? Is it polling the node on a MQTT topic, or is there some other mechanism? Specifically I’m curious about which port(s) this communication is on.

1 Like

I am pretty sure by mDNS.

I had the same problem awhile back and I found the fix was to add the following to the docker run command:


It is using mDNS by default and as stated by @finity you can force it to use ping instead (ICMP) if needed by passing option at docker or in plugin setting if you use hassio :slight_smile:

Copied from Docker ESPHome docs:

ESPHome uses mDNS to show online/offline state in the dashboard view. So for that feature to work you need to enable host networking mode

mDNS might not work if your Home Assistant server and your ESPHome nodes are on different subnets. If your router supports Avahi, you are able to get mDNS working over different subnets.

Just follow the next steps:

  1. Enable Avahi on both subnets.
  2. Enable UDP traffic from ESPHome node’s subnet to on port 5353.

@finity where did you find this?
I have my IoT devices on a separate subnet and have been trying to get mDNS working across subnets (found instructions for this, but so far haven’t gotten it working).

I didn’t know you could change it to ping - just wondering if this was in the documentation somewhere, and I missed it.


No, I didn’t find it. I posted about the same problem a while back and somebody else gave me the answer. I don’t know where they found it.

Does that require setting the wifi manual IP in ESPHome yaml for the device?

I’m not sure if it’s required but I would assume so. I put in a fixed IP in my devices by default so I’ve not tried it without it.

Setting ESPHome to use Ping instead of mDNS worked like a charm! But are there any downsides to this? Or can I just leave it at using Ping and be happy? :slight_smile:

I’ve been running it like that for a month or so with no issues. But I really don’t use it very often since all of my devices are already programmed.

I just stumbled on something that might help some people as well.
There is a tag for wifi domain, but default it is set to .local.
**domain** ( *Optional* , string): Set the domain of the node hostname used for uploading. For example, if it’s set to .local, all uploads will be sent to .local. Defaults to .local.

# Example configuration entry
  ssid: MyHomeNetwork
  password: VerySafePassword
  domain: .local

I changed this to the domain my router has and suddenly the little green dots finally work!
This is across subnet too - the only downside is that the button to open the web-interface still goes to .local… but I’ll take it! Strike that - I refreshed ESPHome Dashboard, and the button for the web interface is now pointing to the correct domain too!

Everything seems to be working correctly now - just with adding the domain key to the WIFI setup. I am now very happy with this fixed!



Setting domain: “” was exactly what I needed to make ESPHome work for me on Windows Docker.

My router with caching name server is set to include names of DHCP devices. So I could open the CLI and ping test_node1. But ESPHome was trying to contact test_node1.local and failed. As soon as I set the domain to null, everything started working.

I’m having the same issue on HA running on a pi. I tried configuring through add on configuration in UI, but it made no difference. Any idea on how to configure it to ping instead of mDNS. My sensor is working perfectly apart from this, the ESP home sees it online for a few seconds when I restart it and then status changes to offline but everything keeps functioning other than that.

Who cares, as long as it is working?

But it is dealt with just above here

Add the environment variable ESPHOME_DASHBOARD_USE_PING=true as @finity noted above. Also documented here Frequently Asked Questions — ESPHome.

To add the variable with HA addons: ssh into your HA then open the addons.json file.
Look for "description": "ESPHome add-on for intelligently managing all your ESP8266/ESP32 devices", then append:

      "environment": {


Documentation on Add-on config: Add-On Configuration | Home Assistant Developer Docs

No; in the addon use the configuration tab and tick the status_use_ping option.

That would certainly make things easier but I can’t seem to find that option. Running version 1.20.1 and use browsers in private/incognito mode. No luck in the mobile app neither.

Click on the “Show unused optional configuration options”

I haven’t tried the addon myself. I’m running esphome in a Docker container. But wouldn’t “unused optional configuration options” be the same as “non-functional”? I.e. not implemented?