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 DS18B20 Waterproof 1-Wire Thermal Probe USD 2.00
1 x PCA9685 16-Channel 12-Bit PWM I²C Module USD 2.30
1 x MCP4728 4-Channel 12-Bit DAC I²C Breakout Module USD 7.00
2 x MC33074PG OP-AMP 14DIP USD 8.20
1 x LM2596 3A DC-DC Step Down Power Module USD 1.20
1 x MT3608 2A DC-DC Step Up Power Module 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. Either use a 5 V power supply unit or feed a DC-DC voltage converter with power from one of your devices like your light source or pump. With these 5 V entered through the ESP32 board's USB connector or '5V'/'VIN' pin you also get 3.3 V at its '3V3' pin, with the provided current usually being enough to power the OLED display, DS18B20 temperature sensors, PCA9685 PWM and MCP4728 DAC module. But I urge you to avoid overloading the tiny voltage converter of your ESP board, which may otherwise end up in smoke! 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 reliably.

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
Coral Box DCA 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 Nanostream Electronic
    6040, 6055, 6095
Turbelle Stream Electronic
    6105, 6155, 6255,
    6150 (Stream 3/3+)
DC 0 .. 10 V
Waveline DC6000, DC12000, DC20000
WavePuck, WavePuck II
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.

Printed Case Total Printed Case Panel
Though I run a breadboard-mounted AquariOS controller reliably for years now, it's better to keep the sensitive electronics protected within a case. You'll soon find here .STL-files to print a wall-mount home for your AquariOS controller built upon a 10 x 16 cm PCB.

Apart from access to the ESP's USB-connector and a cut-out for the DC power jack it has holes in the base plate ready for lots of screw-in mini-XLR sockets to connect all your devices. The display panel holds a 2.8" TFT touch screen on the left. In the middle there are 3 stacked 10-segment bargraph displays, masked for light = 8 * blue, pump = 8 * green and temperature = 4 * red. Below two 5 mm LEDs, the left one white as a pulsating sample heartbeat indicator, the right one as a power indicator. On the right the (red) feed button, finally the power switch and below the WiFi mode toggle (open = Station mode, closed = Access Point mode).

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.1.8 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 & ESP32-S2) from Espressif's ESP32 Resources page and also extract its contents. Start the 'flash_download_tool_3.8.5.exe' application, select 'Developer Mode' 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 the WiFi mode switch is closed 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!

Please consider that the integrated web server cooperates best with the Mozilla Firefox browser. Other web browsers may have issues, e.g. timeout problems due to a slow response by the underpowered ESP32 server hardware.

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.

As already mentioned, AquariOS controls external devices through a 16-channel PWM module (PCA9685) and a 4-channel digital-analog-converter module (MCP4728), which comnmunicate with the processor through its I²C interface. Their 1-byte standard addresses are 0x40 (PCA9685) and 0x60 (MCP4728), to be entered in 2-digit hexadecimal format (like '40' or '60'). Enter '00' to deactivate the respective module.

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 header line temperature comes from the sensor at 'Address 1'.

Apart from the (adjusted) temperature sensor input the TFT screen can also display the targeted temperature for each of the 4 output ports. At 'Temperature Target Display' you define in which intervals the temperature table switches to that port data, for one second at a time. With the output data being shown the background color turns from red to blue. An interval of '00:00' suppresses, whereas '00:01' constantly shows target temperatures.

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 in the upper left corner 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 just one click away.

On the other hand, with a 'Factory Reset' the non-volatile memory is completely erased, which means, that apart from table data and probe calibration variables all parameters at the Config page including your network connection credentials have to be reentered. As long as you don't restart the device, you can afterwards repopulate NV-RAM with the table data currently used by the system by clicking the respective 'Save' buttons. But at first you should reenter network access data to avoid later-on having to restart AquariOS in Access Point Mode to get access.

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 doesn't look very complex, as there only time anchor values (Weekday(s) / Time) along with their corresponding power resp. light intensities have to be entered. Intensities are stored as 1-byte values, which is why numbers are shown in hexadecimal notation (0..255 => 00..FF). Processing is then done with the entered 8-bit power values extended to the 12-bit range (0..4095 / 000..FFF) supported by the PWM / DAC output interfaces, which allows smooth transitions.

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', which rearranges the table, sorted in ascending order based on 'Time' with all inactive entries ('Weekday' set to 'Never') gathered at the bottom. 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' ('Auto').

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.

Light Season
There are situations, where light intensity has to be changed gradually over a longer time period. Either you consider to implement seasonal variations in illumination. Or you have to ramp up intensity over weeks to slowly acclimate sensitive corals to a new environment without risking bleaching due to overexposure to light. That's where you need the 'Light Season' module.

Simply design a series of anchor points during the course of a year, each of which defines a dimming factor ranging from 0% (dark) up to a maximum of 250% (2½ times the underlying light intensity).

Here the time axis represents a full year, which is divided into 12 months of equal length measured in time units. Anchor points now have to be located on a time grid of tenths of a month, where '1.0' means January 1st 00:00.0, with each tenth adding 365/120 = 3.04 (within leap years 366/120 = 3.05) days up to 3 days before New Year's Eve ('12.9'). There's a Fractional Months Calculator to help with such date conversions.

Finally assign that rule to a 'Light Program' by selecting the according channel at 'Ssn Chan' with the 'Ssn Acti' box being checked. To shift the curve on the time axis increase the 'Ssn Ysft' value above the '0.0' months default. So to move the curve a quarter of a year to the right enter '3.0' (months). In case you use the Fractional Months Calculator be aware to subtract '1' from the resulting fractional value, as shifting starts from '0', meaning no shifting at all.

Light Season Moon
A simple method to simulate moon phases would be to create a list of alternating '0' and '100' percent values at half monthly intervals and assign that schedule to an adequately dimmed light channel.

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 that 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.

You achieve maximum flexibility by extending all of your pump shapes to the full 00..FF range and later on rescaling and shifting these curves at the 'Pump Automation' table according to your respective needs. For example, if a minimum of 25% output has to be guaranteed throughout a full-scale shape program, enter these 25% as the Offset of that shape, which you then also have to scale down to 75% of its size to make it still fit into the given power range.

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.

Most pumps don't immediately start up with only minimum voltage on the control wire. Tunze DC pumps for example need at least about 30 percent of their maximum voltage to spin in stable rotation. Below that you risk overheating and accelerated attrition due to an eccentric wobbling impeller. And there may be situations, where the maximum pump throughput has to be restricted for whatever reason. AquariOS accommodates such requirements, as it allows to transpose the calculated power values into a narrower power band defined by the upper and lower 'Powr Range' parameter, where the '00' .. 'FF' preset means no change.

Now, with such an output transition in action, you have to decide, whether at zero power the pump has to remain spinning at idle speed, or to be stopped. The former would be better for short periods to avoid stressing on-off cycles, while the latter saves energy and prevents wear during longer inactivities. Select device type 'VariOn' to always keep power within 'Powr Range', and 'VariOff' to regulate power down to zero when the lower border of that range is reached (or in other words deactivate 'Powr Range' calculations at zero).

Be aware, that the on-screen display doesn't reflect the output modifications resulting from 'Powr Range' calculations, which are only done to compensate device weaknesses approaching the targeted output waveform.

Mode can once again be 'Inactive', 'Off', 'On', 'Fixed' (with 'Fix Powr' defining intensity) and 'Auto'matic (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', 'Auto' / '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.

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

The temperature chart demonstrates that difference. While on the left up to 15:00 an SSR driven by AquariOS controls power supply to an Eheim-Jäger 3606 150 W heater in a 125 l / 33 gal tank (hysteresis 0.0°C), later-on that heater is directly connected to the electrical grid and thereby controlled by its internal bimetal thermostat, resulting in noticeable temperature swings.

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

When, with a 'Heater' device type selected, temperature falls below the target minus hysteresis value, power is turned on with the display showing '+'. As temperature now rises, at and above target value display changes to 'X' indicating hysteresis range, where heating still continues. If it falls back below the hysteresis range you'll once again see '+'. Finally, at target temperature, power is turned off with the display indicator switching to '-'. When with the now inactive device temperature falls back into hysteresis range '|' is shown until it comes below target temperature minus hysteresis, where the heater is activated again.

The same goes with the 'Cooler' type. Above target temperature plus hysteresis value the chiller unit gets powered till temperature falls down to target temperature with the indicator showing '+' above hysteresis range and 'X' within that range above target temperature. With the device finally switching off at target temperature, again '-' is shown changing to '|' with temperature rising into 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.

Temperature Program
The graph on the left shows temperatures measured while running an automation program with four time-temperature anchors defined (00:00 - 25.5°C / 03:00 - 25.5°C / 12:00 - 27.0°C / 15:00 - 27.0°C).

With an hysteresis of 0.1°C the shape of the curve isn't as smooth as the waveform in the chart above. On the other hand that wider range results in on-off cycles of about 10 minutes length, whereas with a 'zero tolerance' hysteresis of 0.0°C there are about 10 switching cycles per minute, requiring the usage of an electronic switch like an SSR.

Temperature Season
In order to reflect seasonal changes in our living beings' natural habitats it may be necessary to vary water temperature throughout the year. Apart from freshwater scenarios, where temperature fluctuations may be drastic, even the behavior of reef biotope inhabitants is considerably influenced by this environmental parameter. So, for instance, spawning of Acropora species seems to be triggered and thereby synchronized by a rapid seasonal rise in ocean temperature.

To experience the sequence of seasons with your tank you just have to define a series of temperature correction values, each in a range of ±20.0°C, at the 'Temperature Season' table similar to the 'Light Season' page. Activate that dataset at the 'Temperature Program' page, 'Ssn Acti' and 'Ssn Chan', for a given entry. There you may also shift the curve by fractions of a month with the 'Ssn Ysft' (Season Year Shift) parameter and/or mute/boost/invert the correction value by using the 'Ssn Scal' (Season Scaling) (±125%) percentage value.

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.

TFT Screen Dump - Manual Power
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.

Furthermore there's a manual light and pump power mode only accessible through the MQTT interface. When a channel gets into manual mode the background color of its readout on the TFT screen turns orange.

Imagine, now you're capable of creating an individual graphical user interface that best suits your needs! The demo dashboard presented here was built by using the freely available Node-RED development tool.

Table of MQTT commands and data returned
Direction Topic Payload Description
Name Data
System
Subscribed sc/set rst Restarts AquariOS system
Date & Time
Subscribed dc/set cardinal [milliseconds since epoch, only seconds valid] Sets system date & time
dc/net Induces retrieval from NTP server
dc/get Induces dc/ret publishing
Published dc/ret name Timestamp [ms since epoch (19700101 0000 UTC)] Published system date & time
type dd
valu cardinal
Temperature
Published td/ret name Temperature [°C] Published temperature of active probes (0..3)
type td
chan cardinal
valu float
Feed Control
Subscribed fc/set [ina|act|aut] Sets Feed Mode: Inactive / Active / Count-Down Automation
Published fc/ret name Feed Duration Remaining [s] Published remaining feed duration
type fd
valu cardinal
Light Control
Subscribed lc/set [aut|min|max] Sets Light Mode: Automatic / Minimum (Dark) / 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/set chan cardinal [0..7] Sets Light Program dataset (item 0..7), implies 'lp/get [0..7]'
mode cardinal [0..4]
devi cardinal [0..1]
port cardinal [0..7]
fxpw cardinal [0..255]
auch cardinal [0..9]
ssac boolean [false|true]
ssch cardinal [0..19]
ssys cardinal [0..119]
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]
lp/get cardinal [0..7] Initiates publishing of a Light Program dataset (item 0..7)
Published lp/ret name Light Program Published Light Program dataset (item 0..7)
type lp
Payload similar to 'chan' .. 'spct' described above
Light Manual Override
Subscribed lm/set chan cardinal [0..7] Sets Light Manual Override data (item 0..7), implies 'lm/get [0..7]'
mode boolean [false|true] (optional)     Mode: Inactive / Active
powr cardinal [0..4095] (optional)     Light Power
lm/get cardinal [0..7] Initiates publishing of a Light Manual dataset (item 0..7)
Published lm/ret name Light Manual Override Published Light Manual Override data (item 0..7)
type lm
Payload similar to 'chan' .. 'powr' described above
Pump Manual Override
Subscribed pm/set chan cardinal [0..7] Sets Pump Manual Override data (item 0..7), implies 'pm/get [0..7]'
mode boolean [false|true] (optional)     Mode: Inactive / Active
powr cardinal [0..4095] (optional)     Pump Power
pm/get cardinal [0..7] Initiates publishing of a Pump Manual dataset (item 0..7)
Published pm/ret name Pump Manual Override Published Pump Manual Override data (item 0..7)
type pm
Payload similar to 'chan' .. 'powr' 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/set
Payload {
  "chan":  4,
  "port":  4,
  "devi":  1,
  "mode":  4,
  "fxpw":  63,
  "auch":  4,
  "ssac":  true,
  "ssch":  1,
  "ssys":  73,
  "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,
    "ssac":  true,
    "ssch":  1,
    "ssys":  73,
    "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