How to best document your automation rules?

As my home automation projects gets bigger and bigger, I feel the need for creating some kind of documentation of the project, mainly for the automation rules. Already now I’m not really sure what happens when the sun sets or when everyone leaves the house and I’m lacking some kind of overview. For example I want to be able to find all the devices that are involved in automation rules triggered by sunset. Or the other way around, find all automation rules that is turning on my kitchen lights. This would be useful both when troubleshooting existing automation as well as when creating new rules.
An Excel sheet would somewhat solve it, but I’m looking for a more intuitive way, if it exists.
The dream would be something that could auto generate this from the yaml-files in Hass :heart_eyes:

Is there anyone who has made this kind of documentation and can give me some tips and examples?


@bruhautomation has a great video on documenting your system which covers some of this, but not specifically your automation use case.

As for me, I tend to be an uber-commenter. Whenever I write an automation, or create a template sensor or the like, I always put in comments so that I can go back (or share with another user) and instantly see what does what or why I did such and such. For example, these are two binary template sensors I am using as part of my laundry automation:

#   Automation Templates
#    True when washer power level is below 3.4 watts, high threshold of resting state
#    Default state is true
       value_template: "{{ states('sensor.aeotec_smart_switch_6_power_10_8') | int < 3.4 }}"

#    True when Dryer power level is above 8.4 watts, showing dryer is in operation (as opposed to just having the door open)
#    Default state is false
       value_template: "{{ states('sensor.aeotec_smart_switch_6_power_11_8') | int > 8.4 }}"

Rudimentary as it may be, it works really well.

1 Like

I tried to flesh out as much documentation in my github repo. Aside from the usual suspects, I am trying to keep my TIMELINE up to date which helps figure out what happens when.

Breaking out the automation rules into separate yaml files has also been helpful. I also use Notepad++ which does global searches really well when I need to make an update to light.someLight_in_the_house.

1 Like

I just got my repo up; was working with another user on a tutorial for doing this so it should be available to all soon.

Also found out that even besides putting rules into different files - it’s good to have a TOC in the beginning of the file. As over time you get mora and more rules and start o forget which ones you already have
Something like

########################### Contents
# UPS on battery
# UPS on battery charging
# UPS Critical level
1 Like

Hm. We have a parsed configuration. It could be visualized as a directed graph, right? Nodes are entities, edges are services and group relationships.

Thank for posting that. A lot of ideas from reading through your rules. Do you have an open topic to discuss your git? Have a question on how you fire the events like

 - platform: event
     event_type: good_night

Yes, that’s a good start. I like it to be somewhat graphic rather than having to go through a lot of text.

Thanks a lot everyone! Great input! :ok_hand:
It seems like everyone has their own solution to kind of the same problem, and are happy with it :slight_smile:
I think I will start with my own solution, creating a database containing records with trigger entities, condition entities, action entities and yaml file names. Then use this data and see how it can be visualized in the best way.
Time triggers can be visualized with a time line. Some other triggers perhaps with a directed graph.
Final step (if I like it) will be to have it auto generated from the config files.

All those events are IFTTT events. Fired from IFTTT. Typically an Alexa - > IFTTT Maker -> HA recipe.

Reverse that and you have the beginnings of a visual HA/YAML rule editor! :slight_smile:

1 Like

Here’s my graph visualization prototype:


Holy Cow, that’s awesome! I want that!