Aquarium-Control - User contributions [en]

Automatic start by using systemd

2026-02-17T17:50:42Z

Uwe: /* Configuration of automatic start */

== Content of the startup script ==
The shell script for startup of the control application (<code>/usr/local/bin/aquarium_control_startup</code>) has the following content:

<code>
echo 0 > /var/local/aquarium-ctrl.pid

sudo touch /dev/mqueue/aquarium_control.6UXp

chmod o+rwx /dev/mqueue/aquarium_control.6UXp

/usr/local/bin/aquarium_control > /dev/null&

</code>

It resets any PID in the lock file from previously instances which were potentially not shut down correctly (for example, in case of power failure).
It creates the message queue file which is not a file on the hard drive and sets permission accordingly.
Finally, it starts the control application in the background.

== Configuration of automatic start ==
The content of systemd unit file <code>/lib/systemd/system/aquarium_control.service</code> as following:

<code>
[Unit]

Description=Aquarium Control Application

After=multi-user.target

After=network-online.target time-sync.target
Wants=network-online.target time-sync.target

[Service]

Type=forking

ExecStart=bash /usr/local/bin/aquarium_control_startup

[Install]

WantedBy=multi-user.target
</code>

Upon creation/modification of the unit file, one must run the command <code>sudo systemctl daemon-reload</code> in order to activate the changes.

For starting the control application manually via systemd, one can use the command <code>sudo systemctl start aquarium_control_startup.sh</code>.

Note: Waiting for the NTP before starting the application will avoid a wrong timestamp occurring, but may inhibit the start of the application if the internet connectivity is gone.

== Creating message queues for operation or test of aquarium_control ==
The startup script contains the creation of a set of message queues:

<code>
sudo touch /dev/mqueue/aquarium_control.5UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.5UXp

sudo touch /dev/mqueue/aquarium_control.4UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.4UXp

sudo touch /dev/mqueue/aquarium_control.6UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.6UXp

sudo touch /dev/mqueue/aquarium_control.7UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.7UXp

sudo touch /dev/mqueue/aquarium_control.8UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.8UXp

sudo touch /dev/mqueue/aquarium_control.9UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.9UXp
</code>

Only one of the message queues is required for operating the control application. The other message queues are use for parallel SW unit testing.

== Initialize lock file with zero as PID ==
The startup script contains the following command:

<code>
sudo echo 0 > /var/local/aquarium-ctrl.pid
</code>

The lock file has to be initialised to contain zero upon restart of the server. A missing or empty lock file is interpreted by the control application that something has gone wrong and startup will be aborted. In case of uncontrolled shutdown (e.g. power failure), the PID of the last operation may still be in the lock file, hence a reset to zero is required for this case.

== Start the application to run in the background ==
The start of the application in the background is triggered with the following command:
<code>
/usr/local/bin/aquarium_control > /dev/null&
</code>

Automatic start by using systemd

2026-02-17T17:49:34Z

Uwe: /* Configuration of automatic start */

== Content of the startup script ==
The shell script for startup of the control application (<code>/usr/local/bin/aquarium_control_startup</code>) has the following content:

<code>
echo 0 > /var/local/aquarium-ctrl.pid

sudo touch /dev/mqueue/aquarium_control.6UXp

chmod o+rwx /dev/mqueue/aquarium_control.6UXp

/usr/local/bin/aquarium_control > /dev/null&

</code>

It resets any PID in the lock file from previously instances which were potentially not shut down correctly (for example, in case of power failure).
It creates the message queue file which is not a file on the hard drive and sets permission accordingly.
Finally, it starts the control application in the background.

== Configuration of automatic start ==
The content of systemd unit file <code>/lib/systemd/system/aquarium_control.service</code> as following:

<code>
[Unit]

Description=Aquarium Control Application

After=multi-user.target

After=network-online.target time-sync.target
Wants=network-online.target time-sync.target

[Service]

Type=forking

ExecStart=bash /usr/local/bin/aquarium_control_startup

[Install]

WantedBy=multi-user.target
</code>

Upon creation/modification of the unit file, one must run the command <code>sudo systemctl daemon-reload</code> in order to activate the changes.

For starting the control application manually via systemd, one can use the command <code>sudo systemctl start aquarium_control_startup.sh</code>.

== Creating message queues for operation or test of aquarium_control ==
The startup script contains the creation of a set of message queues:

<code>
sudo touch /dev/mqueue/aquarium_control.5UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.5UXp

sudo touch /dev/mqueue/aquarium_control.4UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.4UXp

sudo touch /dev/mqueue/aquarium_control.6UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.6UXp

sudo touch /dev/mqueue/aquarium_control.7UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.7UXp

sudo touch /dev/mqueue/aquarium_control.8UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.8UXp

sudo touch /dev/mqueue/aquarium_control.9UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.9UXp
</code>

Only one of the message queues is required for operating the control application. The other message queues are use for parallel SW unit testing.

== Initialize lock file with zero as PID ==
The startup script contains the following command:

<code>
sudo echo 0 > /var/local/aquarium-ctrl.pid
</code>

The lock file has to be initialised to contain zero upon restart of the server. A missing or empty lock file is interpreted by the control application that something has gone wrong and startup will be aborted. In case of uncontrolled shutdown (e.g. power failure), the PID of the last operation may still be in the lock file, hence a reset to zero is required for this case.

== Start the application to run in the background ==
The start of the application in the background is triggered with the following command:
<code>
/usr/local/bin/aquarium_control > /dev/null&
</code>

Automatic start by using systemd

2026-02-17T17:49:25Z

Uwe: /* Configuration of automatic start */

== Content of the startup script ==
The shell script for startup of the control application (<code>/usr/local/bin/aquarium_control_startup</code>) has the following content:

<code>
echo 0 > /var/local/aquarium-ctrl.pid

sudo touch /dev/mqueue/aquarium_control.6UXp

chmod o+rwx /dev/mqueue/aquarium_control.6UXp

/usr/local/bin/aquarium_control > /dev/null&

</code>

It resets any PID in the lock file from previously instances which were potentially not shut down correctly (for example, in case of power failure).
It creates the message queue file which is not a file on the hard drive and sets permission accordingly.
Finally, it starts the control application in the background.

== Configuration of automatic start ==
The content of systemd unit file <code>/lib/systemd/system/aquarium_control.service</code> as following:

<code>
[Unit]

Description=Aquarium Control Application

After=multi-user.target

## wait for ntp to get updated time
After=network-online.target time-sync.target
Wants=network-online.target time-sync.target

[Service]

Type=forking

ExecStart=bash /usr/local/bin/aquarium_control_startup

[Install]

WantedBy=multi-user.target
</code>

Upon creation/modification of the unit file, one must run the command <code>sudo systemctl daemon-reload</code> in order to activate the changes.

For starting the control application manually via systemd, one can use the command <code>sudo systemctl start aquarium_control_startup.sh</code>.

== Creating message queues for operation or test of aquarium_control ==
The startup script contains the creation of a set of message queues:

<code>
sudo touch /dev/mqueue/aquarium_control.5UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.5UXp

sudo touch /dev/mqueue/aquarium_control.4UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.4UXp

sudo touch /dev/mqueue/aquarium_control.6UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.6UXp

sudo touch /dev/mqueue/aquarium_control.7UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.7UXp

sudo touch /dev/mqueue/aquarium_control.8UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.8UXp

sudo touch /dev/mqueue/aquarium_control.9UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.9UXp
</code>

Only one of the message queues is required for operating the control application. The other message queues are use for parallel SW unit testing.

== Initialize lock file with zero as PID ==
The startup script contains the following command:

<code>
sudo echo 0 > /var/local/aquarium-ctrl.pid
</code>

The lock file has to be initialised to contain zero upon restart of the server. A missing or empty lock file is interpreted by the control application that something has gone wrong and startup will be aborted. In case of uncontrolled shutdown (e.g. power failure), the PID of the last operation may still be in the lock file, hence a reset to zero is required for this case.

== Start the application to run in the background ==
The start of the application in the background is triggered with the following command:
<code>
/usr/local/bin/aquarium_control > /dev/null&
</code>

Automatic start by using systemd

2026-02-17T17:49:18Z

Uwe: /* Configuration of automatic start */

== Content of the startup script ==
The shell script for startup of the control application (<code>/usr/local/bin/aquarium_control_startup</code>) has the following content:

<code>
echo 0 > /var/local/aquarium-ctrl.pid

sudo touch /dev/mqueue/aquarium_control.6UXp

chmod o+rwx /dev/mqueue/aquarium_control.6UXp

/usr/local/bin/aquarium_control > /dev/null&

</code>

It resets any PID in the lock file from previously instances which were potentially not shut down correctly (for example, in case of power failure).
It creates the message queue file which is not a file on the hard drive and sets permission accordingly.
Finally, it starts the control application in the background.

== Configuration of automatic start ==
The content of systemd unit file <code>/lib/systemd/system/aquarium_control.service</code> as following:

<code>
[Unit]

Description=Aquarium Control Application

After=multi-user.target

\# wait for ntp to get updated time
After=network-online.target time-sync.target
Wants=network-online.target time-sync.target

[Service]

Type=forking

ExecStart=bash /usr/local/bin/aquarium_control_startup

[Install]

WantedBy=multi-user.target
</code>

Upon creation/modification of the unit file, one must run the command <code>sudo systemctl daemon-reload</code> in order to activate the changes.

For starting the control application manually via systemd, one can use the command <code>sudo systemctl start aquarium_control_startup.sh</code>.

== Creating message queues for operation or test of aquarium_control ==
The startup script contains the creation of a set of message queues:

<code>
sudo touch /dev/mqueue/aquarium_control.5UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.5UXp

sudo touch /dev/mqueue/aquarium_control.4UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.4UXp

sudo touch /dev/mqueue/aquarium_control.6UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.6UXp

sudo touch /dev/mqueue/aquarium_control.7UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.7UXp

sudo touch /dev/mqueue/aquarium_control.8UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.8UXp

sudo touch /dev/mqueue/aquarium_control.9UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.9UXp
</code>

Only one of the message queues is required for operating the control application. The other message queues are use for parallel SW unit testing.

== Initialize lock file with zero as PID ==
The startup script contains the following command:

<code>
sudo echo 0 > /var/local/aquarium-ctrl.pid
</code>

The lock file has to be initialised to contain zero upon restart of the server. A missing or empty lock file is interpreted by the control application that something has gone wrong and startup will be aborted. In case of uncontrolled shutdown (e.g. power failure), the PID of the last operation may still be in the lock file, hence a reset to zero is required for this case.

== Start the application to run in the background ==
The start of the application in the background is triggered with the following command:
<code>
/usr/local/bin/aquarium_control > /dev/null&
</code>

Automatic start by using systemd

2026-02-17T17:49:00Z

Uwe: /* Configuration of automatic start */

== Content of the startup script ==
The shell script for startup of the control application (<code>/usr/local/bin/aquarium_control_startup</code>) has the following content:

<code>
echo 0 > /var/local/aquarium-ctrl.pid

sudo touch /dev/mqueue/aquarium_control.6UXp

chmod o+rwx /dev/mqueue/aquarium_control.6UXp

/usr/local/bin/aquarium_control > /dev/null&

</code>

It resets any PID in the lock file from previously instances which were potentially not shut down correctly (for example, in case of power failure).
It creates the message queue file which is not a file on the hard drive and sets permission accordingly.
Finally, it starts the control application in the background.

== Configuration of automatic start ==
The content of systemd unit file <code>/lib/systemd/system/aquarium_control.service</code> as following:

<code>
[Unit]

Description=Aquarium Control Application

After=multi-user.target

# wait for ntp to get updated time
After=network-online.target time-sync.target
Wants=network-online.target time-sync.target

[Service]

Type=forking

ExecStart=bash /usr/local/bin/aquarium_control_startup

[Install]

WantedBy=multi-user.target
</code>

Upon creation/modification of the unit file, one must run the command <code>sudo systemctl daemon-reload</code> in order to activate the changes.

For starting the control application manually via systemd, one can use the command <code>sudo systemctl start aquarium_control_startup.sh</code>.

== Creating message queues for operation or test of aquarium_control ==
The startup script contains the creation of a set of message queues:

<code>
sudo touch /dev/mqueue/aquarium_control.5UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.5UXp

sudo touch /dev/mqueue/aquarium_control.4UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.4UXp

sudo touch /dev/mqueue/aquarium_control.6UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.6UXp

sudo touch /dev/mqueue/aquarium_control.7UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.7UXp

sudo touch /dev/mqueue/aquarium_control.8UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.8UXp

sudo touch /dev/mqueue/aquarium_control.9UXp

sudo chmod o+rwx /dev/mqueue/aquarium_control.9UXp
</code>

Only one of the message queues is required for operating the control application. The other message queues are use for parallel SW unit testing.

== Initialize lock file with zero as PID ==
The startup script contains the following command:

<code>
sudo echo 0 > /var/local/aquarium-ctrl.pid
</code>

The lock file has to be initialised to contain zero upon restart of the server. A missing or empty lock file is interpreted by the control application that something has gone wrong and startup will be aborted. In case of uncontrolled shutdown (e.g. power failure), the PID of the last operation may still be in the lock file, hence a reset to zero is required for this case.

== Start the application to run in the background ==
The start of the application in the background is triggered with the following command:
<code>
/usr/local/bin/aquarium_control > /dev/null&
</code>

Control application

2026-01-30T18:17:16Z

Uwe: /* Threads */

The main control application of Aquarium control implements the following features:

* [[Data acquisition of water temperature, pH and conductivity]]
* [[Data acquisition of ambient temperature and humidity]]
* [[Fresh water refill control|Refill control for fresh water]]
* Feed control
* Water temperature control using air ventilation and heater
* Balling mineral dosing

The control of the relays for operating the devices can use two different modes:
* [[Arduino-based relay actuation|Using an Arduino-based relay actuation]]
* Using the GPIO of the Raspberry Pi (requires additional hardware)

Additionally, the main control application implements the following supporting features:
* [[Version comparison between database and application]]
* Configuration using a Rust .toml configuration file
* Logging
* Command interface to receive instructions from outside of the application via a POSIX message queue
* Storage of recorded data in SQL database
* File-based communication to RAM-disk
* Usage of simulator to run with simulated sensor data for development purposes
* Schedule checks to limit the hour of day of operating certain actuators
* [[Communication with HW Watchdog]]
* [[Temperature gradient calculation]]
The application is written in Rust and is [[automatic start by using systemd| automatically started using systemd]].

The documentation of the software is available [http://vps2483992.servdiscount-customer.com/aquarium_control_doc/aquarium_control/ here].

Development for the main control application requires the [[setup of the development environment]].

There is a [[Release procedure|release procedure]] which is highly recommended to be followed also by anyone developing the SW further.

= Architecture =
== Startup of the application ==
The startup uses a two-layer approach:
# main() - Simple error handler wrapper that calls run() and exits with code 1 on errors
# run() - The actual initialization orchestrator that performs the major steps

=== Phase 1: Command Line & Configuration ===
* Parses command line arguments ("help", "version", config file)
* Sets the default config file: <code>/etc/aquarium_control/aquarium_control.toml</code>
* Loads configuration and creates <code>ExecutionConfig</code> (boolean flags determining which modules to run)

=== Phase 2: System Setup ===
* Initializes the logging system
* Logs version information and executable hash
* Verifies root privileges (required for hardware access)
* Publishes process ID to file for client communication

=== Phase 3: Database & Hardware ===
* Connects to database (MariaDB)
* Creates component-specific SQL interfaces (<code>Schedule</code>, <code>Balling</code>, <code>Refill</code>, <code>Heating</code>, <code>Feed</code>, <code>Data</code>)
* Validates database schema and version compatibility
* Initializes hardware components if configured:
** RGB LEDs
** GPIO handlers
** Tank level switch
** I2C interface
** Atlas Scientific sensors
** DHT temperature/humidity sensors
** Relay actuator (Controllino)

=== Phase 4: Communication Channels ===
* Creates the <code>Channels</code> struct containing ~30+ inter-thread communication channels
* Uses custom <code>AquaSender</code>/<code>AquaReceiver</code> wrappers for MPSC channels
* Establishes bidirectional and unidirectional message paths between all modules

=== Phase 5: Component Initialization ===
Instantiates all high-level control components:
* data logger
* sensor manager
* relay manager
* food injection
* mineral dosing (balling)
* water injection/refill
* heating control
* ventilation control
* monitors
* watchdog
* schedule checker
* temperature gradient calculation
* IPC messaging system

=== Phase 6: Thread Spawning ===
* Uses <code>std::thread::scope</code> for guaranteed cleanup
* Spawns threads conditionally based on <code>ExecutionConfig</code> flags
* Critical: A 3-second startup delay allows sensors to acquire first data before control loops activate

=== Architecture of thread configuration ===
* The <code>Channels</code> module (<code>src/launch/channels.rs</code>) acts as a central wiring diagram, with the Signal Handler serving as the main event coordinator.
* The <code>ExecutionConfig</code> decouples configuration from execution - threads only receive flags about which modules are active, not the full config - this also avoids ownership issues.

== Threads ==
The application spawns the following threads:
{| class="wikitable" style="margin:auto"
|+ Overview of threads
|-
! Thread name !! Purpose
|-
| signal_handler || Receiving signals from the operating system
|-
| schedule_check || Polling the database to capture changes of the actuator channel. Informing other threads about it.
|-
| sensor_manager || Data acquisition
|-
| relay_manager || Actuation of relays
|-
| data_logger || Recording of data
|-
| tank_level_switch || Postprocessing of tank level switch position signal
|-
| refill || Fresh water refill control
|-
| heating || Heating control
|-
| ventilation || Ventilation control
|-
| balling || Balling mineral dosing control
|-
| watchdog || Sending alive signal to Raspberry Pi hardware watchdog
|-
| monitors || Diagnostics (not implemented as of January, 2026)
|-
| messaging || Receiving communication via message queue
|-
| memory || Monitoring memory utilization
|-
| ds18b20 || Recording data from DS18B20 temperature sensor
|-
| feed || Feed control
|-
| i2c_interface || Communication via I2C
|-
| atlas_scientific || Recording data from Atlas Scientific temperature sensor
|-
| dht || Recording data from DHT sensor
|-
| publish_pid || Writing PID to lock file
|-
| temperature_gradient || [[Temperature gradient calculation]]

|}

= Measurement using Atlas Scientific circuits =
The core Abstraction (<code>AtlasScientificDriver</code> Trait) is defined in <code>src/sensors/atlas_scientific_driver.rs</code>, this trait serves as the common interface for all sensor types. It enforces three key behaviors:
* <code>send_request_to_i2c_interface</code>: Encapsulates how to trigger a measurement (e.g., constructing specific I2C commands).
* <code>receive_response_from_i2c_interface</code>: Handles parsing the raw byte response from the I2C bus into a normalized floating-point value.
* <code>device_init</code>: Performs hardware-specific setup (crucial for OEM type sensor circuit).

Circuit-type-specific implementations
* OEM Driver (<code>AtlasScientificOem</code>):
** Protocol: Uses a binary, register-based protocol.
** Initialization: Requires an explicit "Wake Up" command (writing to <code>REG_WAKEUP</code>) and verifies the hardware by reading the <code>REG_DEVICE_TYPE</code>.
** Read Cycle: Writes a register address (e.g., <code>REG_DATA_MSB_PH</code>), waits for a short processing time, and reads 4 bytes.
** Parsing: Decodes the 4-byte response as a Big Endian unsigned integer and divides it by a specific scale factor (e.g., 1000.0) to get the float value.
* EZO Driver (<code>AtlasScientificEzo</code>):
** Protocol: Uses a text-based (ASCII) command protocol.
** Initialization: Minimal or no-op (these devices are typically always ready or auto-on).
** Read Cycle: Sends the ASCII character 'R', waits for a longer processing time, and reads a fixed 8-byte response.
** Parsing: Validates "magic" start/end bytes (1 and 0), converts the inner ASCII string (e.g., "23.50") to a float.

Context and factory (<code>AtlasScientific</code> struct)
* The main <code>AtlasScientific</code> struct acts as the context. It holds a <code>HashMap<AquariumSignal</code>, <code>Box<dyn AtlasScientificDriver>></code>.
* Factory Logic: The <code>create_drivers</code> method functions as a factory. It reads the <code>aquarium_control.toml</code> configuration (specifically fields like <code>sensor_type_ph = "oem"</code> or <code>"ezo"</code>) and
instantiates the correct driver implementation for each sensor (temperature, pH, conductivity).
* Execution: The main thread loop calls <code>driver.send_request...</code> and <code>driver.receive_response...</code> on the active driver, unaware of whether it is communicating via binary registers or ASCII commands.

Communication Flow

The architecture decouples protocol logic from bus I/O:
# Driver creates an abstraction-specific <code>I2cRequest</code> (containing address, write buffer, read length, delay).
# <code>AtlasScientific</code> thread sends this request via a channel to the <code>I2cInterface</code> thread.
# <code>I2cInterface</code> thread performs the physical I2C transaction.
# <code>AtlasScientific</code> thread receives the raw bytes and passes them back to the driver for parsing.
# Additionally, <code>AtlasScientific</code> performs measurement value checks informing deviations to <code>Monitors</code>.

This design enables the system to mix and match sensor types (e.g., an OEM type pH sensor circuit with an EZO type temperature sensor circuit) purely through configuration changes.

= Monitors =
The Monitors module (<code>src/watchmen/monitors.rs</code>) is a dedicated thread that aggregates and stores historical system state information.
It interacts with the following modules:
* Refill
* Signal handler

The Monitors thread receives data from the other thread by polling the channels.

The data is transferred in specific structs ("Views"), e.g. <code>RefillView</code>.

<code>Monitors</code> contains a deduplication logic: Data is only stored when it differs from previous sample.

The number of samples is also limited (rolling window), to avoid overflow.

= Commissioning =
For the [[commissioning software|commissioning of the aquarium control]], there is a separate binary which resides in <code>src/bin/commissioning.rs</code>.

Control application

2026-01-30T18:16:39Z

Uwe: /* Threads */

The main control application of Aquarium control implements the following features:

* [[Data acquisition of water temperature, pH and conductivity]]
* [[Data acquisition of ambient temperature and humidity]]
* [[Fresh water refill control|Refill control for fresh water]]
* Feed control
* Water temperature control using air ventilation and heater
* Balling mineral dosing

The control of the relays for operating the devices can use two different modes:
* [[Arduino-based relay actuation|Using an Arduino-based relay actuation]]
* Using the GPIO of the Raspberry Pi (requires additional hardware)

Additionally, the main control application implements the following supporting features:
* [[Version comparison between database and application]]
* Configuration using a Rust .toml configuration file
* Logging
* Command interface to receive instructions from outside of the application via a POSIX message queue
* Storage of recorded data in SQL database
* File-based communication to RAM-disk
* Usage of simulator to run with simulated sensor data for development purposes
* Schedule checks to limit the hour of day of operating certain actuators
* [[Communication with HW Watchdog]]
* [[Temperature gradient calculation]]
The application is written in Rust and is [[automatic start by using systemd| automatically started using systemd]].

The documentation of the software is available [http://vps2483992.servdiscount-customer.com/aquarium_control_doc/aquarium_control/ here].

Development for the main control application requires the [[setup of the development environment]].

There is a [[Release procedure|release procedure]] which is highly recommended to be followed also by anyone developing the SW further.

= Architecture =
== Startup of the application ==
The startup uses a two-layer approach:
# main() - Simple error handler wrapper that calls run() and exits with code 1 on errors
# run() - The actual initialization orchestrator that performs the major steps

=== Phase 1: Command Line & Configuration ===
* Parses command line arguments ("help", "version", config file)
* Sets the default config file: <code>/etc/aquarium_control/aquarium_control.toml</code>
* Loads configuration and creates <code>ExecutionConfig</code> (boolean flags determining which modules to run)

=== Phase 2: System Setup ===
* Initializes the logging system
* Logs version information and executable hash
* Verifies root privileges (required for hardware access)
* Publishes process ID to file for client communication

=== Phase 3: Database & Hardware ===
* Connects to database (MariaDB)
* Creates component-specific SQL interfaces (<code>Schedule</code>, <code>Balling</code>, <code>Refill</code>, <code>Heating</code>, <code>Feed</code>, <code>Data</code>)
* Validates database schema and version compatibility
* Initializes hardware components if configured:
** RGB LEDs
** GPIO handlers
** Tank level switch
** I2C interface
** Atlas Scientific sensors
** DHT temperature/humidity sensors
** Relay actuator (Controllino)

=== Phase 4: Communication Channels ===
* Creates the <code>Channels</code> struct containing ~30+ inter-thread communication channels
* Uses custom <code>AquaSender</code>/<code>AquaReceiver</code> wrappers for MPSC channels
* Establishes bidirectional and unidirectional message paths between all modules

=== Phase 5: Component Initialization ===
Instantiates all high-level control components:
* data logger
* sensor manager
* relay manager
* food injection
* mineral dosing (balling)
* water injection/refill
* heating control
* ventilation control
* monitors
* watchdog
* schedule checker
* temperature gradient calculation
* IPC messaging system

=== Phase 6: Thread Spawning ===
* Uses <code>std::thread::scope</code> for guaranteed cleanup
* Spawns threads conditionally based on <code>ExecutionConfig</code> flags
* Critical: A 3-second startup delay allows sensors to acquire first data before control loops activate

=== Architecture of thread configuration ===
* The <code>Channels</code> module (<code>src/launch/channels.rs</code>) acts as a central wiring diagram, with the Signal Handler serving as the main event coordinator.
* The <code>ExecutionConfig</code> decouples configuration from execution - threads only receive flags about which modules are active, not the full config - this also avoids ownership issues.

== Threads ==
The application spawns the following threads:
{| class="wikitable" style="margin:auto"
|+ Overview of threads
|-
! Thread name !! Purpose
|-
| signal_handler || Receiving signals from the operating system
|-
| schedule_check || Polling the database to capture changes of the actuator channel. Informing other threads about it.
|-
| sensor_manager || Data acquisition
|-
| relay_manager || Actuation of relays
|-
| data_logger || Recording of data
|-
| tank_level_switch || Postprocessing of tank level switch position signal
|-
| refill || Fresh water refill control
|-
| heating || Heating control
|-
| ventilation || Ventilation control
|-
| balling || Balling mineral dosing control
|-
| watchdog || Sending alive signal to Raspberry Pi hardware watchdog
|-
| monitors || Diagnostics (not implemented as of January, 2026)
|-
| messaging || Receiving communication via message queue
|-
| memory || Monitoring memory utilization
|-
| ds18b20 || Recording data from DS18B20 temperature sensor
|-
| feed || Feed control
|-
| i2c_interface || Communication via I2C
|-
| atlas_scientific || Recording data from Atlas Scientific temperature sensor
|-
| dht || Recording data from DHT sensor
|-
| publish_pid || Writing PID to lock file
|-
| temperature_gradient || [[Temperature Gradient Calculation]]

|}

= Measurement using Atlas Scientific circuits =
The core Abstraction (<code>AtlasScientificDriver</code> Trait) is defined in <code>src/sensors/atlas_scientific_driver.rs</code>, this trait serves as the common interface for all sensor types. It enforces three key behaviors:
* <code>send_request_to_i2c_interface</code>: Encapsulates how to trigger a measurement (e.g., constructing specific I2C commands).
* <code>receive_response_from_i2c_interface</code>: Handles parsing the raw byte response from the I2C bus into a normalized floating-point value.
* <code>device_init</code>: Performs hardware-specific setup (crucial for OEM type sensor circuit).

Circuit-type-specific implementations
* OEM Driver (<code>AtlasScientificOem</code>):
** Protocol: Uses a binary, register-based protocol.
** Initialization: Requires an explicit "Wake Up" command (writing to <code>REG_WAKEUP</code>) and verifies the hardware by reading the <code>REG_DEVICE_TYPE</code>.
** Read Cycle: Writes a register address (e.g., <code>REG_DATA_MSB_PH</code>), waits for a short processing time, and reads 4 bytes.
** Parsing: Decodes the 4-byte response as a Big Endian unsigned integer and divides it by a specific scale factor (e.g., 1000.0) to get the float value.
* EZO Driver (<code>AtlasScientificEzo</code>):
** Protocol: Uses a text-based (ASCII) command protocol.
** Initialization: Minimal or no-op (these devices are typically always ready or auto-on).
** Read Cycle: Sends the ASCII character 'R', waits for a longer processing time, and reads a fixed 8-byte response.
** Parsing: Validates "magic" start/end bytes (1 and 0), converts the inner ASCII string (e.g., "23.50") to a float.

Context and factory (<code>AtlasScientific</code> struct)
* The main <code>AtlasScientific</code> struct acts as the context. It holds a <code>HashMap<AquariumSignal</code>, <code>Box<dyn AtlasScientificDriver>></code>.
* Factory Logic: The <code>create_drivers</code> method functions as a factory. It reads the <code>aquarium_control.toml</code> configuration (specifically fields like <code>sensor_type_ph = "oem"</code> or <code>"ezo"</code>) and
instantiates the correct driver implementation for each sensor (temperature, pH, conductivity).
* Execution: The main thread loop calls <code>driver.send_request...</code> and <code>driver.receive_response...</code> on the active driver, unaware of whether it is communicating via binary registers or ASCII commands.

Communication Flow

The architecture decouples protocol logic from bus I/O:
# Driver creates an abstraction-specific <code>I2cRequest</code> (containing address, write buffer, read length, delay).
# <code>AtlasScientific</code> thread sends this request via a channel to the <code>I2cInterface</code> thread.
# <code>I2cInterface</code> thread performs the physical I2C transaction.
# <code>AtlasScientific</code> thread receives the raw bytes and passes them back to the driver for parsing.
# Additionally, <code>AtlasScientific</code> performs measurement value checks informing deviations to <code>Monitors</code>.

This design enables the system to mix and match sensor types (e.g., an OEM type pH sensor circuit with an EZO type temperature sensor circuit) purely through configuration changes.

= Monitors =
The Monitors module (<code>src/watchmen/monitors.rs</code>) is a dedicated thread that aggregates and stores historical system state information.
It interacts with the following modules:
* Refill
* Signal handler

The Monitors thread receives data from the other thread by polling the channels.

The data is transferred in specific structs ("Views"), e.g. <code>RefillView</code>.

<code>Monitors</code> contains a deduplication logic: Data is only stored when it differs from previous sample.

The number of samples is also limited (rolling window), to avoid overflow.

= Commissioning =
For the [[commissioning software|commissioning of the aquarium control]], there is a separate binary which resides in <code>src/bin/commissioning.rs</code>.

Control application

2026-01-30T18:15:54Z

Uwe: /* Phase 5: Component Initialization */

The main control application of Aquarium control implements the following features:

* [[Data acquisition of water temperature, pH and conductivity]]
* [[Data acquisition of ambient temperature and humidity]]
* [[Fresh water refill control|Refill control for fresh water]]
* Feed control
* Water temperature control using air ventilation and heater
* Balling mineral dosing

The control of the relays for operating the devices can use two different modes:
* [[Arduino-based relay actuation|Using an Arduino-based relay actuation]]
* Using the GPIO of the Raspberry Pi (requires additional hardware)

Additionally, the main control application implements the following supporting features:
* [[Version comparison between database and application]]
* Configuration using a Rust .toml configuration file
* Logging
* Command interface to receive instructions from outside of the application via a POSIX message queue
* Storage of recorded data in SQL database
* File-based communication to RAM-disk
* Usage of simulator to run with simulated sensor data for development purposes
* Schedule checks to limit the hour of day of operating certain actuators
* [[Communication with HW Watchdog]]
* [[Temperature gradient calculation]]
The application is written in Rust and is [[automatic start by using systemd| automatically started using systemd]].

The documentation of the software is available [http://vps2483992.servdiscount-customer.com/aquarium_control_doc/aquarium_control/ here].

Development for the main control application requires the [[setup of the development environment]].

There is a [[Release procedure|release procedure]] which is highly recommended to be followed also by anyone developing the SW further.

= Architecture =
== Startup of the application ==
The startup uses a two-layer approach:
# main() - Simple error handler wrapper that calls run() and exits with code 1 on errors
# run() - The actual initialization orchestrator that performs the major steps

=== Phase 1: Command Line & Configuration ===
* Parses command line arguments ("help", "version", config file)
* Sets the default config file: <code>/etc/aquarium_control/aquarium_control.toml</code>
* Loads configuration and creates <code>ExecutionConfig</code> (boolean flags determining which modules to run)

=== Phase 2: System Setup ===
* Initializes the logging system
* Logs version information and executable hash
* Verifies root privileges (required for hardware access)
* Publishes process ID to file for client communication

=== Phase 3: Database & Hardware ===
* Connects to database (MariaDB)
* Creates component-specific SQL interfaces (<code>Schedule</code>, <code>Balling</code>, <code>Refill</code>, <code>Heating</code>, <code>Feed</code>, <code>Data</code>)
* Validates database schema and version compatibility
* Initializes hardware components if configured:
** RGB LEDs
** GPIO handlers
** Tank level switch
** I2C interface
** Atlas Scientific sensors
** DHT temperature/humidity sensors
** Relay actuator (Controllino)

=== Phase 4: Communication Channels ===
* Creates the <code>Channels</code> struct containing ~30+ inter-thread communication channels
* Uses custom <code>AquaSender</code>/<code>AquaReceiver</code> wrappers for MPSC channels
* Establishes bidirectional and unidirectional message paths between all modules

=== Phase 5: Component Initialization ===
Instantiates all high-level control components:
* data logger
* sensor manager
* relay manager
* food injection
* mineral dosing (balling)
* water injection/refill
* heating control
* ventilation control
* monitors
* watchdog
* schedule checker
* temperature gradient calculation
* IPC messaging system

=== Phase 6: Thread Spawning ===
* Uses <code>std::thread::scope</code> for guaranteed cleanup
* Spawns threads conditionally based on <code>ExecutionConfig</code> flags
* Critical: A 3-second startup delay allows sensors to acquire first data before control loops activate

=== Architecture of thread configuration ===
* The <code>Channels</code> module (<code>src/launch/channels.rs</code>) acts as a central wiring diagram, with the Signal Handler serving as the main event coordinator.
* The <code>ExecutionConfig</code> decouples configuration from execution - threads only receive flags about which modules are active, not the full config - this also avoids ownership issues.

== Threads ==
The application spawns the following threads:
{| class="wikitable" style="margin:auto"
|+ Overview of threads
|-
! Thread name !! Purpose
|-
| signal_handler || Receiving signals from the operating system
|-
| schedule_check || Polling the database to capture changes of the actuator channel. Informing other threads about it.
|-
| sensor_manager || Data acquisition
|-
| relay_manager || Actuation of relays
|-
| data_logger || Recording of data
|-
| tank_level_switch || Postprocessing of tank level switch position signal
|-
| refill || Fresh water refill control
|-
| heating || Heating control
|-
| ventilation || Ventilation control
|-
| balling || Balling mineral dosing control
|-
| watchdog || Sending alive signal to Raspberry Pi hardware watchdog
|-
| monitors || Diagnostics (not implemented as of January, 2026)
|-
| messaging || Receiving communication via message queue
|-
| memory || Monitoring memory utilization
|-
| ds18b20 || Recording data from DS18B20 temperature sensor
|-
| feed || Feed control
|-
| i2c_interface || Communication via I2C
|-
| atlas_scientific || Recording data from Atlas Scientific temperature sensor
|-
| dht || Recording data from DHT sensor
|-
| publish_pid || Writing PID to lock file

|}

= Measurement using Atlas Scientific circuits =
The core Abstraction (<code>AtlasScientificDriver</code> Trait) is defined in <code>src/sensors/atlas_scientific_driver.rs</code>, this trait serves as the common interface for all sensor types. It enforces three key behaviors:
* <code>send_request_to_i2c_interface</code>: Encapsulates how to trigger a measurement (e.g., constructing specific I2C commands).
* <code>receive_response_from_i2c_interface</code>: Handles parsing the raw byte response from the I2C bus into a normalized floating-point value.
* <code>device_init</code>: Performs hardware-specific setup (crucial for OEM type sensor circuit).

Circuit-type-specific implementations
* OEM Driver (<code>AtlasScientificOem</code>):
** Protocol: Uses a binary, register-based protocol.
** Initialization: Requires an explicit "Wake Up" command (writing to <code>REG_WAKEUP</code>) and verifies the hardware by reading the <code>REG_DEVICE_TYPE</code>.
** Read Cycle: Writes a register address (e.g., <code>REG_DATA_MSB_PH</code>), waits for a short processing time, and reads 4 bytes.
** Parsing: Decodes the 4-byte response as a Big Endian unsigned integer and divides it by a specific scale factor (e.g., 1000.0) to get the float value.
* EZO Driver (<code>AtlasScientificEzo</code>):
** Protocol: Uses a text-based (ASCII) command protocol.
** Initialization: Minimal or no-op (these devices are typically always ready or auto-on).
** Read Cycle: Sends the ASCII character 'R', waits for a longer processing time, and reads a fixed 8-byte response.
** Parsing: Validates "magic" start/end bytes (1 and 0), converts the inner ASCII string (e.g., "23.50") to a float.

Context and factory (<code>AtlasScientific</code> struct)
* The main <code>AtlasScientific</code> struct acts as the context. It holds a <code>HashMap<AquariumSignal</code>, <code>Box<dyn AtlasScientificDriver>></code>.
* Factory Logic: The <code>create_drivers</code> method functions as a factory. It reads the <code>aquarium_control.toml</code> configuration (specifically fields like <code>sensor_type_ph = "oem"</code> or <code>"ezo"</code>) and
instantiates the correct driver implementation for each sensor (temperature, pH, conductivity).
* Execution: The main thread loop calls <code>driver.send_request...</code> and <code>driver.receive_response...</code> on the active driver, unaware of whether it is communicating via binary registers or ASCII commands.

Communication Flow

The architecture decouples protocol logic from bus I/O:
# Driver creates an abstraction-specific <code>I2cRequest</code> (containing address, write buffer, read length, delay).
# <code>AtlasScientific</code> thread sends this request via a channel to the <code>I2cInterface</code> thread.
# <code>I2cInterface</code> thread performs the physical I2C transaction.
# <code>AtlasScientific</code> thread receives the raw bytes and passes them back to the driver for parsing.
# Additionally, <code>AtlasScientific</code> performs measurement value checks informing deviations to <code>Monitors</code>.

This design enables the system to mix and match sensor types (e.g., an OEM type pH sensor circuit with an EZO type temperature sensor circuit) purely through configuration changes.

= Monitors =
The Monitors module (<code>src/watchmen/monitors.rs</code>) is a dedicated thread that aggregates and stores historical system state information.
It interacts with the following modules:
* Refill
* Signal handler

The Monitors thread receives data from the other thread by polling the channels.

The data is transferred in specific structs ("Views"), e.g. <code>RefillView</code>.

<code>Monitors</code> contains a deduplication logic: Data is only stored when it differs from previous sample.

The number of samples is also limited (rolling window), to avoid overflow.

= Commissioning =
For the [[commissioning software|commissioning of the aquarium control]], there is a separate binary which resides in <code>src/bin/commissioning.rs</code>.

Temperature gradient calculation

2026-01-30T18:14:12Z

Uwe: Created page with "= Temperature Gradient Calculation = The **Temperature Gradient Calculation** module in the Aquarium Control system is responsible for determining the rate of change of the water temperature over time. By calculating the slope (gradient) of the temperature curve, the system can identify trends—such as heating up, cooling down, or stable conditions—more effectively than by looking at instantaneous values alone. This data serves as basis for more sophisticated diagnos..."

= Temperature Gradient Calculation =

The **Temperature Gradient Calculation** module in the Aquarium Control system is responsible for determining the rate of change of the water temperature over time. By calculating the slope (gradient) of the temperature curve, the system can identify trends—such as heating up, cooling down, or stable conditions—more effectively than by looking at instantaneous values alone. This data serves as basis for more sophisticated diagnostics.

== Overview ==

The primary purpose of this module is to provide a reliable trend indicator for the thermal control logic. It helps in:
* **Verifying Actuator Effectiveness**: Confirming that the heater is actually raising the temperature or that the fans are cooling it down.
* **Anomaly Detection**: Identifying rapid temperature spikes or drops that might indicate sensor failure or equipment malfunction.
* **Predictive Control**: Allowing control loops to react to the ''direction'' of the temperature change: Providing the basis for PID-control, potentially reducing overshoot - this feature is currently not planned for implementation.

== Algorithm ==

The module employs a **Least Squares Linear Regression** algorithm on a sliding window of historical data points to calculate the gradient. This method is chosen to smooth out sensor noise and quantization errors.

=== Process ===
# **Sampling**: The module performs measurement calculation at a configured `sampling_interval`.
# **Data Acquisition**: It retrieves the current water temperature from the central `SensorManager` and captures the current timestamp.
# **Storage**: The data point $(t, T)$ is pushed into a First-In-First-Out (FIFO) buffer (sliding window).
# **Window Management**: If the buffer exceeds the configured `sample_size`, the oldest data point is removed.
# **Calculation**: Once the buffer is full, the gradient $m$ is calculated using the formula:
#:<math>m = \frac{N \sum(xy) - \sum x \sum y}{N \sum x^2 - (\sum x)^2}</math>
#:Where:
#:* $N$ is the number of samples.
#:* $x$ is the time in seconds (normalized relative to the oldest sample to preserve floating-point precision).
#:* $y$ is the temperature in degrees Celsius.
# **Output**: The resulting slope $m$ (representing °C/second) is updated in a shared memory location protected by a Mutex.

== Configuration ==

The behavior of the gradient calculation is defined in the application's TOML configuration file (typically `/etc/aquarium_control/aquarium_control.toml`) under the `[temperature_gradient]` section.

{| class="wikitable"
! Parameter !! Type !! Description !! Constraints
|-
| `active` || Boolean || Master switch to enable or disable the calculation logic. || `true` / `false`
|-
| `execute` || Boolean || Determines if the thread should be spawned (primarily for testing). || `true` / `false`
|-
| `sampling_interval` || Integer || The time duration (in seconds) between two consecutive temperature samples. || Must be > 0.
|-
| `sample_size` || Integer || The number of historical data points to keep in the sliding window for regression. || Must be between 2 and 100.
|}

=== Example Configuration ===
<syntaxhighlight lang="toml">
[temperature_gradient]
active = true
execute = true
sampling_interval = 10 # Take a sample every 10 seconds
sample_size = 20 # Calculate trend based on the last 20 samples (200 seconds window)
</syntaxhighlight>

== Architecture and Integration ==

The Temperature Gradient module is implemented as a standalone thread that runs concurrently with other system components.

=== Dependencies ===
* **Input**: It consumes data from the `SensorManager`. Specifically, it reads the `water_temperature` field from the shared `SensorManagerSignals` structure.
* **Output**: It writes the calculated gradient (`f64`) to a shared `Arc<Mutex<f64>>`, which can be read by other components (e.g., logging or safety checks).
* **Lifecycle**: It is managed by the `SignalHandler`. It listens for `Quit` or `Terminate` commands via a dedicated channel to ensure graceful shutdown.

=== Thread Communication ===
The module uses Rust's `mpsc` (multi-producer, single-consumer) channels for control signals and `Arc<Mutex<...>>` for data sharing.

{{Graph:Mermaid|
graph LR
SensorManager[SensorManager] -.->|Reads Temp| TempGradient[TemperatureGradient]
TempGradient -->|Updates Gradient| SharedState[Mutex<f64>]
SignalHandler[SignalHandler] -->|Control Signals| TempGradient
TempGradient -->|Acknowledge| SignalHandler
}}

== Error Handling ==

The module defines specific error types in `TemperatureGradientError` to handle initialization failures:
* **InvalidSamplingInterval**: Raised if the interval is set to 0.
* **InvalidSampleSize**: Raised if the sample size is outside the allowed range (2-100).

During runtime, the module includes logic to prevent log flooding. If it fails to acquire a lock on the sensor data or the output mutex, it logs the error once and inhibits further identical error logs until a successful operation occurs.

Control application

2026-01-30T18:09:27Z

Uwe:

The main control application of Aquarium control implements the following features:

* [[Data acquisition of water temperature, pH and conductivity]]
* [[Data acquisition of ambient temperature and humidity]]
* [[Fresh water refill control|Refill control for fresh water]]
* Feed control
* Water temperature control using air ventilation and heater
* Balling mineral dosing

The control of the relays for operating the devices can use two different modes:
* [[Arduino-based relay actuation|Using an Arduino-based relay actuation]]
* Using the GPIO of the Raspberry Pi (requires additional hardware)

Additionally, the main control application implements the following supporting features:
* [[Version comparison between database and application]]
* Configuration using a Rust .toml configuration file
* Logging
* Command interface to receive instructions from outside of the application via a POSIX message queue
* Storage of recorded data in SQL database
* File-based communication to RAM-disk
* Usage of simulator to run with simulated sensor data for development purposes
* Schedule checks to limit the hour of day of operating certain actuators
* [[Communication with HW Watchdog]]
* [[Temperature gradient calculation]]
The application is written in Rust and is [[automatic start by using systemd| automatically started using systemd]].

The documentation of the software is available [http://vps2483992.servdiscount-customer.com/aquarium_control_doc/aquarium_control/ here].

Development for the main control application requires the [[setup of the development environment]].

There is a [[Release procedure|release procedure]] which is highly recommended to be followed also by anyone developing the SW further.

= Architecture =
== Startup of the application ==
The startup uses a two-layer approach:
# main() - Simple error handler wrapper that calls run() and exits with code 1 on errors
# run() - The actual initialization orchestrator that performs the major steps

=== Phase 1: Command Line & Configuration ===
* Parses command line arguments ("help", "version", config file)
* Sets the default config file: <code>/etc/aquarium_control/aquarium_control.toml</code>
* Loads configuration and creates <code>ExecutionConfig</code> (boolean flags determining which modules to run)

=== Phase 2: System Setup ===
* Initializes the logging system
* Logs version information and executable hash
* Verifies root privileges (required for hardware access)
* Publishes process ID to file for client communication

=== Phase 3: Database & Hardware ===
* Connects to database (MariaDB)
* Creates component-specific SQL interfaces (<code>Schedule</code>, <code>Balling</code>, <code>Refill</code>, <code>Heating</code>, <code>Feed</code>, <code>Data</code>)
* Validates database schema and version compatibility
* Initializes hardware components if configured:
** RGB LEDs
** GPIO handlers
** Tank level switch
** I2C interface
** Atlas Scientific sensors
** DHT temperature/humidity sensors
** Relay actuator (Controllino)

=== Phase 4: Communication Channels ===
* Creates the <code>Channels</code> struct containing ~30+ inter-thread communication channels
* Uses custom <code>AquaSender</code>/<code>AquaReceiver</code> wrappers for MPSC channels
* Establishes bidirectional and unidirectional message paths between all modules

=== Phase 5: Component Initialization ===
Instantiates all high-level control components:
* data logger
* sensor manager
* relay manager
* food injection
* mineral dosing (balling)
* water injection/refill
* heating control
* ventilation control
* monitors
* watchdog
* schedule checker
* IPC messaging system

=== Phase 6: Thread Spawning ===
* Uses <code>std::thread::scope</code> for guaranteed cleanup
* Spawns threads conditionally based on <code>ExecutionConfig</code> flags
* Critical: A 3-second startup delay allows sensors to acquire first data before control loops activate

=== Architecture of thread configuration ===
* The <code>Channels</code> module (<code>src/launch/channels.rs</code>) acts as a central wiring diagram, with the Signal Handler serving as the main event coordinator.
* The <code>ExecutionConfig</code> decouples configuration from execution - threads only receive flags about which modules are active, not the full config - this also avoids ownership issues.

== Threads ==
The application spawns the following threads:
{| class="wikitable" style="margin:auto"
|+ Overview of threads
|-
! Thread name !! Purpose
|-
| signal_handler || Receiving signals from the operating system
|-
| schedule_check || Polling the database to capture changes of the actuator channel. Informing other threads about it.
|-
| sensor_manager || Data acquisition
|-
| relay_manager || Actuation of relays
|-
| data_logger || Recording of data
|-
| tank_level_switch || Postprocessing of tank level switch position signal
|-
| refill || Fresh water refill control
|-
| heating || Heating control
|-
| ventilation || Ventilation control
|-
| balling || Balling mineral dosing control
|-
| watchdog || Sending alive signal to Raspberry Pi hardware watchdog
|-
| monitors || Diagnostics (not implemented as of January, 2026)
|-
| messaging || Receiving communication via message queue
|-
| memory || Monitoring memory utilization
|-
| ds18b20 || Recording data from DS18B20 temperature sensor
|-
| feed || Feed control
|-
| i2c_interface || Communication via I2C
|-
| atlas_scientific || Recording data from Atlas Scientific temperature sensor
|-
| dht || Recording data from DHT sensor
|-
| publish_pid || Writing PID to lock file

|}

= Measurement using Atlas Scientific circuits =
The core Abstraction (<code>AtlasScientificDriver</code> Trait) is defined in <code>src/sensors/atlas_scientific_driver.rs</code>, this trait serves as the common interface for all sensor types. It enforces three key behaviors:
* <code>send_request_to_i2c_interface</code>: Encapsulates how to trigger a measurement (e.g., constructing specific I2C commands).
* <code>receive_response_from_i2c_interface</code>: Handles parsing the raw byte response from the I2C bus into a normalized floating-point value.
* <code>device_init</code>: Performs hardware-specific setup (crucial for OEM type sensor circuit).

Circuit-type-specific implementations
* OEM Driver (<code>AtlasScientificOem</code>):
** Protocol: Uses a binary, register-based protocol.
** Initialization: Requires an explicit "Wake Up" command (writing to <code>REG_WAKEUP</code>) and verifies the hardware by reading the <code>REG_DEVICE_TYPE</code>.
** Read Cycle: Writes a register address (e.g., <code>REG_DATA_MSB_PH</code>), waits for a short processing time, and reads 4 bytes.
** Parsing: Decodes the 4-byte response as a Big Endian unsigned integer and divides it by a specific scale factor (e.g., 1000.0) to get the float value.
* EZO Driver (<code>AtlasScientificEzo</code>):
** Protocol: Uses a text-based (ASCII) command protocol.
** Initialization: Minimal or no-op (these devices are typically always ready or auto-on).
** Read Cycle: Sends the ASCII character 'R', waits for a longer processing time, and reads a fixed 8-byte response.
** Parsing: Validates "magic" start/end bytes (1 and 0), converts the inner ASCII string (e.g., "23.50") to a float.

Context and factory (<code>AtlasScientific</code> struct)
* The main <code>AtlasScientific</code> struct acts as the context. It holds a <code>HashMap<AquariumSignal</code>, <code>Box<dyn AtlasScientificDriver>></code>.
* Factory Logic: The <code>create_drivers</code> method functions as a factory. It reads the <code>aquarium_control.toml</code> configuration (specifically fields like <code>sensor_type_ph = "oem"</code> or <code>"ezo"</code>) and
instantiates the correct driver implementation for each sensor (temperature, pH, conductivity).
* Execution: The main thread loop calls <code>driver.send_request...</code> and <code>driver.receive_response...</code> on the active driver, unaware of whether it is communicating via binary registers or ASCII commands.

Communication Flow

The architecture decouples protocol logic from bus I/O:
# Driver creates an abstraction-specific <code>I2cRequest</code> (containing address, write buffer, read length, delay).
# <code>AtlasScientific</code> thread sends this request via a channel to the <code>I2cInterface</code> thread.
# <code>I2cInterface</code> thread performs the physical I2C transaction.
# <code>AtlasScientific</code> thread receives the raw bytes and passes them back to the driver for parsing.
# Additionally, <code>AtlasScientific</code> performs measurement value checks informing deviations to <code>Monitors</code>.

This design enables the system to mix and match sensor types (e.g., an OEM type pH sensor circuit with an EZO type temperature sensor circuit) purely through configuration changes.

= Monitors =
The Monitors module (<code>src/watchmen/monitors.rs</code>) is a dedicated thread that aggregates and stores historical system state information.
It interacts with the following modules:
* Refill
* Signal handler

The Monitors thread receives data from the other thread by polling the channels.

The data is transferred in specific structs ("Views"), e.g. <code>RefillView</code>.

<code>Monitors</code> contains a deduplication logic: Data is only stored when it differs from previous sample.

The number of samples is also limited (rolling window), to avoid overflow.

= Commissioning =
For the [[commissioning software|commissioning of the aquarium control]], there is a separate binary which resides in <code>src/bin/commissioning.rs</code>.

Main Page

2026-01-27T06:43:40Z

Uwe:

This is the Aquarium Control developer documentation.

Aquarium-Control is a control system for salt-water aquariums.

The main features include:
* [[Refill control for fresh water]]
* [[Data acquisition of water temperature, pH and conductivity|Data acquisition of temperature, pH, conductivity]]
* [[Data acquisition of ambient temperature and humidity|Data acquisition of ambient temperature and humidity]]
* Temperature control using ventilation fans and heater
* Automatic feeder
* Balling mineral dosing

The components of the control system are assembled in one [[control cabinet]].

Aquarium-Control consists of the following SW elements:

{| class="wikitable"
|-
!|Repository name
!|Description
!|Programming language
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-android-mobile-app/ AquariumControl Android Mobile App]
|| [[Android application]]
|| Kotlin
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-api AquariumControl API]
|| [[REST API]]
|| php
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-controllino-relay-actuator AquariumControl Controllino Relay Actuator]
|| [[Arduino-based relay actuation]]
|| C
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-database AquariumControl Database]
|| [[SQL database]] using MariaDB
|| SQL
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-ios-mobile-app AquariumControl iOS Mobile App]
|| [https://getapp.cc/app/6480310799 App for Apple mobile devices]
|| Swift
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-main-control AquariumControl Main Control]
|| [[Control application]], [[Terminal client]] and test server
|| Rust
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-webpage AquariumControl Webpage]
|| [[Dynamic Webpage]]
|| Java Script
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-deb AquariumControl Debian package]
|| [[Debian package]]
|| Bash
|-
|}

The control application, the REST API, the webpage and the SQL database are designed to run on a [https://www.raspberrypi.org Raspberry Pi].

Main Page

2026-01-27T06:43:02Z

Uwe:

This is the Aquarium Control developer documentation.

Aquarium-Control is a control system for salt-water aquariums.

The main features include:
* [[Refill control for fresh water]]
* [[Data acquisition of water temperature, pH and conductivity|Data acquisition of temperature, pH, conductivity]]
* [[Data acquisition of ambient temperature and humidity|Data acquisition of ambient temperature and humidity]]
* Temperature control using ventilation fans and heater
* Automatic feeder
* Balling mineral dosing

The components of the control system are assembled in one [[control cabinet]].

Aquarium-Control consists of the following SW elements:

{| class="wikitable"
|-
!|Repository name
!|Description
!|Programming language
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-android-mobile-app/ AquariumControl Android Mobile App]
|| [[Android application]]
|| Kotlin
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-api AquariumControl API]
|| [[REST API]]
|| php
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-controllino-relay-actuator AquariumControl Controllino Relay Actuator]
|| [[Arduino-based relay actuation]]
|| C
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-database AquariumControl Database]
|| [[SQL database]] using MariaDB
|| SQL
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-ios-mobile-app AquariumControl iOS Mobile App]
|| [https://getapp.cc/app/6480310799 App for Apple mobile devices]
|| Swift
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-main-control AquariumControl Main Control]
|| [[Control application]], [[Terminal client] and test server]
|| Rust
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-webpage AquariumControl Webpage]
|| [[Dynamic Webpage]]
|| Java Script
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-deb AquariumControl Debian package]
|| [[Debian package]]
|| Bash
|-
|}

The control application, the REST API, the webpage and the SQL database are designed to run on a [https://www.raspberrypi.org Raspberry Pi].

Main Page

2026-01-27T06:42:20Z

Uwe:

This is the Aquarium Control developer documentation.

Aquarium-Control is a control system for salt-water aquariums.

The main features include:
* [[Refill control for fresh water]]
* [[Data acquisition of water temperature, pH and conductivity|Data acquisition of temperature, pH, conductivity]]
* [[Data acquisition of ambient temperature and humidity|Data acquisition of ambient temperature and humidity]]
* Temperature control using ventilation fans and heater
* Automatic feeder
* Balling mineral dosing

The components of the control system are assembled in one [[control cabinet]].

Aquarium-Control consists of the following SW elements:

{| class="wikitable"
|-
!|Repository name
!|Description
!|Programming language
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-android-mobile-app/ AquariumControl Android Mobile App]
|| [[Android application]]
|| Kotlin
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-api AquariumControl API]
|| [[REST API]]
|| php
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-controllino-relay-actuator AquariumControl Controllino Relay Actuator]
|| [[Arduino-based relay actuation]]
|| C
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-database AquariumControl Database]
|| [[SQL database]] using MariaDB
|| SQL
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-ios-mobile-app AquariumControl iOS Mobile App]
|| [https://getapp.cc/app/6480310799 App for Apple mobile devices]
|| Swift
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-main-control AquariumControl Main Control]
|| [[Control application]] and [[Terminal client]]
|| Rust
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-webpage AquariumControl Webpage]
|| [[Dynamic Webpage]]
|| Java Script
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-deb AquariumControl Debian package]
|| [[Debian package]]
|| Bash
|-
|}

The control application, the REST API, the webpage and the SQL database are designed to run on a [https://www.raspberrypi.org Raspberry Pi].

Main Page

2026-01-17T10:49:28Z

Uwe:

This is the Aquarium Control developer documentation.

Aquarium-Control is a control system for salt-water aquariums.

The main features include:
* [[Refill control for fresh water]]
* [[Data acquisition of water temperature, pH and conductivity|Data acquisition of temperature, pH, conductivity]]
* [[Data acquisition of ambient temperature and humidity|Data acquisition of ambient temperature and humidity]]
* Temperature control using ventilation fans and heater
* Automatic feeder
* Balling mineral dosing

The components of the control system are assembled in one [[control cabinet]].

Aquarium-Control consists of the following SW elements:

{| class="wikitable"
|-
!|Repository name
!|Description
!|Programming language
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-android-mobile-app/ AquariumControl Android Mobile App]
|| [[Android application]]
|| Kotlin
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-api AquariumControl API]
|| [[REST API]]
|| php
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-controllino-relay-actuator AquariumControl Controllino Relay Actuator]
|| [[Arduino-based relay actuation]]
|| C
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-database AquariumControl Database]
|| [[SQL database]] using MariaDB
|| SQL
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-ios-mobile-app AquariumControl iOS Mobile App]
|| [https://getapp.cc/app/6480310799 App for Apple mobile devices]
|| Swift
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-main-control AquariumControl Main Control]
|| [[Control application]] and [[Terminal client]]
|| Rust
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-test-server AquariumControl Test Server]
|| Development tool
|| Rust
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-webpage AquariumControl Webpage]
|| [[Dynamic Webpage]]
|| Java Script
|-
|| [https://bitbucket.org/in-dubio/aquariumcontrol-deb AquariumControl Debian package]
|| [[Debian package]]
|| Bash
|-
|}

The control application, the REST API, the webpage and the SQL database are designed to run on a [https://www.raspberrypi.org Raspberry Pi].

Commissioning software

2026-01-11T16:38:04Z

Uwe:

The commissioning software provides functionality to operate all sensors and actuators without activating the controls.
[[File:commissioning_software.png|thumb|Snapshot of commissioning software]]

Commissioning software

2026-01-11T16:37:18Z

Uwe:

The commissioning software provides functionality to operate all sensors and actuators without activating the controls.
[[File:commissioning_sofware.png|thumb|Snapshot of commissioning software]]

File:Commissioning software.png

2026-01-11T16:35:51Z

Uwe: Snapshot of commissioning software

== Summary ==
Snapshot of commissioning software

Commissioning software

2026-01-11T13:35:38Z

Uwe: Created page with "The commissioning software provides functionality to operate all sensors and actuators without activating the controls."

The commissioning software provides functionality to operate all sensors and actuators without activating the controls.

Control application

2026-01-11T13:34:36Z

Uwe: /* Commissioning */

The main control application of Aquarium control implements the following features:

* [[Data acquisition of water temperature, pH and conductivity]]
* [[Data acquisition of ambient temperature and humidity]]
* [[Fresh water refill control|Refill control for fresh water]]
* Feed control
* Water temperature control using air ventilation and heater
* Balling mineral dosing

The control of the relays for operating the devices can use two different modes:
* [[Arduino-based relay actuation|Using an Arduino-based relay actuation]]
* Using the GPIO of the Raspberry Pi (requires additional hardware)

Additionally, the main control application implements the following supporting features:
* [[Version comparison between database and application]]
* Configuration using a Rust .toml configuration file
* Logging
* Command interface to receive instructions from outside of the application via a POSIX message queue
* Storage of recorded data in SQL database
* File-based communication to RAM-disk
* Usage of simulator to run with simulated sensor data for development purposes
* Schedule checks to limit the hour of day of operating certain actuators
* [[Communication with HW Watchdog]]
The application is written in Rust and is [[automatic start by using systemd| automatically started using systemd]].

The documentation of the software is available [http://vps2483992.servdiscount-customer.com/aquarium_control_doc/aquarium_control/ here].

Development for the main control application requires the [[setup of the development environment]].

There is a [[Release procedure|release procedure]] which is highly recommended to be followed also by anyone developing the SW further.

= Architecture =
== Startup of the application ==
The startup uses a two-layer approach:
# main() - Simple error handler wrapper that calls run() and exits with code 1 on errors
# run() - The actual initialization orchestrator that performs the major steps

=== Phase 1: Command Line & Configuration ===
* Parses command line arguments ("help", "version", config file)
* Sets the default config file: <code>/etc/aquarium_control/aquarium_control.toml</code>
* Loads configuration and creates <code>ExecutionConfig</code> (boolean flags determining which modules to run)

=== Phase 2: System Setup ===
* Initializes the logging system
* Logs version information and executable hash
* Verifies root privileges (required for hardware access)
* Publishes process ID to file for client communication

=== Phase 3: Database & Hardware ===
* Connects to database (MariaDB)
* Creates component-specific SQL interfaces (<code>Schedule</code>, <code>Balling</code>, <code>Refill</code>, <code>Heating</code>, <code>Feed</code>, <code>Data</code>)
* Validates database schema and version compatibility
* Initializes hardware components if configured:
** RGB LEDs
** GPIO handlers
** Tank level switch
** I2C interface
** Atlas Scientific sensors
** DHT temperature/humidity sensors
** Relay actuator (Controllino)

=== Phase 4: Communication Channels ===
* Creates the <code>Channels</code> struct containing ~30+ inter-thread communication channels
* Uses custom <code>AquaSender</code>/<code>AquaReceiver</code> wrappers for MPSC channels
* Establishes bidirectional and unidirectional message paths between all modules

=== Phase 5: Component Initialization ===
Instantiates all high-level control components:
* data logger
* sensor manager
* relay manager
* food injection
* mineral dosing (balling)
* water injection/refill
* heating control
* ventilation control
* monitors
* watchdog
* schedule checker
* IPC messaging system

=== Phase 6: Thread Spawning ===
* Uses <code>std::thread::scope</code> for guaranteed cleanup
* Spawns threads conditionally based on <code>ExecutionConfig</code> flags
* Critical: A 3-second startup delay allows sensors to acquire first data before control loops activate

=== Architecture of thread configuration ===
* The <code>Channels</code> module (<code>src/launch/channels.rs</code>) acts as a central wiring diagram, with the Signal Handler serving as the main event coordinator.
* The <code>ExecutionConfig</code> decouples configuration from execution - threads only receive flags about which modules are active, not the full config - this also avoids ownership issues.

== Threads ==
The application spawns the following threads:
{| class="wikitable" style="margin:auto"
|+ Overview of threads
|-
! Thread name !! Purpose
|-
| signal_handler || Receiving signals from the operating system
|-
| schedule_check || Polling the database to capture changes of the actuator channel. Informing other threads about it.
|-
| sensor_manager || Data acquisition
|-
| relay_manager || Actuation of relays
|-
| data_logger || Recording of data
|-
| tank_level_switch || Postprocessing of tank level switch position signal
|-
| refill || Fresh water refill control
|-
| heating || Heating control
|-
| ventilation || Ventilation control
|-
| balling || Balling mineral dosing control
|-
| watchdog || Sending alive signal to Raspberry Pi hardware watchdog
|-
| monitors || Diagnostics (not implemented as of January, 2026)
|-
| messaging || Receiving communication via message queue
|-
| memory || Monitoring memory utilization
|-
| ds18b20 || Recording data from DS18B20 temperature sensor
|-
| feed || Feed control
|-
| i2c_interface || Communication via I2C
|-
| atlas_scientific || Recording data from Atlas Scientific temperature sensor
|-
| dht || Recording data from DHT sensor
|-
| publish_pid || Writing PID to lock file

|}

= Measurement using Atlas Scientific circuits =
The core Abstraction (<code>AtlasScientificDriver</code> Trait) is defined in <code>src/sensors/atlas_scientific_driver.rs</code>, this trait serves as the common interface for all sensor types. It enforces three key behaviors:
* <code>send_request_to_i2c_interface</code>: Encapsulates how to trigger a measurement (e.g., constructing specific I2C commands).
* <code>receive_response_from_i2c_interface</code>: Handles parsing the raw byte response from the I2C bus into a normalized floating-point value.
* <code>device_init</code>: Performs hardware-specific setup (crucial for OEM type sensor circuit).

Circuit-type-specific implementations
* OEM Driver (<code>AtlasScientificOem</code>):
** Protocol: Uses a binary, register-based protocol.
** Initialization: Requires an explicit "Wake Up" command (writing to <code>REG_WAKEUP</code>) and verifies the hardware by reading the <code>REG_DEVICE_TYPE</code>.
** Read Cycle: Writes a register address (e.g., <code>REG_DATA_MSB_PH</code>), waits for a short processing time, and reads 4 bytes.
** Parsing: Decodes the 4-byte response as a Big Endian unsigned integer and divides it by a specific scale factor (e.g., 1000.0) to get the float value.
* EZO Driver (<code>AtlasScientificEzo</code>):
** Protocol: Uses a text-based (ASCII) command protocol.
** Initialization: Minimal or no-op (these devices are typically always ready or auto-on).
** Read Cycle: Sends the ASCII character 'R', waits for a longer processing time, and reads a fixed 8-byte response.
** Parsing: Validates "magic" start/end bytes (1 and 0), converts the inner ASCII string (e.g., "23.50") to a float.

Context and factory (<code>AtlasScientific</code> struct)
* The main <code>AtlasScientific</code> struct acts as the context. It holds a <code>HashMap<AquariumSignal</code>, <code>Box<dyn AtlasScientificDriver>></code>.
* Factory Logic: The <code>create_drivers</code> method functions as a factory. It reads the <code>aquarium_control.toml</code> configuration (specifically fields like <code>sensor_type_ph = "oem"</code> or <code>"ezo"</code>) and
instantiates the correct driver implementation for each sensor (temperature, pH, conductivity).
* Execution: The main thread loop calls <code>driver.send_request...</code> and <code>driver.receive_response...</code> on the active driver, unaware of whether it is communicating via binary registers or ASCII commands.

Communication Flow

The architecture decouples protocol logic from bus I/O:
# Driver creates an abstraction-specific <code>I2cRequest</code> (containing address, write buffer, read length, delay).
# <code>AtlasScientific</code> thread sends this request via a channel to the <code>I2cInterface</code> thread.
# <code>I2cInterface</code> thread performs the physical I2C transaction.
# <code>AtlasScientific</code> thread receives the raw bytes and passes them back to the driver for parsing.
# Additionally, <code>AtlasScientific</code> performs measurement value checks informing deviations to <code>Monitors</code>.

This design enables the system to mix and match sensor types (e.g., an OEM type pH sensor circuit with an EZO type temperature sensor circuit) purely through configuration changes.

= Monitors =
The Monitors module (<code>src/watchmen/monitors.rs</code>) is a dedicated thread that aggregates and stores historical system state information.
It interacts with the following modules:
* Refill
* Signal handler

The Monitors thread receives data from the other thread by polling the channels.

The data is transferred in specific structs ("Views"), e.g. <code>RefillView</code>.

<code>Monitors</code> contains a deduplication logic: Data is only stored when it differs from previous sample.

The number of samples is also limited (rolling window), to avoid overflow.

= Commissioning =
For the [[commissioning software|commissioning of the aquarium control]], there is a separate binary which resides in <code>src/bin/commissioning.rs</code>.

Control application

2026-01-11T13:34:16Z

Uwe: /* Commissioning */

The main control application of Aquarium control implements the following features:

* [[Data acquisition of water temperature, pH and conductivity]]
* [[Data acquisition of ambient temperature and humidity]]
* [[Fresh water refill control|Refill control for fresh water]]
* Feed control
* Water temperature control using air ventilation and heater
* Balling mineral dosing

The control of the relays for operating the devices can use two different modes:
* [[Arduino-based relay actuation|Using an Arduino-based relay actuation]]
* Using the GPIO of the Raspberry Pi (requires additional hardware)

Additionally, the main control application implements the following supporting features:
* [[Version comparison between database and application]]
* Configuration using a Rust .toml configuration file
* Logging
* Command interface to receive instructions from outside of the application via a POSIX message queue
* Storage of recorded data in SQL database
* File-based communication to RAM-disk
* Usage of simulator to run with simulated sensor data for development purposes
* Schedule checks to limit the hour of day of operating certain actuators
* [[Communication with HW Watchdog]]
The application is written in Rust and is [[automatic start by using systemd| automatically started using systemd]].

The documentation of the software is available [http://vps2483992.servdiscount-customer.com/aquarium_control_doc/aquarium_control/ here].

Development for the main control application requires the [[setup of the development environment]].

There is a [[Release procedure|release procedure]] which is highly recommended to be followed also by anyone developing the SW further.

= Architecture =
== Startup of the application ==
The startup uses a two-layer approach:
# main() - Simple error handler wrapper that calls run() and exits with code 1 on errors
# run() - The actual initialization orchestrator that performs the major steps

=== Phase 1: Command Line & Configuration ===
* Parses command line arguments ("help", "version", config file)
* Sets the default config file: <code>/etc/aquarium_control/aquarium_control.toml</code>
* Loads configuration and creates <code>ExecutionConfig</code> (boolean flags determining which modules to run)

=== Phase 2: System Setup ===
* Initializes the logging system
* Logs version information and executable hash
* Verifies root privileges (required for hardware access)
* Publishes process ID to file for client communication

=== Phase 3: Database & Hardware ===
* Connects to database (MariaDB)
* Creates component-specific SQL interfaces (<code>Schedule</code>, <code>Balling</code>, <code>Refill</code>, <code>Heating</code>, <code>Feed</code>, <code>Data</code>)
* Validates database schema and version compatibility
* Initializes hardware components if configured:
** RGB LEDs
** GPIO handlers
** Tank level switch
** I2C interface
** Atlas Scientific sensors
** DHT temperature/humidity sensors
** Relay actuator (Controllino)

=== Phase 4: Communication Channels ===
* Creates the <code>Channels</code> struct containing ~30+ inter-thread communication channels
* Uses custom <code>AquaSender</code>/<code>AquaReceiver</code> wrappers for MPSC channels
* Establishes bidirectional and unidirectional message paths between all modules

=== Phase 5: Component Initialization ===
Instantiates all high-level control components:
* data logger
* sensor manager
* relay manager
* food injection
* mineral dosing (balling)
* water injection/refill
* heating control
* ventilation control
* monitors
* watchdog
* schedule checker
* IPC messaging system

=== Phase 6: Thread Spawning ===
* Uses <code>std::thread::scope</code> for guaranteed cleanup
* Spawns threads conditionally based on <code>ExecutionConfig</code> flags
* Critical: A 3-second startup delay allows sensors to acquire first data before control loops activate

=== Architecture of thread configuration ===
* The <code>Channels</code> module (<code>src/launch/channels.rs</code>) acts as a central wiring diagram, with the Signal Handler serving as the main event coordinator.
* The <code>ExecutionConfig</code> decouples configuration from execution - threads only receive flags about which modules are active, not the full config - this also avoids ownership issues.

== Threads ==
The application spawns the following threads:
{| class="wikitable" style="margin:auto"
|+ Overview of threads
|-
! Thread name !! Purpose
|-
| signal_handler || Receiving signals from the operating system
|-
| schedule_check || Polling the database to capture changes of the actuator channel. Informing other threads about it.
|-
| sensor_manager || Data acquisition
|-
| relay_manager || Actuation of relays
|-
| data_logger || Recording of data
|-
| tank_level_switch || Postprocessing of tank level switch position signal
|-
| refill || Fresh water refill control
|-
| heating || Heating control
|-
| ventilation || Ventilation control
|-
| balling || Balling mineral dosing control
|-
| watchdog || Sending alive signal to Raspberry Pi hardware watchdog
|-
| monitors || Diagnostics (not implemented as of January, 2026)
|-
| messaging || Receiving communication via message queue
|-
| memory || Monitoring memory utilization
|-
| ds18b20 || Recording data from DS18B20 temperature sensor
|-
| feed || Feed control
|-
| i2c_interface || Communication via I2C
|-
| atlas_scientific || Recording data from Atlas Scientific temperature sensor
|-
| dht || Recording data from DHT sensor
|-
| publish_pid || Writing PID to lock file

|}

= Measurement using Atlas Scientific circuits =
The core Abstraction (<code>AtlasScientificDriver</code> Trait) is defined in <code>src/sensors/atlas_scientific_driver.rs</code>, this trait serves as the common interface for all sensor types. It enforces three key behaviors:
* <code>send_request_to_i2c_interface</code>: Encapsulates how to trigger a measurement (e.g., constructing specific I2C commands).
* <code>receive_response_from_i2c_interface</code>: Handles parsing the raw byte response from the I2C bus into a normalized floating-point value.
* <code>device_init</code>: Performs hardware-specific setup (crucial for OEM type sensor circuit).

Circuit-type-specific implementations
* OEM Driver (<code>AtlasScientificOem</code>):
** Protocol: Uses a binary, register-based protocol.
** Initialization: Requires an explicit "Wake Up" command (writing to <code>REG_WAKEUP</code>) and verifies the hardware by reading the <code>REG_DEVICE_TYPE</code>.
** Read Cycle: Writes a register address (e.g., <code>REG_DATA_MSB_PH</code>), waits for a short processing time, and reads 4 bytes.
** Parsing: Decodes the 4-byte response as a Big Endian unsigned integer and divides it by a specific scale factor (e.g., 1000.0) to get the float value.
* EZO Driver (<code>AtlasScientificEzo</code>):
** Protocol: Uses a text-based (ASCII) command protocol.
** Initialization: Minimal or no-op (these devices are typically always ready or auto-on).
** Read Cycle: Sends the ASCII character 'R', waits for a longer processing time, and reads a fixed 8-byte response.
** Parsing: Validates "magic" start/end bytes (1 and 0), converts the inner ASCII string (e.g., "23.50") to a float.

Context and factory (<code>AtlasScientific</code> struct)
* The main <code>AtlasScientific</code> struct acts as the context. It holds a <code>HashMap<AquariumSignal</code>, <code>Box<dyn AtlasScientificDriver>></code>.
* Factory Logic: The <code>create_drivers</code> method functions as a factory. It reads the <code>aquarium_control.toml</code> configuration (specifically fields like <code>sensor_type_ph = "oem"</code> or <code>"ezo"</code>) and
instantiates the correct driver implementation for each sensor (temperature, pH, conductivity).
* Execution: The main thread loop calls <code>driver.send_request...</code> and <code>driver.receive_response...</code> on the active driver, unaware of whether it is communicating via binary registers or ASCII commands.

Communication Flow

The architecture decouples protocol logic from bus I/O:
# Driver creates an abstraction-specific <code>I2cRequest</code> (containing address, write buffer, read length, delay).
# <code>AtlasScientific</code> thread sends this request via a channel to the <code>I2cInterface</code> thread.
# <code>I2cInterface</code> thread performs the physical I2C transaction.
# <code>AtlasScientific</code> thread receives the raw bytes and passes them back to the driver for parsing.
# Additionally, <code>AtlasScientific</code> performs measurement value checks informing deviations to <code>Monitors</code>.

This design enables the system to mix and match sensor types (e.g., an OEM type pH sensor circuit with an EZO type temperature sensor circuit) purely through configuration changes.

= Monitors =
The Monitors module (<code>src/watchmen/monitors.rs</code>) is a dedicated thread that aggregates and stores historical system state information.
It interacts with the following modules:
* Refill
* Signal handler

The Monitors thread receives data from the other thread by polling the channels.

The data is transferred in specific structs ("Views"), e.g. <code>RefillView</code>.

<code>Monitors</code> contains a deduplication logic: Data is only stored when it differs from previous sample.

The number of samples is also limited (rolling window), to avoid overflow.

= Commissioning =
For the [[commissioning of the aquarium control|commissioning software]], there is a separate binary which resides in <code>src/bin/commissioning.rs</code>.

Control application

2026-01-11T13:34:02Z

Uwe: /* Commissioning */

The main control application of Aquarium control implements the following features:

* [[Data acquisition of water temperature, pH and conductivity]]
* [[Data acquisition of ambient temperature and humidity]]
* [[Fresh water refill control|Refill control for fresh water]]
* Feed control
* Water temperature control using air ventilation and heater
* Balling mineral dosing

The control of the relays for operating the devices can use two different modes:
* [[Arduino-based relay actuation|Using an Arduino-based relay actuation]]
* Using the GPIO of the Raspberry Pi (requires additional hardware)

Additionally, the main control application implements the following supporting features:
* [[Version comparison between database and application]]
* Configuration using a Rust .toml configuration file
* Logging
* Command interface to receive instructions from outside of the application via a POSIX message queue
* Storage of recorded data in SQL database
* File-based communication to RAM-disk
* Usage of simulator to run with simulated sensor data for development purposes
* Schedule checks to limit the hour of day of operating certain actuators
* [[Communication with HW Watchdog]]
The application is written in Rust and is [[automatic start by using systemd| automatically started using systemd]].

The documentation of the software is available [http://vps2483992.servdiscount-customer.com/aquarium_control_doc/aquarium_control/ here].

Development for the main control application requires the [[setup of the development environment]].

There is a [[Release procedure|release procedure]] which is highly recommended to be followed also by anyone developing the SW further.

= Architecture =
== Startup of the application ==
The startup uses a two-layer approach:
# main() - Simple error handler wrapper that calls run() and exits with code 1 on errors
# run() - The actual initialization orchestrator that performs the major steps

=== Phase 1: Command Line & Configuration ===
* Parses command line arguments ("help", "version", config file)
* Sets the default config file: <code>/etc/aquarium_control/aquarium_control.toml</code>
* Loads configuration and creates <code>ExecutionConfig</code> (boolean flags determining which modules to run)

=== Phase 2: System Setup ===
* Initializes the logging system
* Logs version information and executable hash
* Verifies root privileges (required for hardware access)
* Publishes process ID to file for client communication

=== Phase 3: Database & Hardware ===
* Connects to database (MariaDB)
* Creates component-specific SQL interfaces (<code>Schedule</code>, <code>Balling</code>, <code>Refill</code>, <code>Heating</code>, <code>Feed</code>, <code>Data</code>)
* Validates database schema and version compatibility
* Initializes hardware components if configured:
** RGB LEDs
** GPIO handlers
** Tank level switch
** I2C interface
** Atlas Scientific sensors
** DHT temperature/humidity sensors
** Relay actuator (Controllino)

=== Phase 4: Communication Channels ===
* Creates the <code>Channels</code> struct containing ~30+ inter-thread communication channels
* Uses custom <code>AquaSender</code>/<code>AquaReceiver</code> wrappers for MPSC channels
* Establishes bidirectional and unidirectional message paths between all modules

=== Phase 5: Component Initialization ===
Instantiates all high-level control components:
* data logger
* sensor manager
* relay manager
* food injection
* mineral dosing (balling)
* water injection/refill
* heating control
* ventilation control
* monitors
* watchdog
* schedule checker
* IPC messaging system

=== Phase 6: Thread Spawning ===
* Uses <code>std::thread::scope</code> for guaranteed cleanup
* Spawns threads conditionally based on <code>ExecutionConfig</code> flags
* Critical: A 3-second startup delay allows sensors to acquire first data before control loops activate

=== Architecture of thread configuration ===
* The <code>Channels</code> module (<code>src/launch/channels.rs</code>) acts as a central wiring diagram, with the Signal Handler serving as the main event coordinator.
* The <code>ExecutionConfig</code> decouples configuration from execution - threads only receive flags about which modules are active, not the full config - this also avoids ownership issues.

== Threads ==
The application spawns the following threads:
{| class="wikitable" style="margin:auto"
|+ Overview of threads
|-
! Thread name !! Purpose
|-
| signal_handler || Receiving signals from the operating system
|-
| schedule_check || Polling the database to capture changes of the actuator channel. Informing other threads about it.
|-
| sensor_manager || Data acquisition
|-
| relay_manager || Actuation of relays
|-
| data_logger || Recording of data
|-
| tank_level_switch || Postprocessing of tank level switch position signal
|-
| refill || Fresh water refill control
|-
| heating || Heating control
|-
| ventilation || Ventilation control
|-
| balling || Balling mineral dosing control
|-
| watchdog || Sending alive signal to Raspberry Pi hardware watchdog
|-
| monitors || Diagnostics (not implemented as of January, 2026)
|-
| messaging || Receiving communication via message queue
|-
| memory || Monitoring memory utilization
|-
| ds18b20 || Recording data from DS18B20 temperature sensor
|-
| feed || Feed control
|-
| i2c_interface || Communication via I2C
|-
| atlas_scientific || Recording data from Atlas Scientific temperature sensor
|-
| dht || Recording data from DHT sensor
|-
| publish_pid || Writing PID to lock file

|}

= Measurement using Atlas Scientific circuits =
The core Abstraction (<code>AtlasScientificDriver</code> Trait) is defined in <code>src/sensors/atlas_scientific_driver.rs</code>, this trait serves as the common interface for all sensor types. It enforces three key behaviors:
* <code>send_request_to_i2c_interface</code>: Encapsulates how to trigger a measurement (e.g., constructing specific I2C commands).
* <code>receive_response_from_i2c_interface</code>: Handles parsing the raw byte response from the I2C bus into a normalized floating-point value.
* <code>device_init</code>: Performs hardware-specific setup (crucial for OEM type sensor circuit).

Circuit-type-specific implementations
* OEM Driver (<code>AtlasScientificOem</code>):
** Protocol: Uses a binary, register-based protocol.
** Initialization: Requires an explicit "Wake Up" command (writing to <code>REG_WAKEUP</code>) and verifies the hardware by reading the <code>REG_DEVICE_TYPE</code>.
** Read Cycle: Writes a register address (e.g., <code>REG_DATA_MSB_PH</code>), waits for a short processing time, and reads 4 bytes.
** Parsing: Decodes the 4-byte response as a Big Endian unsigned integer and divides it by a specific scale factor (e.g., 1000.0) to get the float value.
* EZO Driver (<code>AtlasScientificEzo</code>):
** Protocol: Uses a text-based (ASCII) command protocol.
** Initialization: Minimal or no-op (these devices are typically always ready or auto-on).
** Read Cycle: Sends the ASCII character 'R', waits for a longer processing time, and reads a fixed 8-byte response.
** Parsing: Validates "magic" start/end bytes (1 and 0), converts the inner ASCII string (e.g., "23.50") to a float.

Context and factory (<code>AtlasScientific</code> struct)
* The main <code>AtlasScientific</code> struct acts as the context. It holds a <code>HashMap<AquariumSignal</code>, <code>Box<dyn AtlasScientificDriver>></code>.
* Factory Logic: The <code>create_drivers</code> method functions as a factory. It reads the <code>aquarium_control.toml</code> configuration (specifically fields like <code>sensor_type_ph = "oem"</code> or <code>"ezo"</code>) and
instantiates the correct driver implementation for each sensor (temperature, pH, conductivity).
* Execution: The main thread loop calls <code>driver.send_request...</code> and <code>driver.receive_response...</code> on the active driver, unaware of whether it is communicating via binary registers or ASCII commands.

Communication Flow

The architecture decouples protocol logic from bus I/O:
# Driver creates an abstraction-specific <code>I2cRequest</code> (containing address, write buffer, read length, delay).
# <code>AtlasScientific</code> thread sends this request via a channel to the <code>I2cInterface</code> thread.
# <code>I2cInterface</code> thread performs the physical I2C transaction.
# <code>AtlasScientific</code> thread receives the raw bytes and passes them back to the driver for parsing.
# Additionally, <code>AtlasScientific</code> performs measurement value checks informing deviations to <code>Monitors</code>.

This design enables the system to mix and match sensor types (e.g., an OEM type pH sensor circuit with an EZO type temperature sensor circuit) purely through configuration changes.

= Monitors =
The Monitors module (<code>src/watchmen/monitors.rs</code>) is a dedicated thread that aggregates and stores historical system state information.
It interacts with the following modules:
* Refill
* Signal handler

The Monitors thread receives data from the other thread by polling the channels.

The data is transferred in specific structs ("Views"), e.g. <code>RefillView</code>.

<code>Monitors</code> contains a deduplication logic: Data is only stored when it differs from previous sample.

The number of samples is also limited (rolling window), to avoid overflow.

= Commissioning =
For the [commissioning of the aquarium control|commissioning software], there is a separate binary which resides in <code>src/bin/commissioning.rs</code>.

Control application

2026-01-11T13:32:27Z

Uwe:

The main control application of Aquarium control implements the following features:

* [[Data acquisition of water temperature, pH and conductivity]]
* [[Data acquisition of ambient temperature and humidity]]
* [[Fresh water refill control|Refill control for fresh water]]
* Feed control
* Water temperature control using air ventilation and heater
* Balling mineral dosing

The control of the relays for operating the devices can use two different modes:
* [[Arduino-based relay actuation|Using an Arduino-based relay actuation]]
* Using the GPIO of the Raspberry Pi (requires additional hardware)

Additionally, the main control application implements the following supporting features:
* [[Version comparison between database and application]]
* Configuration using a Rust .toml configuration file
* Logging
* Command interface to receive instructions from outside of the application via a POSIX message queue
* Storage of recorded data in SQL database
* File-based communication to RAM-disk
* Usage of simulator to run with simulated sensor data for development purposes
* Schedule checks to limit the hour of day of operating certain actuators
* [[Communication with HW Watchdog]]
The application is written in Rust and is [[automatic start by using systemd| automatically started using systemd]].

The documentation of the software is available [http://vps2483992.servdiscount-customer.com/aquarium_control_doc/aquarium_control/ here].

Development for the main control application requires the [[setup of the development environment]].

There is a [[Release procedure|release procedure]] which is highly recommended to be followed also by anyone developing the SW further.

= Architecture =
== Startup of the application ==
The startup uses a two-layer approach:
# main() - Simple error handler wrapper that calls run() and exits with code 1 on errors
# run() - The actual initialization orchestrator that performs the major steps

=== Phase 1: Command Line & Configuration ===
* Parses command line arguments ("help", "version", config file)
* Sets the default config file: <code>/etc/aquarium_control/aquarium_control.toml</code>
* Loads configuration and creates <code>ExecutionConfig</code> (boolean flags determining which modules to run)

=== Phase 2: System Setup ===
* Initializes the logging system
* Logs version information and executable hash
* Verifies root privileges (required for hardware access)
* Publishes process ID to file for client communication

=== Phase 3: Database & Hardware ===
* Connects to database (MariaDB)
* Creates component-specific SQL interfaces (<code>Schedule</code>, <code>Balling</code>, <code>Refill</code>, <code>Heating</code>, <code>Feed</code>, <code>Data</code>)
* Validates database schema and version compatibility
* Initializes hardware components if configured:
** RGB LEDs
** GPIO handlers
** Tank level switch
** I2C interface
** Atlas Scientific sensors
** DHT temperature/humidity sensors
** Relay actuator (Controllino)

=== Phase 4: Communication Channels ===
* Creates the <code>Channels</code> struct containing ~30+ inter-thread communication channels
* Uses custom <code>AquaSender</code>/<code>AquaReceiver</code> wrappers for MPSC channels
* Establishes bidirectional and unidirectional message paths between all modules

=== Phase 5: Component Initialization ===
Instantiates all high-level control components:
* data logger
* sensor manager
* relay manager
* food injection
* mineral dosing (balling)
* water injection/refill
* heating control
* ventilation control
* monitors
* watchdog
* schedule checker
* IPC messaging system

=== Phase 6: Thread Spawning ===
* Uses <code>std::thread::scope</code> for guaranteed cleanup
* Spawns threads conditionally based on <code>ExecutionConfig</code> flags
* Critical: A 3-second startup delay allows sensors to acquire first data before control loops activate

=== Architecture of thread configuration ===
* The <code>Channels</code> module (<code>src/launch/channels.rs</code>) acts as a central wiring diagram, with the Signal Handler serving as the main event coordinator.
* The <code>ExecutionConfig</code> decouples configuration from execution - threads only receive flags about which modules are active, not the full config - this also avoids ownership issues.

== Threads ==
The application spawns the following threads:
{| class="wikitable" style="margin:auto"
|+ Overview of threads
|-
! Thread name !! Purpose
|-
| signal_handler || Receiving signals from the operating system
|-
| schedule_check || Polling the database to capture changes of the actuator channel. Informing other threads about it.
|-
| sensor_manager || Data acquisition
|-
| relay_manager || Actuation of relays
|-
| data_logger || Recording of data
|-
| tank_level_switch || Postprocessing of tank level switch position signal
|-
| refill || Fresh water refill control
|-
| heating || Heating control
|-
| ventilation || Ventilation control
|-
| balling || Balling mineral dosing control
|-
| watchdog || Sending alive signal to Raspberry Pi hardware watchdog
|-
| monitors || Diagnostics (not implemented as of January, 2026)
|-
| messaging || Receiving communication via message queue
|-
| memory || Monitoring memory utilization
|-
| ds18b20 || Recording data from DS18B20 temperature sensor
|-
| feed || Feed control
|-
| i2c_interface || Communication via I2C
|-
| atlas_scientific || Recording data from Atlas Scientific temperature sensor
|-
| dht || Recording data from DHT sensor
|-
| publish_pid || Writing PID to lock file

|}

= Measurement using Atlas Scientific circuits =
The core Abstraction (<code>AtlasScientificDriver</code> Trait) is defined in <code>src/sensors/atlas_scientific_driver.rs</code>, this trait serves as the common interface for all sensor types. It enforces three key behaviors:
* <code>send_request_to_i2c_interface</code>: Encapsulates how to trigger a measurement (e.g., constructing specific I2C commands).
* <code>receive_response_from_i2c_interface</code>: Handles parsing the raw byte response from the I2C bus into a normalized floating-point value.
* <code>device_init</code>: Performs hardware-specific setup (crucial for OEM type sensor circuit).

Circuit-type-specific implementations
* OEM Driver (<code>AtlasScientificOem</code>):
** Protocol: Uses a binary, register-based protocol.
** Initialization: Requires an explicit "Wake Up" command (writing to <code>REG_WAKEUP</code>) and verifies the hardware by reading the <code>REG_DEVICE_TYPE</code>.
** Read Cycle: Writes a register address (e.g., <code>REG_DATA_MSB_PH</code>), waits for a short processing time, and reads 4 bytes.
** Parsing: Decodes the 4-byte response as a Big Endian unsigned integer and divides it by a specific scale factor (e.g., 1000.0) to get the float value.
* EZO Driver (<code>AtlasScientificEzo</code>):
** Protocol: Uses a text-based (ASCII) command protocol.
** Initialization: Minimal or no-op (these devices are typically always ready or auto-on).
** Read Cycle: Sends the ASCII character 'R', waits for a longer processing time, and reads a fixed 8-byte response.
** Parsing: Validates "magic" start/end bytes (1 and 0), converts the inner ASCII string (e.g., "23.50") to a float.

Context and factory (<code>AtlasScientific</code> struct)
* The main <code>AtlasScientific</code> struct acts as the context. It holds a <code>HashMap<AquariumSignal</code>, <code>Box<dyn AtlasScientificDriver>></code>.
* Factory Logic: The <code>create_drivers</code> method functions as a factory. It reads the <code>aquarium_control.toml</code> configuration (specifically fields like <code>sensor_type_ph = "oem"</code> or <code>"ezo"</code>) and
instantiates the correct driver implementation for each sensor (temperature, pH, conductivity).
* Execution: The main thread loop calls <code>driver.send_request...</code> and <code>driver.receive_response...</code> on the active driver, unaware of whether it is communicating via binary registers or ASCII commands.

Communication Flow

The architecture decouples protocol logic from bus I/O:
# Driver creates an abstraction-specific <code>I2cRequest</code> (containing address, write buffer, read length, delay).
# <code>AtlasScientific</code> thread sends this request via a channel to the <code>I2cInterface</code> thread.
# <code>I2cInterface</code> thread performs the physical I2C transaction.
# <code>AtlasScientific</code> thread receives the raw bytes and passes them back to the driver for parsing.
# Additionally, <code>AtlasScientific</code> performs measurement value checks informing deviations to <code>Monitors</code>.

This design enables the system to mix and match sensor types (e.g., an OEM type pH sensor circuit with an EZO type temperature sensor circuit) purely through configuration changes.

= Monitors =
The Monitors module (<code>src/watchmen/monitors.rs</code>) is a dedicated thread that aggregates and stores historical system state information.
It interacts with the following modules:
* Refill
* Signal handler

The Monitors thread receives data from the other thread by polling the channels.

The data is transferred in specific structs ("Views"), e.g. <code>RefillView</code>.

<code>Monitors</code> contains a deduplication logic: Data is only stored when it differs from previous sample.

The number of samples is also limited (rolling window), to avoid overflow.

= Commissioning =
For the commissioning of the aquarium control, there is a separate binary which resides in <code>src/bin/commissioning.rs</code>.

Control cabinet

2026-01-10T09:26:32Z

Uwe: /* Requirements */

The control cabinet includes the following components

* Main control unit (Raspberry Pi)
* Relay actuation unit
* Power supply 12V
* Fuses
* Circuit breaker
* Main switch
* Relays for overvoltage protection
* Sockets for power output to pumps and skimmer

= Requirements =
# The control cabinet shall have the possibility to cut off the connection to the power supply (all wires).
# The control cabinet shall limit the current drawn from the 230V AC power supply.
# The control cabinet shall limit the current drawn by each actuator (all pumps, skimmer, feeder, heater, ventilation fans).
# The control cabinet shall provide manual override switches accessible without opening the cabinet allowing to switch off the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
#* Feeder
# The control cabinet shall provide power sockets for the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
# The control cabinet shall provide signal indicator lamps for the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
# The control cabinet shall provide a pair of rail mount terminals for each 12V DC devices:
#* all Balling mineral dosing pumps
#* fresh-water refill pump
#* ventilation fan #1
#* ventilation fan #2
# The control cabinet shall provide a pair of rail mount terminals for the tank level switch.
# The control cabinet shall provide a pair of rail mount terminals for each of 230V devices that do not use a power socket:
#* feeder
# The control cabinet shall provide 230V AC supply voltage to 12V power supply.
# The control cabinet shall provide 12V DC supply voltage to the sensor processing board of the Raspberry Pi.
#* Note: The sensor processing board transforms the 12V DC to the 5V DC voltage required by the Raspberry Pi.
# The control cabinet shall provide 12V DC supply voltage to the relay actuator (Controllino).
# The control cabinet shall provide 12V DC voltage to the relay inputs of the Controllino.
# The control cabinet shall provide 12V DC voltage from the relay outputs of the Controllino to the fuse of each actuator.
#* Note: The ventilation fans share one relay output but have distinct fuses.
# The control cabinet shall provide 12V DC voltage from the fuse output of each actuator to the rail mount terminal of each actuator.
# The control cabinet shall provide 230V AC supply voltage to the relay inputs of the relay actuator.
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator to the fuse of the heater.
# The control cabinet shall provide 230V AC voltage from the fuse of the heater to the power socket of the heater.
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator to the fuse of the feeder.
# The control cabinet shall provide 230V AC voltage from the fuse of the feeder to the rail mount terminal for the feeder.
# The control cabinet shall provide transient overvoltage protection by means of an additional set of relays (overvoltage protection relay) for each 230V AC pumps:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator for each of the following devices to control terminal of their respective overvoltage protection relay:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall provide voltage from the output of the Controllino to the input of each of the overvoltage protection relays:
# The control cabinet shall provide 230V AC voltage from the overvoltage protection to the respective fuse.
# The control cabinet shall provide 230V AC voltage from the fuse of each of the following devices to their respective power socket:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall connect one USB port of the Raspberry Pi with the USB port of the Controllino.
# The control cabinet shall allow to route all cables (power supply, actuators, sensors) to outside of the cabinet - preferably at the bottom of the cabinet.

Control cabinet

2026-01-09T10:26:49Z

Uwe: /* Requirements */

The control cabinet includes the following components

* Main control unit (Raspberry Pi)
* Relay actuation unit
* Power supply 12V
* Fuses
* Circuit breaker
* Main switch
* Relays for overvoltage protection
* Sockets for power output to pumps and skimmer

= Requirements =
# The control cabinet shall have the possibility to cut off the connection to the power supply (all wires).
# The control cabinet shall limit the current drawn from the 230V AC power supply.
# The control cabinet shall limit the current drawn by each actuator (all pumps, skimmer, feeder, heater, ventilation fans).
# The control cabinet shall provide manual override switches accessible without opening the cabinet allowing to switch off the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
#* Feeder
# The control cabinet shall provide power sockets for the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
# The control cabinet shall provide signal indicator lamps for the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
# The control cabinet shall provide a pair of rail mount terminals for each 12V DC devices:
#* all Balling mineral dosing pumps
#* fresh-water refill pump
#* ventilation fan #1
#* ventilation fan #2
# The control cabinet shall provide a pair of rail mount terminals for the tank level switch.
# The control cabinet shall provide a pair of rail mount terminals for each of 230V devices that do not use a power socket:
#* feeder
# The control cabinet shall provide 230V AC supply voltage to 12V power supply.
# The control cabinet shall provide 12V DC supply voltage to the sensor processing board of the Raspberry Pi.
#* Note: The sensor processing board transforms the 12V DC to the 5V DC voltage required by the Raspberry Pi.
# The control cabinet shall provide 12V DC supply voltage to the relay actuator (Controllino).
# The control cabinet shall provide 12V DC voltage to the relay inputs of the Controllino.
# The control cabinet shall provide 12V DC voltage from the relay outputs of the Controllino to the fuse of each actuator.
#* Note: The ventilation fans share one relay output but have distinct fuses.
# The control cabinet shall provide 12V DC voltage from the fuse output of each actuator to the rail mount terminal of each actuator.
# The control cabinet shall provide 230V AC supply voltage to the relay inputs of the relay actuator.
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator to the fuse of the heater.
# The control cabinet shall provide 230V AC voltage from the fuse of the heater to the power socket of the heater.
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator to the fuse of the feeder.
# The control cabinet shall provide 230V AC voltage from the fuse of the feeder to the rail mount terminal for the feeder.
# The control cabinet shall provide transient overvoltage protection by means of an additional set of relays (overvoltage protection relay) for each 230V AC pumps:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator for each of the following devices to control terminal of their respective overvoltage protection relay:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall provide 230V AC voltage to the input of each of the overvoltage protection relays:
# The control cabinet shall provide 230V AC voltage from the overvoltage protection to the respective fuse.
# The control cabinet shall provide 230V AC voltage from the fuse of each of the following devices to their respective power socket:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall connect one USB port of the Raspberry Pi with the USB port of the Controllino.
# The control cabinet shall allow to route all cables (power supply, actuators, sensors) to outside of the cabinet - preferably at the bottom of the cabinet.

Control cabinet

2026-01-09T10:25:17Z

Uwe: /* Requirements */

The control cabinet includes the following components

* Main control unit (Raspberry Pi)
* Relay actuation unit
* Power supply 12V
* Fuses
* Circuit breaker
* Main switch
* Relays for overvoltage protection
* Sockets for power output to pumps and skimmer

= Requirements =
# The control cabinet shall have the possibility to cut off the connection to the power supply (all wires).
# The control cabinet shall limit the current drawn from the 230V AC power supply.
# The control cabinet shall limit the current drawn by each actuator (all pumps, skimmer, feeder, heater, ventilation fans).
# The control cabinet shall provide switches accessible without opening the cabinet allowing to switch off the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
#* Feeder
# The control cabinet shall provide power sockets for the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
# The control cabinet shall provide signal indicator lamps for the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
# The control cabinet shall provide a pair of rail mount terminals for each 12V DC devices:
#* all Balling mineral dosing pumps
#* fresh-water refill pump
#* ventilation fan #1
#* ventilation fan #2
# The control cabinet shall provide a pair of rail mount terminals for the tank level switch.
# The control cabinet shall provide a pair of rail mount terminals for each of 230V devices that do not use a power socket:
#* feeder
# The control cabinet shall provide 230V AC supply voltage to 12V power supply.
# The control cabinet shall provide 12V DC supply voltage to the sensor processing board of the Raspberry Pi.
#* Note: The sensor processing board transforms the 12V DC to the 5V DC voltage required by the Raspberry Pi.
# The control cabinet shall provide 12V DC supply voltage to the relay actuator (Controllino).
# The control cabinet shall provide 12V DC voltage to the relay inputs of the Controllino.
# The control cabinet shall provide 12V DC voltage from the relay outputs of the Controllino to the fuse of each actuator.
#* Note: The ventilation fans share one relay output but have distinct fuses.
# The control cabinet shall provide 12V DC voltage from the fuse output of each actuator to the rail mount terminal of each actuator.
# The control cabinet shall provide 230V AC supply voltage to the relay inputs of the relay actuator.
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator to the fuse of the heater.
# The control cabinet shall provide 230V AC voltage from the fuse of the heater to the power socket of the heater.
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator to the fuse of the feeder.
# The control cabinet shall provide 230V AC voltage from the fuse of the feeder to the rail mount terminal for the feeder.
# The control cabinet shall provide transient overvoltage protection by means of an additional set of relays (overvoltage protection relay) for each 230V AC pumps:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator for each of the following devices to control terminal of their respective overvoltage protection relay:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall provide 230V AC voltage to the input of each of the overvoltage protection relays:
# The control cabinet shall provide 230V AC voltage from the overvoltage protection to the respective fuse.
# The control cabinet shall provide 230V AC voltage from the fuse of each of the following devices to their respective power socket:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall connect one USB port of the Raspberry Pi with the USB port of the Controllino.
# The control cabinet shall allow to route all cables (power supply, actuators, sensors) to outside of the cabinet - preferably at the bottom of the cabinet.

Control cabinet

2026-01-09T10:22:05Z

Uwe: /* Requirements */

The control cabinet includes the following components

* Main control unit (Raspberry Pi)
* Relay actuation unit
* Power supply 12V
* Fuses
* Circuit breaker
* Main switch
* Relays for overvoltage protection
* Sockets for power output to pumps and skimmer

= Requirements =
# The control cabinet shall have the possibility to cut off the connection to the power supply (all wires).
# The control cabinet shall limit the current drawn from the 230V AC power supply.
# The control cabinet shall limit the current drawn by each actuator (all pumps, skimmer, feeder, heater, ventilation fans).
# The control cabinet shall provide switches accessible without opening the cabinet allowing to switch off the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
#* Feeder
# The control cabinet shall provide power sockets for the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
# The control cabinet shall provide signal indicator lamps for the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
# The control cabinet shall provide a rail mount terminal block for all 12V DC devices:
#* all Balling mineral dosing pumps
#* fresh-water refill pump
#* ventilation fan #1
#* ventilation fan #2
# The control cabinet shall provide a rail mount terminal block for all 230V devices that do not use a power socket:
#* feeder
# The control cabinet shall provide 230V AC supply voltage to 12V power supply.
# The control cabinet shall provide 12V DC supply voltage to the sensor processing board of the Raspberry Pi.
#* Note: The sensor processing board transforms the 12V DC to the 5V DC voltage required by the Raspberry Pi.
# The control cabinet shall provide 12V DC supply voltage to the relay actuator (Controllino).
# The control cabinet shall provide 12V DC voltage to the relay inputs of the Controllino.
# The control cabinet shall provide 12V DC voltage from the relay outputs of the Controllino to the fuse of each actuator.
#* Note: The ventilation fans share one relay output but have distinct fuses.
# The control cabinet shall provide 12V DC voltage from the fuse output of each actuator to the rail mount terminal of each actuator.
# The control cabinet shall provide 230V AC supply voltage to the relay inputs of the relay actuator.
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator to the fuse of the heater.
# The control cabinet shall provide 230V AC voltage from the fuse of the heater to the power socket of the heater.
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator to the fuse of the feeder.
# The control cabinet shall provide 230V AC voltage from the fuse of the feeder to the rail mount terminal for the feeder.
# The control cabinet shall provide transient overvoltage protection by means of an additional set of relays (overvoltage protection relay) for each 230V AC pumps:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator for each of the following devices to control terminal of their respective overvoltage protection relay:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall provide 230V AC voltage to the input of each of the overvoltage protection relays:
# The control cabinet shall provide 230V AC voltage from the overvoltage protection to the respective fuse.
# The control cabinet shall provide 230V AC voltage from the fuse of each of the following devices to their respective power socket:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall connect one USB port of the Raspberry Pi with the USB port of the Controllino.
# The control cabinet shall allow to route all cables (power supply, actuators, sensors) to outside of the cabinet - preferably at the bottom of the cabinet.

Control cabinet

2026-01-09T10:20:57Z

Uwe: /* Requirements */

The control cabinet includes the following components

* Main control unit (Raspberry Pi)
* Relay actuation unit
* Power supply 12V
* Fuses
* Circuit breaker
* Main switch
* Relays for overvoltage protection
* Sockets for power output to pumps and skimmer

= Requirements =
# The control cabinet shall have the possibility to cut off the connection to the power supply (all wires).
# The control cabinet shall limit the current drawn from the 230V AC power supply.
# The control cabinet shall limit the current drawn by each actuator (all pumps, skimmer, feeder, heater, ventilation fans).
# The control cabinet shall provide switches accessible without opening the cabinet allowing to switch off the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
#* Feeder
# The control cabinet shall provide power sockets for the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
# The control cabinet shall provide signal indicator lamps for the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
# The control cabinet shall provide a rail mount terminal block for all 12V DC devices:
#* all Balling mineral dosing pumps
#* fresh-water refill pump
#* ventilation fan #1
#* ventilation fan #2
# The control cabinet shall provide a rail mount terminal block for all 230V devices that do not use a power socket:
#* feeder
# The control cabinet shall provide 230V AC supply voltage to 12V power supply.
# The control cabinet shall provide 12V DC supply voltage to the sensor processing board of the Raspberry Pi.
#* Note: The sensor processing board transforms the 12V DC to the 5V DC voltage required by the Raspberry Pi.
# The control cabinet shall provide 12V DC supply voltage to the relay actuator (Controllino).
# The control cabinet shall provide 12V DC voltage to the relay inputs of the Controllino.
# The control cabinet shall provide 12V DC voltage from the relay outputs of the Controllino to the fuse of each actuator.
#* Note: The ventilation fans share one relay output but have distinct fuses.
# The control cabinet shall provide 12V DC voltage from the fuse output of each actuator to the rail mount terminal of each actuator.
# The control cabinet shall provide 230V AC supply voltage to the relay inputs of the relay actuator.
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator to the fuse of the heater.
# The control cabinet shall provide 230V AC voltage from the fuse of the heater to the power socket of the heater.
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator to the fuse of the feeder.
# The control cabinet shall provide 230V AC voltage from the fuse of the feeder to the rail mount terminal for the feeder.
# The control cabinet shall provide transient overvoltage protection by means of an additional set of relays (overvoltage protection relay) for each 230V AC pumps:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator for each of the following devices to control terminal of their respective overvoltage protection relay:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall provide 230V AC voltage to the input of each of the overvoltage protection relays:
# The control cabinet shall provide 230V AC voltage from the overvoltage protection to the respective fuse.
# The control cabinet shall provide 230V AC voltage from the fuse of each of the following devices to their respective power socket:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall allow to route all cables (power supply, actuators, sensors) to outside of the cabinet - preferably at the bottom of the cabinet.

Control cabinet

2026-01-09T10:12:59Z

Uwe: /* Requirements */

The control cabinet includes the following components

* Main control unit (Raspberry Pi)
* Relay actuation unit
* Power supply 12V
* Fuses
* Circuit breaker
* Main switch
* Relays for overvoltage protection
* Sockets for power output to pumps and skimmer

= Requirements =
# The control cabinet shall have the possibility to cut off the connection to the power supply (all wires).
# The control cabinet shall limit the current drawn from the 230V AC power supply.
# The control cabinet shall limit the current drawn by each actuator (all pumps, skimmer, feeder, heater, ventilation fans).
# The control cabinet shall provide switches accessible without opening the cabinet allowing to switch off the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
#* Feeder
# The control cabinet shall provide power sockets for the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
# The control cabinet shall provide signal indicator lamps for the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
# The control cabinet shall provide a rail mount terminal block for all 12V DC devices:
#* all Balling mineral dosing pumps
#* fresh-water refill pump
#* ventilation fan #1
#* ventilation fan #2
# The control cabinet shall provide a rail mount terminal block for all 230V devices that do not use a power socket:
#* feeder
# The control cabinet shall provide 230V AC supply voltage to 12V power supply.
# The control cabinet shall provide 12V DC supply voltage to the Raspberry Pi.
# The control cabinet shall provide 12V DC supply voltage to the relay actuator (Controllino).
# The control cabinet shall provide 12V DC voltage to the relay inputs of the Controllino.
# The control cabinet shall provide 12V DC voltage from the relay outputs of the Controllino to the fuse of each actuator.
#* Note: The ventilation fans share one relay output but have distinct fuses.
# The control cabinet shall provide 12V DC voltage from the fuse output of each actuator to the rail mount terminal of each actuator.
# The control cabinet shall provide 230V AC supply voltage to the relay inputs of the relay actuator.
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator to the fuse of the heater.
# The control cabinet shall provide 230V AC voltage from the fuse of the heater to the power socket of the heater.
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator to the fuse of the feeder.
# The control cabinet shall provide 230V AC voltage from the fuse of the feeder to the rail mount terminal for the feeder.
# The control cabinet shall provide transient overvoltage protection by means of an additional set of relays (overvoltage protection relay) for each 230V AC pumps:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator for each of the following devices to control terminal of their respective overvoltage protection relay:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall provide 230V AC voltage to the input of each of the overvoltage protection relays:
# The control cabinet shall provide 230V AC voltage from the overvoltage protection to the respective fuse.
# The control cabinet shall provide 230V AC voltage from the fuse of each of the following devices to their respective power socket:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall allow to route all cables (power supply, actuators, sensors) to outside of the cabinet - preferably at the bottom of the cabinet.

Control cabinet

2026-01-09T10:10:36Z

Uwe:

The control cabinet includes the following components

* Main control unit (Raspberry Pi)
* Relay actuation unit
* Power supply 12V
* Fuses
* Circuit breaker
* Main switch
* Relays for overvoltage protection
* Sockets for power output to pumps and skimmer

= Requirements =
# The control cabinet shall have the possibility to cut off the connection to the power supply (all wires).
# The control cabinet shall limit the current drawn from the 230V AC power supply.
# The control cabinet shall limit the current drawn by each actuator (all pumps, skimmer, feeder, heater, ventilation fans).
# The control cabinet shall provide switches accessible without opening the cabinet allowing to switch off the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
#* Feeder
# The control cabinet shall provide power sockets for the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
# The control cabinet shall provide signal indicator lamps for the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
# The control cabinet shall provide a rail mount terminal block for all 12V DC devices:
#* all Balling mineral dosing pumps
#* fresh-water refill pump
#* ventilation fan #1
#* ventilation fan #2
# The control cabinet shall provide a rail mount terminal block for all 230V devices that do not use a power socket:
#* feeder
# The control cabinet shall provide 230V AC supply voltage to 12V power supply.
# The control cabinet shall provide 12V DC supply voltage to the relay actuator (Controllino).
# The control cabinet shall provide 12V DC voltage to the relay inputs of the Controllino.
# The control cabinet shall provide 12V DC voltage from the relay outputs of the Controllino to the fuse of each actuator.
#* Note: The ventilation fans share one relay output but have distinct fuses.
# The control cabinet shall provide 12V DC voltage from the fuse output of each actuator to the rail mount terminal of each actuator.
# The control cabinet shall provide 230V AC supply voltage to the relay inputs of the relay actuator.
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator to the fuse of the heater.
# The control cabinet shall provide 230V AC voltage from the fuse of the heater to the power socket of the heater.
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator to the fuse of the feeder.
# The control cabinet shall provide 230V AC voltage from the fuse of the feeder to the rail mount terminal for the feeder.
# The control cabinet shall provide transient overvoltage protection by means of an additional set of relays (overvoltage protection relay) for each 230V AC pumps:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator for each of the following devices to control terminal of their respective overvoltage protection relay:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall provide 230V AC voltage to the input of each of the overvoltage protection relays:
# The control cabinet shall provide 230V AC voltage from the overvoltage protection to the respective fuse.
# The control cabinet shall provide 230V AC voltage from the fuse of each of the following devices to their respective power socket:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall allow to route all cables (power supply, actuators, sensors) to outside of the cabinet - preferably at the bottom of the cabinet.

Control cabinet

2026-01-09T10:09:57Z

Uwe: /* Requirements */

The control cabinet includes the following components

* Main control unit (Raspberry Pi)
* Relay actuation unit
* Power supply 12V
* Fuses
* Circuit breaker
* Main switch
* Relays for [[manual control of pumps and skimmer]]
* Sockets for power output to pumps and skimmer

= Requirements =
# The control cabinet shall have the possibility to cut off the connection to the power supply (all wires).
# The control cabinet shall limit the current drawn from the 230V AC power supply.
# The control cabinet shall limit the current drawn by each actuator (all pumps, skimmer, feeder, heater, ventilation fans).
# The control cabinet shall provide switches accessible without opening the cabinet allowing to switch off the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
#* Feeder
# The control cabinet shall provide power sockets for the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
# The control cabinet shall provide signal indicator lamps for the following devices:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
#* Heater
# The control cabinet shall provide a rail mount terminal block for all 12V DC devices:
#* all Balling mineral dosing pumps
#* fresh-water refill pump
#* ventilation fan #1
#* ventilation fan #2
# The control cabinet shall provide a rail mount terminal block for all 230V devices that do not use a power socket:
#* feeder
# The control cabinet shall provide 230V AC supply voltage to 12V power supply.
# The control cabinet shall provide 12V DC supply voltage to the relay actuator (Controllino).
# The control cabinet shall provide 12V DC voltage to the relay inputs of the Controllino.
# The control cabinet shall provide 12V DC voltage from the relay outputs of the Controllino to the fuse of each actuator.
#* Note: The ventilation fans share one relay output but have distinct fuses.
# The control cabinet shall provide 12V DC voltage from the fuse output of each actuator to the rail mount terminal of each actuator.
# The control cabinet shall provide 230V AC supply voltage to the relay inputs of the relay actuator.
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator to the fuse of the heater.
# The control cabinet shall provide 230V AC voltage from the fuse of the heater to the power socket of the heater.
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator to the fuse of the feeder.
# The control cabinet shall provide 230V AC voltage from the fuse of the feeder to the rail mount terminal for the feeder.
# The control cabinet shall provide transient overvoltage protection by means of an additional set of relays (overvoltage protection relay) for each 230V AC pumps:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall provide 230V AC voltage from the relay output of the relay actuator for each of the following devices to control terminal of their respective overvoltage protection relay:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall provide 230V AC voltage to the input of each of the overvoltage protection relays:
# The control cabinet shall provide 230V AC voltage from the overvoltage protection to the respective fuse.
# The control cabinet shall provide 230V AC voltage from the fuse of each of the following devices to their respective power socket:
#* Protein skimmer
#* Main pump #1
#* Main pump #2
#* Auxiliary pump #1
#* Auxiliary pump #2
# The control cabinet shall allow to route all cables (power supply, actuators, sensors) to outside of the cabinet - preferably at the bottom of the cabinet.

Control cabinet

2026-01-09T10:04:43Z

2026-01-08T18:31:57Z

Uwe: /* Measurement using Atlas Scientific circuits */

The main control application of Aquarium control implements the following features:

* [[Data acquisition of water temperature, pH and conductivity]]
* [[Data acquisition of ambient temperature and humidity]]
* [[Fresh water refill control|Refill control for fresh water]]
* Feed control
* Water temperature control using air ventilation and heater
* Balling mineral dosing

The control of the relays for operating the devices can use two different modes:
* [[Arduino-based relay actuation|Using an Arduino-based relay actuation]]
* Using the GPIO of the Raspberry Pi (requires additional hardware)

Additionally, the main control application implements the following supporting features:
* [[Version comparison between database and application]]
* Configuration using a Rust .toml configuration file
* Logging
* Command interface to receive instructions from outside of the application via a POSIX message queue
* Storage of recorded data in SQL database
* File-based communication to RAM-disk
* Usage of simulator to run with simulated sensor data for development purposes
* Schedule checks to limit the hour of day of operating certain actuators
* [[Communication with HW Watchdog]]
The application is written in Rust and is [[automatic start by using systemd| automatically started using systemd]].

The documentation of the software is available [http://vps2483992.servdiscount-customer.com/aquarium_control_doc/aquarium_control/ here].

Development for the main control application requires the [[setup of the development environment]].

There is a [[Release procedure|release procedure]] which is highly recommended to be followed also by anyone developing the SW further.

== Architecture ==
=== Startup of the application ===
The startup uses a two-layer approach:
# main() - Simple error handler wrapper that calls run() and exits with code 1 on errors
# run() - The actual initialization orchestrator that performs the major steps

==== Phase 1: Command Line & Configuration ====
* Parses command line arguments ("help", "version", config file)
* Sets the default config file: <code>/etc/aquarium_control/aquarium_control.toml</code>
* Loads configuration and creates <code>ExecutionConfig</code> (boolean flags determining which modules to run)

==== Phase 2: System Setup ====
* Initializes the logging system
* Logs version information and executable hash
* Verifies root privileges (required for hardware access)
* Publishes process ID to file for client communication

==== Phase 3: Database & Hardware ====
* Connects to database (MariaDB)
* Creates component-specific SQL interfaces (<code>Schedule</code>, <code>Balling</code>, <code>Refill</code>, <code>Heating</code>, <code>Feed</code>, <code>Data</code>)
* Validates database schema and version compatibility
* Initializes hardware components if configured:
** RGB LEDs
** GPIO handlers
** Tank level switch
** I2C interface
** Atlas Scientific sensors
** DHT temperature/humidity sensors
** Relay actuator (Controllino)

==== Phase 4: Communication Channels ====
* Creates the <code>Channels</code> struct containing ~30+ inter-thread communication channels
* Uses custom <code>AquaSender</code>/<code>AquaReceiver</code> wrappers for MPSC channels
* Establishes bidirectional and unidirectional message paths between all modules

==== Phase 5: Component Initialization ====
Instantiates all high-level control components:
* data logger
* sensor manager
* relay manager
* food injection
* mineral dosing (balling)
* water injection/refill
* heating control
* ventilation control
* monitors
* watchdog
* schedule checker
* IPC messaging system

==== Phase 6: Thread Spawning ====
* Uses <code>std::thread::scope</code> for guaranteed cleanup
* Spawns threads conditionally based on <code>ExecutionConfig</code> flags
* Critical: A 3-second startup delay allows sensors to acquire first data before control loops activate

==== Architecture of thread configuration ====
* The <code>Channels</code> module (<code>src/launch/channels.rs</code>) acts as a central wiring diagram, with the Signal Handler serving as the main event coordinator.
* The <code>ExecutionConfig</code> decouples configuration from execution - threads only receive flags about which modules are active, not the full config - this also avoids ownership issues.

=== Threads ===
The application spawns the following threads:
{| class="wikitable" style="margin:auto"
|+ Overview of threads
|-
! Thread name !! Purpose
|-
| signal_handler || Receiving signals from the operating system
|-
| schedule_check || Polling the database to capture changes of the actuator channel. Informing other threads about it.
|-
| sensor_manager || Data acquisition
|-
| relay_manager || Actuation of relays
|-
| data_logger || Recording of data
|-
| tank_level_switch || Postprocessing of tank level switch position signal
|-
| refill || Fresh water refill control
|-
| heating || Heating control
|-
| ventilation || Ventilation control
|-
| balling || Balling mineral dosing control
|-
| watchdog || Sending alive signal to Raspberry Pi hardware watchdog
|-
| monitors || Diagnostics (not implemented as of January, 2026)
|-
| messaging || Receiving communication via message queue
|-
| memory || Monitoring memory utilization
|-
| ds18b20 || Recording data from DS18B20 temperature sensor
|-
| feed || Feed control
|-
| i2c_interface || Communication via I2C
|-
| atlas_scientific || Recording data from Atlas Scientific temperature sensor
|-
| dht || Recording data from DHT sensor
|-
| publish_pid || Writing PID to lock file

|}

== Measurement using Atlas Scientific circuits ==
The core Abstraction (<code>AtlasScientificDriver</code> Trait) is defined in <code>src/sensors/atlas_scientific_driver.rs</code>, this trait serves as the common interface for all sensor types. It enforces three key behaviors:
* <code>send_request_to_i2c_interface</code>: Encapsulates how to trigger a measurement (e.g., constructing specific I2C commands).
* <code>receive_response_from_i2c_interface</code>: Handles parsing the raw byte response from the I2C bus into a normalized floating-point value.
* <code>device_init</code>: Performs hardware-specific setup (crucial for OEM type sensor circuit).

Circuit-type-specific implementations
* OEM Driver (<code>AtlasScientificOem</code>):
** Protocol: Uses a binary, register-based protocol.
** Initialization: Requires an explicit "Wake Up" command (writing to <code>REG_WAKEUP</code>) and verifies the hardware by reading the <code>REG_DEVICE_TYPE</code>.
** Read Cycle: Writes a register address (e.g., <code>REG_DATA_MSB_PH</code>), waits for a short processing time, and reads 4 bytes.
** Parsing: Decodes the 4-byte response as a Big Endian unsigned integer and divides it by a specific scale factor (e.g., 1000.0) to get the float value.
* EZO Driver (<code>AtlasScientificEzo</code>):
** Protocol: Uses a text-based (ASCII) command protocol.
** Initialization: Minimal or no-op (these devices are typically always ready or auto-on).
** Read Cycle: Sends the ASCII character 'R', waits for a longer processing time, and reads a fixed 8-byte response.
** Parsing: Validates "magic" start/end bytes (1 and 0), converts the inner ASCII string (e.g., "23.50") to a float.

Context and factory (<code>AtlasScientific</code> struct)
* The main <code>AtlasScientific</code> struct acts as the context. It holds a <code>HashMap<AquariumSignal</code>, <code>Box<dyn AtlasScientificDriver>></code>.
* Factory Logic: The <code>create_drivers</code> method functions as a factory. It reads the <code>aquarium_control.toml</code> configuration (specifically fields like <code>sensor_type_ph = "oem"</code> or <code>"ezo"</code>) and
instantiates the correct driver implementation for each sensor (temperature, pH, conductivity).
* Execution: The main thread loop calls <code>driver.send_request...</code> and <code>driver.receive_response...</code> on the active driver, unaware of whether it is communicating via binary registers or ASCII commands.

Communication Flow

The architecture decouples protocol logic from bus I/O:
# Driver creates an abstraction-specific <code>I2cRequest</code> (containing address, write buffer, read length, delay).
# <code>AtlasScientific</code> thread sends this request via a channel to the <code>I2cInterface</code> thread.
# <code>I2cInterface</code> thread performs the physical I2C transaction.
# <code>AtlasScientific</code> thread receives the raw bytes and passes them back to the driver for parsing.
# Additionally, <code>AtlasScientific</code> performs measurement value checks informing deviations to <code>Monitors</code>.

This design enables the system to mix and match sensor types (e.g., an OEM type pH sensor circuit with an EZO type temperature sensor circuit) purely through configuration changes.

== Monitors ==
The Monitors module (<code>src/watchmen/monitors.rs</code>) is a dedicated thread that aggregates and stores historical system state information.
It interacts with the following modules:
* Refill
* Signal handler

The Monitors thread receives data from the other thread by polling the channels.

The data is transferred in specific structs ("Views"), e.g. <code>RefillView</code>.

<code>Monitors</code> contains a deduplication logic: Data is only stored when it differs from previous sample.

The number of samples is also limited (rolling window), to avoid overflow.

Control application

2026-01-08T18:21:21Z

2026-01-08T09:55:30Z

Uwe: /* Startup of the application */