ESPHome Add-on vs. Integration? (newbie question)

I just started using ESPHome and I’ve seen 2 very different “types” of ESPHome device adoption that I’m trying to understand.

I installed the ESPHome Add-on.

For one of my devices (a RATGDO), inclusion seemed like a pretty computationally intensive (though straightfoward, thankfully) activity. It seemed that ESPHome was compiling a me-specific software image and then flashing the device with this new firmware OTA. The device is listed within the ESPHome add-on and I periodically get notifications about ESPHome software updates for this device.

For a second device (an Athom smart plug), once I got the device connected to wifi, it just showed up as a newly discovered device via the ESPHome integration. I included/adopted it (in main Home Assistant, not in the ESPHome add-on) and now can see it in my HA devices. But it does not appear in the ESPHome add-on (alongside the RATGDO).

My question is: what is the difference between these 2 apparently different levels of ESPHome inclusion/device management? I get the impression that for the RATGDO, ESPHome is not only providing a translation interface between the device and HA but it is also managing the firmware on the device and for the plug it is only the former. Is this accurate?

I’ve seen instructions for other devices that say that initial flashing requires the device to be USB-connected to the computer and often requires a device-specific YAML file in order to generate the proper firmware image… but subsequent updates can be flashed OTA. But it seems like some commercial devices come “pre-flashed” and discoverable. Can these pre-flashed devices then be re-flashed OTA (as there are no easily-accessible physical connections available) from the ESPHome add-on? Is that something I should be doing? What are the advantages/disadvantages of doing so?

Thank you!

ESPHome is a lot of things, and their documentation doesn’t always do the best job of laying it out for newbies to understand how they are all connected. I struggled with this at first so you’re not alone.

ESPHome is a platform (in the software development sense) for writing, compiling (building) and installing custom firmware for embedded devices. Its main strength/appeal is that it allows you to build your own brand new (physical) device, and create a fully tailored firmware image for it, without writing any low-level code (but it has the power-user option of slipping in as little or as much code as you want). The firmware is created from a YAML configuration file which is fairly easy to read and beginner-friendly.

ESPHome is also a set of utilities e.g. Add-on / docker container / Python package, to design, deploy, and manage your devices and firmware images — a web dashboard, command-line tools, and a web flasher utility for example are all part of ESPHome. The web flasher makes it easy to get started with a blank device, and subsequent firmware upgrades can be installed over-the-air using the dashboard or command-line tools.

ESPHome is an integration for Home Assistant, providing a way of accessing devices and using their sensors, actuators, etc in your home automation ecosystem. Devices “discovered” (not adopted) by the HA integration are “operational” and give you access to complex automation control in conjunction with other, non-ESPHome, devices also controlled and monitored by Home Assistant. The integration doesn’t care how the firmware was compiled or installed on the device, just that it is running and discoverable on the network.

It is entirely possible to deploy devices running ESPhome (the firmware) using ESPhome (the utilities) but never use ESPHome (the integration), because ESPHome (the platform) also provides a simple on-device web interface and multiple APIs (custom encrypted, web/REST, and MQTT) for other automation systems, or just a manual tinkerer, to access their device in other ways.

Exactly. The devices in the add-on dashboard are the configuration files (YAML) that can be compiled into firmware images. If you want to customize, or update, a device’s firmware you must have installed ESPHome (the Add-on/Utilities) and “adopted” its configuration YAML (which may require getting it from the manufacturer if it was pre-flashed) in order to have full customization control over the firmware of the device. At a minimum, you can upgrade it when bugs are fixed.

Note: As of today, HA 2024.7 announces a new feature where pre-flashed “Made for ESPHome” device manufacturers can issue and deploy firmware updates without requiring you to compile them yourself, meaning if you don’t want to customize a pre-flashed device, you may never need to install the Add-on to keep it up-to-date.

To use some examples from my experience:

  • I purchased an Athom presence sensor pre-flashed with ESPHome and adopted/customized the YAML because I hated the blue light was on all the time when someone was in the room, so I changed it to flash once whenever motion is detected. The power of open source!
  • I developed an ESPHome firmware for a vending machine controller that will never be connected to Home Assistant integration, but will be sending data via MQTT to my central inventory system. I could never have developed this firmware in C code on my own.
  • I run ESPHome utilities on my Mac, installed via Python, because it is the fastest computer in my house and can compile firmware images in just a few seconds compared to my HA server thin client which takes several minutes (and because docker containers on Macs are cumbersome). I can edit, flash, and troubleshoot devices completely separate from my HA server using these utilities.

The devices that you see in the ESPHome UI are those devices that have a yaml file in config/esphome

You can download Athom device yaml files from their Github page.

1 Like

Thanks @peterxian ! Can you share any instructions for doing this? I have an Athom ESP32-C3 smart plug that has been adopted by Home Assistant via the ESPHome integration (so it shows up in my device lists), but it does NOT show up in my ESPHome add-on. I have a copy of the devices .yaml file from GitHub. Based on what you’ve written, it sounds like it should be possible to reflash the smart plug OTA, since it is already an ESPHome device (important because it does not have any easily-accessible data connections to enable flashing via USB), but I can’t figure out how to.

I tried clicking on “add device” in the ESPHome Add-on, hoping it would ask for a .YAML and let me choose an already-recognized-by-the-ESPHome-integration device, but no luck there…


You can only adept the device using OTA if the device has the web-interface enabled in yaml.

(you can go to the devices website by http:192.168.1.x)

If web is not available, the only way to adapt them is to flash them by hardwire (serial).

PS: You only use the esphome-addon to generate the binaries to flash the units, after that you no longer need the addon (you could even use a completely different machine to flash them, you don’t need the esphome addon to be on HAOS).
So the esphome addon has nothing to do with the esphome integration :wink:

Aha, so I if I understand correctly, I should generate a binary in the ESPHome Add-on and then reflash by going to the SSID generated by the smart plug and uploading my new binary as if it were a manufacturer’s firmware update? Thanks!

Just one question: how do I create this binary in the ESPHome add-on? It sounds like the binary must be based on the device specific YAML that I downloaded from the manufacturer’s GitHub. But if I go into the ESPHome add-on and click “add device” it does not give me the option to upload a YAML. How do I do this?

… and then once it has generated the binary, how do I download it from the ESPHome add-on? The ESPHome add-on seems pretty insistent on only installing firmware via USB, and I didn’t see an option to download a binary to manually install… Any pointers?

Thanks so much!

Afirmative :wink:
At least when it comes to a 3rd party device, on existing devices (the one’s already on your own wifi), you can just visit open their local website.

You hit ‘edit’ and a page will show up where you can just paste the yaml into.

When you hit generate, it will offer you some options to choose from on how to flash the device

The last option is manual download :wink: