What is dashboard_import:?

I am trying to understand the yaml file on an Athom switch, but this line makes little sense:

  package_import_url: github://athom-tech/athom-configs/athom-sw01.yaml

What is the purpose of this? The file on github is a copy of the yaml file, so I have two of each component??

You know the esphome docs are searchable right? Sharing ESPHome devices — ESPHome

Yes, and the explanation in the docs doesn’t tell me why this is in the YAML file. From what I read, I don’t need anything in my local yaml file because it’s all in the imported file?


I also read that without understanding what dashboard_import is…

1 Like

I think the main benefit is that ESPHome will detect updates from the creator.
ESPHome Dashboard Import for Easy Updates and Renaming - YouTube


I too would like to know what it does. The page doesn’t at all explain anything about it.

I can share my experience and hopefully clarify a few things. I have many Unity boards and they’re all flashed with the same config. They end up clashing with each other when they’re discovered by the ESPHome Dashboard (they all have the same hostname, logs cannot be accessed, OTA no longer work, etc…)

However, when package_import_url is used it provides the ESPHome Dashboard with more insight and allows the user to ‘adopt’ the config. See screenshot below.
Once adopted, a basic config will be created for the device with the package pointing to the publicly accessible package_import_url.

Now there are 2 important properties that you should be aware of:

  1. The name substitution is suffixed with the mac suffix. This fixes the issues with the duplicated hostnames (“unity.local” becomes “unity-14350c.local”). Without this substitution all devices will have the same hostname.
  2. name_add_mac_suffix is set to false. This is done because the name substitution supersedes the benefits of name_add_mac_suffix, so there is no longer any use for it. However, this must be included to override the public config where it is set to true.

Screenshot 2023-01-19 022351

Another benefit of dashboard_import is when the public config’s project version is incremented, ESPHome will detect there is an update.

Hope this helps!


Hi, thanks for your clarification. Do you also know how to manage a structure with more nested yaml and folders to import? shall I create a remote package for each file? Unfortunately I’m unaware how to link yaml located in subfolders.
In local it works great with includes. Thank you.

You can import remote yaml files like this:

  # Git repo examples
    url: https://github.com/esphome/non-existant-repo
    ref: main # optional
    files: [file1.yml, file2.yml]
    refresh: 1d # optional

It doesn’t look like it supports folder imports so you’ll need to specify each file.
I would experiment with including the directory in the files list. If it works then it could save you some time. For example: [folderA/file1.yml, folderB/file2.yml]

Reference: Configuration Types — ESPHome

Hope that helps!

Hi Loop,
I already tested the directory in this way [folderA/file1.yml, folderB/file2.yml] and it works. The problem is that I followed the nesting method provided by Jesse jesserockz/esphome-configs: My personal ESPHome config files (github.com) because I considered it would be used as a best practice in the further developement . It is a very smart method when you need to keep your configurations up to date with monthly esphome changelog.

For instance consider this scenario athom-tech/athom-configs: Athom Technology Official Center (github.com) where an hardware developer needs to mantain updated all his devices. What I’m trying to do is making:

  1. a common configuration for all my products
  2. a common configuration for frequently used entities I can include in an easy way where I need to
  3. a separate folder with custom and unique configs related to the speficic device (filters, custom templates etc).

Jesse’s methos is great when used in local, unfortunately at this time won’t work with dashboard import, with packages and finally you could not apply to Made for ESPHome — ESPHome unless you import each file wich is a big pain and I don’t think would let you to merge definitions properly.

As far as I notice, many hardware developers seems to be stuck at this point: Athom for instance has a unique long yaml for each device and as you can notice on their github they are stuck with last “friendly_name” breaking change.

Unfortunately I haven’t experienced these issues to be able to provide constructive advice :frowning: My configuration is fairly simple in comparison to what you’re trying to achieve. It only uses one external component from git and it allows users to update whenever I make a change.

1 Like

Yeah I was using your method before things became more complex.

Unfortunately as other manufacturer, I can’t mantain updates if we can’t go through this step :slightly_frowning_face:

If you follow the link to the yaml in question, you can see it is just an ordinary esp config…

Personally i wouldn’t use them like an import, but just copy what i need and create my own yaml from it :thinking: