Edit Configuration

Programming A ESPHome Device By Describing Its Hardware

Once you added a new device to ESPHome Dashboard, you are now ready to program its microcontroller - without actually writing a single line of code. Instead, you describe your hardware to ESPHome.

Here is the typical workflow:

  • Adjusting Configuration: edit the default configuration of an ESPHome device, and describe the attached hardware it uses.
  • Install Updated Firmware: let ESPHome create new firmware based on your updated configuration, and upload it wirelessly to your microcontroller

It is really this simple.

Prerequisites

This article assumes that you already completed these steps:

Recap: How To Successfully Provision A New EspHome Device

Let’s recap the process of one of the many ways to initialize a new microcontroller in ESPHome:

  1. Create New Device: inside the ESPHome Dashboard, create a new device during which you will be asked to name your project, and to select the type of microcontroller you are using. At the end of the creation process, the dialog offers to Install the created firmware to your microcontroller. Choose Skip.

  2. Microcontrollers that you have previously provisioned and that are powered on will be marked with ONLINE in the tiles’ upper right corner. Your newly added configuration hasn’t yet been uploaded to any microcontroller, so it is obviously still marked as OFFLINE:

  1. Now your actual microcontroller is provisioned: the automatically created firmware needs to be uploaded for the first time. This initial provisioning requires that you connect the microcontroller via USB cable to the computer running ESPHome. Then click the three dot menu, and choose Install:

  1. This invokes the firmware upload tool. Choose Plug into the computer running ESPHome Dashboard, and select the USB port the microcontroller is connected to:

  1. Now the firmware is compiled and will be uploaded to your microcontroller. You see a terminal window that logs every step, similar to what you would see in a manual IDE like platformio.

  1. In the dialog showing the terminal window, click STOP to no longer listen to the status messages. In your ESPHome Dashboard, your microcontroller will now be marked ONLINE: it is now running the ESPHome firmware that you just uploaded.

If this quick guide did not work for you, start with provisioning a new microcontroller.

Editing The Configuration

To open and view the configuration of an ESPHome device, click EDIT. This opens its current configuration in the editor.

Do not touch the default configuration (unless you know what you are doing and would for example like to rename your project, or change its WiFi connection).

Move to the end of the configuration, and begin adding new lines that describe the additional components that your project is using. How that is accomplished, and what exactly you add to your configuration will be explained in great detail in these examples.

When you edit a configuration, always make sure you click SAVE in the upper right corner when you are done. Closing the editor without saving immediately discards all changes without confirmation.

Validating Edited Configuration

Once you changed a configuration, always validate it immediately after closing the editor: click the three-dot menu in the ESPHome device tile, and then click Validate.

If your configuration is formally ok, the validation result should always be Configuration is valid!. If you get errors instead, these are the top two reasons:

Caveat: Indentation

A configuration really is a tree-like hierarchical structure using YAML format: items are grouped by indentation. That’s why correct item order and strict indentation is crucial.

This is a typical error message that may bite you:

mapping values are not allowed here
  in "/config/esphome/push-button.yaml", line 35, column 18

It essentially translates to: ESPHome came across key words that did not make sense at that position. So most likely, they are in the wrong order, or due to wrong indentation, they were misinterpreted.

Here is an example of such a configuration (don’t focus on the details, just look at the general structure):

binary_sensor:
  - platform: gpio
    pin: GPIO4
         inverted: true
    name: Pushbutton1
    filters: - delayed_on: 10ms
             - delayed_off: 10ms
    mode:
        input: true
        pullup: true

This is how the configuration should have been formatted:

binary_sensor:
  - platform: gpio
    name: Pushbutton1
    pin: 
        number: GPIO4
        inverted: true
        mode:
          input: true
          pullup: true
    filters: 
      - delayed_on: 10ms
      - delayed_off: 10ms

As you see, the order, the indentation, and thus the grouping is essential for ESPHome to correctly understand your input.

Breaking Changes

From time to time, ESPHome receives updates. Occasionally, these updates introduce breaking changes. So when you update ESPHome and your existing configurations no longer work and suddenly produce validation errors like the one below, most likely the general ESPHome formatting rules have changed:

Failed config

ota.unknown: [source /config/esphome/push-button.yaml:19]
  
  'ota' requires a 'platform' key but it was not specified.

The breaking change in this example was introduced with ESPHome version 2024.6.0. Until then, OTA was defined like this:

ota:
  password: "..."

Beginning with version 2024.6.0, it now needs to be defined like so:

ota:
  - platform: esphome
    password: "..."

Unfortunately, ESPHome does not fix such formatting changes automatically. Instead, you need to manually adjust all of your existing configurations. Newly created devices will automatically use the new format.

Uploading Configuration

Once your updated configuration is validated, it is time to upload it to your microcontroller and put it to work:

  1. In ESPHome Dashboard, make sure your microcontroller is marked ONLINE. Click the three-dot menu, and choose Install.

  2. Since your microcontroller has already been provisioned, you can choose Wirelessly, and upload the new firmware conveniently via OTA (over-the-air).

  3. ESPHome compiles the new firmware and then uses OTA to wirelessly transfer the new firmware to your microcontroller:

  1. Once the firmware is installed, click STOP to close the terminal window. Verify that your microcontroller is labeled ONLINE in ESPHome Dashboard, indicating that it booted correctly with the new firmware.

You just successfully re-programmed your microcontroller - without writing any code.

Slow Website?

This website is typically very fast, and pages should appear instantly. If this site is very slow for you, then your routing may be messed up, and this issue does not only affect done.land, but potentially a few other websites and downloads as well. Here are simple steps to speed up your Internet experience and fix issues with slow websites and downloads..

Comments

Please do leave comments below. I am using utteran.ce, an open-source and ad-free light-weight commenting system.

Here is how your comments are stored

Whenever you leave a comment, a new github issue is created on your behalf.

  • All comments become trackable issues in the Github Issues section, and I (and you) can follow up on them.

  • There is no third-party provider, no disrupting ads, and everything remains transparent inside github.

Github Users Yes, Spammers No

To keep spammers out and comments attributable, all you do is log in using your (free) github account and grant utteranc.es the permission to submit issues on your behalf.

If you don’t have a github account yet, go get yourself one - it’s free and simple.

If for any reason you do not feel comfortable with letting the commenting system submit issues for you, then visit Github Issues directly, i.e. by clicking the red button Submit Issue at the bottom of each page, and submit your issue manually. You control everything.

Discussions

For chit-chat and quick questions, feel free to visit and participate in Discussions. They work much like classic forums or bulletin boards. Just keep in mind: your valued input isn’t equally well trackable there.

  Show on Github    Submit Issue

(content created Jun 10, 2024 - last updated Jul 12, 2024)