SuncrestReef
That Apex guy
Neptune Apex Programming Tutorials, Part 2: Timers
For inspiration: a beautiful 10-gallon nano tank.
This photo is from the Reef2Reef archives courtesy of @Dferrari13 ©2019, All Rights Reserved.
Note From the Editor:
This article is Part 2 of a series. Part 1 may be found here.
This article and several future ones by the same author were originally part of several presentations made to a local aquarium club on programming your Neptune Apex Controller. The article is reprinted with permission from the author.
Because this topic will be of great interest to some readers but no interest to others who have not automated their systems, R2R will run these programming articles every Friday until we come to the end of the series.
Photos, images, and diagrams included in this article below are all courtesy of the author, @SuncrestReef ©2019, All Rights Reserved.
~~~~~~~~~~~~~~~~~~~~~~~
Timers: OSC, If Time, DOW, Defer, When, and Min Time
One of the most common tasks in reefing is to turn on and off a device on a specific schedule, whether that’s based on time of day, a repeating cycle of a number of minutes or hours, or on specific days of the week. The Apex gives you a number of choices on how to program outputs based on timers, each with a specific purpose:
OSC
The OSC (short for Oscillation) command is great for turning things on and off in a repeating cycle. It uses three separate timers:
OSC MMM:SS/MMM:SS/MMM:SS Then [ON/OFF/Profile]
The timers define Delay before first run / Time to run / Delay until next run
The maximum value you can specify for any one of the timers is 999:99, which equates to 16 hours, 39 minutes, 59 seconds.
Here are a few examples:
OSC 000:00/005:00/005:00 Then ON
This would turn on the output for 5 minutes, then turn it off for 5 minutes, and repeat indefinitely:
OSC 000:00/007:00/002:00 Then ON
This would turn on the output for 7 minutes, then turn it off for 2 minutes, and repeat indefinitely:
OSC 007:00/002:00/000:00 Then ON
This would wait for 7 minutes, then turn on the output for 2 minutes, then turn it off for 0 minutes. It would then repeat the 7 minute off, 2 minute on cycle.
One reason to use the initial delay would be to stagger two different outputs so they don’t run at the exact same time, such as dosing pumps.
The odd thing about the initial delay timer is that it calculates from midnight of January 1, 1996. If your timer values added together are evenly divisible into 1440 (24 hours), then your output will always come on at the same times each day. If they are not divisible into 1440, then each day will be slightly different, and you’d have to do some interesting math to figure out when it would turn on on any given day.
My personal example:
I use the OSC command to activate my Swabbie skimmer neck cleaner every six hours. The Swabbie has a motor that rotates the cleaning wiper in the skimmer neck very slowly, so it needs to run for about 2 minutes to thoroughly wipe all the crud from the neck. Here is the programming for my Swabbie output:
Fallback OFF
OSC 000:00/002:00/358:00 Then ON
If Output EB_3_Skimmer = OFF Then OFF
The first line — Fallback OFF — instructs the Apex to turn off this output if the Apex ever gets disconnected from the Energy Bar where the Swabbie is plugged in. This could also apply if the Apex locks up and becomes unresponsive (which rarely happens). This just basically means don’t run the program if the Apex unit isn’t in control of the situation.
The OSC timers in this example are:
Since my timers multiplied by 4 = 1440, my OSC timers trigger the Swabbie at the same times each day: Midnight, 6am, noon, 6pm.
If Time
If Time is used to turn on or turn off an output between a range of time:
If Time HH:MM to HH:MM Then [ON/OFF/Profile]
The If Time command is much simpler than OSC, but it does have a few intricacies to be aware of:
The times can only be specified in hours and minutes (in 24 hour format), so it is not as granular as the OSC command which goes down to minutes and seconds.
A very important thing to know is that the beginning time and ending times are inclusive. For example:
Set OFF
If Time 10:00 to 10:01 Then ON
will turn on the output at 10:00 and turn it off at 10:02:
This means that the shortest duration you can run an output using If Time is actually two minutes. You cannot specify the same value for the start and end times, so 10:00 to 10:00 is invalid. If you want to use If Time for a shorter duration, it would need to be combined with the Defer statement:
Set OFF
If Time 10:00 to 10:01 Then ON
Defer 001:00 Then ON
This will cause it to wait until 10:01 to turn on, then turn off at 10:02. effectively giving you a 1 minute timer:
I’ll explain Defer in more detail in the next section.
Another tip for If Time is that you can span midnight with your start and end time. For example, I run my refugium light on the opposite schedule from my display tank lights:
Set OFF
If Time 18:00 to 08:00 Then ON
DOW
The DOW (Day Of Week) command can use to turn on or off and output based on the day of week.
If DOW SMTWTFS Then [ON/OFF/Profile]
The letters for each day of the week are placeholders, and if you substitute one with a hyphen, then that day will evaluate False and the output will not be triggered for that day. For example:
Set OFF
If DOW SM-W-FS Then ON
This would turn on the output every day except for Tuesday and Thursday.
DOW is particularly useful when combined with the If Time command. Let’s say you want to run a circulation pump once per day for an hour every day except on Saturday when you are doing maintenance:
Set OFF
If Time 12:00 to 12:59 Then ON
If DOW ------S Then OFF
Remember from my introduction section that the last line of programming that evaluates True will dictate what the output does. In this example, the If Time command is true from 12:00 to 12:59, but the DOW command will evaluate True only on Saturday since that’s the only placeholder not replaced with a hyphen.
Defer
Defer is used to delay taking action on an output for a period of time.
Defer MMM:SS Then [ON/OFF]
This command is different than other ON/OFF commands because it’s actually delaying the outlet from changing from off to on, or from on to off, for the specified amount of time. In the above example using If Time where we need the output to turn on for less than 2 minutes, but If Time can’t do that, so the Defer delay was used to prevent the output from turning on until the 1 minute delay elapsed.
Defer is particularly useful when basing an output on the reading of a probe or sensor. For example, if you have a float switch in your sump to trigger your ATO pump when the water is low, but the water surface has small ripples that can cause the float switch to go up and down with the water movement, it could trigger your ATO pump on and off rapidly for no valid reason. To prevent this, the Defer command can be used to wait for the float switch to provide a consistent reading for a period of time, ensuring that the water really is low enough to justify turning on the ATO pump:
Set OFF
If Float1 Open Then ON
Defer 000:10 Then ON
In this example, the float switch needs to continuously report Open for 10 seconds before the pump will actually be turned on. Once the float switch first reports Open, the Defer countdown timer begins. If after 3 seconds the float switch reports Closed, then the timer is reset to 10 seconds.
A good analogy for Defer is the shot clock in NBA basketball. (sorry to those non-basketball fans reading this). Once your team has the ball, you have 24 seconds to make a shot. If the ball doesn’t touch the rim, the ball is turned over to your opponent. But if you do make a shot that hits the rim but doesn’t go in, the shot clock is reset and you have another 24 seconds to try again. The Defer is just a countdown timer that once it expires, the output can then change state.
To take our float switch example one step further, I’ll add another Defer to handle the situation when the ATO pump is adding water and the float switch finally reports Closed due to the rising water level. Since there are still ripples on the water surface, it might toggle between Open and Closed several times before it finally settles in on Closed.
Set OFF
If Float1 Open Then ON
Defer 000:10 Then ON
Defer 000:10 Then OFF
Defer statements can be placed anywhere in the list of programming lines because they apply to the output itself and are not part of what evaluates as True or False. Another way to represent this is:
Set OFF
If Float1 Open Then ON
— — — — — — — — — — —
Defer 000:10 Then ON
Defer 000:10 Then OFF
(don’t put the dashes into your program….this is just for a visualization)
The program is above the dashed line, and the last line to evaluate as True dictates how to set the output state. The Defer statements are then controlling how long to wait before setting the output state.
When
The When command is very unique in Apex programming. It is used to switch an output’s tile from AUTO to OFF if a condition is met. It is most commonly used for ATO pump programming, since a failed optical switch or float switch could allow the ATO pump to continue flooding your sump with fresh water, harming your tank inhabitants and flooding your home; or perhaps the ATO reservoir is empty and the pump continues to run dry. Once triggered, the output is forced into manual OFF mode and the programming will no longer operate until you manually move the slider back to the AUTO position.
Using our ATO pump example from above, here we add the When command. This assumes that our ATO pump should never need to run for more that 3 minutes straight under normal evaporation conditions.
Set OFF
If Float1 Open Then ON
Defer 000:10 Then ON
Defer 000:10 Then OFF
When ON > 003:00 Then OFF
Like the Defer commands, When may be placed anywhere in the list of programming lines. I tend to place Defer and When commands at the end for ease of reading and troubleshooting.
Min Time
The Min Time command is similar to Defer, but with a distinct difference:
Again, the most common example of Min Time is for the ATO pump. Rather than having it turn on and off every few minutes as dictated by the float switch for the slightest amount of evaporation, you can force it to run less frequently even though that means it needs to pump water a bit longer.
Set OFF
If Float1 Open Then ON
Defer 000:10 Then ON
Defer 000:10 Then OFF
When ON > 003:00 Then OFF
Min Time 060:00 Then OFF
This tells the output to remain Off for at least 60 minutes. Once that timer expires, the specified programming commands will operate again as normal.
Hopefully this tutorial has been helpful. Stay tuned for the next article in this series--ATK programming and troubleshooting--which builds on what I covered here.
~~~~~~~~~~
We encourage all our readers to join the Reef2Reef forum. It’s easy to register, free, and reefkeeping is much easier and more fun in a community of fellow aquarists. We pride ourselves on a warm and family-friendly forum where everyone is welcome. You will also find lots of contests and giveaways with our sponsors.
~~~~~~~~~~~
Author Profile: @SuncrestReef
John Halsey is a reefing hobbyist who keeps a Red Sea Reefer XL 425 in his living room. He is new to reefing with just over one year of experience, but has been successful in keeping a healthy mixed reef by following best practices learned here on R2R as well as actively participating in his local aquarist club -- PNWMAS -- in Portland, Oregon. John retired from his 30-year career in IT support, and put that technical expertise to good use by automating much of his aquarium equipment with an extensive Neptune Apex system.
~~~~~~~~~~~
For inspiration: a beautiful 10-gallon nano tank.
This photo is from the Reef2Reef archives courtesy of @Dferrari13 ©2019, All Rights Reserved.
Note From the Editor:
This article is Part 2 of a series. Part 1 may be found here.
This article and several future ones by the same author were originally part of several presentations made to a local aquarium club on programming your Neptune Apex Controller. The article is reprinted with permission from the author.
Because this topic will be of great interest to some readers but no interest to others who have not automated their systems, R2R will run these programming articles every Friday until we come to the end of the series.
Photos, images, and diagrams included in this article below are all courtesy of the author, @SuncrestReef ©2019, All Rights Reserved.
~~~~~~~~~~~~~~~~~~~~~~~
Timers: OSC, If Time, DOW, Defer, When, and Min Time
One of the most common tasks in reefing is to turn on and off a device on a specific schedule, whether that’s based on time of day, a repeating cycle of a number of minutes or hours, or on specific days of the week. The Apex gives you a number of choices on how to program outputs based on timers, each with a specific purpose:
- OSC: A repeating On/Off interval, where you specify the number of minutes & seconds to be ON, and the number of minutes and seconds to be OFF
- If Time: Turn on or off between specific times on the clock, down to the minute
- DOW: Turn on or off based on the day of week
- Defer: A delay of time in minutes and seconds to wait before turning on or off
- When: A failsafe to switch an output from AUTO to OFF if it has been on or off for longer than specified in minutes and seconds. Requires manual intervention to reactivate the automatic programming.
- Min Time: A delay of minutes and seconds before the output is allowed to turn on or off, regardless of the programming conditions
OSC
The OSC (short for Oscillation) command is great for turning things on and off in a repeating cycle. It uses three separate timers:
OSC MMM:SS/MMM:SS/MMM:SS Then [ON/OFF/Profile]
The timers define Delay before first run / Time to run / Delay until next run
The maximum value you can specify for any one of the timers is 999:99, which equates to 16 hours, 39 minutes, 59 seconds.
Here are a few examples:
OSC 000:00/005:00/005:00 Then ON
This would turn on the output for 5 minutes, then turn it off for 5 minutes, and repeat indefinitely:
This would turn on the output for 7 minutes, then turn it off for 2 minutes, and repeat indefinitely:
OSC 007:00/002:00/000:00 Then ON
This would wait for 7 minutes, then turn on the output for 2 minutes, then turn it off for 0 minutes. It would then repeat the 7 minute off, 2 minute on cycle.
The odd thing about the initial delay timer is that it calculates from midnight of January 1, 1996. If your timer values added together are evenly divisible into 1440 (24 hours), then your output will always come on at the same times each day. If they are not divisible into 1440, then each day will be slightly different, and you’d have to do some interesting math to figure out when it would turn on on any given day.
My personal example:
I use the OSC command to activate my Swabbie skimmer neck cleaner every six hours. The Swabbie has a motor that rotates the cleaning wiper in the skimmer neck very slowly, so it needs to run for about 2 minutes to thoroughly wipe all the crud from the neck. Here is the programming for my Swabbie output:
Fallback OFF
OSC 000:00/002:00/358:00 Then ON
If Output EB_3_Skimmer = OFF Then OFF
The first line — Fallback OFF — instructs the Apex to turn off this output if the Apex ever gets disconnected from the Energy Bar where the Swabbie is plugged in. This could also apply if the Apex locks up and becomes unresponsive (which rarely happens). This just basically means don’t run the program if the Apex unit isn’t in control of the situation.
The OSC timers in this example are:
- 000:00 = zero minutes from midnight until the first run
- 002:00 = two minutes of actual run time
- 358:00 = 5 hours & 58 minutes to delay until the next run
Since my timers multiplied by 4 = 1440, my OSC timers trigger the Swabbie at the same times each day: Midnight, 6am, noon, 6pm.
If Time
If Time is used to turn on or turn off an output between a range of time:
If Time HH:MM to HH:MM Then [ON/OFF/Profile]
The If Time command is much simpler than OSC, but it does have a few intricacies to be aware of:
The times can only be specified in hours and minutes (in 24 hour format), so it is not as granular as the OSC command which goes down to minutes and seconds.
A very important thing to know is that the beginning time and ending times are inclusive. For example:
Set OFF
If Time 10:00 to 10:01 Then ON
will turn on the output at 10:00 and turn it off at 10:02:
This means that the shortest duration you can run an output using If Time is actually two minutes. You cannot specify the same value for the start and end times, so 10:00 to 10:00 is invalid. If you want to use If Time for a shorter duration, it would need to be combined with the Defer statement:
Set OFF
If Time 10:00 to 10:01 Then ON
Defer 001:00 Then ON
This will cause it to wait until 10:01 to turn on, then turn off at 10:02. effectively giving you a 1 minute timer:
Another tip for If Time is that you can span midnight with your start and end time. For example, I run my refugium light on the opposite schedule from my display tank lights:
Set OFF
If Time 18:00 to 08:00 Then ON
The DOW (Day Of Week) command can use to turn on or off and output based on the day of week.
If DOW SMTWTFS Then [ON/OFF/Profile]
The letters for each day of the week are placeholders, and if you substitute one with a hyphen, then that day will evaluate False and the output will not be triggered for that day. For example:
Set OFF
If DOW SM-W-FS Then ON
This would turn on the output every day except for Tuesday and Thursday.
Set OFF
If Time 12:00 to 12:59 Then ON
If DOW ------S Then OFF
Remember from my introduction section that the last line of programming that evaluates True will dictate what the output does. In this example, the If Time command is true from 12:00 to 12:59, but the DOW command will evaluate True only on Saturday since that’s the only placeholder not replaced with a hyphen.
Defer
Defer is used to delay taking action on an output for a period of time.
Defer MMM:SS Then [ON/OFF]
This command is different than other ON/OFF commands because it’s actually delaying the outlet from changing from off to on, or from on to off, for the specified amount of time. In the above example using If Time where we need the output to turn on for less than 2 minutes, but If Time can’t do that, so the Defer delay was used to prevent the output from turning on until the 1 minute delay elapsed.
Defer is particularly useful when basing an output on the reading of a probe or sensor. For example, if you have a float switch in your sump to trigger your ATO pump when the water is low, but the water surface has small ripples that can cause the float switch to go up and down with the water movement, it could trigger your ATO pump on and off rapidly for no valid reason. To prevent this, the Defer command can be used to wait for the float switch to provide a consistent reading for a period of time, ensuring that the water really is low enough to justify turning on the ATO pump:
Set OFF
If Float1 Open Then ON
Defer 000:10 Then ON
In this example, the float switch needs to continuously report Open for 10 seconds before the pump will actually be turned on. Once the float switch first reports Open, the Defer countdown timer begins. If after 3 seconds the float switch reports Closed, then the timer is reset to 10 seconds.
A good analogy for Defer is the shot clock in NBA basketball. (sorry to those non-basketball fans reading this). Once your team has the ball, you have 24 seconds to make a shot. If the ball doesn’t touch the rim, the ball is turned over to your opponent. But if you do make a shot that hits the rim but doesn’t go in, the shot clock is reset and you have another 24 seconds to try again. The Defer is just a countdown timer that once it expires, the output can then change state.
To take our float switch example one step further, I’ll add another Defer to handle the situation when the ATO pump is adding water and the float switch finally reports Closed due to the rising water level. Since there are still ripples on the water surface, it might toggle between Open and Closed several times before it finally settles in on Closed.
Set OFF
If Float1 Open Then ON
Defer 000:10 Then ON
Defer 000:10 Then OFF
Defer statements can be placed anywhere in the list of programming lines because they apply to the output itself and are not part of what evaluates as True or False. Another way to represent this is:
Set OFF
If Float1 Open Then ON
— — — — — — — — — — —
Defer 000:10 Then ON
Defer 000:10 Then OFF
(don’t put the dashes into your program….this is just for a visualization)
The program is above the dashed line, and the last line to evaluate as True dictates how to set the output state. The Defer statements are then controlling how long to wait before setting the output state.
When
The When command is very unique in Apex programming. It is used to switch an output’s tile from AUTO to OFF if a condition is met. It is most commonly used for ATO pump programming, since a failed optical switch or float switch could allow the ATO pump to continue flooding your sump with fresh water, harming your tank inhabitants and flooding your home; or perhaps the ATO reservoir is empty and the pump continues to run dry. Once triggered, the output is forced into manual OFF mode and the programming will no longer operate until you manually move the slider back to the AUTO position.
Using our ATO pump example from above, here we add the When command. This assumes that our ATO pump should never need to run for more that 3 minutes straight under normal evaporation conditions.
Set OFF
If Float1 Open Then ON
Defer 000:10 Then ON
Defer 000:10 Then OFF
When ON > 003:00 Then OFF
Like the Defer commands, When may be placed anywhere in the list of programming lines. I tend to place Defer and When commands at the end for ease of reading and troubleshooting.
Min Time
The Min Time command is similar to Defer, but with a distinct difference:
- Defer - will delay an outlet from changing its state for a specified period of time
- Min Time - will ensure an outlet stays in its current state for a minimum period of time
Again, the most common example of Min Time is for the ATO pump. Rather than having it turn on and off every few minutes as dictated by the float switch for the slightest amount of evaporation, you can force it to run less frequently even though that means it needs to pump water a bit longer.
Set OFF
If Float1 Open Then ON
Defer 000:10 Then ON
Defer 000:10 Then OFF
When ON > 003:00 Then OFF
Min Time 060:00 Then OFF
This tells the output to remain Off for at least 60 minutes. Once that timer expires, the specified programming commands will operate again as normal.
Hopefully this tutorial has been helpful. Stay tuned for the next article in this series--ATK programming and troubleshooting--which builds on what I covered here.
~~~~~~~~~~
We encourage all our readers to join the Reef2Reef forum. It’s easy to register, free, and reefkeeping is much easier and more fun in a community of fellow aquarists. We pride ourselves on a warm and family-friendly forum where everyone is welcome. You will also find lots of contests and giveaways with our sponsors.
~~~~~~~~~~~
Author Profile: @SuncrestReef
John Halsey is a reefing hobbyist who keeps a Red Sea Reefer XL 425 in his living room. He is new to reefing with just over one year of experience, but has been successful in keeping a healthy mixed reef by following best practices learned here on R2R as well as actively participating in his local aquarist club -- PNWMAS -- in Portland, Oregon. John retired from his 30-year career in IT support, and put that technical expertise to good use by automating much of his aquarium equipment with an extensive Neptune Apex system.
~~~~~~~~~~~
