HCA Admin
Sep 01, 2009, 01:22 PM
Summary
The HCA sample file MyHome.hca that came with your HCA installation was constructed to provide you some ideas on what HCA can do. It contains some programs that may help your in your own home. This note describes some features in the sample home that you may want to look at. It also describes what each program in the sample does.
Introduction
The sample file provided when you installed HCA contains a number of features that you may want to examine. We constructed the sample as a way to highlight HCA features and techniques. Some of the methods we used in the sample might be applicable to your own home. In addition to describing the what, we also describe the why – why were elements of the home design done in the way they appear in the sample.
This sample home is built using mostly Insteon devices, UPB keypads – they are a bit nicer than the Insteon keypads and some X10 devices where needed. So the sample shows a number of techniques for working with cross protocol devices.
The house contains three floors – represented by three displays that use DXF file backgrounds – and a number of rooms – Kitchen, Rec Room, Great Room, Bedroom, etc. Also in the home are a number of folders that don’t represent rooms: Outside, Patio, and Deck. Also are some folders not used for rooms at all: Home, Home Programs, and Status.
This points up one HCA feature. Folders can be used to represent anything you want – rooms in your home or collections of devices, programs, and groups that make sense in your application.
Finding your way around: References and Schedule tab
As you look though this example, the reference tab on the properties dialog for devices, programs, and groups shows where it is used in other places. For example, open the properties for the device Hot Tub Room – Tub Filter. Choosing the References tab shows that this device is used by two programs. Also, open the device Great Room – Floor Lamp. This device is used by a group and a schedule. To see the schedule entries that apply to this device all you need do is choose the Schedule tab and the schedule entries display. You can also create new schedule entries by simply double-clicking on the “Add new” branches on the Schedule tab.
Cross protocol use
Open the properties for Home – Entry Lights. This is an Insteon device but look on the triggers page. This device has two triggers for a UPB Keypad.
What does it mean for a device to have a trigger? When HCA receives a message it checks all devices, programs, and groups to see if they contain a trigger that matches the message received. When the trigger matches a program trigger the program I started. But for a device the trigger is translated into what the device can understand and a message is sent to control that device. A translation of the command happens if there is a change in protocol. In this example, the UPB keypad sends Activate and Deactivate commands, and these are translated into Insteon On and Off commands.
To see another example of this, open the properties for Home – Stairway Light Upper. This Insteon device has a number of triggers from X10 motion sensors. Choose the Triggers tab to see this.
Home mode use
This sample home makes use extensively of Home Modes. Almost all devices has non-default home modes selected for one or more of the modes. For example, look at the properties for the device Bedroom – Charge Port. When the home is in Away mode, the device is always off. It goes off when entering the mode and stays off regardless of schedules or programs as long as the Home is in the Away mode. Also in this device you can see that when you wake up, the device goes back on.
Also look at the Rec Room – Lamp. It is set in Away mode to go off and to stay off while in Away mode. But look at the schedule as well. It schedules this device to turn on each day. What happens when you are away? Does the schedule control the device? No. Because the mode says that when Away to suspend all actions. This makes it very simple to schedule devices like this. You want the schedule to happen when you are not away but not when you are way. The Home Mode selected in the device makes this happen.
Another features you should example isn the Bedroom – Closet Light. Open its properties and choose the Green tab. This device is set up to automatically go off after it has been on for 6 minutes – dimming down one minute before going off. How does HCA know it has gone on? A wireless sensor is used when the door is opened and that starts a program that turns the light on. Two notes about this program. First the program just has to turn the light on. Turning it off happens due to the setting on the device. The second feature is the program, if the closet is opened and the home is in the away mode, it sends an email message. Why? Well, this is an example! It does show using a test element to test the current email and also uses the Email element to send the email.
Insteon scenes
There are a number of Insteon devices setup with scenes. Right-click on the Rec Room – Lamp device and select VSE from the popup menu. The right pane of the HCA window clears and the Visual Scene Editor appears. This is a pictorial representation of the scenes that this device participates in. Note that there are two scenes – both initiated by the keypad in the rec room. The VSE was used to create these scenes rather than manually linking. Once a scene has been created HCA knows about it and it can be scheduled and programs can be used to activate the scene. In a program a scene element is used and in a schedule there is a scene type of control.
Interesting programs
This example contains a number of programs that you may want to examine. Look at the Outside – Garden Watering program. It starts off by testing the wind speed and if too great the program stops. It then uses the various outputs on the Insteon EZIO to control the watering valves.
Another interesting program is the programs that respond to the bathroom motion sensors. This program is a bit complex but the idea is as follows: If I walk into the bathroom during the night I want the light to come on at a low level. It does this by testing the time. The light is then turned off after a few minutes. Since the motion sensor can retrigger many times the program first has to check to see if the light is already on. The question is it on at the level the program previously set or have I changed the level manually by using the switch paddle. If I have raised the light level I don’t want the program to shut it off.
Something similar happens in the program Status – Motion Sensor Driveway. This program, started when the driveway sensor reports an entry controls the outside lights. But what it does is first to save the current light level. Then the light level is increased to 100% for a few minutes. After which the light level is restored.
The hot tub program set
This set of programs is the most complex in the sample home. Like with the Wake Up program it’s important to see what our goals are:
The hot tub filter needs to run at least six hours a day.
We want to press one button to get the hot tub ready to use, the heater and filter on and the room lights on if dark.
The hot tub takes about 30 minutes to warm up. We want to be told it's ready 30 minutes after the hot tub heater is started.
We want to be told when we have been in for 30 minutes, the maximum time we should be in. We want to be told after 20 minutes so we can get ready to get out.
We want to press one button when we are done. It should turn off the heater and filter and the room lights too.
We don’t want to get in the hot tub and have the filter cut off because it was scheduled to go off. As long as we are in the tub, the filter must stay on.
When we are shutting the tub down and were in the tub during the time the filter is normally on, we don’t want the filter to go off before its had its six hour run for the day. That’s a lot of goals, but HCA can accomplish them all.
Program Hot tub maintenance
This program is started by an ON or OFF command. We have scheduled it to start at 2pm by an ON command and again at 8pm by an OFF command. This schedule entry is in both the At Home and Away schedules. Here is what the program does:
If started by an ON, it turns on the filter and sets the flag "Hot tub filter on for maintenance" to Yes.
If started by an OFF, it first tests the flag "Hot tub in use". If that flag is No, the hot tub filter is turned off. Regardless of this test, the flag "Hot tub filter on for maintenance" is set to No. It also does some stuff with its icon so that during the time the hot tub filter is on, the program shows its icon in the ON representation.
The purpose of the two flags is important. Here is what they mean:
Flag|Yes|No
Hot tub filter on for maintenance|The filter is on for its daily maintenance cycle|The filter need not be on for its daily cycle
Hot tub in use|The hot tub is being used|The hot tub is not being used
In this program, by testing the "Hot tub in use" flag when we are about to turn off the filter, we know not to turn it off if someone is using the hot tub.
Program Hot tub use
This program is also started by an ON or OFF command. Starting by an ON gets the tub ready to use. Starting by an OFF finishes up our use.
Here is what the program does when started by an ON command:
If it’s dark (using the It’s Dark flag) the room lights are turned on.
The flag "Hot tub in use" is set to Yes.
The filter and heater are both turned on.
The program delays for 30 minutes.
An ON command is sent to the SC546 chime.
The program Hot tub watchdog is started – but using an ON command, and not using the Start Program element. This is crucial and explained below.
Here is what happens when the program starts by an OFF command:
The heater is turned off
If the filter should still be on for maintenance, it remains on, otherwise it is turned off. This decision is made using the "Hot tub filter on for maintenance" flag. If the flag has the value Yes, the filter needs to remain on.
The room lights are turned off. If they were never turned on, this command has no effect.
The program also manages its own icon so that the ON representation is shown on the HCA display when the hot tub is in use, and the OFF representation otherwise.
The crucial point in this program is the use of the ON element to start the Hot tub watchdog program. When HCA is running a program you can’t start it again. If you try from the HCA user interface, the Start selection on the context menu is replaced by Stop. If a program is running and a schedule would have it start, that schedule entry has no effect. This prevents multiple copies of the same program from running concurrently.
Why is this important to this set of programs? While we have not looked into the Hot tub watchdog program in detail, it’s function is to let us know when its time to get out of the tub. The important point is that it runs for a while. We can get out of the tub anytime. When we get out, we want to be able to start the Hot tub use program with an OFF command. The hot tub use program can’t still be running or we could not start it. The Start Program element starts another program and waits until it's finished before continuing on. Starting a program using an ON element causes that program to run concurrently with the program that started it.
By using the ON element, we get the watchdog program running and then exit the hot tub use program. Since the program is now not running, HCA can start it as soon as we press the OFF button when we leave the hot tub. This happens regardless of whether the hot tub watchdog program is still running.
Finally, lets look at the hot tub watchdog program. Here is what it does:
It delays 20 minutes. The length of time we can safely stay in the tub.
It next checks to see if we have left the tub at this time. This test is done by seeing if the heater is on or off. When we leave the tub we start the hot tub use program (by an OFF button press) and this turns off the heater. So if the heater is on, we have not gotten out.
If we are still in, HCA tells us it's time to get out by either ringing the chime or dimming the room lights. We dim the lights if they were previously turned on and if they are not on, we use the chime.
We delay five minutes, then perform the same elements as steps 2 and 3.
We delay another five minutes, and if we are still not out, we start the hot tub use program using an OFF command.
These three programs working together, complex though they are, establish the goals that we set for automating our hot tub use.
Status folder
A very interesting program is in the status folder. The intent here is to use a KeypadLinc not as a keypad but to use the LEDs as a status reporting device. Three of the LEDs are used to report the red-yellow-green status that HCA shows in the status bar. It does this by using three programs. Each uses an “expression” trigger. This is a special trigger that HCA evaluates each minute and if the expression evaluates to TRUE, the program runs.
The other thing the KeypadLinc status reporting device is to count and display the number of times the driveway sensor has registered an entry during a day. It displays this in a 4 bit binary code – hey, we all are geeks here! This is all in the Display Count program.
Text based scripts
The program Home Programs – All Lights program uses a text based script to turn all the house lights on or off. The script, written in VBScript, is included in the sample folder and shows how to use the HCA objects and method to control HCA devices.
NOTE: The sample program contains the paths to the text scripts and they will have to be changed for your system. Scripts are stored in your documents area, HCA folder, Scripts sub-folder.
Conclusion
That’s the sample. While a bit contrived in points, it does show off most of the facilities in HCA devices, programs, groups, and schedules. The sample also contains a custom icon we added using the icon gallery, and even some sample date book entries we added for your amusement.
We hope it can serve as a starting point for your home design.
The HCA sample file MyHome.hca that came with your HCA installation was constructed to provide you some ideas on what HCA can do. It contains some programs that may help your in your own home. This note describes some features in the sample home that you may want to look at. It also describes what each program in the sample does.
Introduction
The sample file provided when you installed HCA contains a number of features that you may want to examine. We constructed the sample as a way to highlight HCA features and techniques. Some of the methods we used in the sample might be applicable to your own home. In addition to describing the what, we also describe the why – why were elements of the home design done in the way they appear in the sample.
This sample home is built using mostly Insteon devices, UPB keypads – they are a bit nicer than the Insteon keypads and some X10 devices where needed. So the sample shows a number of techniques for working with cross protocol devices.
The house contains three floors – represented by three displays that use DXF file backgrounds – and a number of rooms – Kitchen, Rec Room, Great Room, Bedroom, etc. Also in the home are a number of folders that don’t represent rooms: Outside, Patio, and Deck. Also are some folders not used for rooms at all: Home, Home Programs, and Status.
This points up one HCA feature. Folders can be used to represent anything you want – rooms in your home or collections of devices, programs, and groups that make sense in your application.
Finding your way around: References and Schedule tab
As you look though this example, the reference tab on the properties dialog for devices, programs, and groups shows where it is used in other places. For example, open the properties for the device Hot Tub Room – Tub Filter. Choosing the References tab shows that this device is used by two programs. Also, open the device Great Room – Floor Lamp. This device is used by a group and a schedule. To see the schedule entries that apply to this device all you need do is choose the Schedule tab and the schedule entries display. You can also create new schedule entries by simply double-clicking on the “Add new” branches on the Schedule tab.
Cross protocol use
Open the properties for Home – Entry Lights. This is an Insteon device but look on the triggers page. This device has two triggers for a UPB Keypad.
What does it mean for a device to have a trigger? When HCA receives a message it checks all devices, programs, and groups to see if they contain a trigger that matches the message received. When the trigger matches a program trigger the program I started. But for a device the trigger is translated into what the device can understand and a message is sent to control that device. A translation of the command happens if there is a change in protocol. In this example, the UPB keypad sends Activate and Deactivate commands, and these are translated into Insteon On and Off commands.
To see another example of this, open the properties for Home – Stairway Light Upper. This Insteon device has a number of triggers from X10 motion sensors. Choose the Triggers tab to see this.
Home mode use
This sample home makes use extensively of Home Modes. Almost all devices has non-default home modes selected for one or more of the modes. For example, look at the properties for the device Bedroom – Charge Port. When the home is in Away mode, the device is always off. It goes off when entering the mode and stays off regardless of schedules or programs as long as the Home is in the Away mode. Also in this device you can see that when you wake up, the device goes back on.
Also look at the Rec Room – Lamp. It is set in Away mode to go off and to stay off while in Away mode. But look at the schedule as well. It schedules this device to turn on each day. What happens when you are away? Does the schedule control the device? No. Because the mode says that when Away to suspend all actions. This makes it very simple to schedule devices like this. You want the schedule to happen when you are not away but not when you are way. The Home Mode selected in the device makes this happen.
Another features you should example isn the Bedroom – Closet Light. Open its properties and choose the Green tab. This device is set up to automatically go off after it has been on for 6 minutes – dimming down one minute before going off. How does HCA know it has gone on? A wireless sensor is used when the door is opened and that starts a program that turns the light on. Two notes about this program. First the program just has to turn the light on. Turning it off happens due to the setting on the device. The second feature is the program, if the closet is opened and the home is in the away mode, it sends an email message. Why? Well, this is an example! It does show using a test element to test the current email and also uses the Email element to send the email.
Insteon scenes
There are a number of Insteon devices setup with scenes. Right-click on the Rec Room – Lamp device and select VSE from the popup menu. The right pane of the HCA window clears and the Visual Scene Editor appears. This is a pictorial representation of the scenes that this device participates in. Note that there are two scenes – both initiated by the keypad in the rec room. The VSE was used to create these scenes rather than manually linking. Once a scene has been created HCA knows about it and it can be scheduled and programs can be used to activate the scene. In a program a scene element is used and in a schedule there is a scene type of control.
Interesting programs
This example contains a number of programs that you may want to examine. Look at the Outside – Garden Watering program. It starts off by testing the wind speed and if too great the program stops. It then uses the various outputs on the Insteon EZIO to control the watering valves.
Another interesting program is the programs that respond to the bathroom motion sensors. This program is a bit complex but the idea is as follows: If I walk into the bathroom during the night I want the light to come on at a low level. It does this by testing the time. The light is then turned off after a few minutes. Since the motion sensor can retrigger many times the program first has to check to see if the light is already on. The question is it on at the level the program previously set or have I changed the level manually by using the switch paddle. If I have raised the light level I don’t want the program to shut it off.
Something similar happens in the program Status – Motion Sensor Driveway. This program, started when the driveway sensor reports an entry controls the outside lights. But what it does is first to save the current light level. Then the light level is increased to 100% for a few minutes. After which the light level is restored.
The hot tub program set
This set of programs is the most complex in the sample home. Like with the Wake Up program it’s important to see what our goals are:
The hot tub filter needs to run at least six hours a day.
We want to press one button to get the hot tub ready to use, the heater and filter on and the room lights on if dark.
The hot tub takes about 30 minutes to warm up. We want to be told it's ready 30 minutes after the hot tub heater is started.
We want to be told when we have been in for 30 minutes, the maximum time we should be in. We want to be told after 20 minutes so we can get ready to get out.
We want to press one button when we are done. It should turn off the heater and filter and the room lights too.
We don’t want to get in the hot tub and have the filter cut off because it was scheduled to go off. As long as we are in the tub, the filter must stay on.
When we are shutting the tub down and were in the tub during the time the filter is normally on, we don’t want the filter to go off before its had its six hour run for the day. That’s a lot of goals, but HCA can accomplish them all.
Program Hot tub maintenance
This program is started by an ON or OFF command. We have scheduled it to start at 2pm by an ON command and again at 8pm by an OFF command. This schedule entry is in both the At Home and Away schedules. Here is what the program does:
If started by an ON, it turns on the filter and sets the flag "Hot tub filter on for maintenance" to Yes.
If started by an OFF, it first tests the flag "Hot tub in use". If that flag is No, the hot tub filter is turned off. Regardless of this test, the flag "Hot tub filter on for maintenance" is set to No. It also does some stuff with its icon so that during the time the hot tub filter is on, the program shows its icon in the ON representation.
The purpose of the two flags is important. Here is what they mean:
Flag|Yes|No
Hot tub filter on for maintenance|The filter is on for its daily maintenance cycle|The filter need not be on for its daily cycle
Hot tub in use|The hot tub is being used|The hot tub is not being used
In this program, by testing the "Hot tub in use" flag when we are about to turn off the filter, we know not to turn it off if someone is using the hot tub.
Program Hot tub use
This program is also started by an ON or OFF command. Starting by an ON gets the tub ready to use. Starting by an OFF finishes up our use.
Here is what the program does when started by an ON command:
If it’s dark (using the It’s Dark flag) the room lights are turned on.
The flag "Hot tub in use" is set to Yes.
The filter and heater are both turned on.
The program delays for 30 minutes.
An ON command is sent to the SC546 chime.
The program Hot tub watchdog is started – but using an ON command, and not using the Start Program element. This is crucial and explained below.
Here is what happens when the program starts by an OFF command:
The heater is turned off
If the filter should still be on for maintenance, it remains on, otherwise it is turned off. This decision is made using the "Hot tub filter on for maintenance" flag. If the flag has the value Yes, the filter needs to remain on.
The room lights are turned off. If they were never turned on, this command has no effect.
The program also manages its own icon so that the ON representation is shown on the HCA display when the hot tub is in use, and the OFF representation otherwise.
The crucial point in this program is the use of the ON element to start the Hot tub watchdog program. When HCA is running a program you can’t start it again. If you try from the HCA user interface, the Start selection on the context menu is replaced by Stop. If a program is running and a schedule would have it start, that schedule entry has no effect. This prevents multiple copies of the same program from running concurrently.
Why is this important to this set of programs? While we have not looked into the Hot tub watchdog program in detail, it’s function is to let us know when its time to get out of the tub. The important point is that it runs for a while. We can get out of the tub anytime. When we get out, we want to be able to start the Hot tub use program with an OFF command. The hot tub use program can’t still be running or we could not start it. The Start Program element starts another program and waits until it's finished before continuing on. Starting a program using an ON element causes that program to run concurrently with the program that started it.
By using the ON element, we get the watchdog program running and then exit the hot tub use program. Since the program is now not running, HCA can start it as soon as we press the OFF button when we leave the hot tub. This happens regardless of whether the hot tub watchdog program is still running.
Finally, lets look at the hot tub watchdog program. Here is what it does:
It delays 20 minutes. The length of time we can safely stay in the tub.
It next checks to see if we have left the tub at this time. This test is done by seeing if the heater is on or off. When we leave the tub we start the hot tub use program (by an OFF button press) and this turns off the heater. So if the heater is on, we have not gotten out.
If we are still in, HCA tells us it's time to get out by either ringing the chime or dimming the room lights. We dim the lights if they were previously turned on and if they are not on, we use the chime.
We delay five minutes, then perform the same elements as steps 2 and 3.
We delay another five minutes, and if we are still not out, we start the hot tub use program using an OFF command.
These three programs working together, complex though they are, establish the goals that we set for automating our hot tub use.
Status folder
A very interesting program is in the status folder. The intent here is to use a KeypadLinc not as a keypad but to use the LEDs as a status reporting device. Three of the LEDs are used to report the red-yellow-green status that HCA shows in the status bar. It does this by using three programs. Each uses an “expression” trigger. This is a special trigger that HCA evaluates each minute and if the expression evaluates to TRUE, the program runs.
The other thing the KeypadLinc status reporting device is to count and display the number of times the driveway sensor has registered an entry during a day. It displays this in a 4 bit binary code – hey, we all are geeks here! This is all in the Display Count program.
Text based scripts
The program Home Programs – All Lights program uses a text based script to turn all the house lights on or off. The script, written in VBScript, is included in the sample folder and shows how to use the HCA objects and method to control HCA devices.
NOTE: The sample program contains the paths to the text scripts and they will have to be changed for your system. Scripts are stored in your documents area, HCA folder, Scripts sub-folder.
Conclusion
That’s the sample. While a bit contrived in points, it does show off most of the facilities in HCA devices, programs, groups, and schedules. The sample also contains a custom icon we added using the icon gallery, and even some sample date book entries we added for your amusement.
We hope it can serve as a starting point for your home design.