Documenting your Smart Home

browetd · July 19, 2022, 6:26pm

Regarding documentation or structuring HA, here is what I did (I am writing/updating all the files in yaml directly using the file editor of HA as I started to use HA a long time ago and all gui interfaces where not existing at that time):

I am splitting my automations based on some kind of domains: one file for each domain. For example, I am naming my files containing Electrical Vehicule automations: EV_electrical_vehicule.yaml… Same approach for heaters, airconditioning, pool, etc…All these files are in a subdirectory of /config called automations.
In these automation files and for each automation, I am trying to document what the automation is doing, when it is triggered and what are the conditions to fullfill to be executed… adding some remarks if necessary to understand the reasons for some conditions, triggers or actions… For some automations, it is obvious what the automation is doing, but some can be very complex or tricky and needs to be documented. So I decided to document all the same way. example:

#=Done================================================================================================
#
# Calcul température de fonctionnement de l'electrolyseur et de la pompe de la piscine:
#   - en été: de mars à octobre
#   - suivant le mode de fonctionnement de refroidissement automatique et température piscine
# quand:
#   - à l'heure d'extinction de la pompe pour calculer planning du lendemain
#   - si changement de mode de refroidissement automatique
# conditions:
#   - si le refroidissement automatique de la piscine est activé
#   - et si la température de la piscine à l'entrée de la pompe à chaleur est inférieure ou égale à la température target pour le refroidissement
#   - et si la température de la piscine (pour le calcul: voir sensors) est connue (comprise entre 5 et 50°C, la valeur doit être au moins 6°C pour faire tourner la piscine minimum 3 heures par jour)
#   - ou si le refroidissement automatique de la piscine est désactivé
#   - et on est en été (de mars à octobre)
#   - et si la température de la piscine (pour le calcul: voir sensors) est connue (comprise entre 5 et 50°C, la valeur doit être au moins 6°C pour faire tourner la piscine minimum 3 heures par jour)
#
# les limites de fonctionnement sont calculées en partant de l'heure de milieu de plage et en retirant/ajoutant une nombre d'heures égal à la température de la piscine divisée par 4.
# Donc si la température de la piscine est de 6°C, la plage se situe donc entre la plage du milieu - 1,5 heure et la plage du milieu + 1,5 h...
#
- alias: calculate_time_montreal_ete
  initial_state: true
  trigger:
    - platform: time
      at: input_datetime.h_ext_pompe_m
    - platform: state
      entity_id: input_boolean.poolstage_refroidissement_auto
  condition: 
    condition: or
    conditions:
      - condition: and
... etc etc ...

For each automation, I am writing some comments linked with steps into a message file (that I am closing everyday at midnight, keeping 7 version/days of those files)… So I can track easily by reading this file what steps where executed during a specific day and when… example:

2022-07-19 05:58:00   **** DM-014.1 Allumage Pompe Piscine
2022-07-19 05:58:00   **** DM-016.1 Allumage Electrolyseur Piscine Montréal
2022-07-19 06:00:00   **** DM-019.1 Extinction chauffe-eau Salle de Bain (haut) Montréal
2022-07-19 06:15:02   **** EV-001.1 Chargeur Voiture: demande extinction...
2022-07-19 06:15:11   **** AG-015.1 Theme set to light (day)
2022-07-19 06:18:11   **** MQ-015.1 Ecriture Heures Lever et Coucher du Soleil à Montréal (remote via mqtt)
2022-07-19 07:00:00   **** EM-001.1 Change Energy Tariff to the next one
2022-07-19 09:03:51   **** EV-003.1 Chargeur Voiture éteint...

As you can see, every record in the file contains the time the step of the automation was executed, a reference to the file where the automation was executed (EV for the last one, so related to EV_electrical_vehicule.yaml) a number+step to find the automation/step having generated the message and a comment about the step(s) executed…

regarding dashboard, I splitted also all the tabs/paths by creating one file per tab/path. regrouping those files into a subdirectory called lovelace in /config directory… If for some reasons I have group of identical cards existing in multiple tabs, I am creating specific files for those cards. Those files are stored in another subdirectory of /config called tiles. I am incorporating the reference of that card into the lovelace yaml files for building one tab/paths… example:

#==============================================================================================
#**********************************************************************************************
#**                                                                                          **
#**                               Tableau de bord                                            **
#**                                                                                          **
#**********************************************************************************************
#==============================================================================================

- title: Tableau de bord Montréal
  path: montreal
  icon: mdi:billboard
  cards:
#
# Left Stack
#
      - type: vertical-stack
        cards:

#
# Cards for Alarm Off Display Status - MONTREAL
#
        - !include /config/tiles/Alarme-Montreal-Titre.yaml
        - !include /config/tiles/Alarme-Montreal-Status.yaml
        - !include /config/tiles/Alarme-Montreal-Timer.yaml
        - !include /config/tiles/Alarme-Montreal-Code.yaml

#

disadvantage: less flexibility in creating the layout of your different tabs.
advantage: If I change one file in the tiles directory, automatically all the tabs/path of lovelace using it are updated (instead of updating each file in the lovelace directory). I didn’t do this at the beginning but I decided to change the approach when the lovelace files where very long/difficult to maintain… This is a consequence of my decision to split my dashboard into multiple tabs…

I am using a lot of button-cards (installed using HACS) in lovelace, therefore I am using a lot of template cards to simplify the creation of repetitive cards (like lights cards, switches cards, alarms, heaters, airconditioning, etc…). This is simplifying the writing of those cards.
documenting sensors (in fact everywhere you use templates) is also a good idea as some templates could be very complex and difficult to understand when you come back a few months later and have to change it… for that one I have some home work to do to develop a good documentation…

This is the way I have organized my HA files, this is just of course examples and a feedback… I have two sites managed the same way with a dashboard with 27 tabs/paths in one location (the other one has only 15 tabs/paths). I have 335 automations on one site and 131 on the other one… Pretty big configurations, where a good documentation helps to maintain it.

aceindy · July 19, 2022, 7:04pm

if you want to save and look backwards, why not use github for that? It is an integral part of HA’s file editor…

As well as VisualStudioCode:

That is the whole point of a versioning system

AllHailJ · July 19, 2022, 10:10pm

I have used git but not recently and it is just easier to back up.

stevemann · July 20, 2022, 2:41am

Lots of comments in yaml files.
I also maintain a notebook (MediaWiki) for everyhing. My PC, my Home Assistant, my Ubuntu, really anything want to recall later.

Packages look interesting, but I haven’t been able to grok.

donburch888 · July 25, 2022, 8:07am

As others have said, the “how” is contained in the current configuration files, and should be backed up.

What I have tried to focus on is the “why?”. HA has meant one learning curve after another after another … too many things to even try to fully understand any one thing … which makes it too easy to forget how and why i got to the current point. I buy another device, and its “how the heck did I end up configuring the last device in Localtuya ?”

I have a word document (currently 52 pages with index) reminding me of the basics (with links to the tutorials or web documents I actually used) and the "gotcha"s i worked around, the naming convention I adopted, etc.

OK, I tend to get verbose and write like it’s a tutorial, but that’s mostly me getting my thoughts straight

ankabout · July 25, 2022, 12:40pm

Thanks for all the good ideas here. I’m surprised they are all “coding documentation” advice, but happy for it, as it’s a clever way to do so.

I was myself referring more to things like:

I have 10 devices
There’s a smart plug under the kitchen
These devices are linked to service X
etc.

And then the same for routines/automations, etc.

This last one seems to be something everyone logs in the code/config files, so that’s an interesting way to go.

stevemann · July 25, 2022, 5:56pm

I use Mediawiki. Because it’s database driven indexing is very convenient. I don’t know how many pages it represents, but the database is currently 557 mb.

aceindy · July 25, 2022, 6:45pm

https://github.com/hassio-addons/addon-bookstack ??

jcallaghan · July 25, 2022, 7:56pm

A very interesting topic close to my heart.

After testing our various solutions like Bookstack, GitBook and Notion I decided to use a private GitHub repo. I wanted something that would look after itself and be somewhat detached from my self-hosting while also being simple to work with and allow me to unwind by writing some Markdown.

I use issues to document anything from an appliance, Docker container config through to where the shut off valves are for the gas and water. Think of this as our family and home Wiki. The contents that some people print in those lovely bound books. The repo is shared with my SO and she knows to head there to try to answer her own questions first.

For me it was about having that one place where something was documented and over time it has become more of a discipline and more detailed. With issue comments I capture additional information for that given “thing”. The GitHub mobile app works great, issues can be created and edited on the go as well as uploading pictures straight from the phone.

I have taken it a little beyond the basics by creating some Actions that create index pages with links to the issues. This leaves me with a Markdown file of all Appliances for example and another with all my Docker config. I have a number of these Markdown files. Another great benefit is GitHub has a great rest API which you can integrate with Home Assistant to create issues or even add comments.

Staying tuned to learn from others.

Nick4 · September 4, 2022, 7:22pm

I use DokuWiki for this (and other things)

kenwiens · March 11, 2023, 8:58pm

Currently I maintain a separate spreadsheet for my automation documentation. For each automation I list a category (eg “alert”), the trigger, the name,. the basic functionality (description) and a status flag (prod vs test).

Now this is very time consuming, and for some automations the documentation takes longer to write than the automation did, it’s also painful when I make minor changes to an automation (it seems that we “tweak” automations for quite some time to get them just right) and forget to update the documentation.

I hate duplicating effort, and a lot of the documentation effort is cut and pasting from the actual automation. It seems to me that the effort could be dramatically reduced by some enhancements to the automation page. Currently the automation page gives the automation name and when it was last triggered (and a disabled / active flag). If the following fields were added to that screen, then this page could be my documentation summary:

Description (maybe only the first 160 characters or such if this becomes unmanageable - I could easily put the key information into 160 or less characters)
Trigger (use the trigger summary that HA already generates and displays when you open the automation
Actions (maybe - in my case the description might suffice)

As it is now, I try to cram the triggers and actions all into the name field

Brononius · August 4, 2023, 7:45am

Personal I’m running nextcloud for all my data.
In here, I maintain 2 files:

A document for global (or human?) explanation,
A spreadsheet with all my hardware (zwave nodes, network nodes, KNX actors, vendor appliances, software, etc.)

Several times, I remind my family about these files and that they’ll be important one day. My family isn’t really IT-minded, so not very interested in how it works. As long as it works.

The spreadsheet is really an inventory, and only intended for me. It helps me keep track of the IP’s, ID’s, hostnames, rules (functions/ideas)…
For the moment, I’m migrating to HA (in the past, I came from linuxMCE, openHAB). And this sheet helps me keep track of what I’ve done, and still have to do.

The document is really some poetry regarding the setup.
Why certain addons, where to find the backups, how to restart… This document is 80% focused on my family. If one day something happens to me, they won’t be completely lost. I’ve got so many sensors, and the house really runs on them, that I’m really afraid it would be a huge cost for them to ‘rebuild’ the house to a working solution.

Beside, on my website I try to explain the most fun or useful ideas for home automation.

I’m certainly going to follow this topic further. For years, I’ve been looking for THE way to document. Maybe, a little maybe, after my migration to HA it becomes time to really put the effort into it…

pgr · September 2, 2023, 6:44pm

@jcallaghan do you connect your Github Pages solution to the HASS site in any way? Or are they two completely independent systems?

MattSee · October 9, 2023, 7:53pm

But you´re not using it in the same instance as HA, or?

I would like to set something up similar to mediawiki within HA directly (equal to bookstack), but also without changing the required DB to e.g. MariaDB…

Does anybody by chance have a good idea how to achieve that - hosting a Wiki from HA directly?

aceindy · October 9, 2023, 8:05pm

Bookstack - Home Assistant Community Add-on??

stevemann · October 9, 2023, 8:11pm

Nothing else is running in my Home Assistant installation. My HA is running the X-86 Generic binary of HAOS on an Intel I3 NUC. Rock solid.

My MediaWiki server is on a separate Intel I7 NUC along with a couple of others, like Plex. (My first MediaWiki was on a Raspberry Pi 3). I am not sure I would want MediaWiki connected to Home Assistant in any way. It is a living document and too dynamic. If I learn something new about a particular subject I go to that page and edit it.

MattSee · October 12, 2023, 6:26pm

@aceindy Bookstack requires MariaDB which slows down backup creation tremendously… i don´t want that.

@stevemann Ah okay, got it. But right now running HA solely on my NUC is just a waste of capacities as well… so i´d like to be able to run MediaWiki server in the same instance or at last aside from HA.

ultraforce · October 15, 2023, 2:32am

With the mention of documentation by using yaml files what exactly should be done for stuff where they’ve initially been set up using the UI? I don’t exactly know how to through Studio Code Server to view any hidden yamls that may be created by the integrations and add-ons.

Edwin_D · April 28, 2024, 9:17am

A bit late for an answer, but for those who come to this thread with the same question: In automations and scripts you can use the top right menu to select Rename.

There you’ll find the description field. It can hold as much text as you like, and even supports markdown for formatting. So for instance the following description:

**This is a documentation test**

* Test 1
* Test 2
* *Test 3*

Looks fine to me

Shows this in the automation editor on top of the automation:

Also note that automations, scrips and scenes, even when built in the GUI, can just as easily be edited through VisualStudio Code, but the GUI may not keep the documentation you entered as yaml comments. So the description way is safer.

Nick4 · May 1, 2024, 9:59am

If you have your HA documentation running on HA and it goes down, how are you gonna get to your documentation?!

Of course it’s preference to run additional services on a HA instance - or not.
I have seen the craziest things that fellow HA users run on their HA.
I’m reluctant to do that: let HA do HA things and install services that have nothing to do with it in some other way.

If you have bought a beefy system, just for HA, which is overpowered for the job it might be obvious to stack other things on HA, even more if they are easy to install (HACS)
The thing is: when your HA goes down, for whatever reason, briefly or not, all these services might not work either.
Another result of doing it this way: your HA might become less stable because of this.

A solution can be to install virutalisation software on your system and virtualise HA and the other services in their seperate container.