Carlos Santos

iOS Dev

Homeassistant configuration structure

2019-04-25 3 mintech unsplash-logoChris Ried

I’ve been working on my Homeassistant config for quite a while now, so I would like to share my folder structure.

I’ve seen quite a lot of examples out there, and I tried to collect the best ideas of all of them, leveraging scalability of the tree of configurations and keeing it simple when I need to search for something there.

I’ll show you my structure and then I’ll give you some examples of the configs.

Folders πŸ—‚

Here’s an output of a tree -d call on my /hass-config folder:

β”œβ”€β”€ automations
β”œβ”€β”€ binary_sensors
β”œβ”€β”€ custom_components
β”œβ”€β”€ includes
β”‚   β”œβ”€β”€ lovelace
β”‚   └── packages
β”œβ”€β”€ scenes
β”œβ”€β”€ sensors
β”‚   └── templates
β”œβ”€β”€ switches
└── www

πŸ“‚ automations

Inside the automations folder, I keep a single file for each automation.

This is easier for SCM, and you’ll go exactly to the right file when you open the folder:

β”œβ”€β”€ fontdoor.yaml
β”œβ”€β”€ newupdate.yaml
β”œβ”€β”€ sunroom_movement.yaml
└── ...

Where, i.e., newupdate.yaml contains a single automation entry:

- id: 'home_assistant_update'
  initial_state: True
    platform: state
    entity_id: updater.updater
  - data:
      message: "New HomeAssistant Update available"
    service: telegram_bot.send_message

So, there are a lot of automation files, but how do we join them all? Quite easy, actually.

Your configuration.yaml file must contain the following:

automation: !include_dir_merge_list automations

This means that: every file contained inside automations folder, will be treated as an element of an array, so the contents of each file must contain a valid automation node.

The same process applies for binary_sensors, switches, scenes folders.

πŸ“‚ www

On this folder, I save my custom components, to use in Lovelace UI.

Things like:

custom_components πŸ“‚

In order to have my custom UI components up2date with their source code, I have my custom_updater script on this folder. As per docs, it β€œallows you to track and update custom cards or components and python scripts”.

Really handy πŸ‘Œ

πŸ“‚ includes/lovelace

In order to have my Lovelace UI configuration organized + keeping it scalable, I keep this folder as a source to feed my ui-lovelace.yaml, following this structure:

β”œβ”€β”€ main.yaml
β”œβ”€β”€ ...
β”œβ”€β”€ lights.yaml
β”œβ”€β”€ configuration.yaml

As main.yaml represents the root of the configuration, each yaml file is a tab on my Lovelace UI.

Here you can see how I call all these separate files, on my ui-lovelace.yaml file:

title: Home
  - url: /local/mini-graph-card-bundle.js # Here is a custom UI component
    type: module
  - url: /local/mini-media-player-bundle.js # Here is another custom UI component
    type: module
  - !include includes/lovelace/main.yaml # These are the files for
  - !include includes/lovelace/lights.yaml
  - !include includes/lovelace/configuration.yaml

Wrap up

There are a lot of config organizations you can use, but the best is the one that fits your needs.

So gather some ideas, read a lot of github user shared configurations, and you’ll eventually get your stuff organized too.

Most definitely you’ll learn some new cool automations that you didn’t know they were possible ✨.

It’s a process, not an immediate task.

I’ll be sharing my config soon, it’s it the process of being prepared to be open-source. ⏳

Sources πŸ“š

For more information on the best practices of splitting your massive configuration.yaml, check the following links: