How To Split Home Assistant Configuration YAML Dummies Guide

Are you finding that your configuration.yaml file is getting longer and more confusing?

Are you a person who likes to organise things into neat little categories and you feel the urge to bring order to your YAML configuration?

Look no further!

In this tutorial we will learn how to split the configuration.yaml file into a nice and neat file structure.

If you are obsessive about organisation then this post is definitely for you, because your house is perfectly organised, so why shouldn’t your smart home configuration match?!

Table of Contents

1. Prerequisite
2. Configuration YAML
3. File structure
   1. Including files
   2. Including directories
      1. Merging lists
      2. Merging dictionaries
   3. Secrets file
      1. Create a secrets.yaml file
      2. Add credentials
      3. Include secrets in the configuration
4. Conclusion

Prerequisite

If you are completely new to Home Assistant then I would recommend keeping everything in the configuration.yaml file, until you feel more confident with the way in which things work in Home Assistant.

As you build up knowledge and add more to your configuration, you will naturally reach the point where it becomes necessary to split the configuration.

If your configuration.yaml file is still quite empty, go ahead and check out some of my other Home Assistant tutorials, you will soon fill it up!

Configuration YAML

The configuration.yaml file is the main file that contains our Home Assistant configuration, located in the root directory.

/config/configuration.yaml

Within this file are all of the integrations that we wish to use in Home Assistant. We can represent the basic configuration with the following diagram.

Let’s look at an example configuration.yaml file.

Within a basic configuration we should find the default_config integration along with some of the other basic integrations.

# Siytek.com configuration.yaml

# Home Assistant required
default_config:

# Automations
automation:
  - alias: 'link LEDs to TV on'
    trigger:
      platform: state
      entity_id: media_player.massive_sony
      to: 'on'
    action:
        - service: light.turn_on
          entity_id: light.ledstriptvcab

# Scenes
scene:
  - name: downstairs movie
    entities:
       light.treelamp:
          state: on
          brightness_pct: 30
  - name: downstairs work
     entities:
        light.treelamp:
           state: on
           brightness_pct: 30

This configuration.yaml file contains a single automation and two scenes and would likely look quite complex to a new user. It is easy to see how this file could get very long, very quickly!

File structure

So how can we split this up into more manageable chunks? We can simply move sections of our code into separate files in order to make a tree structure.

If we take our example above, we can split it into three separate files. Firstly we can move the automation and scene integrations to separate files.

# Automations
- alias: 'link LEDs to TV on'
  trigger:
    platform: state
    entity_id: media_player.massive_sony
    to: 'on'
  action:
      - service: light.turn_on
        entity_id: light.ledstriptvcab

# Scenes
- name: downstairs movie
  entities:
     light.treelamp:
        state: on
        brightness_pct: 30
- name: downstairs work
   entities:
      light.treelamp:
         state: on
         brightness_pct: 30

Including files

Now we can link these two new files using an !include statement in our configuration.yaml file.

# Siytek.com configuration.yaml

# Home Assistant required
default_config:

# Includes
automation: !include automation.yaml
scene: !include scene.yaml

Now our new configuration has three files with the automation and scene integration split into separate files. It is organised as shown in the following diagram. Note that all of these files are in the main /config directory.

This is a good method for dividing the configuration file up into separate files but as we can only have one instance of each integration, how can we divide things up further?

Including directories

Another way we can split the configuration is to include directories instead of files. In order to do this we need to keep the integrations in the configuration.yaml file, but point the integration to a directory in order to populate it.

Merging lists

When we specify a directory for a particular integration, all of the files within the directory will be merged. This allows us to split the integration into several files. Our automation file only has one list entry so it will remain the same as before.

# Automations
- alias: 'link LEDs to TV on'
  trigger:
    platform: state
    entity_id: media_player.massive_sony
    to: 'on'
  action:
      - service: light.turn_on
        entity_id: light.ledstriptvcab

However as we have two scenes, we will split these into two seperate files. We can do this by including each entry in the list in a separate file.

# Automations
- alias: downstairs movie
  trigger:
    platform: state
    entity_id: media_player.massive_sony
    to: 'on'
  action:
      - service: light.turn_on
        entity_id: light.ledstriptvcab

# Scenes 2 - Downstairs Work
- name: downstairs work
   entities:
      light.treelamp:
         state: on
         brightness_pct: 30

Now we will create a directory for the automations and a directory for the scenes in the /config directory. We will place the automation.yaml file in the directory for automations. Then we will place scene_1.yaml and scene_2.yaml into the scenes directory.

/config/automations
/config/scenes

Now we can include these directories in our configuration.yaml file. We will use the !include_dir_merge_list statement, which will merge all of the YAML files in the specified directory into one list.

See line 7 to 8:

# Siytek.com configuration.yaml

# Home Assistant required
default_config:

# Includes
automation: !include_dir_merge_list automations/
scene: !include_dir_merge_list scenes/

Now our file structure has two new directories along side the configuration.yaml file. In each directory is a set of YAML files for the associated integration.

Each time we wish to add a new integration, we can just add a new YAML file in the relevant directory. Note that the name of the file does not matter, all YAML files in the directory will be merged, regardless of their file name.

Merging dictionaries

We also need to consider how to merge integrations that are entered as a dictionary rather than a list. An example would be the script integration, so let’s take a look at an example. First we will create a directory for scripts.

/config/scripts

Now we will create two files in this new directory for two different scripts, which send out mobile notifications when the doors are opened.

front_door_open_push:
  alias: Front door open push notification
  description: 'Send a push notification for front door open'
  sequence:
    - alias: Send notification
      service: notify.mobile_app_iphone
      data:
        title: "Door Sensors"
        message: "Front door is open!"

back_door_open_push:
  alias: Back door open push notification
  description: 'Send a push notification for back door open'
  sequence:
    - alias: Send notification
      service: notify.mobile_app_iphone
      data:
        title: "Door Sensors"
        message: "Back door is open!"

Notice how each of the scripts begins with a dictionary definition rather than the list “-” operator?

# List
- alias: 'some cool automation list'

# dictionary
some_cool_script:

This means that we need to use the !include_dir_merge_named statement instead.

See line 9:

# Siytek.com configuration.yaml

# Home Assistant required
default_config:

# Includes
automation: !include_dir_merge_list automations/
scene: !include_dir_merge_list scenes/
script: !include_dir_merge_named scripts/

Apart from using a different statement to tell Home Assistant to merge the directory as a dictionary rather than a list, the end result is the same as with our example for automations and scenes. Now our structure looks like the following diagram.

Secrets file

Another way to tidy up your configuration is to move all of the keys, passwords and other sensitive data to one file.

This can be useful if you need to change any credentials and also if you want to make your configuration available to the public on Github.

It also makes it easier to quickly copy and paste into forums if you need help with your configuration and want to include it in a post, without worrying about accidently including your sensitive information!

Create a secrets.yaml file

In order to do this we need to create a secrets.yaml file in the config directory.

/config/secrets.yaml

Let’s look at an example using the Google integration for Google calendar. Here is the integration implemented in the configuration.yaml file with the client ID and client secret included in the file.

See line 12 to 14:

# Siytek.com configuration.yaml

# Home Assistant required
default_config:

# Includes
automation: !include_dir_merge_list automations/
scene: !include_dir_merge_list scenes/
script: !include_dir_merge_named scripts/

# Google Integration
google:
  client_id: 584938694594-51oj4gu6gkake18275ra78oki97uevkn.apps.googleusercontent.com
  client_secret: PfRtEsFa-bN3h-PofdESt4sw

Add credentials

In order to move the credentials to the secrets file, we must first create secrets.yaml and add a reference for each item we wish to include.

google_client_id: 584938694594-51oj4gu6gkake18275ra78oki97uevkn.apps.googleusercontent.com
google_client_secret: PfRtEsFa-bN3h-PofdESt4sw

Include secrets in the configuration

Now we can replace the credentials in our configuration.yaml file using the !secret statement.

See line 12 to 14:

# Siytek.com configuration.yaml

# Home Assistant required
default_config:

# Includes
automation: !include_dir_merge_list automations/
scene: !include_dir_merge_list scenes/
script: !include_dir_merge_named scripts/

# Google Integration
google:
  client_id: !secret google_client_id
  client_secret: !secret google_client_secret

Now that we have added our secrets file, our final example configuration is represented in the following diagram.

Conclusion

Home Assistant configurations can quickly get complicated as a lot of YAML must be added in order to add more functionality to the system.

Thankfully there is a simple yet sophisticated way to organise the data!

You should now have a basic understanding of how to split the configuration across different files and directories and now it is up to you how you choose to arrange your files.

Go ahead and add yet more YAML to your configuration by following some more of my awesome Home Assistant tutorials!