How to publish/share ESPHome device configurations


Currently I am working on my first ESPHome project: automating my (non-smart) lawn mower robot.
Now I am getting up to the point that the lack of version control on my project is starting to itch. So I would like to put my YAML on github.

It would be nice to make it public, so that others can make use of it as well.
Now this page gives some pointers on what not to publish (like secrets and keys). But what do I have to modify in my YAML to make it suitable for publication and what will a user (and future me) have to do to make use of the published YAML?

e.g. the api encryption key in my YAML sounds like an essential part. But also one that I should not publish.

Remove anything specific to your config on everything you publish on GitHub.

Use substitutions to insert those specifics into the yaml when compiling to code…

The ESPHome webpage you linked to pretty much contains all info you need. You may have to read it multiple times before you fully understand in my experience :grin:

Put it on

Thanks for the responses. I will attempt to read the page a couple of more times :wink:
In the meanwhile, I will just publish the whole thing, with all local specifics redacted. It is version control, so I can update it to be more correct anytime :slightly_smiling_face:

Thanks for the tip on, not sure if it applies though; my project is not a product, it is a DIY addon for a lawn mower robot.

Use secrets for anything sensitive, and keep your secrets off public GitHub.

I have published my lawn mower ESPHome project here:

It is still unclear to me, how to a user should install it though :face_with_diagonal_mouth:

I did the following:

  • Add new device in ESP home web interface
  • Copy paste the yaml code into the editor
  • Filled in the wifi SSID and password in the yaml code :woozy_face:
  • Manually filled in a (random) API key (not needed I guess?)
  • When the mower came online, I could “adopt” it
  • Adopting the mower created a new ESP Home device, so I deleted the other ESP Home device.
  • Finally, it prompted that an updated configuration was available, so I installed that.

Is this how a new user should go about installing a shared ESP home configuration? Or am I missing something here…

1 Like

Nice hack;)

I think what you’ve done is fine for your first project (and quite advanced really).

Since it’s a yaml based project, your copy/paste approach to setting up a new ESPHome node and the project is not too uncommon and probably fine for now.

I think a lot of users flash a bare bones config, get OTA, then add details of the project, then flash that. Well that’s what I do.

Anyone who’s used ESPHome before would probably be fine, new users would need to be pointed to basic getting started instructions.

1 Like

Depends a little whether a seller (eg Athom) supply a device with adoptable firmware on it, or if you are offering a diy project which people have to do an initial flash on.

1 Like

Thanks :slight_smile:
I found a few projects that provide a web-serial based installer, that flashes a binary from a github pipeline into the ESP. That would be somewhat overkill for me.

Also I suspect that the first new users (if any :sweat_smile:) will probably need to make some adjustments, for the project to perform well in their setup.

Sadly the second D1 Mini I ordered was DOA, so I cannot really experiment with the initial setup process (unless I want to reassemble my mower over and over again)