esphomeyaml Core Configuration

Here you specify some core information that esphomeyaml 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
esphomeyaml:
    name: livingroom
    platform: ESP32
    board: nodemcu-32s

Configuration variables:

  • name (Required, string): This is the name of the node. It should always be unique to the node and no other node in your system can use the same name. It can also only contain upper/lowercase characters, digits and underscores.
  • platform (Required, string): The platform your board is on, either ESP32 or ESP8266. See arduino_version.
  • board (Required, string): The board esphomeyaml should specify for platformio. For the ESP32, choose the appropriate one from this list and use this list for ESP8266-based boards.

Advanced options:

  • esphomelib_version (Optional): The version of the C++ esphomelib framework to use. See esphomelib_version.
  • arduino_version (Optional): The version of the arduino framework to link the project against. See arduino_version.
  • build_path (Optional, string): Customize where esphomeyaml will store the build files for your node. By default, esphomeyaml puts all platformio project files under a folder <NODE_NAME>/, but you can customize this behavior using this option.
  • 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

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.

esphomelib_version

With the esphomelib_version parameter you can tell esphomeyaml which version of the C++ framework to use when compiling code. For example, you can configure using the most recent (potentially unstable) version of esphomelib straight from github. Or you can configure the use of a local copy of esphomelib using this configuration option.

First, you can configure the use of either the latest esphomelib stable release (latest), the latest development code from GitHub (dev), or a specific version number (1.8.0).

# Example configuration entry
esphomeyaml:
  # ...
  # Use the latest esphomelib stable release
  esphomelib_version: latest

  # Or use the latest code from github
  esphomelib_version: dev

  # Use a specific version number
  esphomelib_version: 1.8.0

Alternatively, if you want to develop for esphomelib, you can download the latest code from GitHub, extract the contents, and point esphomeyaml to your local copy. Then you can modify the esphomelib to your needs or to fix bugs.

# Example configuration entry
esphomeyaml:
  # ...
  # Use a local copy of esphomelib
  esphomelib_version:
    local: path/to/esphomelib

And last, you can make esphomeyaml use a specific branch/commit/tag from a remote git repository:

# Example configuration entry
esphomeyaml:
  # ...
  # Use a specific commit/branch/tag from a remote repository
  esphomelib_version:
    # Repository defaults to https://github.com/OttoWinter/esphomelib.git
    repository: https://github.com/OttoWinter/esphomelib.git
    branch: master

  esphomelib_version:
    repository: https://github.com/somebody/esphomelib.git
    commit: d27bac9263e8a0a5a00672245b38db3078f8992c

  esphomelib_version:
    repository: https://github.com/OttoWinter/esphomelib.git
    tag: v1.8.0

arduino_version

esphomelib 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 esphomeyaml which arduino framework to use for compiling.

# Example configuration entry
esphomeyaml:
  # ...
  # 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):

Warning

Over-the-Air update passwords do not work with the arduino framework version 2.3.0

For the ESP32, there’s currently only one arduino framework version: 1.0.0.

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.

esphomeyaml:
  # ...
  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 (for example positive values) mean a high priority and thus also your code being executed earlier. So for example negative priorities are executed very late. Defaults to -10. Priorities (you can use any value between them too):
    • 100: This is where all hardware initialization of vital components is executed. For example setting switches to their initial state.
    • 50.0: This is where most sensors are set up.
    • 10: At this priority, WiFi is initialized.
    • 7.5: MQTT initialization takes place at this priority.
    • -5.0: The individual frontend counterparts for the backend components are configured at this priority
    • -10.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.

esphomeyaml:
  # ...
  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).

esphomeyaml:
  # ...
  on_loop:
    then:
      # do something