ESPHome Core Configuration

Here you specify some core information that ESPHome needs to create firmwares. Most importantly, this is the section of the configuration where you specify the name of the node, the platform and board you’re using.

# Example configuration entry
esphome:
    name: livingroom
    platform: ESP32
    board: nodemcu-32s

Configuration variables:

  • name (Required, string): This is the name of the node. It should always be unique in your esphome network. May only contain upper/lowercase characters, digits and underscores. See Changing ESPHome Node Name.
  • platform (Required, string): The platform your board is on, either ESP32 or ESP8266. See arduino_version.
  • board (Required, string): The board ESPHome should specify for platformio. For the ESP32, choose the appropriate one from this list and use this list for ESP8266-based boards. This only affects pin aliases and some internal settings, if unsure choose the generic board option!

Advanced options:

  • arduino_version (Optional): The version of the arduino framework to link the project against. See arduino_version.
  • build_path (Optional, string): Customize where ESPHome will store the build files for your node. By default, ESPHome puts all platformio project files under a folder <NODE_NAME>/, but you can customize this behavior using this option.
  • platformio_options (Optional, mapping): Additional options to pass over to platformio in the platformio.ini file. See platformio_options.
  • use_custom_code (Optional, boolean): Whether to configure the project for writing custom components. This sets up some flags so that custom code should compile correctly
  • includes (Optional, list of files): A list of C[++] files to include in the main (auto-generated) sketch file for custom components. The paths in this list are relative to the directory where the YAML configuration file is in. Should have file extension .h - See includes for more info.
  • libraries (Optional, list of libraries): A list of platformio libraries to include in the project. See platformio lib install.

ESP8266 Options:

  • esp8266_restore_from_flash (Optional, boolean): Whether to save & restore data from flash on ESP8266s. Defaults to no. See esp8266_restore_from_flash for more info

Automations:

  • on_boot (Optional, Automation): An automation to perform when the node starts. See on_boot.
  • on_shutdown (Optional, Automation): An automation to perform right before the node shuts down. See on_shutdown.
  • on_loop (Optional, Automation): An automation to perform on each loop() iteration. See on_loop.

arduino_version

ESPHome uses the arduino framework internally to handle all low-level interactions like initializing the WiFi driver and so on. Unfortunately, every arduino framework version often has its own quirks and bugs, especially concerning WiFi performance. With the arduino_version option you can tell ESPHome which arduino framework to use for compiling.

# Example configuration entry
esphome:
  # ...
  # Default: use the recommended version, usually this equals
  # the latest version.
  arduino_version: recommended

  # Use the latest stable version
  arduino_version: latest

  # Use the latest staged version from GitHub, try this if you have WiFi problems
  arduino_version: dev

  # Use a specific version
  arduino_version: 2.3.0

For the ESP8266, you currently can manually pin the arduino version to these values (see the full list of arduino frameworks here):

For the ESP32, there are these arduino framework versions:

esp8266_restore_from_flash

With this option you can control where the state of certain components is kept on the ESP. Components like light, switch, fan and globals can restore their state upon boot.

However, by default this data is stored in the “RTC memory” section of the ESP8266s. This memory is cleared when the ESP8266 is disconnected from power. So by default the state cannot be recovered after power loss.

To still have these components restore their state upon power loss the state can additionally be saved in flash memory by setting this option to true.

Beware: The flash has a limited number of write cycles (usually around 100 000), after that the flash section will fail. So do not use this option when you have components that update rapidly. These include GPIO switches that are used internally (disable restoring with the restore_mode option), certain light effects like random and the on_value_range trigger.

on_boot

This automation will be triggered when the ESP boots up. By default, it is executed after everything else is already set up. You can however change this using the priority parameter.

esphome:
  # ...
  on_boot:
    priority: -10
    # ...
    then:
      - switch.turn_off: switch_1

Configuration variables:

  • priority (Optional, float): The priority to execute your custom initialization code. A higher value means a high priority and thus also your code being executed earlier. Please note this is an esphome-internal value and any change will not be marked as a breaking change. Defaults to -10. Priorities (you can use any value between them too):
    • 800.0: This is where all hardware initialization of vital components is executed. For example setting switches to their initial state.
    • 600.0: This is where most sensors are set up.
    • 250.0: At this priority, WiFi is initialized.
    • 200.0: Network connections like MQTT/native API are set up at this priority.
    • -100.0: At this priority, pretty much everything should already be initialized.
  • See Automation.

on_shutdown

This automation will be triggered when the ESP is about to shut down. Shutting down is usually caused by too many WiFi/MQTT connection attempts, Over-The-Air updates being applied or through the Deep Sleep Component.

Note

It’s not guaranteed that all components are in a connected state when this automation is triggered. For example, the MQTT client may have already disconnected.

esphome:
  # ...
  on_shutdown:
    then:
      - switch.turn_off: switch_1

Configuration variables: See Automation.

on_loop

This automation will be triggered on every loop() iteration (usually around every 16 milliseconds).

esphome:
  # ...
  on_loop:
    then:
      # do something

platformio_options

Platformio supports a number of options in its platformio.ini file. With the platformio_options parameter you can tell ESPHome what options to pass into the env section of the platformio file (Note you can also do this by editing the platformio.ini file manually).

You can view a full list of platformio options here: https://docs.platformio.org/en/latest/projectconf/section_env.html

# Example configuration entry
esphome:
  # ...
  platformio_options:
    upload_speed: 115200
    board_build.f_flash: 80000000L

includes

With includes you can include source files in the generated platformio project. All files declared with this option are copied to the project each time it is compiled.

You can always look at the generated platformio project (<CONFIG_DIR>/<NODENAME>) to see what is happening - and if you want you can even copy the include files directly into the src/ folder. The includes option is only a helper option that does that for you.

# Example configuration entry
esphome:
  # ...
  includes:
    - my_switch.h

This option behaves differently depending on what the included file is pointing at:

  • If the include string is pointing at a directory, the entire directory tree is copied over to the src/ folder.
  • If the include string is point at a header file (.h, .hpp, .tcc) - it is copied in the src/ folder AND included in the main.cpp. This way the lambda code can access it.
  • If the include str

Changing ESPHome Node Name

Trying to change the name of a node or its address in the network? You can do so with the use_address option of the WiFi configuration.

Change the device name or address in your YAML to the new value and additionally set use_address to point to the old address like so:

# Step 1. Changing name from test8266 to kitchen
esphome:
  name: kitchen
  # ...

wifi:
  # ...
  use_address: test8266.local

Now upload the updated config to the device. As a second step, you now need to remove the use_address option from your configuration again so that subsequent uploads will work again (otherwise it will try to upload to the old address).

# Step 2
esphome:
  name: kitchen
  # ...

wifi:
  # ...
  # Remove or comment out use_address
  # use_address: test8266.local

The same procedure can be done for changing the static IP of a device.