Homepage Down Bottom AquariOS - Aquarium Operating System

Totale 30.12.2015

Down Up Top Introduction

Board Schematic
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 controller working for no more than 20 USD, which in my opinion represents excellent value for the money.

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 I2C devices, which are a PCA9685 16-channel PWM module and an MCP4728 4-channel digital-to-analog converter. The 16 PWM outputs divide into 8 LED plus 4 pump channels, which are time driven, furthermore 4 temperature controlled heater / cooler 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).

Down Up Top Hardware

The AquariOS device consists of only a few very cheap components, easily available on the Internet. With the microcontroller attached to a common USB power adapter and a few LEDs indicating PWM output levels the system is built on a breadboard within less that an hour, ready for your first experiments.

Later on with everything working fine it's time to attach your terminal devices like PWM-driven light sources, voltage-controlled pumps or relay-switched heaters, coolers and feeders etc. to the controller unit.

Down Up Top Firmware

ESP32 Flash Tool
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.2 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.

Down Up Top Configuration

Main Configuration
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 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.

Down Up Top Light

Light Automation
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').

Light Program
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.

Down Up Top Pump

Pump Shape
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.

Pump Automation
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.

Pump Program
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.

Down Up Top Temperature

Temperature Control
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.

Temperature Program
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
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.

Down Up Top !!! Important Notes !!!


Down Up Top And now ... Action!

Up Top

Copyright © Christian Danner, 2017.

Homepage: www.danner-net.de
EMail: aquarios@danner-net.de