Setup reef-pi for RevB Deluxe Controller

July 29, 2020 – Version 1.0

Safety Reminder

• READ & FOLLOW ALL SAFETY INSTRUCTIONS
• DANGER

• Never handle electrical equipment with wet hands
• special care should be taken since water is employed in the use of aquarium equipment
• Do not attempt repairs to commercial equipment yourself, return to place of purchase or the manufacturer’s authorized service facility

• Ensure all components (power adapters, power boards, controllers, wires, etc.) are properly set up according to manufacturer’s recommendations, to prevent accidental damage
• If an appliance shows any signs of abnormal water leakage, immediately unplug it from its power source
• If an appliance falls into the water, DO NOT reach for it, first unplug it from its source of power
• Carefully examine the appliance(s) after installation. It should NOT be plugged in, if there is any sign of water on parts not intended to be wet.
• Do not operate any appliance if it has a damaged cord or plug, or it is malfunctioning or has been dropped or damaged in any manner
• Avoid the possibility of the appliance plug or receptacle getting wet, position the aquarium stand and tank or sump, to one side of a wall-mounted socket or power board, to prevent water from dripping onto the socket, plug or power board

A “drip loop”, shown in the diagram below, should be set up by the user, for each electrical cord connected to an aquarium appliance to a socket. The “drip loop” is that part of the electrical cord below the level of the socket, or the connector of an extension lead, if used, and the socket or power board, to prevent water travelling along the cord and coming in contact with the socket.

• If the plug, socket or power board does get wet, DON’T unplug the cord. Disconnect the fuse or circuit breaker that supplies power to the appliance, then, and ONLY then unplug the appliance and examine the socket or power board for the presence of water
• Always unplug an appliance from the outlet, when not in use, before putting on or taking off parts, and before cleaning
• Never yank the cord to pull plug from outlet, grasp the plug firmly to remove
• Read and observe all important notices on the appliance
• If an extension cord is necessary, a cord with the proper rating should be used. Care should be taken to arrange cords, such that they are not a trip hazard
• Indoor use ONLY
• For Calcium reactor operation, refer to the manufacturer’s instructions, as per it’s manual
• For Robo-Tank operation, refer to the operating instructions, as per it’s manual
• Keep controller cool and dry, do not expose to direct sunlight or heat

Table of Contents

Table of Contents        4

2. Setup reef-pi – Configuration        6

3. Setup reef-pi – Settings        7

Advance Settings        8

4. Setup reef-pi – Telemetry        9

Adafruit IO Logging        9

Email Alerts        10

5. Setup reef-pi – Authentication        11

6. Setup reef-pi – Pi Clock Stretching for I2C        12

7. Setup reef-pi – Necessary Drivers        13

8. Setup reef-pi – Connectors Explained        14

9. Setup reef-pi – Setting up Connectors for the Robo-Tank Controller        15

Adding Connectors - Inlets (Sensor Ports)        16

Adding Outlets – AC Outlets        17

Adding Outlets – DC Ports        18

Adding Jacks – DC Ports        19

Adding Jacks – Selectable PWM/Analog Ports        20

Adding Analog Inputs – pH Circuits        21

10. Using reef-pi        22

11. Using reef-pi – Equipment        23

12. Using reef-pi – Timers        24

Special Characters        25

Timer Examples        25

13. Using reef-pi – Lights        26

14. Using reef-pi – Temperature        29

Advanced Settings - Temperature        30

Temperature Calibration        31

15. Using reef-pi – ATO        32

Advanced Settings        32

16. Using reef-pi – pH        33

Advanced Settings        33

Calibrate pH Probe        35

17. Using reef-pi – Dosing Pumps        36

Advanced Settings        36

18. Using reef-pi – Macros        38

Macro Example – Automatic Water Change        39

19. Using reef-pi – Dashboard        42

Contributors        43

Questions or comments contact me, Rob Fowler at info@robo-tank.ca        43

2. Setup reef-pi – Configuration

The first thing you need to do is configure reef-pi for Robo-Tank, don’t connect any sensors or equipment until you have done this.

This is all done on the ‘Configuration’ tab at the top of the screen.

After you make any changes on any of the sub-tabs under ‘Configuration’ you must go to the ‘Admin’ sub-tab and press the ‘Reload’ button. This will restart reef-pi so the settings can take effect. This can be easy to forget so if you have any issues after you change some main settings come here and press the ‘Reload’ button.

Note: Depending on what you change you may need to refresh your browser.

The ‘Sign Out’ button will log you out of reef-pi.

The ‘Reboot’ button will restart the Raspberry Pi.

The ‘Power Off’ button will power down the Raspberry Pi, you will have to power cycle the controller if you press this button.

3. Setup reef-pi – Settings

The first thing to do is set up the modules you’ll be using. Modules are the tabs that show at the top of the screen, for example if you unchecked ‘ATO’ the tab at the top would be gone.

1. Click the ‘Configuration’ tab at the top of the screen.
2. For now you can leave the default settings, but you need to check some boxes under the ‘Capabilities’ section at the bottom to work with Robo-Tank. Your screen should look like the one below. If you don’t monitor pH you can leave it unchecked.
3. Press the ‘Update’ button.
4. Now you need to ‘Reload’ reef-pi as described on the previous page. Click the ‘Admin’ sub-tab at the top of the page.
5. Press the ‘Reload’ button.
6. Refresh your browser page and you’ll see all the tabs at the top change like the image below.

Note: ‘Dev Mode’ should never be turned on, this is only for development and will stop the program from operating correctly.

Continued on next page…

Advance Settings

• Name – This field allows you to give reef-pi a custom name and shows up in the top left corner of reef-pi.
• Interface – Network adapter that the web-ui is bound to. ie which physical port the web server will listen on.
• Address – Protocol/port and URL that the web-ui uses. Note that leaving off the port number and saving will cause reef-pi to become inaccessible.
• Rpi Pwm Frequency – The Raspberry Pi has two PWM outputs and you can change the frequency if needed, typically the default is fine, you can choose from 10 – 1000.
• Language – You can change the language for the template
• Display –  This is an updated feature and doesn’t apply at this time.
• Notification – This will enable / disable email alerts.
• Enable profiling –
• Enable Prometheus – Prometheus is an advanced monitoring and analytics tool, originally developed for cloud infrastructure monitoring at SoundCloud. It can be used by reef-pi to store metrics for long term analytics and possibly other advanced data-driven functionality in the future.
• Capabilities – These are the different modules available in reef-pi, each are reflected in the tabs at that top.

• Equipment – This module allows you to set up outputs to control equipment.
• Timers – This module allows you to create schedules.
• Lighting – This module is fine tuned to control lights but can be used for other equipment as well.
• ATO – This module allows you to add inputs for reading sensors.
• Temperature – This module allows you to connect multiple DS18B20 temperature sensors.
• Camera – This module adds support for an official raspberry Pi camera.
• Doser – This module is fine tuned to control dosing pumps but can be used for other equipment as well.
• pH – This module allows you to monitor and control equipment based on pH
• Macro – This module allows you to execute a series of steps to automate tasks such as water changes.
• Health Check – This module allows reef-pi to monitor the health of the Raspberry Pi.
• Dashboard – This module allows you to view graphs for the other modules.
• Dev Mode – This enables development mode, for normal use this should be left unchecked.
• Alert on health check – This enables email alerts if the resources on the Raspberry Pi get low.

4. Setup reef-pi – Telemetry

The telemetry tab allows you to set up Adafruit feeds, email alerts and set the limit on reef-pi graphs.

• Current limit –
• Historical limit –

Adafruit IO Logging

• Adafruit.IO

• Username – This is your username for your Adafruit account.
• AIO Key – This is the key code for your Adafruit account.
• Prefix –

Continued on next page…

Email Alerts

reef-pi uses SMTP to send emails, you can use Gmail or your own server.

1. server – Enter the address of your SMTP server
2. port – This is the outgoing port number of your SMTP server, typically this is 587
3. from – This is the email address the email will be sent from, it should correspond with the server.
4. To – This is where the email alert will be sent
5. Password – This is the password for the ‘from’ email address.
6. Limit per hour – This sets a limit of emails that can be sent per hour. Some free SMTP services have a limit of emails that can be sent, be sure you adjust this so you don’t go over your limit if it applies. The default of 10 is fine in most cases.

Note: After you add your credentials you should go to the ‘Admin’ tab and ‘Reboot’ reef-pi.

Click here to view a detailed manual showing you how to configure your Gmail account.

5. Setup reef-pi – Authentication

After you install reef-pi the default login is reef-pi for both username and password. You should change this for better protection.

1. Click the ‘Configuration’ tab at the top of the screen.
2. Click the ‘Authentication’ sub-tab and enter a username and password.
3. Press the ‘Update’ button.
4. Switch to the ‘Admin’ tab to ‘Reload’ reef-pi.

Note: Anytime you visit this page the ‘Password’ field will be blank so your password isn’t visible.

6. Setup reef-pi – Pi Clock Stretching for I2C

Note: If you installed reef-pi using the install script this page can be skipped as it will have been added.

The hardware on Raspberry Pi supports clock stretching however the drivers don’t so we need to manually adjust the clock speed on the Pi so it works with all I2C devices. This is required to use the Robo-Tank pH circuit.

1. Remove microSD card from Raspberry Pi.
2. Plug the microSD card in your card reader on your local computer.
3. Open the config.txt file, this is located in the root directory of the microSD card.
4. Scroll to the bottom of the file and add the following line.

dtparam=i2c_arm_baudrate=10000

5. Remove microSD card from computer and plug back in Raspberry Pi

If you prefer to do this using a terminal you can follow the instructions here.

https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/i2c-clock-stretching

Aside from allowing all devices to work with Raspberry Pi this will improve reliability if you connect I2C devices using cable. I2C is very noise sensitive and slowing down the bus will help compensate somewhat.

7. Setup reef-pi – Drivers

reef-pi uses a set of drivers to control different equipment and expansion modules, before you can use Robo-Tank you need to add a driver for a PCA9685 chip and another for the pH circuit if applicable. The driver for pH will depend on the circuit you are using.

1. Click the ‘Configuration’ tab at the top of the page.
2. Click the ‘Drivers’ sub-tab.

By default you will only see ‘Raspberry Pi’ in the list, this is the main driver to control the I/O pins on the Pi.

Let’s add a driver for the PCA9685, this controls 8 DC ports and 8 PWM/Analog ports on the controller.

1. Click the + sign under ‘Raspberry Pi’.
2. Name the driver, use ‘Extra Ports’ as that’s what this manual refers to but it can be anything.
3. From the ‘Type’ dropdown box select ‘PCA9685’.
4. Two boxes will appear, ‘Address’ and ‘Frequency’, set the ‘Address’ to 64 and the ‘Frequency’ to 800, these should be the default values.
5. Press the ‘Save’ button.

If you have a pH circuit you can add that now.

1. Click the + sign under ‘Raspberry Pi’.
2. Name the driver, you can use ‘pH’ or whatever you like, just remember what it is, if you add multiple pH sensors make the name unique to it so it’s easy in the future to know what it is.
3. For Robo-Tank pH circuit (instructions to add clock stretching to Raspberry Pi on previous page.)

1. From the ‘Type’ dropdown box select ‘ph-ezo’.
2. Change the ‘Address’ field to 99.

4. For the Roberto_b analog pH circuit

1. From the ‘Type’ dropdown box select ‘ph-board’.
2. Change the ‘Address’ field from 40-44 depending what your circuit is set to, probably 40.

5. Press the ‘Save’ button.
6. When finished remember to switch to the ‘Admin’ tab to ‘Reload’ reef-pi so the changes will take effect.

8. Setup reef-pi – Connectors Explained

Now that you’ve set up the ‘Drivers’ you need to add ‘Connectors’ for each device or port the driver controls. You might wonder why this is necessary, it’s because some drivers have the ability to be an input or output, this tells reef-pi what you want to do with that driver.

There are 4 types of connectors, let's review what each type does based on the deluxe controller and in the following pages we’ll add the ‘Connectors’ you need.

• Inlets –  Inlets are used for the 5 sensor ports on the deluxe controller, these will be your optical, non-contact, float switches or other Arduino compatible sensors that you use for your ATO or AWC system or anything else you have in mind. The Raspberry Pi pins are 3.3v tolerant but the controller board allows 5v sensors to be used.

To clarify, Inlets are not analog, they read a LOW or HIGH signal from the sensor so only the top and bottom end is reported which works for most water sensors as the on/off range is small, currently reef-pi doesn’t support analog sensors.

You can also ‘Reverse’ or invert an inlet, when you control equipment with a sensor the system will turn the equipment on if the sensor see’s water and the equipment is switched off when the sensor doesn’t see water. If you want the reverse to happen check this box. You can experiment with this and changing it won’t damage any sensors.

• Outlets – These are used to control the AC outlets and DC ports, you need to set up an ‘Outlet’ connector for each port. When a port is configured as an ‘Outlet’ it will put out a LOW or HIGH signal according to reef-pi which is essentially on or off. You can also ‘Reverse’ or invert an ‘Outlet’, this will change ‘LOW = off’ to ‘LOW = on’ giving you more flexibility. You can access these connectors on the ‘Equipment’ tab. It’s important not to get ‘Inlets’ and ‘Outlets’ mixed up, if you plugged a sensor in a port that was configured as an ‘Outlet’ 3.3v - 5v would go into your sensor and likely damage it.
• Jacks – These can be used to control the 8 selectable PWM / Analog outputs on the deluxe controller. When you use ‘Jack’ Connectors you can access them on the ‘Dosing pumps’ tab and ‘Lights’ tab. Dosing pumps and lights have their own system for specific controls and can be used for other things however you can’t control anything from the Dosing pumps or Lights tab using a sensor or Macro, if you want to control the port with a sensor you should add an ‘Outlet’ connector for the port instead.
• Analog Inputs – Analog inputs are used for drivers that put out an analog value, you use these for your pH circuits. You can access these connectors on the ‘pH’ tab.

9. Setup reef-pi – Setting up Connectors for the Robo-Tank Controller

The following will explain what connectors you need to add for the deluxe controller as it comes shipped.

The image below shows all the available ports on the deluxe controller, I will refer to the port names and numbers on the following pages while you set up the connectors for each port.

Adding Connectors - Inlets (Sensor Ports)

As explained above Inlets are for all your sensors such as optical, non-contact or float switches use Inlets as the connector type. Follow the steps below.

1. Click the + sign under ‘Inlets’ and give the inlet a name such as ‘Sensor 1’. When you add your sensors to the ‘ATO’ tab you can give it a descriptive name.
2. The ‘Reverse’ option will depend on your setup, either option won’t harm any sensors so you can experiment to find the best option for you. This will reverse the sensor when it controls equipment, LOW = off will become LOW = on. Remember after changing a setting here you need to ‘Reload’ reef-pi from the ‘Admin’ tab.
3. Select the ‘Pin’ number and ‘Driver’ to match the inlet you’re setting up. The list is below.
4. Repeat steps 1 – 3 four more times so you have all sensors setup. If you won’t be using all 5 sensor ports you only need to add inlets for the ones you are using, later you can add more.

Sensor Port 1 = Pin 17 – Driver Raspberry Pi 

Sensor Port 2 = Pin 27 – Driver Raspberry Pi

Sensor Port 3 = Pin 19 – Driver Raspberry Pi

Sensor Port 4 = Pin 20 – Driver Raspberry Pi

Sensor Port 5 = Pin 26 – Driver Raspberry Pi 

Sensor Port 6 = Pin 21 – Driver Raspberry Pi

Adding Outlets – AC Outlets

The physical connectors for the AC outlets are the two large DB9 9 pin serial connectors on the side of the case.

1. Click the + sign under ‘Outlets’ and give the Outlet a name such as ‘Outlet 1’. When you add your AC outlets to the ‘Equipment’ tab you can use a descriptive name.
2. ‘Reverse’ option, for most setups and the Robo-Tank power bar you will leave this unchecked unless you want the outlet to operate in reverse, off will be on and vice versa, this is good if your relays are wired differently.
3. Select the ‘Pin’ number and ‘Driver’ to match the outlet you’re setting up. The list is below.
4. Repeat steps 1 – 3 until you’ve added all the AC outlets you’ll be using. If your power bar has 8 outlets or relays add each of them so the pin is configured correctly.

Note: Each outlet port is connected directly to a Raspberry Pi pin, this puts out +3.3v when an outlet is on and 0v when an outlet is off. Other power bars with a DB9 connector may not be compatible, if you have something you want to use and unsure contact me and I’ll look into it.

Universal power bar uses outlet 1 -6 for each.

Adding Outlets – DC Ports

Now you can add ‘Outlet’ connectors for any DC ports that will have equipment you turn on/off like an AC outlet such as fan, lights, pumps, etc. Things like this you decide which DC port you will use and set it up under the ‘Outlets’ connector type. Remember DC port 1, 2 and 3 have an emergency backup float wired into the circuit so use it for a critical operation.

Note: If you’re connecting a dosing pump or LED stripe light to a DC port and want to control the speed you would configure it as a ‘Jacks’ instead (see next page).

1. Click the + sign under ‘Outlets’ and give the Outlet a name such as ‘DC Port 1’. When you add your device to the ‘Equipment’ tab you can use a descriptive name.
2. ‘Reverse’ option, for most setups you will leave this unchecked unless you want the DC port to operate in reverse, off will be on and vice versa.
3. Select the ‘Pin’ number and ‘Driver’ to match the DC port you’re setting up. The list is below.
4. Repeat steps 1 – 3 until you’ve added all the DC ports you’ll be using. You can come back later and add more when you use them.

Adding Jacks – DC Ports

‘Jacks’ are different from ‘Outlets’ as these are controlled via a PWM signal. Instead of being turned on or off you can adjust the speed or brightness of whatever you connect assuming it’s controllable.

You’ll notice the ‘pins’ field doesn’t show any pin numbers like the ‘Inlets’ or ‘Outlets’, this is because you can assign multiple pins to a Jack.

Let’s say you have an RGB LED strip light that runs on 12v DC power. You could connect each color to a DC port and control them individually. As there are 3 colors you would need to assign 3 pins to your jack, you could use 11, 10,9 which is DC Port 5, 6 and 7.

1. Click the + sign under ‘Jacks’ and give the Jack a name such as ‘DC Port 1’. When you add your device to the ‘Dosing Pump’ or ‘Lights’ tab you can use a descriptive name.
2. ‘Reverse’ option, for most setups you will leave this unchecked unless you want the DC port to operate in reverse, off will be on and vice versa.
3. Add the ‘Pins’ separated by a comma and ‘Driver’ to match the DC port you’re setting up. The list is below.
4. Repeat steps 1 – 3 until you’ve added all the DC ports you’ll be using. You can come back later and add more when you use them.

Adding Jacks – Selectable PWM/Analog Ports

These ports put out a selectable 0-5v / 0-10v PWM / Analog signal to control LED drivers and other controllable equipment.

1. Click the + sign under ‘Jacks’ and give the Jack a name such as ‘PWM Port 1’. When you add your device to the ‘Dosing Pump’ or ‘Lights’ tab you can use a descriptive name.
2. ‘Reverse’ option, for most setups you will leave this unchecked unless you want the Port to operate in reverse, off will be on and vice versa.
3. Select the ‘Pin’ number and ‘Driver’ to match the port you’re setting up. The list is below.
4. Repeat steps 1 – 3 until you’ve added all the PWM/Analog Ports you’ll be using. You can come back later and add more when you use them.

Adding Analog Inputs – pH Circuits

This is where you add your pH circuits.

1. Click the + sign under ‘Analog Inputs’ and give the pH circuit a good name so you will always know what it is.
2. Select the pH ‘Driver’ that you set up earlier from the dropdown list.
3. Select ‘Pin’ 0 from the dropdown list.
4. Repeat steps 1 – 3 until you’ve added all the pH circuits you’ll be using.

10. Using reef-pi

Now you should have successfully configured Robo-Tank to work with reef-pi and are ready to use it. As you can see at the top of reef-pi there are different tabs, these are the different systems within reef-pi. One thing to note is thinking outside the box can help you achieve more with your controller. Over the next few pages we will explore what you can achieve in each on the tabs.

11. Using reef-pi – Equipment

The first tab of reef-pi is ‘Equipment’ and handles all the ‘Outlet’ connectors you added earlier. You can see in the example below you’ll have a list of the equipment you are controlling. The ‘On/Off’ button will turn the equipment on/off however it should be noted the outlet will not stay in that state indefinitely, if any sensor or timer decides it should be on it will immediately turn back on if you turn it off. If you want manual control of equipment you must first disable any timers or sensors that control it.

The following steps explain how to add your equipment.

1. Click the + sign to add a piece of equipment and give it a good name so you will always know what it is.
2. Select the port you set up in the previous step from the dropdown list.
3. Click the ‘Add’ button.
4. Repeat steps 1 – 3 until you’ve added everything you need.

12. Using reef-pi – Timers

The next tab at the top is ‘Timers’, where you can set schedules to control the equipment you just setup. You can also set up timers for reminders and macros. The ‘On/Off’ button will enable/disable the timer, if you disable it the timer will not work.

1. Click the + sign to add a timer, give it a good name so you will always know what it is.
2. The ‘Timer Status’ field allows you to disable the timer, this can also be automated using ‘Macros’.
3. Set the ‘Function’ field to match your needs, you have 3 options, once selected the other fields will update accordingly.

1. Equipment – This allows you to select any piece of equipment that you added on the ‘Equipment’ tab.
2. Reminder – This will allow you to set up just an email reminder.
3. Macros – This will trigger a ‘Macro’ that you may have set up, these are used to automate equipment and suspend sensors and timers, check out the ‘Macros’ section for more details.

Attention! For the moment (version 4.1) timers trigger macros in reverse! So build the macro in reverse order and check the field "reversible".

4. If you selected ‘Equipment’ or ‘Macro’ from the ‘Function’ field you need to then select the respected piece of equipment or macro that you want to control.
5. Now you can set when the timer is triggered using the remaining fields.
6. Click the ‘Save’ button.
7. Repeat steps 1 – 6 until you’ve added all the timers you need

The following table explains the timer fields.

Continued on next page…

Special Characters

Special characters add a lot of flexibility to the timers and most are optional so don’t be overwhelmed by this.

• Asterisk  *        Represents every ‘Allowed Values’ above – Example: every day of the week, every hour, etc.
• Hyphen  -        Represents a range of the ‘Allowed Values’ above – Example: hour can be ‘2-6’ to trigger the timer every hour between 2-6.
• Comma  ,        Used to separate and select multiple ‘Allowed Values’ above – Example: day of week can be ‘MON,WED,FRI’ which will trigger the timer on those days.
• Slash  /Represents after every ‘Allowed Values’ above. Example: Hour value “*/3” represents after every 3 hours
• Question  ?        Question mark may be used to leave either day-of-month or day-of-week out of the timer

Timer Examples

Important Note:

One thing to note, you'll notice in the timers you can select an option to have the timer turn something on and off after a set delay, don't use that feature. Instead create 2 separate timers, one timer to turn on the equipment at say 9:00 am and then another to turn it off at say 9:10am.

If you use the same timer for both and the Pi restarts between the two times the port may be stuck on until the next schedule comes around to turn it off. With a separate off timer if Pi restarts at 9:05am it'll still know at 9:10 to turn off the equipment.

13. Using reef-pi – Lights

The next tab at the top is ‘Lights’ and handles all the ‘Jack’ connectors you added earlier. On this tab you can add your lights or other PWM/Analog controllable equipment. You can also control some of the DC ports from the Lights tab so long as you set up those DC port connectors as ‘Jacks’.

1. Click the + sign to add a light, give it a good name so you will always know what it is.
2. Select the ‘Jack' that you setup previously from the dropdown list.

3. Click the ‘add’ button.
4. A new section will show up with the name and 3 buttons, ‘Auto’, ‘Edit’, and ‘Delete’.

1. Auto – This button reflects the mode the light is in, press it to switch between automatic and manual mode
2. Edit – Press this button to edit the light settings
3. Delete – Press this button to delete the light

Continued on next page…

5. Press the ‘Edit’ button to change the settings for your light. The image below represents a single pin on the Jacks connector we added earlier, each pin assigned to the Jack will appear as a separate channel. For example if your light has 4 channels you would set up the Jack connector with 4 output pins to get 4 lights channels.
6. Now you can change the ‘Channel Name’ if you so desire and assign a color to it.
7. Each channel has a ‘Min’ and ‘Max’ setting in percentage, set these to your desired levels.

Continued on next page…

9. Now select a ‘Profile’ type for that channel, there are 3 to choose from.

1. Fixed – This profile will set the channel to a constant level. Set the time you want it to turn on/off and the brightness.

2. Interval – This profile allows you to set the levels in percentage in 2 hour intervals. The lights will fade through each of intervals which are in 2 hour spans.

3. Diurnal – This profile simulates a sunrise / sunset by fading your lights to the ‘Min’ and ‘Max’ values you set up. Simply set the start and end time and it’ll do the rest.

10. Repeat steps 1 – 8 until you’ve added all the lights you need.

14. Using reef-pi – Temperature

The next tab at the top is ‘Temperature’, this module doesn’t use any drivers or connectors.

1. Click the + sign to add a temperature sensor, give it a good name so you will always know what it is.
2. Click the ‘Sensor’ field and you should see 1 or more rows with sensor ID’s, each of these represents a DS18B20 sensor, select one and set the other fields to your liking.
3. Click the ‘Save’ button.
4. Repeat steps 1 – 3 until you’ve added all the DS18B20 sensors you need.

NOTE: All the sensors are attached to the same pin internally on the Pi, so each sensor is identified by its pre-programmed hardware ID, which can be obtuse. Best practice is to physically attach each sensor individually, write down the ID & purpose/location for the newly attached sensor, then move on to attaching the next sensor. This process allows you to identify the location/purpose of each sensor. For example, you may choose to add one ambient air temp, one tank water temp and/or one sump temp; knowing which-is-which is important in these use-cases.

Continued on next page…

Advanced Settings - Temperature

1. Unit – Select the format for the temperature
2. Check Frequency – This represents how often the sensor is checked.
3. Sensor Status – With this you can disable the sensor manually or automatically using a Macro. This is handy during maintenance if the sensor controls a heater or chiller. When you disable the sensor the equipment won’t turn on. Check out the Macros or Maintenance section for more information.
4. Alerts – If you have notifications enabled you can receive emails if the temperature goes below or above the set level.
5. Control – This setting gives the ability to control any of the equipment you set up, usually this is a heater or chiller but you could also connect a buzzer so you have an audible alarm.

• Nothing – If this option is selection the sensor won’t control anything
• Equipment – When you select this the following fields will be enabled, at this time all fields are required, if you set up a heater you need to add fake info for a chiller as well.

• Heater Threshold – This is the threshold for the heater. When you use the heater to control something this will turn the device on when the temperature drops below the level you choose.
• Chiller Threshold – This is the threshold for the chiller. When you use the chiller to control something this will turn the device on when the temperature goes above the level you choose.
• Hysteresis – This setting is important and stops the equipment from rapidly turning on/off. For example if you set the hysteresis to 0.2 and the heater threshold to 76.4 the heater will only switch when the temperature goes beyond (76.4+/- 0.2). There’s a chart you can place on the dashboard that will show how often the equipment switches so you can adjust the hysteresis if you find it switched too often or not enough.
• Heater – This dropdown list will display all the equipment you set up on the Equipment tab of reef-pi. Select the device you would like to control using the heater threshold.
• Chiller – This dropdown list will display all the equipment you set up on the Equipment tab of reef-pi. Select the device you would like to control using the chiller threshold.

• Macro – The settings described above for Equipment also apply to a Macro however a Macro runs a set of steps. Check out the Macro section for more information on Macros.

Continued on next page…

Temperature Calibration

After you add a DS18B20 temperature sensor you can disable, edit, delete or calibrate it.

6. Press the ‘Calibrate’ button, a window will open and show the raw temperature.
7. Fill a glass cup with cold water and ice cubes and place your sensor in the cup with ice surrounding the probe, don’t let it touch the glass for best results.
8. Let it sit a few minutes.
9. If you use Celsius enter 0 in the ‘Set Temperature’ field, for Fahrenheit enter 32. This is the temperature of ice so we know the sensor is calibrated.
10. You can clear the calibration by changing the temperature format.

15. Using reef-pi – ATO

The next tab at the top is ‘ATO’ and handles all the ‘Inlet’ connectors you added earlier. This is where you can set up all your sensors. Even though the tab is labeled ATO you can use the sensors you add for other functions such as AWC or whatever you need. If your sensor is compatible with the controller you add it here.

1. Click the + sign to add a sensor, give it a good name so you will always know what it is.
2. Click the ‘Inlet’ field and select one of the Inlets you set up previously.
3. Setup the other fields to your liking and click the ‘Save’ button.
4. Repeat steps 1 – 3 until you’ve added all the sensors you need.

Advanced Settings

11. Check Frequency – This sets how often the sensor is read.
12. ATO Status – With this you can manually disable the sensor during maintenance or whatever, you can also use a Macro to change the status automatically.
13. Alerts – If you have notifications enabled you can receive emails if this feature runs too long.
14. Control – This setting gives the ability to control any of the equipment you set up using the sensor. There are 3 options to choose from.

• Nothing – If this option is selection the sensor won’t control anything
• Equipment – When you select this option you choose a piece of equipment from the ‘Control Pump’ field.
• Macro – With this option selected you can choose a Macro you setup from the ‘Control Pump’ field. Check out the Macro section for more information on Macros.

16. Using reef-pi – pH

The next tab at the top is ‘pH’ and handles some of the ‘Analog Input’ connectors you added earlier.  On this tab you can add your pH probes.

1. Click the + sign to add a new probe, give it a good name so you will always know what it is.
2. Click the ‘Analog Input’ field and select the pH connector you added earlier.
3. Setup the other fields to your liking and click the ‘Save’ button.
4. Repeat steps 1 – 3 until you’ve added all the probes you need.

Advanced Settings

15. Check Frequency – This represents how often the sensor is checked.
16. pH Status – With this you can disable the pH manually or automatically using a Macro.
17. Alerts – If you have notifications enabled you can receive emails if the pH goes below or above the set levels.

Continued on next page…

Advanced Settings (continued)

18. Control – This setting gives the ability to control any of the equipment you set up.

• Nothing – If this option is selection the pH won’t control anything
• Equipment – When you select this the following fields will be enabled, at this time all fields are required.

• Lower Threshold – If the pH drops below the lower threshold the selected device will turn on, if the pH goes above the lower threshold the device will turn off.
• Upper Threshold – If the pH drops below the upper threshold the selected device will turn on, if the pH goes above the lower threshold the device will turn off.
• Hysteresis – This setting is important and stops the equipment from rapidly turning on/off. For example if you set the hysteresis to 0.2 and lower threshold to 8.1 the device will only switch when the pH goes beyond (8.1+/- 0.2).
• Lower Function – This dropdown list will display all the equipment you set up on the Equipment tab of reef-pi. Select the device you would like to control using the heater threshold.
• Upper Function – This dropdown list will display all the equipment you set up on the Equipment tab of reef-pi. Select the device you would like to control using the chiller threshold.

• Macro – The settings described above for Equipment also apply to a Macro however a Macro runs a set of steps. Check out the Macro section for more information on Macros.

Calibrate pH Probe

After you set up your probe following the instructions above you should calibrate it before using it. The calibration data is stored by reef-pi, if you delete your probe from the list you’ll have to recalibrate. If you want to clear the calibration data you should also delete your probe and set it up again.

1. Before you can calibrate you need to disable your probe by selecting ‘disable’ from the ‘pH Status’ drop down box and saving the changes.
2. Press the ‘Calibrate’ button and you’ll see the following screen.

You can choose to do a 1 or 2 point calibration, the midpoint buffer should be as close to 7.0 as you can get. If you choose to do a 2 point calibration the 2nd solution is typically 10.0. Your pH reading should fall between the two buffer solutions. If you expect your pH to be 7.8 you shouldn’t calibrate with a 7.0 and 4.0 buffer as your results won’t be as accurate.

3. Enter the value of your buffer solution in the ‘Midpoint’ text box.
4. Clean your pH probe with distilled or filtered water and flick to remove water droplets so you don’t contaminate your buffer solution. Avoid wiping the probe with anything as this can cause static and affect your calibration.
5. Place the probe in your ‘Midpoint’ buffer solution and let it sit for a few minutes, the “Current Reading” is a raw value and doesn’t reflect any calibration data. If you have a -200 or something showing this is likely caused from the type of pH circuit you have, once you finish calibration a valid reading will show.
6. Once the probe has sat for a while press the ‘Run’ button.
7. Proceed to the ‘Second Point’ if you choose to do it and repeat steps 3-6, if not you can press ‘Done’.
8. Now you can ‘Enable’ your pH again and you should see the same value as your buffer solution.

17. Using reef-pi – Dosing Pumps

The next tab at the top is ‘Dosing Pumps’ and handles some of the ‘Jack’ connectors you added earlier. On this tab you can set up your dosing pumps or other equipment. You can control other equipment you set up as ‘Jack’ from here.

1. Click the + sign to add a new device, give it a good name so you will always know what it is.
2. Click the ‘Jack’ field and select one you set up previously.
3. Click the ‘Pin’ field and select one of the pins you assigned to the Jack.
4. Setup the schedule for the dosing pump, see the latter half of the timer section for scheduling details.
5. Click the ‘Save’ button.
6. Repeat steps 1 – 5 until you’ve added all the equipment you need.

Advanced Settings

19. Doser Status – This allows you to manually disable the dosing pump, you can also disable it automatically using a Macro.
20. Duration – Set how long you want your dosing pump to run.
21. Speed – Set the speed you would like your dosing pump to run.

Continued on next page…

Dosing Pump Calibration

Once you’ve added your dosing pump you can calibrate it, this will help you determine what to set the ‘Duration’ to.

1. Press the ‘Calibrate’ button to open the calibration window.
2. Place the output tube from your dosing pump in a small measuring vessel. If you don’t have a measuring vessel to match the dose size you require, use something you have and do some math.
3. Press the ‘Run’ button, if you don’t get the expected dose increase the duration and try again until you get what you expect.
4. Mark down the numbers you settle on and press the ‘Done’ button.
5. Press the ‘Edit’ button for the dosing pump you just calibrated and change the speed and duration to match your calibration.
6. Press the ‘Save’ button.

18. Using reef-pi – Macros

The next tab at the top is ‘Macros’, this is where you can create automated tasks such as a water change. Macros are powerful but do take some understanding to get the best out of them.

After you add Macros you can run them manually or you can use timers and sensors to trigger them as well. Macros are a set of instructions for the controller to follow, when a macro starts it will go through each step until it’s complete. Ultimately macros enable or disable systems and turn equipment on or off.

The following steps detail how to add a macro.

1. Click the + sign to add a new Macros, give it a good name so you will always know what it is.
2. Click the + sign above the ‘Save’ button to add a ‘Step’.
3. From the ‘Steps’ dropdown list select a module

1. Wait – adds a delay between steps
2. Equipment – used to turn on/off any piece of equipment on the equipment tab
3. ATO – used to enable / disable sensors
4. Temperature – used to enable / disable DS18B20 temperature sensors
5. Doser - used to enable / disable equipment on the dosing tab.
6. Timers - used to enable / disable timers
7. pHprobes - used to enable / disable pH sensors
8. subsystem – used to enable / disable all devices on one of the above modules
9. macro – used to enable / disable macros

4. Select the sensor or equipment within the module.
5. Select an action from the next dropdown.
6. Repeat steps 2 – 5 until you’ve added all the steps you need on your macro.
7. Click the ‘Save’ button.
8. Repeat steps 1 – 7 until you’ve added all the macros you need.

Macro Example – Automatic Water Change

In the following example we're going to set up an AWC system using a low level sensor, high level sensor, drain pump and refill pump. We will also assume you have an Auto Top Off system running as well but this is optional. Before you can create the macro you need to make sure you’ve already added your AC or DC pumps on the ‘Equipment’ tab and sensors on the ‘ATO’ tab.

Here’s an example of the pumps we will use for the AWC. As you can see we have a Drain and Fill pump available in the ‘Equipment’ tab.

Here’s an example of the sensors we will use for the AWC. As you can see we have a Low Level sensor and a High Level sensor in addition to our ATO sensor available in the ‘ATO’ tab.

Continued on next page…

Follow the steps below to create a Macro for a manual water change.

1. Click the ‘Macros’ tab at the top of reef-pi.
2. If you don’t have any macros setup you will only see a + sign, click this to create a new macro.
3. Name the macro ‘Manual Water Change’ and leave ‘Reversible’ as ‘No’.
4. As you create the Macro you will be clicking the + sign in the image below to add all the steps, this macro will contain 10 steps in total.

Continued on next page…

Let's go through each 'Step' in the macro.

1. The first step is optional and will ‘Turn Off’ the ‘ATO Sensor’ if you have this set up, you need to disable this first so it can’t turn on the ATO pump when the water level drops.
2. This step will ‘Turn On’ the ‘AWC Low Level‘ sensor and will start the draining process. When the macro turns on this sensor the drain pump it's controlling should turn on and water will start draining. If your sensor turns the pump on when no water is sensed, aka backwards, you need to go to the sensors 'Connector' and change the 'Reverse' option.
3. This step adds a 'Wait' period and pauses the macro, it won’t continue to the next step until this expires. The 300 seconds is only an example, you should set this to the longest period you want the drain pump to run but it should be set longer than it takes to drain the tank so the ‘AWC Low Level’ sensor can switch off the drain pump.
4. This step will 'Turn Off' the ‘AWC Low Level’ sensor as it's no longer needed as your tank has been drained.
5. This step will ‘Turn Off’ the ‘AWC Drain Pump’, this is redundant and only makes sure the drain pump has been turned off.
6. This step will 'Turn On' the ‘AWC High Level’ sensor and will start the refill process.  When the macro turns on this sensor the fill pump its controlling should turn on and water will start filling. If your sensor turns the pump on when water is sensed, aka backwards, you need to go to the sensors 'Connector' and change the 'Reverse' option.
7. This step adds another 'Wait' period and pauses the macro, it won’t continue to the next step until this expires. The 300 seconds is only an example, you should set this to the longest period you want the fill pump to run but it should be set longer than it takes to fill the tank so the ‘AWC High Level’ sensor can switch off the fill pump.
8. This step will 'Turn Off' the ‘AWC High Level’ sensor as it's no longer needed as your tank has been filled.
9. This step will ‘Turn Off’ the ‘AWC Fill Pump’, this is redundant and only makes sure the fill pump has been turned off.
10. This step will ‘Turn On’ the ‘ATO Sensor’ setup as well you can turn this back on so your ATO will run as normal again.

    ---

19. Using reef-pi – Dashboard

The first tab at the top is ‘Dashboard’, this is where you can view charts for different equipment and sensors.

1. Click the ‘Configure’ button.
2. Set how many rows and columns you want to view. The dashboard will collapse the chart to the next row if the display screen can’t view that many columns.
3. Click the dropdown and select the module you want to view.
4. Click the 2nd dropdown and select a sensor or system if applicable.
5. Repeat steps 3 – 4 until you’ve added all the charts you need.
6. Click the ‘Update’ button.
7. Click the ‘Back to dashboard’ button

Contributors

Doug Youd - “Cnidus”

Iain Bonnes

Thank-you again for your purchase and I hope you enjoy your Robo-Tank controller.

Questions or comments contact me, Rob Fowler at info@robo-tank.ca