I started using ESPhome and now I have a local smarthome

I have been slowly getting into the field of smart home solutions. I am taking my time, because I do not want to fall into the typical pitfalls of the “easy” smarthome. First of them being vendor lock-in, which becomes especially bad when that vector bankrupts and all of their devices become pretty bricks. And second being privacy and data security. I don’t want my devices to talk to some random servers, sharing data they should not have access to in the first place.

Also I am big fan of FOSS solutions, and I don’t mind making stuff myself, both with a soldering iron, and in the command line.

And it looks like I found something that ticks all the boxes: ESPHome

In the tl;dr version, ESPhome is a tool that provides a simple way to configure microcontrollers, allowing to use them with Home Assistant or other smart home software.

ESPhome enviroment sensor visible in Home Assistant

Now, ESPhome supports a metric ton of devices and accessories like sensors or controllers, so I won’t be diving into those details, instead I want to show how it works by showing two ESPhome projects that I did: a relay, and an environment sensor, both connected to Home Assistant.

Initial State

Everything written below assumes that you already have a working Home Assistant running in your home server, and you know a little bit about the command line.

The Hardware

ESPHome supports ESP32 and ESP8266 microcontrollers. It also officially supports the RP2040 devices, such as the Raspberry Pi Pico, but I had multiple problems making them work, that will be a topic for another post.

For the first project I am using an ESP-wroom-32 microcontroller based on the ESP32 chip. You can get them literally dirt cheap, for a few euros each, and they will work just fine with ESPhome. I’ve seen them as cheap as 3 EUR / 15 PLN on aliexpress, and just a bit more expensive at local retailers.

For the second project I went with the Seeed Studio XIAO ESP32C3. It is more modern and advanced than the wroom-32, with a USB-C connector and an external Wi-Fi & Bluetooth antenna. I came across it when browsing one of the electronic shops where I usually buy parts for my projects, and I was impressed by its capabilities.

It’s tiny, the size of a typical coin, yet it supports all of the typical microcontroller interfaces, like SPi, ADC or I2C. It has a built-in USB-C connector for programming, and as for wireless connectivity, Wi-Fi and Bluetooth are also on board. But the thing I liked most is that it has a charge controller for li-ion batteries, which means you can connect a battery straight to the board, and charge it via the USB-C. It supports any 3.7V li-ion battery, and I went with a typical 18650. It’s more expensive than the wroom one, but still in the acceptable range, at 5 EUR / 30 PLN.

The biggest downside for me is that the battery connector pads are tiny and are very difficult to solder to, a JST connector would be a much better solution.

The Relay

The relay that I am using is an IDUINO single channel relay that can handle mains voltage and can be bought for as little as 3 EUR.

The Sensor

As for the sensor I went with a BME280, which is a combined temperature, pressure and humidity sensor. It’s the same sensor I used in my Solar Weather Station project.

Setting up ESPhome

There are multiple ways to install ESPhome, I went with the most “oldschool” way, installing it manually from the command line. It’s also the simplest one to set up, as it only requires having Python on your local machine.

Everything is described in the installation instructions, but here’s the recap:

Create a Python virtual environment (it’s considered a good practice to always create one when working with Python)

python3 -m venv venv

Now, activate it, and install the required dependency and the package itself

For Linux:

source venv/bin/activate
pip install wheel
pip install esphome

for Windows:

venv/Scripts/activate
pip install wheel
pip install esphome

And here you go, ESPhome is installed and ready to be run. Before we run it, though, let’s prepare the hardware.

Of course, those are just examples, you can mix and match hardware as you wish.

Project 1: ESP32 relay

ESP32 connected with the relay

The esp-wroom-32 and the IDUINO relay both come with GPIO headers already soldered, so there is no need to do any additional soldering. All that you need is three female-to-female jumper cables.

The relay has three connectors, negative, positive, and control.

In this PDF documentation you can find the pinout diagram for the ESP-wroom-32

The positive needs to go to the VIN pin on the ESP32, this is the pin that provides 5V output for powering the relay. The negative needs to be connected to one of the ground pins, there’s one next to the VIN pin, so we can use this one. Finally, the control pin needs to be connected to any of the pins on the ESP32 that can be controlled. GPIO13 is right next to the VIN and GND pins, so let’s use this one and have all three cables connected next to each other.

For now you can leave the other side of the relay not connected to anything as we are testing our project.

You can connect mains voltage (120V-220V) to that relay, but remember that working with such high voltage is dangerous and can kill you. Proceed only if you know what you are doing, and at your own risk. Be reasonable.

ESPhome setup

After connecting the relay, connect the ESP32 microncontroller to your computer using a micro-USB cable. With the Python virtual env activated, run:

esphome wizard livingroom-relay.yaml

For the board type select esp32dev. Fill in the Wi-Fi information. Once the wizard is done, a file livingroom-relay.yaml will be created. Open it with your text editor of choice.

At the bottom of the file add:

switch:
  - platform: gpio
    name: "Switch 1"
    pin: GPIO13

Change the name to something more descriptive :)

Once this is done, run

esphome run livingroom-relay.yaml

If this is the first time you are installing ESPhome on that device, the script will install the required software and copy the yml file to the device. This requires the USB cable. Subsequent updates can be done via Wi-Fi, another cool feature of ESPhome.

Once the installation is done, the board will connect to WiFi, the logs will tell what is happening. If all finished successfully, the next step is to go Home Assistant.

Now the magic should happen, and HA should automatically find ESPhome and notify you that a new integration is available. If that didn’t happen, refresh the page after a few minutes, or try to add the integration manually from the integration settings.

Once the integration is added, a new relay toggle button should appear on the HA dashboard, with the name that you provided in the yml file.

Clicking on the toggle button activates the relay, an audible click should be heard as it turns on and off. And in effect, you are able to control dumb devices, even those running on mains voltage, like lamps or fans, from your Home Assistant. And everything happens locally without shady cloud software.

Project 2: Seeed Studio Environment Sensor

Seeed Studio connected with the BME280 sensor

For this project the build process was a bit more involved, as it required soldering the pin headers to both the ESP board and the BME280 sensor.

Then, with two small wires, I connected the 18650 battery case to the pins on the downside of the board. This was not a pro gamer move, soldering the battery pins would be much easier if I did before adding the pin headers. Anyway, with some complicated soldering iron gymnastics, I managed to make it work.

Next was the Wi-Fi & Bluetooth antenna with its tiny connector. The external antenna is another cool feature of that board.

I connected the board with the sensor using female-to-female jumper cables.

The BME280 sensor I am using support I2C connectivity, to this is the protocol I went with. Connecting it with the board requires four cables: VCC, GND, SCL and SDA.

Here’s the pinout diagram for the Seeed board:

I connected the VCC of the sensor with the 3.3V output pin on the board. GND with the GND pin. SDA to the GPIO6 pin, and SCL to the GPIO7 pin. And the hardware part is done.

ESPhome setup

Most parts of the setup are identical as in the first project, so I’ll just glide over them.

Create a new file using the wizard. As the board type, select seeed_xiao_esp32c3. When the yml file is created, at the bottom of it add

i2c:
  sda: GPIO6
  scl: GPIO7
  scan: true
  id: bus_a

sensor:
  - platform: bme280_i2c      
    address: 0x76
    temperature:
      name: "Temperature"
    pressure:
      name: "Pressure"
    humidity:
      name: "Humidity"

This snippet first configures the I2C connection and sets up the BME280. The output will have clear, human-readable names.

Update the file with the provided snippet, run the upload, and again, once the microcontroller is running with the new code, HA should discover it automagically.

Now the cool thing with that board is that you can leave it plugged in and it will charge the 18650 battery in the soldered in battery case. After a few hours of charging, you can plug it off and the board will run under its own power.

From my experience, under default settings and with a good 18650, it reach 5 days of uptime. With more cells, and with longer times between readings (it can be configured in the yml file), it should reach multiples of that runtime.

The full package with the battery and the wireless antenna

ESPhome Dashboard

ESPhome has another cool trick up its sleeve.

esphome dashboard .

Running the command above in the folder where the config files are stored will start a webserver. Opening the provided link in the browser will take you to a dashboard that shows the currently online ESPhome nodes, and the ability to edit their config upload it over Wi-Fi. Super useful stuff when the nodes are in hard to reach places, or are firmly secured.

Bottom Text

This has been just scratching the surface of what ESPhome is capable of. Browsing the docs shows that it can support a lot of different boards and sensors and controllers.

One interesting project that I found is controlling cooling fans: esphome-fan-controller

I feel that ESPhome will be very useful to me once I have my own house. The possibility of having home automation without relying on shady third party software, but instead on one’s own coding and soldering skills is extremely tempting for me.

And on the other hand, ESPhome in my opinion significantly reduces the entry barrier for less technical people by allowing relatively easy means of programming and configuration of microcontrollers. And with the right hardware, like the Grove sensors, soldering is not even required.

And that’s it, if I have any new projects with ESPhome, I will for sure share them with you.

Thanks for reading!

If you enjoyed this post, please consider helping me make new projects by supporting me on the following crowdfunding sites: