How to create generic ESPHome Configuration files

by Pete
Published: Updated: 8 minutes read

ESPHome is a powerful tool for creating custom firmware for ESP8266 and ESP32 microcontrollers. With ESPHome, you can create configuration files that define sensors, switches, lights, and more. These configuration files can be easily adapted and reused across different devices, making it easy to create generic ESPHome configurations. By creating generic configuration files, you can save time and effort in setting up new devices and ensure consistency across your entire project.

In this guide, we’ll explore the benefits of generic ESPHome configurations and show you how to create your own.

Let’s get into it

For every new project, or new sensor I buy, there’s always additional code that needs to be copied over to numerous devices and it all gets confusing, and is prone to errors.

That’s why I created a series of global and reusable configs for components, devboards, products and even Home Assistant files to save me from retyping in the same configs over and over again.

1
Install ESPHome

In case you haven’t install ESPHome. You can do this by installing the ESPHome addon from the Addon Store within Home Assistant.

What esphome looks like when running.

2
Directory structure

Under /config/esphome, I created a folder called common.

There, that’s where my device structure begins. You can create your structure by installing the Samba Share addon, or SSH to the docker instance by installing the Terminal & SSH addon.

I created the following directory structure under common/ where I’d place common configuration files in each that I can use on either esp8266 or esp32 boards.

3
The four common ESPHome functions

You’ve find that most functions sit within these 4 ESPHome categories:

  1. Binary Sensor (or binary_sensor:). This is a component that represents a simple sensor that can have only two states: “on” or “off”.
  2. Switch (or switch:). This is a component that represents a physical or virtual switch that can be used to turn a device on or off.
  3. Text Sensor (or text_sensor:). This is a component that represents a sensor that returns a text value, such as a temperature, humidity, or air quality reading.
  4. Sensor (or sensor:). This is a component that represents a single sensor that measures a physical quantity and provides the measured value to the ESPHome device.

4
Common Files / Features

I found, by experience, that I tend to use the same ESPHome functions like:

  • Status
  • Wifi-Signal
  • Device Restart
  • ESPHome Version

These 4 functions became separate yaml files like so within the /common/devboards/esp32 folder

esp32_binary_common.yaml

  - platform: status
    name: "$device_name Status"

esp32_switch_common.yaml

  - platform: restart
    name: "$device_name Restart"

esp32_text_common.yaml

  - platform: version
    name: "$device_name ESPHome Version"
    hide_timestamp: true

esp32_sensor_common.yaml

  - platform: wifi_signal
    name: "$device_name WiFi Signal Sensor"
    update_interval: 300s

5
Putting it all together in an ESPHome device configuration file

There are some items I keep within my ESP32 yaml files within ESPHome. I suppose you could separate these out too, but the idea (mine anyway), is to use substitutions, and common code files to make a consistent experience – this is especially important when you start to have large device counts.

# ESP32 Exmaple
### Substitutions ###
substitutions:
  device_name: esp32s01
  location: Garage
esphome:
  platform: ESP32
  board: nodemcu-32s
  name: $device_name
 
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  
  # Optional manual IP
  manual_ip:
    static_ip: 10.0.0.38
    gateway: 10.0.0.254
    subnet: 255.255.255.0
  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "$device_name Fallback Hotspot"
    password: !secret ap_password
captive_portal:
# Enable logging
logger:
# Enable Home Assistant API
api:
ota:
##### Include Global Custom Files
<<: !include common/devboards/esp32/esp32_common.yaml
sensor:
  - <<: !include common/devboards/esp32/esp32_sensor_common.yaml  
binary_sensor:  
  - <<: !include common/devboards/esp32/esp32_binary_common.yaml
switch: 
  - <<: !include common/devboards/esp32/esp32_switch_common.yaml
text_sensor: 
  - <<: !include common/devboards/esp32/esp32_text_common.yaml 

You’ll note that instead of typing in the device name numerous times, the substitution and associated variable of $device_name takes care of any reference for us, even when we’re including configuration files.

6
What we end up with

When we compile the firmware for this device, if all goes well, you should see these entities appear. And no matter how many ESP devices you have, the naming will always be the same – which is awesome for creating Dashboards and automatons down the track.

Device Configuration
Configuration item that includes Firmware version (comparing the server) and a device restart switch
Device entities
Information about the current firmware version, is the device connected to the API, and a Wi-Fi signal sensor

In Conclusion

Creating generic ESPHome configuration files can save time and effort by enabling easy reusability of code across different projects. This can be achieved by breaking down the configuration files into separate components and using includes to reference them in different projects.

Additionally, the use of templates and placeholders can further enhance the generic nature of the configuration files, making it easier to customize them for specific use cases. By following these practices, developers can improve their efficiency and productivity in creating ESPHome-based projects.