It occurred to me that a lot of the programming examples we've put here so far have been fairly involved. There's not a lot out there that really tells new HAI users how to get started with automation and writing code for the controller, so I'm going to start a series here on basics of programming automation code for the Omni/Lumina series.
First of all, if you want to write automation code for your Omni or Lumina controller, you really really need PC Access. Since version 3.0 of the Omni firmware introduced multiple and compound conditions, it is no longer really possible to do programming through a console. And even if it was, you really do not want to do things that way -- the interface is just too limited. The end user version is about $50 at the authorized online outlets; the part number is 1106W.
The automation code is divided into blocks, which are independent chunks of code. Each block consists of the following, in this order:
A block of code is executed when its trigger event occurs. An event is when the status of something that the system keeps track of changes -- the time of day, a light being turned on or off, the alarm being armed or disarmed, the status of a security zone, a scene being selected, etc. The trigger condition specifies which event should cause the block of code to be entered. If the block has more than one trigger, the occurrence of any of its trigger events will cause the block to be entered. The block is entered only once; it is not entered again until an event specified by one of its trigger clauses occurs again.
Two of the easiest-to-understand triggers are TIMED and EVERY. TIMED events occur at a specified time of day, or at a time relative to sunrise or sunset. They can be further qualified to only occur on a specific date, or on certain days of the week. Here is an example:
This is exactly how the code appears in PC Access. (The number "36" at left is a sequential block number that PC Access adds; it is not part of the code.) The triggering event for this block will occur when the time becomes 6:20 PM, but only on Mondays, Wednesdays, and Fridays. Note that it will be triggered only once on that day, when the time rolls over from 6:19:59 to 6:20:00; it will not keep reoccurring until the time becomes 6:21.
An EVERY event happens at a specified interval. A simple example:
This will write a message to the system log every four hours. Interval settings allowed range from 5 seconds to 12 hours. Note that the triggering event occurs when the time of day is evenly divisible by the interval; it is not based on when the controller was started up. So, in the example above, if we start the controller at 2:33 PM, the first time this block of code will be executed will not be at 6:33 PM; it will be at 4:00 PM.
Here is an example with more than one trigger:
This code will be entered when either of the two garage doors is opened. (The doors each have a magnetic sensor which is connected to a zone on the controller.)
Note that it is legal for two or more blocks to specify the same trigger. In this case, when the triggering event occurs, each block will be entered in the order that they appear in PC Access. A following block will not be entered until the preceding block has completed.
Next I'll discuss actions (I'll come back to conditions in a bit). Actions are things that the controller can do -- turn lights on and off, change thermostat settings, or arm/disarm the alarm, to name a few. With only a few exceptions, anything that your Omni or Lumina is capable of doing, you can do with an action. In the code listing, all actions start with the word "THEN". An example:
At the specified time, this code block is executed, and it turns on the specified lights and logs the message. Actions always occur in the specified order, so in this code block, the kitchen soffit fans will be turned on first, and the message logging will be the last thing that happens.
(Note about the trigger: The controller calculates the time of sunrise and sunset each day. It does this based on your latitude, longitude, and time zone, which is why it is important to set these properly when you install your system.)
Now, about conditions. What conditions allow you to do is check additional criteria before the actions in a block are executed. This makes the decision to execute a block much more sophisticated than what can be accomplished with triggers alone. Whatever combination of conditions is specified, they must collectively evaluate to a true statement. If they don't, the block is executed immediately and none of the actions in the block are executed. In the code listing in PC Access, all conditions begin with the word "AND". An example:
First of all, we see that this block has two trigger conditions. It will be entered at 5:30 AM on weekdays, or 7:30 AM on weekends. The condition (the line starting with AND) will then check to see if the outdoor temperature is below 35 degrees. Only if this is true will the action be executed. If the outdoor temperature is 35 or above, the thermostat's heat setpoint will not be changed.
Note the difference between a trigger and a condition. This block's triggers are the two times of day and days of week specified. The outdoor temperature sensor's value is, in this case, not being used as a trigger; a change in the outdoor temperature cannot trigger this block. Rather, when the block is entered, the condition checks the value of the outdoor temperature at that moment, and it makes a decision based on that.
You can combine conditions. Normally, conditions are combined with an "AND" operation such that they must all be true in order for the actions to be executed. However, you can separate groups of conditions with an "OR" statement, and the total condition will evaluate to true of either of the two groups evaluates to true. In grouping, AND has priority over OR. This is all easier to understand by looking at an example, so here is a fairly complex one:
The master bath heater will be turned on for 40 minutes if at least one of the following is true:
* The main floor thermostat is in the heat mode, and the outdoor temperature is below 60.
* The main floor thermostat is in the auto mode, and the outdoor temperature is below 53.
* The main floor thermostat is in the emergency heat mode.
* The "master bath heat special" flag is on. (I'll talk about flags in a future installment.)
A few further notes about how conditions are evaluated: A light that is dimmable is considered "on" unless it is completely off. (If you look at the light unit's status in PC Access and it says "LEVEL xx%", it's on.) A condition that tests to see if the security mode is NIGHT will also be considered true if the mode is NIGHT DELAY; similarly, a condition that tests for DAY mode will be true if the current mode is DAY INSTANT, and a condition that tests for AWAY mode will be true if the current mode is VACATION. When a condition tests for a time of day, the beginning of the day is considered 12:01 AM and the end of the day is considered midnight; thus, a condition that tests to see if the time is greater than 10:00 AM will be true if the time is between 10:01 AM and midnight.
First of all, if you want to write automation code for your Omni or Lumina controller, you really really need PC Access. Since version 3.0 of the Omni firmware introduced multiple and compound conditions, it is no longer really possible to do programming through a console. And even if it was, you really do not want to do things that way -- the interface is just too limited. The end user version is about $50 at the authorized online outlets; the part number is 1106W.
The automation code is divided into blocks, which are independent chunks of code. Each block consists of the following, in this order:
- At least one trigger
- Zero or more conditions
- At least one action
A block of code is executed when its trigger event occurs. An event is when the status of something that the system keeps track of changes -- the time of day, a light being turned on or off, the alarm being armed or disarmed, the status of a security zone, a scene being selected, etc. The trigger condition specifies which event should cause the block of code to be entered. If the block has more than one trigger, the occurrence of any of its trigger events will cause the block to be entered. The block is entered only once; it is not entered again until an event specified by one of its trigger clauses occurs again.
Two of the easiest-to-understand triggers are TIMED and EVERY. TIMED events occur at a specified time of day, or at a time relative to sunrise or sunset. They can be further qualified to only occur on a specific date, or on certain days of the week. Here is an example:
Code:
36. TIMED 6:20 PM M-W-F--
THEN SET LIGHTING LEVEL Entrance hall overheads TO 75%
This is exactly how the code appears in PC Access. (The number "36" at left is a sequential block number that PC Access adds; it is not part of the code.) The triggering event for this block will occur when the time becomes 6:20 PM, but only on Mondays, Wednesdays, and Fridays. Note that it will be triggered only once on that day, when the time rolls over from 6:19:59 to 6:20:00; it will not keep reoccurring until the time becomes 6:21.
An EVERY event happens at a specified interval. A simple example:
Code:
15. EVERY 4 HOURS
THEN LOG Mark Time
This will write a message to the system log every four hours. Interval settings allowed range from 5 seconds to 12 hours. Note that the triggering event occurs when the time of day is evenly divisible by the interval; it is not based on when the controller was started up. So, in the example above, if we start the controller at 2:33 PM, the first time this block of code will be executed will not be at 6:33 PM; it will be at 4:00 PM.
Here is an example with more than one trigger:
Code:
6. WHEN Garage door 1 NOT READY
WHEN Garage door 2 NOT READY
THEN Workbench and interior door lts ON FOR 10 MINUTES
This code will be entered when either of the two garage doors is opened. (The doors each have a magnetic sensor which is connected to a zone on the controller.)
Note that it is legal for two or more blocks to specify the same trigger. In this case, when the triggering event occurs, each block will be entered in the order that they appear in PC Access. A following block will not be entered until the preceding block has completed.
Next I'll discuss actions (I'll come back to conditions in a bit). Actions are things that the controller can do -- turn lights on and off, change thermostat settings, or arm/disarm the alarm, to name a few. With only a few exceptions, anything that your Omni or Lumina is capable of doing, you can do with an action. In the code listing, all actions start with the word "THEN". An example:
Code:
34. TIMED 20 MINUTES BEFORE SUNSET MTWTFSS
THEN Kitchen soffit cans ON
THEN Rec room TV lamp ON
THEN Front porch lights ON
THEN Exterior floodlights ON
THEN LOG Evening lights on
At the specified time, this code block is executed, and it turns on the specified lights and logs the message. Actions always occur in the specified order, so in this code block, the kitchen soffit fans will be turned on first, and the message logging will be the last thing that happens.
(Note about the trigger: The controller calculates the time of sunrise and sunset each day. It does this based on your latitude, longitude, and time zone, which is why it is important to set these properly when you install your system.)
Now, about conditions. What conditions allow you to do is check additional criteria before the actions in a block are executed. This makes the decision to execute a block much more sophisticated than what can be accomplished with triggers alone. Whatever combination of conditions is specified, they must collectively evaluate to a true statement. If they don't, the block is executed immediately and none of the actions in the block are executed. In the code listing in PC Access, all conditions begin with the word "AND". An example:
Code:
18. TIMED 5:30 AM MTWTF--
TIMED 7:30 AM -----SS
AND IF Outdoor Temp Sensor CURRENT READING IS LESS THAN 35
THEN Main Floor Tstat HEAT SETPOINT 71
First of all, we see that this block has two trigger conditions. It will be entered at 5:30 AM on weekdays, or 7:30 AM on weekends. The condition (the line starting with AND) will then check to see if the outdoor temperature is below 35 degrees. Only if this is true will the action be executed. If the outdoor temperature is 35 or above, the thermostat's heat setpoint will not be changed.
Note the difference between a trigger and a condition. This block's triggers are the two times of day and days of week specified. The outdoor temperature sensor's value is, in this case, not being used as a trigger; a change in the outdoor temperature cannot trigger this block. Rather, when the block is entered, the condition checks the value of the outdoor temperature at that moment, and it makes a decision based on that.
You can combine conditions. Normally, conditions are combined with an "AND" operation such that they must all be true in order for the actions to be executed. However, you can separate groups of conditions with an "OR" statement, and the total condition will evaluate to true of either of the two groups evaluates to true. In grouping, AND has priority over OR. This is all easier to understand by looking at an example, so here is a fairly complex one:
Code:
19. TIMED 5:50 AM MTWTF--
AND IF Main Floor Tstat SYSTEM MODE IS HEAT
AND IF Outdoor Temp Sensor CURRENT READING IS LESS THAN 60
OR
AND IF Main Floor Tstat SYSTEM MODE IS AUTO
AND IF Outdoor Temp Sensor CURRENT READING IS LESS THAN 53
OR
AND IF Main Floor Tstat SYSTEM MODE IS EMERGENCY HEAT
OR
AND IF Master Bath Heat Special ON
THEN Master bath heater ON FOR 40 MINUTES
The master bath heater will be turned on for 40 minutes if at least one of the following is true:
* The main floor thermostat is in the heat mode, and the outdoor temperature is below 60.
* The main floor thermostat is in the auto mode, and the outdoor temperature is below 53.
* The main floor thermostat is in the emergency heat mode.
* The "master bath heat special" flag is on. (I'll talk about flags in a future installment.)
A few further notes about how conditions are evaluated: A light that is dimmable is considered "on" unless it is completely off. (If you look at the light unit's status in PC Access and it says "LEVEL xx%", it's on.) A condition that tests to see if the security mode is NIGHT will also be considered true if the mode is NIGHT DELAY; similarly, a condition that tests for DAY mode will be true if the current mode is DAY INSTANT, and a condition that tests for AWAY mode will be true if the current mode is VACATION. When a condition tests for a time of day, the beginning of the day is considered 12:01 AM and the end of the day is considered midnight; thus, a condition that tests to see if the time is greater than 10:00 AM will be true if the time is between 10:01 AM and midnight.