When I first came across the ESPHome project a year or so ago. I thought it was interesting and something that I would use if I was building a smart device from scratch. I thought of all the things I could do, but I didn’t really like the idea of all the maintenance I could foresee.
ESPHome is a system to control your ESP8266/ESP32 by simple yet powerful configuration files and control them remotely through Home Automation systems.
It took some persuasion by Ryan Hoffman, who has been building a bunch of custom made ESPHome projects to show me what is possible with ESPHome. I’m starting to kick myself in the butt (better now than never) that I didn’t take time to check this project out sooner. I’ve since purchased multiple ESPHome devices such as the Gosund Mini WiFi Outlet and HiLetgo ESP-WROOM-32 ESP32. The next device that I think will work great for holiday lights is the Gosund Smart Power Strip.
I think one really huge benefit that mostly goes unnoticed for for a larger part of the smart home community is all the retail devices running ESPHome. This means that you can buy devices you might not trust on your networks due to them being from a company you’ve never heard from and completely flashing the firmware to something you’ve created. Yes, there still could be software embedded onto different chips but it’s unlikely.
In the sections below I will cover installing ESPHome to work with Home Assistant, flashing a device, and adding the device to Home Assistant.
ESPHome can use mqtt so you can use it without Home Assistant too!
Here are some of the benefits I’ve noticed since using some of my first devices.
- Open Source (Audited)
- Easy to manage with Over-the-air (OTA) updates
- Flash any ESPHome device (including retail devices)
- Rock Solid
- Rich local automation support right inside the firmware that can use Home Assistant states
Installing the ESPHome add-on
Lets install the ESPHome add-on from Home Assistant Community Add-ons repository. This allows us to run ESPHome locally and have our devices integrate automatically with Home Assistant by taking advantage of all the awesome community work that’s been done. Behind the scenes the add-on uses auto discovery to expose configured devices to Home Assistant automatically!
There is an official getting started guide, but I found it slightly confusing and the steps below straight forward!
- Navigate to http://homeassistant.local:8123/hassio/store.
- Click on the option menu in the upper right and select
https://github.com/hassio-addons/repositoryand then click the
- Click the close button to close the
Manage add-on repositoriesdialog.
- Select the
ESPHomeadd-on or access via the url http://homeassistant.local:8123/hassio/addon/a0d7b954_esphome/info.
- Click the
- Toggle the
Show in sidebaroption for ease of use (Optional)
- Finally, click the
ESPHome should now be running as an add-on and you can access the ESPHome web ui on via the sidebar or directly using http://homeassistant.local:8123/hassio/ingress/a0d7b954_esphome.
A huge misconception I had with ESPHome was that I had to build all my devices. It wasn’t until recently that it was pointed out to me that there are a ton of cheap consumer devices from brands you’ve never heard of, and more than likely never have trusted to ever connect to your IoT/NoT network. This is super awesome game changer! You can build your own device firmware, flash the manufactures device knowing exactly what the device is doing, and then reflash it Over-the-air (OTA) via ESPHome with a few clicks! This really saves on the maintenance as well as having more trust for the security of the device.
My first ESPHome compatible device was the Gosund Mini WiFi Outlet
I’d recommend checking out one of the following links to find retail devices that work with ESPHome
- Amazon ESPHome
- Amazon 2.4GHz WiFi Only (
2.4GHz WiFi Onlyis a really good indication a device is running ESPHome, but double check)
- ESPHome Configs
- TASMOTA devices (An ESPHome alternative)
Once you have a device we need to flash it, in order to flash it we need to configure some software and hardware.
Please note you may BRICK your device by flashing it or break the terms of any device/licenses.
Please note that you can use any free hardware granted you have an unused wifi adaptor. You just need to meet and it meets the requirements of tuya-convert.
Installing tuya-convert on a Pi
In this section I’ll be configuring the Raspberry Pi to run the flashing
software tuya-convert. Please
follow the steps below to get
tuya-convert up and running.
Raspberry Pi OS
- Install the
Raspberry Pi Imager
- Insert a 2GB or bigger SD Card into your computer.
- Launch the
Raspberry Pi Imagerand image the SD Card with the downloaded
Raspberry Pi OS.
- Remount the imaged SD Card.
- Navigate to the root of the SD Card and create a file called
touch ssh). This will allow you to
SSHinto the Pi in a headless manner.
- Eject the SD Card and insert into your Pi.
- Ensure you have ethernet plugged into your Pi
- Power on the Pi and wait.
SSHinto the Pi
ssh email@example.com(you might need to figure out the ip using your router).
- Enter in the default password of
- Install git using
sudo apt-get install gitand enter
tuya-convertby cloning it with
git clone https://github.com/ct-Open-Source/tuya-convert.git.
- Navigate to the
- Install the dependencies by running
tuya-convert is installed, we need to switch gears and build our
custom firmware for our device.
Building the ESPHome Firmware
Now it’s time to jump back into the ESPHome addon we configured earlier. You can access the ESPHome web ui from the sidebar or directly using http://homeassistant.local:8123/hassio/ingress/a0d7b954_esphome.
I’ll be building the firmware for the Gosund Mini WiFi Outlet, if you are using a different ESPHome device, you will need to tweak the following steps slightly.
Create new ESPHome device
- Click the Add button in the lower right hand side to bring up a
Create New Nodemodal.
- Enter in the new Node Name and click
Next. I entered
gosund_wp3_02as this is my second device.
- Select the device type and and click
Next. I selected
- Enter in your WiFi network information or some garbage text (we will configure them via secrets in a little bit) and click
It’s worth pointing out that you may see a red line at the top of your device. This means that your device is offline and hasn’t communicated with ESPHome. If it is green, that means the device is online.
Also, if you look closely at this point to your Home Assistant installation,
you will see that an
esphome folder was created with a yaml file and folder
that matches your Node Name! This allows you to make edits in your editor of
choice and also commit these to source control!
Edit ESPHome Secrets
We will configure some secrets that will be merged into the firmware
configuration. This works much like the lovelace secrets work! You can do this
by clicking on the options menu in the upper right and selecting
It’s also worth pointing out that you can have ESPHome use your Home Assistant secrets.yaml file!
The firmware I will be using uses the following secrets. This may be different for the firmware you are using.
wifi_ssid: "my_secret_network_name" wifi_password: "my_secret_network_password" wifi_fallback_password: "my_secret_network_password" gosund_ota_password: ""
After you’ve configured the secrets hit
Close buttons respectively.
Edit ESPHome Device Firmware
Now that the secrets are configured lets click on the
Edit button of the new
device we created inside of ESPHome. I’m going to copy the
from github into this editor and click
Close buttons respectively.
This firmware supports
substitutions, which allows you to make variable replacements to the firmware easily. I use
substitutionsto change the
Next, click on the ESPHome Device options in the upper right of we just edited
Compile. This will open a modal and start compiling the firmware.
Once we the firmware is compiled there will be an option to
Click this to save the firmware to your machine.
Uploading the firmware to the Pi
The next step could be the most trickiest step of them all (if you are running
Windows), which is getting the firmware onto the pi. We need to copy the file
from the downloads folder to the
This can be done by navigating to the downloads folder in your terminal and
scp gosund_wp3_02.bin firstname.lastname@example.org:/home/pi/tuya-convert/files and
enter in the default password of
raspberry when asked.
Don’t forget to plug in our device and hit the pairing button to enter setup mode!
After the device is in setup mode, switch back over to the Pi that we were
connected to earlier via SSH and run the
You may have to enter
y, to terminate some running service (e.g.,
mosquitto) when prompted. After a while you will be presented with several
Available options: 0) return to stock 1) flash gosund_wp3_02.bin q) quit; do nothing
Double check yourself at this step as you don’t want to flash the wrong firmware!
You will want to flash it with the binary you uploaded in the previous step! Enter in the number of your firmware and follow any remaining prompts. After the device reboots it will now show up in ESPHome highlighted in green and you’ll be asked to configure it in Home Assistant!
It appears there is a new firmware on some Tuya devices that is preventing flashing causing vendor lock in to unknown third party services. There are two workarounds, one requires soldering and the other solution requires a 3D Printer
Adding the flashed device to home assistant
The device will be automatically discovered by the ESPHome add-on and you’ll be asked to configure the device.
Once you configure the device you’ll have several device entities as shown below.
It’s worth noting that you can use the physical button and the relay independently. This is possible because you have full control over how your devices operate when building your firmware!
Updating Device Firmware
If you need to update the device firmware later, it is a simple process. All
you need to do is navigate to the device in the ESPHome Dashboard and click
Edit. After you’ve made your changes, click the
This will compile and upload the firmware to the device Over-the-air (OTA) and
then start tailing the device logs. Just click the
Stop button after the
firmware is updated to close the modal.
I’ve really enjoyed using ESPHome so far. The overall ease of use and seamless integration into Home Assistant feels really polished. I’ve also noticed that all of my ESPHome devices are really stable and rock solid! I’ll be buying more ESPHome devices for my projects.