ESPHome

ESPHome is an open source project that enables us to control devices that run on Espressif’s ESP32 or ESP8266 chips by using YAML-formatted configuration files. ESPHome integrates seamlessly with Home Assistant, our main Smart RV automation software. It is an essential component in our overall Smart RV architecture.

Why ESPHome?

We decided to use ESPHome as our main sensor control software for multiple reasons:

  • Flexibility and Consistency. Being able to use the same software environment, no matter what sensor or smart device is being configured, is a great benefit. We power smart switches, outlets, environmental sensors, motion sensors, current sensors, pressure sensors, … all using the same control software. And we use it to create our own smart devices (e.g. Dometic smart thermostat).
  • Home Assistant Integration. ESPHome is specifically designed to make it easy to integrate with Home Assistant. It supports auto-discovery so that ESPHome powered sensors will automatically show up as HA entities.
  • Cost-effectiveness and low power. ESP-powered boards are amongst the most affordable WiFi-enabled microcontroller boards and available from a variety of vendors. They consume between 70 and 200 mA depending on the type of CPU, and significantly less when in ‘sleep mode’.
  • Local control. ESPHome is designed to work locally without relying on Internet access. This is especially critical in an RV environment where Internet access is not guaranteed. The proprietary software in many modern smart switches and sensors requires cloud access and hence is not suitable for an RV environment.
  • Community. ESPHome has a very active and supportive community. Their Discord channel is a great resource to resolve issues. There is always a community moderator available to help when you get stuck on an issue. This free real-time support for a free software is better than what 99.9% of corporations offer to their paying customers. Quite unbelievable.

ESPHome Installation Options

There are two ways to install ESPHome:

  • Home Assistant Addon. This is the easiest way to run ESPHome. The install takes a few seconds. Follow these instructions. However, for us, this is not very convenient, because it would require us to sit in our RV and physically connect the sensor to our Home Assistant server, each time we want to flash a new sensor with ESPHome for the first time (subsequent updates can happen over WiFi). So instead, we prefer the manual install below.
  • Manual Install. Using the manual install option, you can install ESPHome on any Mac/Windows/Linux PC and manage/configure/test your sensors independently of your Home Assistant installation. The installation process is very straightforward.

ESPHome Manual Install on a Mac

The installation procedure is very straightforward if you are familiar with using the Mac’s command line interface:

  1. Open Terminal and check what Python version you have installed. Version above 3.7.X are required.
python3 --version
  1. Next install wheel and esphome packages:
pip3 install wheel esphome

And that’s it. You can now start creating .yaml files using your favorite text editor and compile them to run on your ESP-powered devices. To do so:

esphome run CONFIGURATION_FILE.yaml

Flashing an ESP device for the first time

The most challenging part of working with ESPHome is loading the software on the chip for the first time. Once that is done, further updating is easily achieved over WiFi. But the first step is challenging because you need to physically connect the device to your computer. Depending on the device, use one of the three methods described below (from easy to difficult):

  • USB flashing. Some ESP devices (e.g. Atom Lite) have a USB interface and built-in UART functionality. This makes it super easy to flash the device. Just use a standard USB cable and you’re done.
  • Exposed headers to UART. Some devices (e.g. Shelly RGBW2) have exposed headers for TX, RX, Power, Ground, and GPIO0. Connect Ground and GPIO0 together, and connect TX, RX, Power, and Ground to (respectively) RX, TX, Power, and Ground on a standard TTL-to-USB adapter (make sure it’s set to 3.3V!) and connect the UART adapter to your computer using a standard USB cable and you’re in business.
  • Soldering to UART. Some devices don’t have exposed headers (e.g. 4ch relay board). In that case you need to solder a wire directly to the TX, RX and GPIO0 pins on the ESP chip. Example. Needless to say, this is a major pain and to be avoided if at all possible. We wasted countless hours doing this.

ESPHome configuration and organization

Here are some tips on how to manage your ESPHome configuration, especially if you followed the manual install like we did:

  • WiFi access. we set up a local WiFi access point in our home with the same name as the WiFi network in the RV. This allows us to work on any sensor outside of the RV before we install it in its final location.
  • Secrets. Never store passwords or other sensitive information in your configuration.yaml files. Instead, create a separate secrets.yaml file and link it from your main configuration.yaml.
  • Packages. This is a very useful feature of ESPHome. It allows us to package pieces of reusable code together in a single file and just add the file name to the main configuration.yaml. It also supports nesting.
    • At the lowest level, we package all basic sensors together (e.g. sensors for IP address, WiFi strength, restart, etc.) as well as all base connectivity details (MQTT connection, WiFi connection, etc.)
    • At the level above that, we package all the functionality of a specific device together (e.g. an Atom Lite device has 1 button, an i2c port and 1 light)
    • At the top level, we specify the specific use case/name of a specific device (e.g. bedroom environmental sensor, living room environmental sensor).
  • Github. We use a linked Github repository to manage our code base. This is very useful, especially when working from more than one computer. I can work from anywhere and always have access to my most recent code base. Check out our code base. It’s public and open source. See how the packaging structure works in practice:
  • Remote Updating. Updating sensors while not physically in the RV or connected to the local RV network can be a challenge when ESPHome does not run locally. There is a way around this:
    • Set up remote VPN access to your local RV network. We use OpenVPN to achieve this.
    • Make sure your Home Assistant dashboard shows the IP addresses of each smart device (add ip_address text sensor to your ESPHome config)
    • Use that IP address to update your ESPHome code by overriding the .local domain name addressing:
      esphome run config.yaml --device IP_ADDRESS