ESPHome Setup

ESPHome is a simple way to program complex actions for ESP32 and ESP8266 devices, all coded in YAML, the same as Home Assistant. It’s great for smart home enthusiasts and makers who want to create a smart device quickly and easily.

Installation

While you write ESPHome in YAML, you can’t just put a YAML file on an ESP32 board and expect it to work, which is why ESPHome YAML files are compiled into a binary that is actually Arduino (C++) or ESP-IDF code. There are two ways to install ESPHome for development, and I find local development easier than the GUI based version available through the ESPHome Device Builder. While the Device Builder is good for those new to coding and not comfortable with the command line, I find it more difficult to debug and get working in the first place. It requires you to physically connect your ESP device to the server running Home Assistant the first time, which can be a hassle if you’re working on a project that is big or bulky or difficult to move around. I also find that OTA updates are difficult to get working for me, so I prefer to flash ESP devices the old-fashioned way by connecting to my computer instead. This guide will only be detailing the manual local development method, so if you want to install the device builder I recommend following this guide instead.

Without further adieu, let’s get started.

Prerequisites

• Python 3.9+ (make sure to add Python to your PATH)
• Pip or sudo apt-get install python3-pip or a similar method

Installing ESPHome

Installation is fairly simple through pip: pip3 install esphome or pip install esphome. If you get an error on linux saying that there is an externally managed environment, you should probably install it in a virtual environment, but I just run pip3 install esphome --break-system-packages and it works fine, although you may have to add the install location to your PATH, which is another can of worms. Be sure to note though, that the ESPHome folks don’t support this method, so you should create a virtual environment and install it there, using

python3 -m venv venv
source venv/bin/activate
pip3 install esphome

Setting up your development environment

If you’re using VS Code you can install the ESPHome extension for better validation of YAML. Here’s some example YAML that I’ll be flashing to my microcontroller:

# Board Setup
esp32:
  board: esp32-s3-devkitc-1
  variant: esp32s3
  flash_size: 4MB

# ESPHome name definitions
esphome:
  name: example
  friendly_name: Example

# Networking Setup
wifi:
  networks:
    - ssid: "Your WiFi SSID"
      password: "Your WiFi Password"
    
  ap:

logger: # Sets up logging for any errors
api: # Allows HA to use the native ESPHome API
captive_portal: # Allows you to manually add WiFi networks if none are found.

light:
  - platform: neopixelbus
    type: GRB
    variant: WS2812
    pin: GPIO1
    num_leds: 10
    name: "Strip Lights"

I’ve attached a NeoPixel strip to my ESP32 device as an example. You can upload this code to your ESP32 device by running esphome run example.yaml. If you already know which serial port your ESP32 device is connected to, you can run esphome run example.yaml --device /dev/ttyACM0 instead. You may then have to press the reset button or physically unplug and replug your ESP device to get it to start running your new code. If you want to, you can then see the logs from it by running esphome logs example.yaml. You can also append --device /dev/ttyACM0 if you already know the serial port it will connect to.

Bonus Tips

I like not having to type out the same commands every time I want to reflash code to my ESP32 device for testing, so I use a short bash/zsh configuration to make it easier:

alias u='esphome run "$ESPHOME_FILE" --device "$ESPHOME_PORT"'
alias ur='esphome run "$ESPHOME_FILE" --device "$ESPHOME_PORT" ; esphome logs "$ESPHOME_FILE" --device "$ESPHOME_PORT"'
alias r='esphome logs "$ESPHOME_FILE" --device "$ESPHOME_PORT"'

You can add this to your bash profile (~/.bashrc) or zsh profile (~/.zshrc) to make it easier to run, or create a file and paste it into your code folder for the project. Then each time you open a new terminal you just have to configure the ESPHOME_FILE and ESPHOME_PORT environment variables (export ESPHOME_FILE=example.yaml and export ESPHOME_PORT=/dev/ttyACM0), run source <filename>, and then you can just run ur to flash the code and view the logs.

Conclusion

I hope this guide was helpful for you in installing ESPHome and getting started with it. I really like using ESPHome because I think it’s a great way to get started with IoT devices, and can do some pretty complex stuff if you want it to. It can be a Voice Assistant with a display, control a HVAC system with relays, or just control some LEDs.