Splitting up the configuration

So you’ve been using Home Assistant for a while now and your configuration.yaml file brings people to tears or you simply want to start off with the distributed approach, here’s how to “split the configuration.yaml” into more manageable (read: humanly readable) pieces.

First off, several community members have sanitized (read: without api keys/passwords etc) versions of their configurations available for viewing, you can see a list of them here.

As commenting code doesn’t always happen, please read on for the details.

Now despite the logical assumption that the configuration.yaml will be replaced by this process it will in fact remain, albeit in a much less cluttered form.

In this lighter version we will still need what could be called the core snippet:

homeassistant:# Name of the location where Home Assistant is runningname:My Home Assistant Instance# Location required to calculate the time the sun rises and setslatitude:37longitude:-121# 'metric' for Metric, 'imperial' for Imperialunit_system:imperial# Pick yours from here: http://en.wikipedia.org/wiki/List_of_tz_database_time_zonestime_zone:America/Los_Angelescustomize:!includecustomize.yaml

Note that each line after homeassistant: is indented two (2) spaces. Since the configuration files in Home Assistant are based on the YAML language, indentation and spacing are important. Also note that seemingly strange entry under customize:.

!include filename.yaml is the statement that tells Home Assistant to insert the contents of filename.yaml at that point. This is how we are going to break a monolithic and hard to read file (when it gets big) into more manageable chunks.

Now before we start splitting out the different components, let’s look at the other components (in our example) that will stay in the base file:

As with the core snippet, indentation makes a difference. The component headers (mqtt:) should be fully left aligned (aka no indent), and the parameters (broker:) should be indented two (2) spaces.

While some of these components can technically be moved to a separate file they are so small or “one off’s” where splitting them off is superfluous. Also, you’ll notice the # symbol (hash/pound). This represents a “comment” as far as the commands are interpreted. Put another way, any line prefixed with a # will be ignored. This makes breaking up files for human readability really convenient, not to mention turning off features while leaving the entry intact. (Look at the zigbee: entry above and the b entry further down)

Now, lets assume that a blank file has been created in the Home Assistant configuration directory for each of the following:

automation.yaml will hold all the automation component details. zones.yaml will hold the zone component details and so forth. These files can be called anything but giving them names that match their function will make things easier to keep track of.

This small example illustrates how the “split” files work. In this case, we start with a “comment block” identifying the file followed by two (2) device tracker entries (owntracks and nmap). These files follow “style 1” that is to say a fully left aligned leading entry (- platform: owntracks) followed by the parameter entries indented two (2) spaces.

It is important to note that each file must contain only one entry when using !include_dir_list.
It is also important to note that if you are splitting a file after adding -id: to support the automation UI,
the -id: line must be removed from each of the split files.

Example: !include_dir_named

configuration.yaml

alexa:intents:LocateIntent:action:service:notify.pushoverdata:message:Your location has been queried via Alexa.speech:type:plaintexttext:>{%- for state in states.device_tracker -%}{%- if state.name.lower() == User.lower() -%}{{ state.name }} is at {{ state.state }}{%- endif -%}{%- else -%}I am sorry. Pootie! I do not know where {{User}} is.{%- endfor -%}WhereAreWeIntent:speech:type:plaintexttext:>{%- if is_state('device_tracker.iphone', 'home') -%}iPhone is home.{%- else -%}iPhone is not home.{% endif %}

can be turned into:

configuration.yaml

alexa:intents:!include_dir_namedalexa/

alexa/LocateIntent.yaml

action:service:notify.pushoverdata:message:Your location has been queried via Alexa.speech:type:plaintexttext:>{%- for state in states.device_tracker -%}{%- if state.name.lower() == User.lower() -%}{{ state.name }} is at {{ state.state }}{%- endif -%}{%- else -%}I am sorry. Pootie! I do not know where {{User}} is.{%- endfor -%}