'Dummy' Documentation

1

When you’re occupied with something, you know every little detail (or you’re supposed to be). But over time, it can become a real nightmare to remember what does what. And for other members of the family, this is a complete different story.

I’ve got fe in each room approx 2 switches with the possibility of 4 functions. And based on rules, they can act of course differently (pushed + lightA on = light off, pushed + light off= lightA on + lightB on). So when you’ve got about 20 switches, you can easily have more then 100 functions.

My question now, do you guys have a system to document the basic functions of your home?
Not the technical details. But in high-level.

Some examples

  • a kind of scheme with each function described
    Button 1: push1: lightA, push2: housemode, push3: panic
    Button 2: push1: lightB, push2, gate, push3: panic

  • Post-it paper on the switches, or …?
    push1: lightA, push2: housemode, push3: panic
    push1: lightB, push2, gate, push3: panic

Simply to explain to the family members (and yourself) the day-to-day operations…

2

Unfortunately my “system” is to avoid that sort of complexity in the first place.

While it does limit what is possible it greatly increases the usability and intuitiveness of the home automation so such documentation is not needed.

Strategies I’ve deployed include:

  • Make the house just do it: Full automation without need for an interface. This is admittedly not always possible but probably more possible than you might think.
  • One button one function: Each button has only one function whether you press it long or short or multiple times.
  • The same interface in different rooms should work the same: For example, if button 1 turns on the lights in one room, button 1 in another room should turn on the lights in that room.
  • Use traditional interfaces where possible: Light switches are light switches, garage door openers are buttons, etc. If they are the same interfaces they grew up with there is nothing to learn and no surprises.
  • Never require a phone for day-to-day operation
  • Do not disable the native interface or require “don’t touch the switch” (this rules out smart bulbs entirely). This also takes the pressure off you when something goes wrong as there is still a backup way to turn on the lights, for example.
  • Use a remote: For some reason, probably a lifetime of training with the TV, people grasp complex interfaces that work like a TV remote easier than wall switches
  • Use a touch screen: I’ve not gone this far yet, but with a touch screen you can build a self documenting interface.
2 Likes
3

I agree. My method is to create an environment that anyone can use. If my mother is coming over to watch the kids she should not struggle to turn a light on. For me, automation enhances the environment, not replaces it. For example, a humidity sensor can turn the bath fan on for the kids when they shower. It does this because I linked it to the switch so it can always be turned on manually if desired.

The old adage applies in HA, just because you can do something doesn’t mean you should.

4

I agree with you all, and I disagree. :blush:

Of course the whole idea is to make all things as simple as possible. But certainly you want to have the liberty to do whatever you want?
With the 1button/1function idea, I guess you’ll have the same issue. I’ll have 20 buttons, 70 functions, you’ll have in my situation 70 buttons. So also a bit hard to keep track on which button does what?

I’ve got about 110 knx switches, 25 knx contacts, 30 zwave contacts and 10 zwave switches. With all this, I’ve got about 25 security sensors, 40 lights, 70 power outlets, various (water level, gate, garagedoor…). And of course, I can put 1 button for each light, but when you can use 1 button for 4 lights, it’s just more ‘cleaner’ in the rooms.
btw I’ve just bought a 8 button panel for my backdoor to centralize the most common things (waiting delivery today), but I don’t see this happen in every room/door.

For the moment, I’ve document it as

Zoom in

This way, my family members can check what can be used for what. In the example above, the cellar (1 push) and attic (2 pushes) are auto OFF after some minutes. If you want to keep them both on for ‘always’, push it 3 times.

ps I already had my house in visio, and put everything (walls, electricity, data, plumbing, furniture, plants…) on different layers. So I had just one extra layer with HA descriptions. But I’m always interested in how other people document things… You’ve got on one side the technical aspect, but not all users have an technical background to understand ‘complex’ schemes…

5

Haha,
the devils adocat question on documentation:-)
i assume that a lot of people moved over from “sealed systems” to openhab.
i am a newbie and refused to use systems like openhab, as i did not want to make my private live another it project.
so, right now, as my process is very agile, my documentation is in the files and in verey commit for my items

Like me, a lot of people first struggled with items vs. things and sitemaps vs. itemfiles.
while on openhab2, i first tried tiu use many of the auto discovered things and links, and finally came up with some personal learnings:
1st: Self explanatory itemnames for groups and items
it far more easy to remember what you tried to accomplish with an item if the name explains :slight_smile:
2nd: Apply proper naming when you lear items to ccu / hue / whatever binding
renaming afterwards might be a pain :slight_smile:
3rd: put explanation into your itemfiles/sitemaps/rules. annoying, but good.
4th: having a plan is good, hovever, how do you identify the physics ?
ie you need to relocate, you might be in a hurry mode, so attaching a label to every cable/actor/switch/bulb reflecting the name might be helpful !

now the bad thing: you most likely start small, did not completely understrand how stuff works, and so you picked the woropn names, fogot to tag or whatever.

So currently i am cleaning up only 20 Hue Bulbs/Strips 8 yes, 5 (items each), 30 WIndows Sensors nd appox 15Valves and temp sensors.

the good thing is i can do it on a learning / test system, as the “production” still runs a HomeaticIP APP

My girlfriend already want´s toi have “that new thing” on my ipad where i can easily apply a defines Color Scheme to a room rather than a bulb , wich is just a selection of groups and a applied rule

1 Like