A recent Feature Request got me thinking about cleaning up my automations to make them more readable.
The UI is a great way to create a simple new automation. You don’t need to know all the options and syntax, and you don’t need to know how to format proper YAML. The result is always a working autmation, which is stored in the automations.yaml
file. But eventually you’ll want to do something more complex which the UI isn’t good at, or you’ll find sample YAML on this forum for an automation you want to try.
When you go to edit the automatically generated YAML file, it can be a confusing mix of different, though perfectly legal, YAML structures. The UI generates random, numeric id’s for each automation. It doesn’t put blank lines or comments in, and it will delete those if you add them. It doesn’t order the automations in any logical sequence.
Luckily, HA allows you to use the !include
statement to break out your configuration into multiple files. By default, configuration.yaml
already has one such statement for automations:
automation: !include automations.yaml
I created a new include, and gave each a label:
automation ui: !include automations.yaml
automation manual: !include my_automations.yaml
I renamed automations.yaml
to my_automations.yaml
and created a new, blank automations.yaml
file. The UI will still add any new automations it creates to that new file, but it can never update my_automations.yaml
.
Note that nothing in my_automations
will be editable from within the UI, but frankly that seems more like a benefit than a limitation to me.
Now I have an automations file I can reformat to my own liking, without having the UI undo any of my changes. Right away I moved similar automations together, added a blank line between each automation, and added comments like this to break it up into sections:
#
# "Away" lighting automations
#
That made it easier to find and compare automations. I had some very confusing ones. YAML is pretty flexible, and all the different automations were created using different standards. Some came from the UI, while others were copied and pasted from samples I found on this forum.
Here’s an automation which I found confusing:
- id: '1568925959816'
alias: Away - Study Lamp Off 945
trigger:
- at: '21:45'
platform: time
condition: []
action:
- data: {}
service: switch.turn_off
target:
entity_id:
- switch.study_lamp_switch
initial_state: 'false'
mode: single
The logic just didn’t jump out at me. Settings for the automation were both at the top and at the bottom. The sequence of lines in the trigger: and action: sections didn’t flow well. I switched things around to work the same, but make more sense to me:
- id: away_study_lamp_off
alias: Away - Study Lamp Off 945
initial_state: 'false'
mode: single
trigger:
- platform: time
at: 21:45
action:
- service: switch.turn_off
target:
entity_id: switch.study_lamp_switch
Obviously some of this is subjective. The point is, I was able to decide on a set of standard coding practices, and make all my automations follow that.
I’m thrilled with the result. My automations are easy to find, easy to understand, and easy to update.
At some point, if having them all in one file becomes unmanageable, I could break them up into multiple files using !include_dir_merge_list
in place of just the !include
.
I should note that there’s also a Feature Request to have automation grouping done within the UI. Feel free to vote for both FRs, and consider this a workaround until all of this can be done in the UI.