What is dashboard_import:?

ESPHome
1

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

dashboard_import:
  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??

2

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

3

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?

3 Likes
4

I also read that without understanding what dashboard_import is…

1 Like
5

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

2 Likes
6

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

7

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

Screenshot 2023-02-22 144925
Screenshot 2023-02-22 144925705×385 14 KB

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!

4 Likes
8

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.

9

You can import remote yaml files like this:

packages:
  # Git repo examples
  remote_package:
    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!

10

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.

11

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
12

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:

14

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:

15

Hello!

Sorry for replying to this older thread, but I have question that exactly fits to the following, because I have not completely understood the use of name_add_mac_suffix. I refer to the quoted post:

In my esp32.yaml (I have several ones for different projects), I use this:

esphome:
  name: ${name}
  friendly_name: ${friendly_name}
  min_version: 2024.6.0
  name_add_mac_suffix: true
  project:
    name: 7wells.my-project
    version: 1.0.0

dashboard_import:
  package_import_url: github://esphome/example-configs/esphome-web/esp32.yaml@main
  import_full_config: true

Till today, I used name_add_mac_suffix: true.

Now I wonder if this is correct in light of the quoted post. Is it?

Thanks for your help! :+1:

16

Configurations imported with package_import_url typically contain name_add_mac_suffix: true. If you don’t want it true in your local copy, simply override it with name_add_mac_suffix: false.

1 Like
17

Thanks, now it makes sense to me, too. :blush:

Apart from that: Does it make sense that I on the one hand import the package (and with import_full_config: true), whereas on the other hand I create my yaml further down all on my own?

18

imported package refer to some 3rd part yaml to be included in your own yaml.

Since i don’t like that, i normally copy/paste (and if required edit) that yaml to my own needs.

In that way I am certain the yaml remains ’as is’, as the referred yaml might have some changes the next time i compile (and i don’t get unwanted surprises)

1 Like
19

I am with @aceindy. Package imports leave you at the mercy of the developer. If their link goes dark, your device can’t be upgraded.

1 Like
20

You can always update your device to the latest ESPHome. But I do keep a version of the dashboard_import locally just in case I want to edit it.

1 Like
21

good find @stevemann :

:+1:t4: