Getting Started
The bare minimum to get going is to buy a pre-built ESP device, connect it to your WiFi, and add it into HA via the ESPHome integration.
Adding a Device to the ESPHome Integration
The ESPHome integration is enabled to use mDNS for auto-discovery. Once a device is connected to your network, it should automatically show up in HA to be added.
If it’s not, you can opt to manually add it.
First option is to click this button:
If that doesn’t work, then you can manually add it in HA by going to Settings → Devices → Click on “Add Integration”
You’ll be prompted to provide the IP address for the device. Click through the prompts and you’re done. It will show up as a new device and will populate entities based on what the vendor configured.
Adding the ESPHome Add-on
Now, let’s assume you want to either reconfigure a pre-built device or build your own. You’re going to need to install the ESPHome package. Arguably the easiest method to install and use it is via the ESPHome add-on.
To make that even simpler, all you should need to do is click this button and select install:
If it doesn’t, again, you can manually install the add-on.
- Go to Settings → Add-ons
- Click on “Add-on Store” in the bottom right-hand corner.
- Find ESPHome in the list
- Select “Install”
Once the add-on is installed, click on “Start” to get it going.
Caveat: There are options to start the add-on when HA boots, enable the watchdog service to automatically restart it if it crashes, and whether or not you want it to show in the sidebar. All of these options are completely up to you. It’s only necessary to have the add-on running when configuring the device(s) and checking for updates.
Configuring a Device
Things can go a few different ways here. If you’re building your own device, then nothing will show up. We’ll cover this farther down.
Prebuilt Devices
Many vendors will use an option called dashboard_import for their devices along with a sub-option to pull a pre-built configuration file from a website (often Github). If that’s the case, then you’ll see an option in the add-on to “adopt” the device. Just click the button.
Caveat if this is your first device
Caveat: If this is your first device, you may see a prompt like this:
The box explains itself, but this is essentially storing your WiFI credentials so you don’t have to input them every time you set a device up. You can, of course, modify what credentials a particular device uses if you’re the type that likes separate WiFi networks depending on the device.
Additionally, another pop-up may show up with an encryption key. This is the API key for the device (mentioned in the first post). You can save it off now or retrieve it later on from the add-on, if needed.
What happens is the add-on will attempt to download the configuration file from the linked website and store it locally to be modified by the user. Once adopted, you can click on “edit” on the device card to view the configuration.
You’ll notice that this is obviously a stripped down configuration as there’s nothing in the configuration file for entities and what-not. You can follow the packages link which shows a much larger configuration file (note the dashboard_import line):
But why?
Vendors want their devices to be as simple as possible to setup and use. The way this works is that the ESPHome add-on pulls the dashboard_import file which is usually just some of the basic configuration options: device name, wifi settings, etc. When you “install” the firmware, the add-on will read the configuration file and, when it sees the line for packages, go out to the internet to pull the rest of the configurations before compiling the firmware. The packages file is cached so that the internet requirement is only needed the first time, per device.
This flow also allows vendors to modify the core configuration to add new features, fix bugs, etc. and, since the configuration is centrally managed, they don’t have to worry about getting the updated configuration to customers. The add-on will periodically check the packages link for changes.
DIY
So, you want to try your hand at making your own device. Or you want to take an existing device and build the configuration from scratch to learn. All of this will be done from the ESPHome add-on assuming that this is from the perspective of a fresh installation. Some of the prompts may change depending on what has been done with your HA installation.
- In the bottom right-hand corner, click on “New Device”
- You’ll see a pop-up prompting you to open the ESPHome Web Flasher, just click “Continue” for now.
- Give your device a name.
- You’ll be presented with a list of device types. Select the option that matches the board type you’re using. With “Use recommended settings” ticked, ESPHome will generate a generic configuration file that should work based on the SoC. If you untick this option, you’ll be provided with an additional selection of official supported, vendor specific boards.
- After selecting your board, you’ll be provided with the API key. For our scenario (using the ESPHome add-on and ESPHome integration from the same HA instance), we can ignore this.
At this point, you’ll have a basic configuration that can be flashed to a device and allow it to connect to your WiFi network. You can opt to click install and move forward with installation, or click skip to make further edits to the configuration file.
I’ve added additional commentary so this will look mildly different for your view.
Installation
We’re almost there. Device is in hand and the configuration file is created. Now it’s time to compile and flash the firmware.
First, you need to determine your flashing method. There are a few options here.
For any method besides “Wirelessly”, you’ll need to know how to get your device into flash mode. This varies by device. Some are done with buttons on the device, some by grounding out a particular pin during power up, some can be done through software, etc.
Wirelessly
The easiest method, but this requires that the device is already on the network, reachable by Home Assistant, and has OTA enabled in the firmware currently on the device. As mentioned in the config commentary, if an OTA password has previously been set, you’ll need to make sure the password matches in the configuration file that you are flashing. There are ways around this, but they’re more advanced and out of scope of this guide. If all else fails, you can go the hardwired route.
If this all checks out, when you select the option ESPHome will immediately begin compiling the firmware and then will automatically upload it to the device once compiled. How long this takes drastically depends on your configuration and the hardware (physical or virtualized) that HA is running on.
Plug into this computer
This option assumes that you are accessing the add-on from a remote computer (because most of us are). Unless you’ve gone through the effort to enable HTTPS connectivity to HA (default setup), this option will not work. If you have not, this method will essentially guide you through the “Manual download” approach that we’ll cover below.
I’ve never used this method, so hopefully someone more familiar will come along and edit this post with more details.
Plug into the computer running ESPHome Dashboard
This option allows you to plug the ESP device into the machine you’re running HA on. If you are running virtualized, this also inherently means that you’ve setup passthrough from the host machine to the VM instance for the USB port or the device itself. Similarly to the OTA option, once you click this option, you’ll be prompted to select your device from a list, and ESPHome will move forward with compiling and flashing the firmware.
Manual Download
This is likely the option most folks will take for the initial installation. This option will compile the firmware and then prompt the user to download the firmware file. For 90% of users, you’ll select the “modern format” option.
- The legacy format is for use with the ESPHome Flasher tool that pre-dates the web flasher.
After you select an option, you’re browser should show a download of a *.bin file (where the * is the device name). Some browsers may block this download, so be aware. The *.bin file is used in tandem with the ESPHome Web Flasher tool.
ESPHome Web Flasher
You’ll need three things:
- A computer running a Chromium-based browser
The mobile version of Chrome is not supported as of this writing. - A copy of the *.bin firmware file on the computer.
- The ESP device connected to the computer in flash mode.
You may need to install drivers for this to work.
Once you’ve got that done, go to the site:
- Select “Connect”
- Select the device from the prompt. It will likely show as a generic JTAG/serial device.
- Select “Install” from the device card.
- Select your *.bin file and click the install button
- Wait for the installation to finish.
Once done, ESPHome will try to do a software reboot of the device. This sometimes does not work. If your device doesn’t connect to the network with a minute or so, give it a restart to see if that helps (via the reset button if available or just remove/add power).
If everything is right, you should see the device be auto-discovered by the HA:
