Homepage Down Bottom AquariOS - Aquarium Operating System

Aquarium

Down Up Top Introduction

Device
In 2015, 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.

ESP32
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 OLED or TFT (touch) display, a few resistors, wires and LEDs, and you get the light controller working for no more than 30 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 output channels to control an armada of light sources, pumps, heaters, feeders 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 web browser. Or there may already be an MQTT home automation system to take control. No active contents, no need to use an external cloud service or install any proprietary software on your computer, thus no leakage of information. System time is automatically retrieved from Internet NTP time servers.

TFT
OLED
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. 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 put out a DC signal to run voltage controlled devices, usually pumps. 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 can be 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). Or you opt for a TFT display, supported since the 1.0.0 firmware release, to get additional real-time graphs of all pump output channels visualizing the power shapes you programmed. TFT touch screen capabilities add access to a GUI for altering important parameters directly, for example to activate feeder mode or switch lights altogether on or off.

Down Up Top Hardware

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

Shopping List
4 x 400 Point Mini Solderless Breadboard 3.35" x 2.16" USD 4.20
1 x Espressif Systems ESP32 WROVER Development Board USD 9.75
2 x LED-10-Segment-Bargraph-Display Fixed Tricolor B10RYG USD 8.00 (5 pcs)
1 x SSD1306 / SSH1106 SPI 128X64 OLED Display Module
or
ILI9341 (XPT2046) SPI 240X320 TFT (Touch) Display Module
USD 5.50
or
USD 6.50
1 x PCA9685 16-Channel 12-Bit PWM I2C Module USD 2.20
1 x MCP4728 4-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

Attention! Starting with version 1.0.0, AquariOS requires an ESP32 WROVER module including at least 4 MB of PSRAM. The older WROOM module no longer works!

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.

Breadboard
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 LEDs to be chained.

Within less that an hour the core system with a few LEDs indicating PWM output levels and the microcontroller attached to a common USB power adapter or your computer's USB port is built on a breadboard, 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-controllable aquarium pumps, most of which I found on the Internet:

Manufacturer Type Mode Voltage
Jebao / Jecod WP pumps
DC pumps
DC 0 .. 5 V
SW pumps DC 0 .. 10 V
Maxspect / IceCap IceCap Gyre Interface Module DC 0 .. 10 V
Reef Octopus VarioS, Pulse 2, Pulse 4 DC 0 .. 10 V
Sicce XStream-E DC 0 .. 10 V
Speedwave DC pumps DC 0 .. 5 V
Tunze Turbelle Stream Electronic
    6055, 6065, 6085,
    6095, 6105, 6125,
    6150, 6155, 6255
DC 0 .. 10 V

I have to make clear, that not all of these data are 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.

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 latest AquariOS 1.0.9 Firmware archive (with its PGP Signature file to check authenticity) from this site and extract the folder it contains to some place. Information on firmware changes can be found in the AquariOS History file.

Then download the Flash Download Tools (ESP8266 & ESP32) from the Espressif's ESP32 Resources page and extract its contents. Start the 'flash_download_tools_v3.6.8.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.

After that's done, press the 'EN' resp. 'RESET' button next to your ESP's USB connector to reset the controller and run the program.

Down Up Top Configuration

Information 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', 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!

The AquariOS device's IP address https://192.168.1.1 leads to the 'Info' page holding data about hard- and software status and a button to start a TFT screen dump to your computer.

Either click the 'Config' button or enter https://192.168.1.1/cfg directly to get to your AquariOS Controller's Configuration page. Being there enter your router's SSID and passphrase and click 'Set'. You may also override the device's MAC address, which is presented in the usual LSB to MSB order. The least significant bit is always set to '0', the flag for unicast addressing. Enter '000000000000' to use the device's genuine MAC address.

Finally restart AquariOS, now with the WiFi mode button released, to make it connect with your WLAN router in order to get Internet access. 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. Apart from the system startup process time gets resynchronized with an NTP Pool server each day at 02:10 and 14:10 local time.

Now set the timezone of your location at 'Date & Time'. Valid text entries for many regions worldwide can be found at the OpenWRT Project website. Click the Timezone Database link to get there. In case AquariOS has no Internet access, this is also the place where you can set your local time manually. Nevertheless, there's no battery-powered real-time clock (RTC) on board, that keeps track of the time beyond a system reboot, which is why Internet access is important for smooth operation when power outages cannot be ruled out.

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 of them provide the data displayed at the OLED / TFT screen and the web interface's header line.

The next paragraph deals with the MQTT configuration, where at least the broker's network address and port have to be entered. The 'Publishing Interval' parameter represents the cycle time of temperature publishing, where '00:00' means no publishing at all.

The 'Reset Data Tables' buttons are there to clear the respective parameter tables as a whole, for example to start a new setup from scratch. Accidentally clicking on one of these buttons does no harm, as to activate that section the checkbox above first has to be ticked. Furthermore all tables' contents are still stored in non-volatile memory. Go to that particular 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.

Finally, by clicking the 'Restart' button the device would get rebooted.

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 fixed intensity directly with the 'Fix Powr' parameter ('Fixed') 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
First of all, BE CAUTIOUS! Not every tank is built to tolerate the stress caused by water continuously swashing back and forth!

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.

TFT Screen Dump
When designing 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 from that starting level to the starting level of the next slice ('Mode'). 'Hold' means you hold the given power value until you reach the next slice, where it then 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 defined Weekday set / time, continuing until the time anchor that follows.

Select one of the shapes you previously created and specify the percentual intensity and offset at the beginning ('Scal Beg' / 'Offs Beg') and the end ('Scal End' / 'Offs End') of the interval. The 'Scale' parameter is there to compress (below 100) or stretch (above 100) the previously designed shape. A negative value inverts the curve. In addition, with a positive or negative 'Offset' that curve can be shifted up resp. down the given percentage of the total range. That's particularly important to lift an inverted, negative graph into positive territory.

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', 'Fixed' (with 'Fix Powr' defining intensity) and 'Automatic' (channel at 'Aut Chan').

Check 'Feed Auto' if certain pumps have to work differently while in feed mode and select the Pump Automation channel ('Feed Chan') that then has to be used.

Down Up Top Temperature

Temperature Control
Add cheap DS18B20 OneWire temperature sensors and AquariOS can also vary water temperature according to your animals' needs. Shallow-water inhabitants for example may benefit from a nocturnal temperature drop. Or 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', 'Fixed' / 'Fix 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, some precautions have to be taken. Plug solely heaters with an integrated mechanic thermostat into your AquariOS controller and set them to a temperature a little above the range AquariOS has to take care of. And add another independent heater to the tank, activated at a temperature below the AquariOS range. That 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'. To make your configuration permanent click 'Save'. That's it.

Down Up Top MQTT

MQTT Dashboard
With version 1.0.5 an MQTT interface was introduced, a first step towards easy integration into home automation systems providing command sets to obtain status data and control processing.

That also means, for less complex configuration tasks you no longer have to deal with the heavyweight web interface. A few clicks using your smartphone for example may stop all pumps and increase light intensity to make maintenance work more comfortable.

Imagine, now you're capable of creating an individual graphical interface that best suits your needs!

Table of MQTT commands and data returned
Direction Topic Payload Description
Name Data
System
Subscribed sm/rst Restarts AquariOS system
Date & Time
Subscribed dm/get Induces dm/ret publishing
dm/net Induces retrieval from NTP server
dm/set cardinal [milliseconds since epoch, only seconds valid] Sets system date & time
Published dm/ret name Timestamp [ms since epoch (19700101 0000 UTC)] Published system date & time
type dd
valu cardinal
Temperature
Published td/[0..3]/ret name Temperature [°C] Published temperature of active probes (0..3)
type td
chan cardinal
valu float
Feed Mode
Subscribed fm/ina Deactivates Feed Mode
fm/act Activates continuous Feed Mode
fm/aut Activates Feed Mode count-down timer automation
Published fm/ret name Feed Duration Remaining [s] Published remaining feed duration
type fd
valu cardinal
Light Mode
Subscribed lm/aut Sets Light Mode Automatic
lm/min Sets Light Mode Minimum / Dark
lm/max Sets Light Mode Maximum / Bright
Light Program
Subscribed lp/sav Saves Light Program data to non-volatile RAM
lp/lod Loads / restores Light Program data from non-volatile RAM
lp/[0..7]/get Ininiates publishing of a Light Program dataset (0..7)
lp/[0..7]/set chan cardinal [0..7] Sets Light Program dataset (0..7), implies lp/[0..7]/get
mode cardinal [0..4]
devi cardinal [0..1]
port cardinal [0..7]
fxpw cardinal [0..255]
auch cardinal [0..9]
feac boolean [false|true]
fech cardinal [0..9]
sact boolean [false|true]
sdst cardinal [0..863998]
srmp cardinal [0..863998]
shld cardinal [0..863998]
spct cardinal [0..300]
Published lp/ret name Light Program Published Light Program dataset [0..7]
type lp
Payload similar to 'chan' .. 'spct' described above


As shown above, the MQTT interface refers to the internal item (channel-, port- etc.) numbers starting with '0'. It's up to the developer of the user interface resp. MQTT dashboard, to translate these values into the common 1+ numbering used on-screen and with the web interface.

A command to be sent to AquariOS either consists of

Topic dm net
Payload

a bare topic,

Topic home/aquarios/dm/set
Payload 1582931367000

a topic with a plain payload containing data

Topic home/aquarios/lp/4/set
Payload {
  "chan":  4,
  "port":  4,
  "devi":  1,
  "mode":  4,
  "fxpw":  63,
  "auch":  4,
  "feac":  false,
  "fech":  4,
  "sact":  true,
  "sdst":  6000,
  "srmp":  1200,
  "shld":  600,
  "spct":  75
}

or a topic with a JSON formatted payload containing a more complex dataset. With data processing <SPC>, <CR> and <LF> characters are ignored. So it's allowed to put all parameters in a single line.

Topic home/aquarios/lp/ret
Payload {
  "vers":  "1.0",
  "time":  1582925077,
  "name":  "Light Program",
  "type":  "lp",
  "load":  {
    "chan":  4,
    "port":  4,
    "devi":  1,
    "mode":  4,
    "fxpw":  63,
    "auch":  4,
    "feac":  false,
    "fech":  4,
    "sact":  true,
    "sdst":  6000,
    "srmp":  1200,
    "shld":  600,
    "spct":  75
  }
}

Data published by AquariOS are also formatted as JSON text blocks. There's an envelope section containing interface version ('vers'), timestamp ('time'), block type description ('name') and block type ID ('type'), followed by a payload section ('load') containing the data to be transmitted.

All messages are sent with QoS 0 ('at most once') and the Retained flag not set.

Currently the MQTT interface reflects only a few aspects of the AquariOS system, but with time further functionality will be added.

Down Up Top !!! Important Notes !!!

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.

Down Up Top And now ... Action!


Up Top

Copyright © Christian Danner, 2020.

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