Documenting a solution

Setup, Configuration and Use Beginners
1
  • Platform information:
    • Hardware: _Intel 5i/ 8GB /500 GB
    • OS: _Windows 7
    • Java Runtime Environment: OPENJDK 11
    • openHAB version: 3.0.2

I’ve been running OpenHAB for 2 years now and have connect garage doors, gates, lights, home alarm systems etc. All is working very well, and now I have a need to document the solution but battle to do this in an effective way.

I have found that I have implemented rules that partially overlaps with other rules. I have followed a naming convention with items, things, channels, and yet I still battle to find my way to what I’m looking for. With a well documented solution it will be easier to navigate when making adjustments, add new rules, I’ll be able to sort our partial duplication etc.

Has anyone documented their solutions and willing to give me a few pointers on how to do this in a effective manner, or point me to a topic (I have searched extensively with no luck)

Much appreciated

2

How much time you got?

The hard part of documentation is maintaining it. Unless you make incremental edits every single time something changes, it quickly becomes obsolete. That’s pretty typical, and the reason why documentation tends to start out well and then slowly get worse over time. It’s also why companies hire technical writers–documentation is a full job unto itself.

My personal experience is that most people don’t want to put in the time and effort to maintain docs–and I include myself in that group. I’ve been a technical writer in the past and enjoyed the challenge of creating new manuals and procedures. However, I hated making minor edits and rewriting when something changed–and that was most of the work.

Since I don’t want to put time into maintaining documentation, I try to leave messages to “future me”, explaining what/why/how “present me” did. Usually I do this as comments in my .rules files, with URLs to relevant websites and OH discussions. However, this doesn’t capture other aspects of my system (e.g. things I’ve done in MainUI or to configure bindings/things).

Now that you’ve got me thinking about it, I might start keeping a journal of my OH activities (including community discussions). The goal won’t be to record exact, step-by-step details, but to capture the broader strokes that I’m likely to forget in the future. There’s also benefit to knowing why I originally set something up in a particular way, and then seeing why I changed it two months later.

I’m not trying to discourage you from writing your own documentation. I’ve just seen a lot of documentation efforts that start out with the best intentions and then get quietly forgotten as other priorities take over. And yes, been responsible for some of those myself.

With that in mind…how much time you got?

2 Likes
3

Why do you have to document the system?
There are real reasons why this might be needed, for instance if you sell a house with the system intact and the new owner wants documentation.
The requirements for that would be different then if you are documenting your own work so upon a hardware failure requires restoring the system

not uncommon, but… it makes you consider how the rules were implemented. As time goes on, you tend to patch things to implement one more little enhancement and the rules get messy. As I refine the process, a bunch of little rules (with very obvious naming) seems to work best (especially with OH3 point and click rule creation)

That is a good start

that is probably because of shear number of items, the search function at the top of every OH3 page helps a bunch

4

This is one of the reasons I like text based items / things / rules. They are easier for me to organise, backup, and to have historical changes (e.g. with git and multiple backup snapshots) and you can add comments into the items files. Yes they’ll say you can backup / put the json db into git etc, but I still prefer text based stuff.

For me, I use a single yaml file that contains most of my items. I then use a tool to convert this yaml to one big .items file using device templates. In the YAML I can have comments about the items. It is much easier to have a good overview of my items in the YAML file.

My rules are “grouped” into functions, e.g. tv.rb (ruby scripting), aircon.rb, pool.rb, motion_triggers.rb, alarm.rb, etc. Each of these files contain multiple rules all related to that particular function. Yet I still have some overlap but that’s fine. Furthermore I can group the rules into subdirectories, eg. lights/ subdir contains multiple rule files related to lights.

Lastly I wrote markdown files in conf/scripts/notes/ e.g. for Tasmota.md that contains device templates, setup commands etc what to do when adding a new tasmota device.

With it all in text files, I can do a search in VSCode, for say “BedRoom_Light” and I can see where it’s being referred to - from my yaml file, to items file, to multiple rule files.

Another thing I’d like to do is using Ansible / Chef or something similar but I’m not there yet.

So in summary other than my documentation about Tasmota setup and what commands to use to set certain things on Tasmota, I don’t have any documentation about openhab itself.

I don’t find a need to document the openhab part, probably mainly because I tinker with my openhab all day every day, all year long, it’s my obsession hobby.

5

:slight_smile:

I think it matters more for those of us who are in a maintenance frame of mind. Aside from a few tweaks, I haven’t made any significant changes to my system in months. I have a poor memory, so when I don’t do something for awhile I forget the specifics and sometimes have to relearn it. So, I can sympathize with the OPs feeling that they could be more efficient if they took some time to write things down.

I’m still too lazy to do it, though.

6

For many of us ‘old timers’ our text based files are our documentation but… we have to think about this in a whole new way and adapt

1 Like
7

Hi Joe - There is no easy answer, which doesn’t involve a bit of time, but my general approach (and learnings) have been as follows:

  • Use a wiki technology for maintaining your documentation. The reason I suggest this, is that consistent & incremental “Micro-Editing” as you deploy things/change things, is easier across a large number of small pages, as opposed to a small number of large Word documents etc.
  • Since I moved over to using the wiki I have found that I have been much better at incrementally maintaining ‘as-built’ documentation than I was in the past
  • In my situation, just like with OpenHAB, I prefer not to rely on cloud based providers where possible (partly based on poor internet, partly based on a self-reliance philisophy), so I am using a local instance of the opensource xWiki solution running on my OpenHAB server.
  • Like everyone else, I still sometimes end up with “Technical Debt” at the end of an integration, swiftly moving on to something way more exciting than writing documentation. I use a freebie Trello board (Hypocrite alert - yes it is a cloud service :slight_smile: ) for my to-do list, and include such documentation tasks to the backlog for a crappy winters night, where not much else would be happening anyway.
  • I maintain way more than just OpenHAB documentation in the wiki - It includes tables for all kinds of things for the house, including wiring, data outlets, irrigation valve circuit ID’s etc. Also can work as a Quasi-portal to OpenHAB, OpenSprinkler, and admin launch links to all kinds of network devices like Firewall, Router, Switch, NAS etc
  • Its pretty easy to export the whole wiki (or sections)i to PDF, so from time to time you can store an offline copy on your Tablet.
  • But I do NOT try and document everything in there. Some things make more sense elsewhere, e.g. Comments in Rules etc, especially if/when there is high-churn in the documentation
  • Next step in the journey is to perhaps split the documentation tree into “Admin/technical” & “User”. Maybe next winter (or the one after that? :slight_smile: )

It’s early days (probably about 2 years since moving to the wiki), and I still have some legacy documentation to complete, but I can easily say I have saved more time than I spent on writing the documentation, by having easy information at my fingertips. Some samples are below

OpenHAB & Integration summary diagram, created with draw.io (which is part of xwiki package):

image
image765×922 135 KB

Slightly off topic, but the second sample is a Wiring Documentation for Automation Panel I recently built up (Integrated back to OpenHAB):
You will see I also grab copies of manuals/specs and drop them into the wiki, so I have a local copy available, if the Internet is unavailable. No guarantees these manuals will be found on the internet forever, especially for items purchased from places like Aliexpress:

image
image1204×961 210 KB

I hope this helps - Happy to answer any questions you have on this approach.

1 Like
8

Thank you everyone for the responses - truly appreciated.

I don’t what to document the whole solution for the sake of just documenting. But in order to get a few requirements fulfilled, I had to come up with very innovative use of items and rules and maybe when I’m more experienced I’ll laugh at that attempt, but in the mean time I have to note it down in order to remember what I was trying to achieve and through which steps and what the dependencies are.

@rpwong I don’t have a lot of time, but sometimes it takes me longer to try and re-engineer what I was thinking at the time than what it would’ve taken to spec it :slight_smile:

I’ll explore a few more options and try out a few suggestions from up top and if I get to solve my problem I’ll post again,

Thanks again to all for responding - very positive first-community-experience.

JB

9

Yeah, that’s what I try to do with the comments I leave for myself. The goal is to remind myself of what my intention was at the time, and then point to the resources I used to figure out the mechanics.

I second this. It’s also worth scanning or taking a photo of the manuals that come with your devices, particularly now that so many devices have a single button that you have to press different ways to do different things, and a single LED that communicates in different blinks or colours.

10

I can write all day on a topic like this but I’ll be brief. tl;dr is don’t write docs, that’s a losing proposition that only increases your work. Instead refactor your code and config in a way that is self documenting and makes sense to you and use the tools available to you. But what that means will be specific to the individual.

Pay close attention to what makes navigating your code and configs challenging and try to address that. Find those overlaps in your rules and see if they can be extracted and generalized so there isn’t overlap. Or maybe that’s a sign that those rules could be merged.

If you are struggling with your items, maybe the naming convention you are using isn’t up to the task. Maybe you need more or less info in the names. Don’t forget you have tags, metadata, Groups, the semantic model, and search to also help you organize Items.

When you are working on a related set of stuff (things, items, and rules) pin them to the developer sidebar (alt-shift-d) and you don’t need to go hunting for them, everything you need is right there.

When you figure out how to do something tricky or even just something you might forget (e.g. creating a timer) creat a Script under Settings → Scripts with an example you can refer back to later.

Use the -Scratchpad- Script for adhoc experimentation and testing.

Use the widgets and rule templates from the marketplace where possible so you don’t have to write code someone has already figured out.

Share tutorials here on the forum. The very act of explaining something goes a long way to fix it in your memory.

1 Like
11

Thank you @rlkoshak - I’m completely with you on using naming convention, schematic model etc. but let me give one example of a use case where there is a gap. I realise that the forum might be able to provide a better why of fulfilling this requirement (which may close the gap for this instance) but I’m using this only as an example.

The problem is this: I have items defined as switches which are only logical and do not represent physical switches. These items are switched on and off by various rules to achieve certain objectives. By looking at the item, there is no way I know off that I can indicate on item level which rules are referring to this switch.
One practical example is this:
When I leave my gate open for x minutes OH sends my mobile a message. I have two limit switches mounted on my gate: one to trigger on GATE_FULLY_CLOSED and one on GATE_FULLY_OPEN. When the gate opens, the GATE_FULLY_CLOSED limit switch opens and this triggers a rule to switch an item ON to start a timer. For this I use the Expiration time on the item. When it runs out the item switches OFF and this triggers a rule to send the message. To find the rule I need its name. I don’t know of a mechanism to indicate on item level which rules manipulate this specific item. My only way is to go to the Rules pages in Settings, and filter on “gate” (knowing that I would have added the term “gate” in the name). There are 16 rules pertaining to gates (for spot lights, alarms, other timers etc). I now have to open 16 rules one by one to find the rule calling the item I’m working on. If I had a concise why of documenting this I could’ve referred to it.

Any insights or wisdom? I’m sure the community must have had the same challenge of trying to find a rule pointing to an specific item?
@rpwong @glen_m Sorry I didn’t provide this example earlier - was planning to spare the community the gory detail :smiley:

JB

12

The problem is going to be that it’s all little gaps like this. You won’t find one silver bullet that addresses them all. You have to tackle them all one-by-one. In this case you want a way to go from an Item to rules. But what if you want to go from the rule to the Items? This can be very challenging in cases where the rule is generic and the Items are not actually referenced directly by name.

If they are referenced by name and not indirectly using a Group or the name is built at runtime (e.g. Associated Item DP) then for now the only effective way is to open and search through automation.json (or use grep if you are good with it). There have been a few tools written that can do this for you in a little bit nicer way but it’s pretty much just wraps this sort of action.

I think there is an issue open to make this sort of search better but it’ll never be full proof.

However, there are things you can do to make this easier. Leave breadcrumbs as you go.

Rules can have tags. Items can have tags. So give them both the same tag and you can search by tag and correlate that way. Or maybe add the ruleUID as a tag to the Item and you can search Items by tag. Or add Item names as tags to the rule. Or do both.

You can add names and descriptions for rules and for the individual Scripts and Conditions that you add to a rule. Add the Item names there or at least add a description that makes it obvious that it’s going to kick off a Timer to send an alert which, assuming you are using Item names that make sense, could be all you need to know which Items are involved. In other words, all your rules should have a meaningful name and a description of what it does. I would expect the description of the rule that starts the Expire Timer to mention that 's what it does (and anything else that it does). Once you know what the rule actually does it should be relatively easy to know which one commands your timer Item, or at least narrow it down to two or so.

For example, the rule that triggers when the GATE_FULL_CLOSED switch opens would have a description along the lines of “Command ON to the gate alert timer Item to send a message after 30 seconds.” or something like that. The Rule that triggers when the timer Item changes might have a description like “Triggers when the gate alert timer changes to ON and sends a telegram message indicating the gate has closed.”

With that you should be able to see right there on the filtered rule page which two rules your Expire Item is involved with. If you use the actual Item name in the description it might be even more obvious.

You can add metadata to the Item and list all the rules it’s used in though that’s probably less useful.

Adding such breadcrumbs as you go is going to be a whole lot easier to keep up to date (though still needs to be maintained) than some separate document maintained in some separate tool.

13

@rlkoshak Breadcrumbs! Brilliant - some good food for thought (no pun intended). I’ll give this some thought and try a few things out - I agree, this will take less effort than getting docs together. I need to up my game on groups and tags…

Much appreciated.
JB

14

Yeah, this is basically what I was trying to say, but 1000% more efficient.