AquariOS - Aquarium Operating System

Two years ago, when I planned and built my lake Victoria tank, I had to decide how to control my custom made LED illumination. I settled on a cheap Arduino Mega 2560 microprocessor board and, apart from a few minor inconveniences, was very happy with its reliable performance. The main nuisance was the spartan LCD / keypad user interface, which mainly allowed to switch lightning modes. So in order to modify light intensity curves or adjust time, which at least had to be done twice a year due to daylight savings nonsense, a USB connection was required.

Fortunately technology makes great strides, and we now have the ESP32, developed by Espressif Systems, which is faster, comes with much more memory and wireless connectivity, and is capable of running the FreeRTOS multitasking operating system. Above all the ESP32 development board is a true bargain. Put it on a solderless breadboard along with a PWM interface board, a small LCD module, a few resistors, wires and LEDs, and you get the light controller working for no more than 25 USD, which in my opinion represents excellent value for the money. A few dollars more and you own a device offering a mix of all in all 20 outputs channels to control an armada of light sources, pumps, heaters and ventilating fans in a flexible way even high-priced commercial products hardly provide.

Apart from a few push buttons (e. g. to start feeding mode manually) AquariOS is completely controllable through its WiFi interface. You only have to have a standard webbrowser. No active contents, no need to install any proprietary program on your computer, thus no leakage of information. System time is automatically retrieved from Internet NTP time servers.

At the current stage AquariOS drives two 12-bit I²C devices, which are a PCA9685 16-channel PWM module and an MCP4728 4-channel digital-to-analog converter. Our 16 PWM outputs divide into 8 LED plus 4 pump channels, which are time driven, furthermore 4 temperature controlled heater / cooler on/off-switch channels, whereas all four DAC leads are dedicated to pump controlling. All output values are set five times a second (at 200 millisecond intervals), which enables you to fine tune your wave pumps according to your tank's metrics. The web interface makes it very easy to program individual pump power shapes right down to the last detail.

Most relevant real-time data as the current date & time, Feed Mode countdown in seconds, the temperature read from a selection of multiple attached DS18B20 thermal probes and output levels of all PWM / DAC channels are shown at an SPI OLED display, the latter in hexadecimal format with the least significant digit removed and '··' / '**' representing 0x000 (minimum/off) resp. 0xFFF (maximum/on).

The AquariOS device consists of only a few very cheap components, easily available on the Internet. These are the core components you may have to add dependent on your controller's future range of duty.

4 x	400 Point Mini Solderless Breadboard 3.35" x 2.16"	USD 4.20
1 x	Espressif Systems ESP32S / CP2102 Development Board	USD 6.50
2 x	LED-10-Segment-Bargraph-Display Fixed Tricolor B10RYG	USD 8.00 (5 pcs)
1 x	1.3" SPI Serial 128X64 OLED LCD Display Screen Module	USD 5.50
1 x	PCA9685 16-Channel 12-Bit PWM I2C Module	USD 2.20
1 x	MCP4728 16-Channel 12-Bit DAC I2C Breakout Module	USD 8.00
2 x	MC33074PG OPAMP 14DIP	USD 8.20
1 x	MT3608 2A DC-DC Step Up Power Booster	USD 0.80

To run the basic AquariOS system you need at least a 5 V power source. With 5 V entered through the ESP32 board's USB connector or '5V'/'VIN' pin you also get 3.3 V at its '3V3' pin, required to power the OLED display, DS18B20 temperature sensors, PCA9685 PWM and MCP4728 DAC module. With the MCP4728 putting out a little above 2 V (2.048 V to be exact) and the PCA9685 generating a PWM amplitude of only about 2.5 V, additional higher voltages, which a DC-DC boost converter can provide, may be needed by both op-amps to control DC pumps and drive SSRs.

No matter, even with such a small step-up converter integrated to supply the op-amps with 15 Vcc, current is expected to be less than 200 mA, way below the 500 mA allowed by USB 2.0 specifications. So a computer connected with the ESP board via a USB cable can be a sufficient power source. But the power supply to choose particularly depends on the equipment that has to be driven. For example a Fostek SSR-40DA used to interface a heater draws additional 40 mA. And with PWM driven high power LEDs you always have to decide on a more expensive power supply unit depending on number, voltage and current of the respective LED chains.

Within less that an hour the core system is built on a breadboard, with a few LEDs indicating PWM output levels and the microcontroller attached to a common USB power adapter or your computer's USB port, ready for your first experiments.

Later on with everything working fine it's time to connect your terminal devices like PWM-driven light sources, voltage-controlled pumps or relay-switched heaters, coolers and feeders etc. with the controller unit. That's when you have to use a voltmeter to adjust amplification of all relevant op-amp outputs according to the needs of the attached DC-controlled pumps and solid-state relays.

Here's the interface parameter listing of a few DC-controlled aquarium pumps, most of which I found on the Internet:

Manufacturer	Type	Mode	Voltage
Jebao	WP pumps DC pumps	DC	0 .. 5 V
Reef Octopus	VarioS	DC	0 .. 10 V
Sicce	XStream-E	DC	0 .. 10 V
Speedwave	DC pumps	DC	0 .. 5 V
Tunze	Turbelle Stream Electronic (6105, 6155, 6255, 6150)	DC	0 .. 10 V
Hydor	Koralia	FM	~ 12 Vpp at ~ 60 Hz AC

I have to make clear, that most of these data are not verified, which is why I urge you to do your own voltage metering with the devices you own before attaching them to the AquariOS system.

In order to upload the AquariOS firmware to the ESP32 processor a USB connection with your Windows PC has to be established, managed by a CP210x USB to UART Bridge VCP Driver, which you may have to install. With the cable connection in place open the Windows Device Manager. There needs to be a 'Silicon Labs CP210x USB to UART Bridge (COMx)' entry at the 'Ports (COM & LPT)' section. Memorize its COM port number, which you later have to select within the ESP32 Flash Tool.

Download the AquariOS 0.9.3 Firmware archive (with its PGP Signature file to check authenticity) from this site and extract the folder it contains to some place.

Then download the Flash Download Tools (ESP8266 & ESP32) from the Espressif's ESP32 Resources page and extract its contents. Start the 'ESPFlashDownloadTool_v3.6.3.exe' application and click the 'ESP32 DownloadTool' button. In the window that now opens select files and set parameters according to the picture on the right. Finally click 'START' to initiate the firmware upload.

To reset the controller and run the program press the 'EN' button next to your ESP's USB connector.

The AquariOS device has no buttons to set network parameters directly. Restart it while pressing the WiFi mode button and it creates an Access Point (SSID 'AQUARIOS-AP', passphrase 'W3tW3tW3t') your computer can connect with. Be aware, that everybody within reach who has knowledge of that publicly available passphrase is able to log into your AquariOS system! So try to leave the Access Point mode ASAP after entering your router's credentials!

At https://192.168.1.1/config you'll find your AquariOS Controller's Configuration page. Being there enter your router's SSID and passphrase and click 'Set'. Finally restart AquariOS (with the WiFi mode button released) to make it connect with your WLAN router. When it succeeds and finds a way to one of the many 'pool.ntp.org' NTP servers on the Internet the LCD screen will present you the correct date and time after a few seconds.

Now set the timezone of your location at 'Date & Time'. Valid text entries for many regions worldwide can be found at the OpenWRT website. In case AquariOS has no Internet access, this is also the place where you can set your local time manually.

At 'Feed Mode' select the time interval [mm:ss] AquariOS remains in Feed Mode after pressing the according button on your device. Below you'll read how to configure light and pumps to run specific feed programs during that period of time.

With DS18B20 OneWire temperature probes attached to your system, select which one of them provides the data displayed at the LCD module and the web interface's header line.

The 'Reset Data Tables' buttons are there to clear the respective parameter tables, for example to start a new setup from scratch. Accidentally clicking on one of these buttons does no harm, as all tables' contents are still stored in the non-volatile memory. Go to the respective page and click 'Save' to make your changes permanent or press 'Load' to restore the original dataset. So feel free to play with pump shapes or other parameters, the starting point is only one click away.

AquariOS programming bases on time anchor points within a 24-hour day, each combined with an associated weekday set defining the days that time is valid. At such anchor points you set certain parameters like the illumination power. AquariOS now interpolates the intercurrent values following a direct line between the anchor points and forwards the calculated results to the output channels.

With light programming the 'Automation' table isn't very complex, as there are only the time anchor values (Weekday(s) / Time) and the power resp. light intensity. To get best results usually the complete byte range is used, which is why numbers are shown in hexadecimal notation (0..255 => 00..FF).

Such anchor - value(s) sets are organized in channels, which on the 'Prog'ram page you finally can assign to output devices. Entering a meaningful name on the top right of each channel's page makes life much easier.

In order to copy a data line up to the input line, where it's editable, select the corresponding 'Chan'nel and 'Item' number and click 'Get'. After modifying parameters press 'Set'. Be aware, that for permanent storage you have to click 'Save' as well, as otherwise your changes are gone at the latest with a system restart.

To create a backup file of your table contents at your computer click 'Download'. You get an hexadecimal ASCII file for a later reupload ('Browse...' / 'Upload').

After defining all light intensity curves you can assign the newly created light automation channels to PWM output ports. The port numbers here (1..8) represent port 1..8 of your PWM module.

First specify the type of your lamp, which may either be On/Off or Variable. With 'On/Off', relevant for devices that don't support dimming, all power values above zero result in an 'FF' intensity, which means the output is continuously on, avoiding the rectangular pulse wave signal typical for PWM, which you get with 'Variable'.

With 'Mode' you have the choice to deactivate the entry and exclude it from using the port ('Inactive'), set the port continuously to '00' ('Off') or 'FF' ('On'), specify a manual intensity directly with the 'Man Pwr' parameter ('Manual') or select an Automation channel at 'Aut Chan' ('Automatic').

Mark 'Feed Auto' to switch to the corresponding 'Feed Chan' Automation Mode while Feed Mode is manually activated.

By checking 'Sun Acti' you activate the (still rudimentary) Sun / Cloud Simulation. There brightness is in- or decreased to the percentage defined at 'Sun Pcnt'. The center of this change is defined by the 'Sun Dist' time interval, starting at midnight repeating all day long. From this center the 'Sun Hold' interval extends to both sides with the 'Sun Ramp' interval added also to the beginning and the end of the simulation period. The example with 'Sun Dist' at '00:15:00.0', 'Sun Ramp' as well as 'Sun Hold' at '00:01:00.0' and 'Sun Pcnt' at 200 results, starting at an intensity of 40, in 40 at 13:13:00.0 continuously increasing up to 80 at 13:14:00.0, held till 13:16:00.0, then decreasing to the initial 40 at 13:17:00.0. Sun / Cloud Simulation is deactivated while in feed mode.

Pump configuration is very similar to light programming. You only have one further layer to create pump power shapes, which then are performed in infinite loops up to the next Pump Automation time anchor.

In order to design shapes you have to put together time slices of variable widths measured in tenths of seconds ('Duration'), also with a 200 millisecond granularity. With each of these slices you define the power at the beginning of that interval ('Power') and the method to move that value to the next slice ('Mode'). 'Hold' means you hold the given power value until you reach the beginning of the next slice, where it changes rapidly. With 'Direct' there's a smooth transition. 'Off' deactivates the table entry. And there are some 'Random' modes to come.

The 'Position' parameter is there to rearrange entries within your list. Select 'Chan'nel and 'Item', set 'Position' to the item number where the entry has to be inserted, finally click 'Set'.

Be aware that item number 1 only runs once after starting the loop, which, reaching its end, always jumps back to position 2. By changing the duration of that entry slice you can easily shift the following loop relative to other shapes.

At the Pump Automation page shapes are arranged to pump timetables to be run day by day. Each time interval, represented by a line, starts at the given Weekday set / time, continuing until the time anchor that follows. Assign one of the shapes from the list of shapes you previously created and specify the percentual intensity at the beginning ('Pct Beg') and the end ('Pct End') of the interval. Finally decide whether you need to delay the shape for example to create waves or gyres by synchronizing the pump with others.

Now you have to assign Pump Programs to the ports, where your pumps are attached. Pump Ports 1..4 are mapped to PWM ports 9..12. Ports 5..8 feed the analog outputs A..D (voltage range 0V to 2.048V) with their downstream operational amplifiers adjusted to the requirements of the connected pumps.

As with the light configuration you have to enter whether it's an On/Off device or a variable speed DC pump.

Mode can once again be 'Inactive', 'Off', 'On', 'Manual' (with 'Man Powr' defining intensity) and 'Automatic' (channel at 'Aut Chan').

Check 'Feed Auto' if certain pumps have to work differently ('Feed Chan') while in feed mode.

Add cheap DS18B20 OneWire temperature sensors and AquariOS can also vary water temperature according to your animals' needs. Place one of the sensors next to your expensive LED equipment to control a fan.

At first a new sensor has to be adjusted. Set 'Bias' to shift the calibration curve up or down, 'Slope' to change, well, its slope.

The Temperature Program works similar to the Light and Pump Program page. Select 'Mode' ('Inactive', 'Off', 'On', 'Manual' / 'Man-Temp', 'Automatic' / 'Aut-Chan')), 'Port' number (1..4 corresponding PWM output 13..16) and device 'Type' ('Heater' or 'Cooler'). With 'Offset' you can shift your target temperature up or down.

'Hyst'eresis defines the temperature range, within which the on/off status of the output doesn't change. Where with mechanical style heaters a low number of switch cycles is important to protect the mechanic bimetal thermostat, with solid-state relays (SSRs) to be used with AquariOS it's just the opposite. To avoid temperature differences that put a great strain on the device, a narrow hysteresis range resulting in many short on-cycles has to be chosen.

For each channel the LCD display shows '·' for inactive, '-' for off ('|' within hysteresis range) and '+' for on ('X' within hysteresis range).

As there's always the chance the system fails, there have to be some precautions. Connect a heater with an integrated mechanic thermostat set to a temperature a little above the range AquariOS takes care of, and add another independent heater to the tank, activated at a temperature below the AquariOS range. This way you avoid cooking or freezing the living beings in your aquarium.

Temperature Automation curves have to be set up similar to Light Automation. Enter a 'Weekday' set / 'Time' combination and the targeted 'Temp'erature and click 'Set'. That's it.

AQUARIOS IS A WORK IN PROGRESS, DISTRIBUTED IN THE HOPE THAT IT WILL BE USEFUL. IT IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR OR COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THIS WORK OR THE USE OR OTHER DEALINGS IN IT.