SuncrestReef
That Apex guy
Seawitch submitted a new Article:
Neptune Apex Programming Tutorials, Part 5: Virtual Outputs
Note From the Editor:
This article is Part 5 of a series. Feel free to go back and read Part 1, Part 2, Part 3, or Part 4.
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.
For inspiration, here's a spectacular macro photo from the author's reef tank.
And here's an interesting photo of how the author shoots photos.
~~~~~~~~~~~~~~~~~~~~~~
Virtual Outputs
So far in this series we have focused a lot on programming outputs that turn on or turn off devices plugged into Energy Bars. These outputs are physical, tangible electrical outlets that have power cords plugged in. Virtual outputs are imaginary outputs that we can use to create more complex programming than would normally be available given the Apex programming limitations. Virtual outputs can be used for a variety of reasons:
Creating a virtual output
Virtual outputs are created from the Outputs screen:
Maintenance master On/Off switch
When I conduct major maintenance in my sump, such as cleaning my return pump or emptying and cleaning out the sump, I normally turn off a number of devices:
Return Pump:
Fallback ON
Set 100
If LkCrpt CLOSED Then OFF
If LkSump CLOSED Then OFF
If SMP_Lo OPEN Then OFF
If Output Maintenance = ON Then OFF
If FeedA 000 Then 1
If FeedB 000 Then 1
Heaters:
Fallback OFF
If Tmp < 78.0 Then ON
If Tmp > 78.0 Then OFF
If Output Maintenance = ON Then OFF
Defer 001:00 Then ON
Defer 000:15 Then OFF
and so on with the other devices. Just that single line of If Output Maintenance = ON Then OFF is all that’s needed. Remember to place that line below any line of code that may turn the device on because the code is processed from top to bottom, as covered in our Introduction tutorial.
Since the Maintenance virtual output doesn’t actually run any program (other than its default Set OFF command), the only way to activate Maintenance mode is to manually move the slider to the ON position:
When you complete your maintenance, move the slider to the OFF position:
Since this output doesn’t have any programming, I prefer to always leave it in the manual OFF position rather than AUTO, even though in this particular example it doesn’t make a difference. My reasoning is that it’s easier to see at a glance when the slider is in the OFF position than seeing it in the AUTO position and then needing to look more closely above the slider to see if it says “On” or “Off” in a smaller font.
This master On/Off switch is by far the simplest usage for virtual outputs. Next, let’s look at some examples that involve a bit more programming.
Providing enhanced control of alarm programming
Virtual outputs provide a way to trigger alerts for certain conditions beyond the simple “If this then ON” commands in the Email Alarm output. My favorite example is a warning if my ATO hasn’t run recently. Under normal circumstances my ATO runs every 30 minutes due to evaporation, or perhaps every 60 or 90 minutes if I happened to add a little excess water to my sump. But it should NEVER wait over 2 hours to run, so if it does I’d like to know. I use a virtual output named Alert_ATO to keep track of this for me:
Set OFF
If ATK_LO OPEN Then ON
Defer 120:00 Then ON
Then in my Email_Alarm output, I added this line:
If Output Alert_ATO = ON Then ON
If you recall from the ATK Troubleshooting tutorial, the lower optical sensor in my sump is named ATK_LO, and when it reports OPEN then the ATK_PMUP output is turned on to refill the sump. This Alert_ATO virtual output is instructed to turn ON when ATK_LO is OPEN, but the Defer 120:00 forces the virtual output to wait for 2 hours before finally changing state to ON, as discussed in the Timers tutorial. If during that 2 hour timer the sump is refilled and ATK_LO changes to CLOSED, then the Defer timer is reset. But if the pump doesn’t run and the 2 hour timer finally reaches zero, the Alert_ATO virtual output finally changes state to ON, and the Email_Alarm is then triggered. Pretty slick!
Once the Email_Alert output is on, it will send text and email messages once per hour until the situation is corrected or the output is manually turned off. For critical alarms this is fine, but sometimes the alarms are not really critical and maybe you don’t want to get up at 2am for something trivial. In those situations, a virtual output can be used to trigger the alarm, but then turn itself off so the alarm doesn’t repeat every hour.
(wow, I just got an alarm about my 2-part container being low…perfect timing to describe an example of a non-critical alarm that doesn’t need to nag me every hour)
Here’s how to program a one-time alert using a virtual output named Alert_2Part:
Set OFF
If ALK_LO OPEN Then ON
If CAL_LO OPEN Then ON
If Time 23:00 To 07:00 Then OFF
Defer 001:00 Then ON
When On > 010:00 Then OFF
This single virtual output is checking both my alkalinity container and calcium container. If either one is low, the output is triggered.
This is an example of an OR comparison. In the next example I’ll show an AND comparison.
Recalling from our Timers tutorial, the Defer timer is used to prevent false alarms due to ripples on the liquid surface inadvertently triggering the optical sensor (in my case, if I accidentally bump the container when it’s nearly low, but not quite at the sensor yet). Once the liquid is below the sensor for at least 1 continuous minute, the output finally changes state to ON, unless it's between 11pm - 7am when I'm sleeping. In my Email_Alarm output, I added this line:
If Output Alert_2Part = ON Then ON
This triggers the actual email and text message. However, instead of getting a repeated alert every hour, the When command on the virtual output turns the output OFF after 10 minutes, which cancels the Email_Alert. Remember the When command is a failsafe that moves the output tile slider to the manual OFF position, so it will no longer run the program until you move it back to AUTO:
Once I finish typing up this tutorial, I’ll go refill my 2-part containers and then set the Alert_2Part virtual output back to AUTO.
AND comparisons
Sometimes you might want an output to turn on only if two or more conditions are true. This is considered an AND comparison. Here’s an example where I use a virtual output to determine if my Radion lights should simulate moon lighting, but only if the moon is visible, and only if my normal lighting schedule is off:
Set OFF
If Moon 000/000 Then ON
If Time 07:00 to 21:00 Then OFF
The Apex’s built in lunar schedule knows when the moon is above the horizon. Since moonrise varies day to day, sometimes it’s visible at night, but sometimes it’s during the day. In this example, the output register is set to ON if the moon is visible, but it’s turned OFF if the time is between 7am - 9pm. This is effectively saying “if the moon is up, AND the time is between 9pm to 7am, then turn ON”.
On my Radion outputs, I just add a line to switch to the moon lighting:
If Output vMoon = ON Then Moonlight
I will cover this topic in more detail in the upcoming Lunar Schedule and Lighting Profiles tutorial.
Virtual outputs are really useful! Hopefully this will get you started with creating some convenient automation for your setup.
In the next installment of this series I’ll go over Alarms in more detail. Stay tuned.
~~~~~~~~~~
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.
~~~~~~~~~~~
Neptune Apex Programming Tutorials, Part 5: Virtual Outputs
Note From the Editor:
This article is Part 5 of a series. Feel free to go back and read Part 1, Part 2, Part 3, or Part 4.
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.
For inspiration, here's a spectacular macro photo from the author's reef tank.
And here's an interesting photo of how the author shoots photos.
~~~~~~~~~~~~~~~~~~~~~~
Virtual Outputs
So far in this series we have focused a lot on programming outputs that turn on or turn off devices plugged into Energy Bars. These outputs are physical, tangible electrical outlets that have power cords plugged in. Virtual outputs are imaginary outputs that we can use to create more complex programming than would normally be available given the Apex programming limitations. Virtual outputs can be used for a variety of reasons:
- Providing a master On/Off switch to easily turn off a number of devices with a single click.
- Providing enhanced control of alarm programming.
- Determining if one condition AND another condition are true, then applying the result of that comparison in an IF command on a physical output programming.
- Automating Feed modes
- Customizing lighting schedules
Creating a virtual output
Virtual outputs are created from the Outputs screen:
- Click the Advanced (gear icon) at the top of the Fusion dashboard to expand the list of icons
- Click the Outputs icon
- Click the Add/Delete (gear icon) at the upper right, then click Add a virtual output
- Enter a descriptive name for the new output. You are limited to 12 characters, and the name must be unique within your list of outputs, inputs, and module names.
- Once the new output has been created, Fusion will indicate that a new tile is available. Click the padlock icon to access the Unused Tiles screen.
- Scroll right to left to get to the newly added output, then drag it to your dashboard, then click the padlock icon again to close the Unused Tiles screen.
- Click the gear icon above the new output to configure it.
- I always recommend enabling the Log checkbox so you’ll have a record of any time the output was turned on or off.
New virtual outputs always default to a single line of code: Set OFF
Maintenance master On/Off switch
When I conduct major maintenance in my sump, such as cleaning my return pump or emptying and cleaning out the sump, I normally turn off a number of devices:
- Return pump
- Skimmer
- Heaters (x2)
- Refugium pump
- ATO
- Dosing pumps (x2)
- Auto water change pumps (x2)
- Sump powerhead
- UV sterilizer
Return Pump:
Fallback ON
Set 100
If LkCrpt CLOSED Then OFF
If LkSump CLOSED Then OFF
If SMP_Lo OPEN Then OFF
If Output Maintenance = ON Then OFF
If FeedA 000 Then 1
If FeedB 000 Then 1
Heaters:
Fallback OFF
If Tmp < 78.0 Then ON
If Tmp > 78.0 Then OFF
If Output Maintenance = ON Then OFF
Defer 001:00 Then ON
Defer 000:15 Then OFF
and so on with the other devices. Just that single line of If Output Maintenance = ON Then OFF is all that’s needed. Remember to place that line below any line of code that may turn the device on because the code is processed from top to bottom, as covered in our Introduction tutorial.
Since the Maintenance virtual output doesn’t actually run any program (other than its default Set OFF command), the only way to activate Maintenance mode is to manually move the slider to the ON position:
This master On/Off switch is by far the simplest usage for virtual outputs. Next, let’s look at some examples that involve a bit more programming.
Providing enhanced control of alarm programming
Virtual outputs provide a way to trigger alerts for certain conditions beyond the simple “If this then ON” commands in the Email Alarm output. My favorite example is a warning if my ATO hasn’t run recently. Under normal circumstances my ATO runs every 30 minutes due to evaporation, or perhaps every 60 or 90 minutes if I happened to add a little excess water to my sump. But it should NEVER wait over 2 hours to run, so if it does I’d like to know. I use a virtual output named Alert_ATO to keep track of this for me:
Set OFF
If ATK_LO OPEN Then ON
Defer 120:00 Then ON
Then in my Email_Alarm output, I added this line:
If Output Alert_ATO = ON Then ON
If you recall from the ATK Troubleshooting tutorial, the lower optical sensor in my sump is named ATK_LO, and when it reports OPEN then the ATK_PMUP output is turned on to refill the sump. This Alert_ATO virtual output is instructed to turn ON when ATK_LO is OPEN, but the Defer 120:00 forces the virtual output to wait for 2 hours before finally changing state to ON, as discussed in the Timers tutorial. If during that 2 hour timer the sump is refilled and ATK_LO changes to CLOSED, then the Defer timer is reset. But if the pump doesn’t run and the 2 hour timer finally reaches zero, the Alert_ATO virtual output finally changes state to ON, and the Email_Alarm is then triggered. Pretty slick!
Once the Email_Alert output is on, it will send text and email messages once per hour until the situation is corrected or the output is manually turned off. For critical alarms this is fine, but sometimes the alarms are not really critical and maybe you don’t want to get up at 2am for something trivial. In those situations, a virtual output can be used to trigger the alarm, but then turn itself off so the alarm doesn’t repeat every hour.
(wow, I just got an alarm about my 2-part container being low…perfect timing to describe an example of a non-critical alarm that doesn’t need to nag me every hour)
Set OFF
If ALK_LO OPEN Then ON
If CAL_LO OPEN Then ON
If Time 23:00 To 07:00 Then OFF
Defer 001:00 Then ON
When On > 010:00 Then OFF
This single virtual output is checking both my alkalinity container and calcium container. If either one is low, the output is triggered.
Recalling from our Timers tutorial, the Defer timer is used to prevent false alarms due to ripples on the liquid surface inadvertently triggering the optical sensor (in my case, if I accidentally bump the container when it’s nearly low, but not quite at the sensor yet). Once the liquid is below the sensor for at least 1 continuous minute, the output finally changes state to ON, unless it's between 11pm - 7am when I'm sleeping. In my Email_Alarm output, I added this line:
If Output Alert_2Part = ON Then ON
This triggers the actual email and text message. However, instead of getting a repeated alert every hour, the When command on the virtual output turns the output OFF after 10 minutes, which cancels the Email_Alert. Remember the When command is a failsafe that moves the output tile slider to the manual OFF position, so it will no longer run the program until you move it back to AUTO:
AND comparisons
Sometimes you might want an output to turn on only if two or more conditions are true. This is considered an AND comparison. Here’s an example where I use a virtual output to determine if my Radion lights should simulate moon lighting, but only if the moon is visible, and only if my normal lighting schedule is off:
Set OFF
If Moon 000/000 Then ON
If Time 07:00 to 21:00 Then OFF
The Apex’s built in lunar schedule knows when the moon is above the horizon. Since moonrise varies day to day, sometimes it’s visible at night, but sometimes it’s during the day. In this example, the output register is set to ON if the moon is visible, but it’s turned OFF if the time is between 7am - 9pm. This is effectively saying “if the moon is up, AND the time is between 9pm to 7am, then turn ON”.
On my Radion outputs, I just add a line to switch to the moon lighting:
If Output vMoon = ON Then Moonlight
I will cover this topic in more detail in the upcoming Lunar Schedule and Lighting Profiles tutorial.
Virtual outputs are really useful! Hopefully this will get you started with creating some convenient automation for your setup.
In the next installment of this series I’ll go over Alarms in more detail. Stay tuned.
~~~~~~~~~~
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.
~~~~~~~~~~~
