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!

Benefits

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)
• Cheap
• 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!

1. Navigate to http://homeassistant.local:8123/hassio/store.
2. Click on the option menu in the upper right and select Repositories.
3. Enter https://github.com/hassio-addons/repository and then click the Add button.
4. Click the close button to close the Manage add-on repositories dialog.
5. Select the ESPHome add-on or access via the url http://homeassistant.local:8123/hassio/addon/a0d7b954_esphome/info.
6. Click the Install button.
7. Toggle the Show in sidebar option for ease of use (Optional)
8. Finally, click the Start button.

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.

ESPHome devices

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 Only is 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.

Hardware Requirements

I used a spare Raspberry Pi 3 B+ that I had laying around, otherwise any Pi that supports Wifi will work like the Raspberry Pi 4 Model B.

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.

1. Download Raspberry Pi OS
2. Install the Raspberry Pi Imager
3. Insert a 2GB or bigger SD Card into your computer.
4. Launch the Raspberry Pi Imager and image the SD Card with the downloaded Raspberry Pi OS.
5. Remount the imaged SD Card.
6. Navigate to the root of the SD Card and create a file called ssh (e.g., touch ssh). This will allow you to SSH into the Pi in a headless manner.
7. Eject the SD Card and insert into your Pi.
8. Ensure you have ethernet plugged into your Pi
9. Power on the Pi and wait.
10. SSH into the Pi ssh pi@10.0.0.100 (you might need to figure out the ip using your router).
11. Enter in the default password of raspberry.
12. Install git using sudo apt-get install git and enter yes when prompted.
13. Install tuya-convert by cloning it with git clone https://github.com/ct-Open-Source/tuya-convert.git.
14. Navigate to the tuya-convert directory using cd tuya-convert.
15. Install the dependencies by running ./install_prereq.sh.

Now that 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

1. Click the Add button in the lower right hand side to bring up a Create New Node modal.
2. Enter in the new Node Name and click Next. I entered gosund_wp3_02 as this is my second device.
3. Select the device type and and click Next. I selected Generic ESP8266.
4. Enter in your WiFi network information or some garbage text (we will configure them via secrets in a little bit) and click Next

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 Secrets Editor.

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 Save and 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 firmware yaml from github into this editor and click Save and Close buttons respectively.

This firmware supports substitutions, which allows you to make variable replacements to the firmware easily. I use substitutions to change the device_name or friendly_name.

Next, click on the ESPHome Device options in the upper right of we just edited and select Compile. This will open a modal and start compiling the firmware. Once we the firmware is compiled there will be an option to Download Binary. 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 /home/pi/tuya-convert/files folder.

This can be done by navigating to the downloads folder in your terminal and entering: scp gosund_wp3_02.bin pi@10.0.0.100:/home/pi/tuya-convert/files and enter in the default password of raspberry when asked.

Flashing…

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 ./start_flash.sh script

pi@raspberrypi:/home/pi/tuya-convert# ./start_flash.sh

You may have to enter y, to terminate some running service (e.g., dnsmasq, mosquitto) when prompted. After a while you will be presented with several options

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!

locked firmware

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 Upload button.

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.

Final Thoughts

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.

Join the mailing list