Once you have provisioned an ESPHome device and made sure it can connect to WiFi, it automatically surfaces in ESPHome Dashboard and can be adopted.
Adoption only applies to devices that use a generic ESPHome firmware. Such devices can be added to any ESPHome Dashboard instance.
Adopting New Device
Once a fully provisioned ESPHome device connects to WiFi, ESPHome Dashboard picks it up and shows a green DISCOVERED.
For adoption to work, make sure the device and ESPHome are connected to the same network. Else, ESPHome won’t discover the new device.
The device initially uses the same temporary name that was assigned by ESPHome Web Tool during provisioning. This name was also shown when the WiFi access was configured.
Understanding ESPHome Adoption
When ESPHome discovers a new wireless device that has been provisioned with a generic firmware, it offers to add this device to your ESPHome environment. If you accept by clicking ADOPT, you personalize it: you assign a unique device name, and ESPHome creates a configuration file for this device, including new unique access keys. The personalized configuration can then be uploaded to the device wirelessly which finalizes adoption.
Once adopted, the device works like any other ESPHome device: it can be edited via its configuration file and updated wirelessly, but only from within the ESPHome instance that adopted it (and has access to its configuration file including its secret access keys).
Adoption only works once, and when a device has been adopted, it is no longer up for adoption by any other ESPHome instance.
The primary advantage of the two-step adoption process (provisioning, then adoption) over directly uploading a manually created configuration is that you do not need a USB cable connection between the device and the computer running ESPHome for the initial firmware upload. Provisioning can use any USB cable connection to any computer, and after adoption, the microcontroller can receive updates wirelessly via OTA.
You can now Adopt the device:
-
Click Adopt. ESPHome opens a dialog, and you can now assign a meaningful name to the device. Click ADOPT.
-
ESPHome now creates a specific configuration for your device that you can later use to configure it. The new configuration needs to be uploaded to the device (actually, a firmware representing the configuration). Click INSTALL if you want to do this now, or click SKIP if you want to adjust the configuration first. In this example, click SKIP because there are a few important adjustments to do.
-
In ESPHome Dashboard, look for the tile that represents the device. In its upper right corner, you should see the label ONLINE. The adoption process has renamed the friendly name, but the device still uses the awkward temporary name for its hostname (mDNS name):
-
To rename the hostname, click the three-dot menu, then click Rename hostname.
-
Enter the new host name. You can only use lower case letters, numbers, and a few special characters. Click RENAME.
ESPHome now recompiles the firmware and uploads it to your device. Click CLOSE to close the terminal window.
Once the device has rebooted, you are done: your device now uses the name you assigned, and the device host name has also been changed.
You can now click EDIT and review or expand your device configuration, save it, then click the three dot menu and choose Install - Wirelessly to program and work with your new device - but only in the ESPHome instance that adopted the device. The device is now no longer generic and can no longer be adopted by other ESPHome instances.
Comments
Please do leave comments below. I am using utteran.ce, an open-source and ad-free light-weight commenting system.
Here is how your comments are stored
Whenever you leave a comment, a new github issue is created on your behalf.
-
All comments become trackable issues in the Github Issues section, and I (and you) can follow up on them.
-
There is no third-party provider, no disrupting ads, and everything remains transparent inside github.
Github Users Yes, Spammers No
To keep spammers out and comments attributable, all you do is log in using your (free) github account and grant utteranc.es the permission to submit issues on your behalf.
If you don’t have a github account yet, go get yourself one - it’s free and simple.
If for any reason you do not feel comfortable with letting the commenting system submit issues for you, then visit Github Issues directly, i.e. by clicking the red button Submit Issue at the bottom of each page, and submit your issue manually. You control everything.
Discussions
For chit-chat and quick questions, feel free to visit and participate in Discussions. They work much like classic forums or bulletin boards. Just keep in mind: your valued input isn’t equally well trackable there.
(content created Jun 07, 2024 - last updated Jul 12, 2024)