Need help Documenting my ISY994i configurations

[Old Surfer Dude]

It is important that I document my configuration because eventually someone else will be responsible for the home automation system.  I have 40 devices and keeping track of everything even gets tough for me.

I envision the first part of the documentation will be a very simple user guide; the location of a device, what it does, and how to operate it.  For everyone reading this topic, it's so obvious that documentation is not necessary.  But, for those who enter my house, it is anything but obvious.  This section is for them.

There would be one section for rebuilding the system from a saved configuration. 

Then there would be section for rebuilding from scratch.  This would have links to existing documentation, like manufacturer's docs and ISY wiki installation instructions.  There would have to be a database that has location, name and ID.  These latter two should be found in a saved configuration file, but I have yet to figure that out.  

If you have done all of this with your system, can you give me some advice on how to proceed?

 

Thanks

OSD

[Techman]

A starting point would be the "Generate Topology" report which you can access in the Admin Console under tools.

Screen shots of your ISY configuration and prints outs of your programs, if any, would provide good documentation.

[Geddy]

@Old Surfer Dude Do you use any cloud storage (i.e. Google Drive, OneDrive, iCloud)? My first suggestion is to start a folder in a cloud drive and keep everything in that. This way you and anybody that comes after you would have an electronic version of what you're trying to do. As soon as something is printed it's outdated. 

As @Techman suggests a Topology and a copy of programs is good starting point. But that's just for the "guts" of the system.

"Generate Topology" is in the tools menu of the admin console. 

 

For programs go to the programs tab and click the root folder ("my programs"). Then right click and select "copy folder to clipboard". Then open a text app (if windows I suggest Notepad) -- something that allows you to paste plain text and not auto correct or auto format. Then PASTE into that text document. SAVE said document. This is now all of your programs stored in a safe place. (note...repeat this process every time you make a backup as part of your documentation set).

I suggest using date file names so you know how recent file are without having to look at the details (yyyymmdd-filename).

The real start of it all will be general information about the hardware and how to access it. And this is where it gets tricky because people that don't know what they're getting into might not follow all the directions (even if provided and clearly written). So the most important thing would be how to contact UDI support. If somebody walks in without knowing anything and wants to do everything the phone number to support should be first thing they see. This way they can call and say "please help, I know nothing". 

Important links to include are as you mentioned manufacturer and wiki, but also the forums.

Ultimately, they can come to these forums and many can help them find there way of accessing the system and maintaining it. 

I wouldn't stress too much on "rebuilding from scratch". Not many would want to take the time to do that. And can get very "wordy".

Just keep it basic (so you don't have to always make sure it's "up to date") and keep a current backup and program file in the folder.

My family has the "what if" shared folder in OneDrive. In there is the "Home Automation Info". I keep the last 3 ISY/Polisy backups and current program text file. 

Good luck as you progress. Good thinking about it as a just in case.

 

[Old Surfer Dude]

Thanks for the input!

I'd never used "generate topology" before and I think I will find that useful.

The copy programs to clipboard will be a bit cumbersome as it generates XML.  Yeah it's readable, once you put in line breaks.  I think I'd have to write a macro to strip it down.  Also, and this is a good thing, I'd have to put more comments in each of my programs.

Not only do I have my data in cloud storage, but also in a local NAS.  (all of that has to be documented, too.) 

I appreciate your ideas and I feel like I'm on the right track.  It's just going to be a lot of work. 

[gzahar]

Thanks for the input!
I'd never used "generate topology" before and I think I will find that useful.
The copy programs to clipboard will be a bit cumbersome as it generates XML.  Yeah it's readable, once you put in line breaks.  I think I'd have to write a macro to strip it down.  Also, and this is a good thing, I'd have to put more comments in each of my programs.
Not only do I have my data in cloud storage, but also in a local NAS.  (all of that has to be documented, too.) 
I appreciate your ideas and I feel like I'm on the right track.  It's just going to be a lot of work. 

If you right click the top program folder and select COPY FOLDER to clipboard it will paste into a text editor as normal text. No XML involved. Make sure you are not trying to export a program.

[Old Surfer Dude]

Thanks @gzahar!

[MrBill]

7 hours ago, Old Surfer Dude said:

The copy programs to clipboard will be a bit cumbersome as it generates XML. 

You're confusing "Export to Clipboard" with "copy to clipboard" or "copy folder to clipboard".  the Export option is XML both of the COPY options are plain text programs views.

[lilyoyo1]

16 hours ago, Old Surfer Dude said:

It is important that I document my configuration because eventually someone else will be responsible for the home automation system.  I have 40 devices and keeping track of everything even gets tough for me.

I envision the first part of the documentation will be a very simple user guide; the location of a device, what it does, and how to operate it.  For everyone reading this topic, it's so obvious that documentation is not necessary.  But, for those who enter my house, it is anything but obvious.  This section is for them.

There would be one section for rebuilding the system from a saved configuration. 

Then there would be section for rebuilding from scratch.  This would have links to existing documentation, like manufacturer's docs and ISY wiki installation instructions.  There would have to be a database that has location, name and ID.  These latter two should be found in a saved configuration file, but I have yet to figure that out.  

If you have done all of this with your system, can you give me some advice on how to proceed?

 

Thanks

OSD

My advice is to keep it simple. While it sounds good to set someone up, providing too much information will overwhelm them. You're better off finding someone who can step in to manage the installation when you're unavailable. 

Everytime I've sold my home, I left the devices but removed all automations except for basic timers such as the outside lights turning on/off. Anything custom was erased. If the new owners wanted custom programming, they could hire me to program for them. 

I do have people that can step up in my absence to manage my system and other client systems. That's the route you should take. Most people do not process and understand technology the way we do so them trying to maintain and program probably won't happen. Giving them a lot of info only lessens that chance even more.

Reality is, it's easier to factory reset everything than to fix someone else's work. Especially for someone not familiar with the Isy. In the time it would take me to learn your programming style, read through all your programs and topology, and understand why you did certain things, I could've just started over which leads to how I handle things.

For every client, they get a USB drive with 3 backups on it. The first is what I call a clean slate backup. This has all devices added to the isy with zero links except for true multi-way switches. Each device is renamed and grouped in folders that corresponds to the room that they are located in. The load switch is identified in the system as well as marked on the wall plate (I use Screwless wall plates). The secondary switches are numbered as well in the same manner. 

The next contains all scenes with no programming done. The last backup contains their final configuration. No matter what i change in the home later on, these 3 remain. 

This allows them or a future programmer, to factory reset the system and re-add everything cleanly should they choose too at whatever level they decide. 

The file also contains how to set/change the password (along with current password), what each backup contains, and how to factory reset the system and restore backup's.

I do my own sort of topology and glossary of terms. There's a copy of what each keypad looks like and what's connected to each button. It also contains the expected behaviors of each button and switch when turned on/off (ie: Turning Music button on starts wife's playlist. Double tap starts husband's playlist for that room. Off, stops music). 

This not only provides the client with a resource on how the system works but also allows someone coming behind me to know what is supposed to happen, when, and how. This way, should they need to rebuild things, they can use their own style of programming to accomplish the same thing. It also allows me to know what I was attempting to accomplish should I need to go back years later to add or change something. 

 

 

[Old Surfer Dude]

Thanks @lilyoyo1!  I like the three flash drives concept.

2 hours ago, lilyoyo1 said:

It also allows me to know what I was attempting to accomplish should I need to go back years later to add or change something. 

I agree.

[Geddy]

13 hours ago, Old Surfer Dude said:

The copy programs to clipboard will be a bit cumbersome as it generates XML.

No, as @gzahar points out it's plain text. That's why I suggested pasting in notepad. If you paste into Word or other word processing program it could auto format the layout and that would be cumbersome. But as I suggested it's just plain text and mega easy. That's typically a step suggested in Firmware update too so you have a logical and readable version of all your programs should something go wrong with the firmware upgrade (i.e. from 4.x to 5.x a lot of adjusting might have been necessary. Having a text record of all programs saves the day!).

 

3 hours ago, lilyoyo1 said:

My advice is to keep it simple.

Great advise! Always keep it simple. Too much will inundate people that might not know what they're doing and they'll just leave it alone. The best thing is to point them in the direction for help and they can seek the help they need and/or learn at their own pace and get help as needed.

 

[Mustang65]

Don't forget to add any required subscriptions and links to them for portals, support.... ID's and passwords

I have a "Work in Progress" that I call "Death Star" (no comments please) and the iCON sits in the middle of my desktop screen. My son is aware of it, but breaks out in a cold sweat when I mention it. i set up a VLAN to my UniFi network for him to access all this stuff. Wife not interested in any of it.... well only the lights coming on and off and the alarm system. Son will probably remove the bulk and install in his house. He spent a lot of time in IT so that is half the battle.