Aquarium-Control - User contributions [en]

Control application

2026-08-01T09:42:44Z

Uwe: /* Using llvm-cov */

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.

= Requirements =

The requirement are structured in two levels:
* system requirements
* software requirements

The requirements coverage report is generated with the following command: <code>oft trace doc src tests -o Html > doc/req/coverage.html</code>

The linkage of the software requirements to the implementation and related test cases has been reverse engineered using the following two prompts for each function group:

<blockquote>Check all software requirements of thermal.md if you can find the matching implementations and tests.</blockquote>

<blockquote>Now do the reverse: Go through the implementation and test cases in src/sensors and the integration tests in tests/sensors and label every test case and at least every function linking to a matching software requirement from sensors.md.</blockquote>

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

The application makes [[use of an asynchronous runtime for the main application]].

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

= Development environment =
== Install Rust ==
<code>curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh</code>

== Install additional development libraries ==
<code>sudo apt-get install -y libudev-dev pkg-config</code>

== Build time ==
Building the release on a Raspberry Pi 4 takes around 16 minutes.

= Test strategy =
== Unit tests ==
Located within the implementation code files within <code>src</code>.

== Integration tests in test ==
Separated from implementation code to the <code>test</code> folder.

== Code coverage measurement ==
=== Using tarpaulin ===
<code>cargo tarpaulin --features "test-utils" --out Html</code>

The measurement takes app. 22 minutes.

=== Using llvm-cov ===
<code>cargo +nightly llvm-cov --features "test-utils" --html --ignore-filename-regex '(main\.rs|.*_channels\.rs|mock.*\.rs|pingable\.rs|privilege_check\.rs|recorder_data_frame\.rs)'</code>

The excluded files contain primarily debug functionality or wrappers without intrinsic logic which distorts the coverage measurement and where adding test cases would be meaningless.

The nightly compiler build needs to be used because the application uses gating to exclude the unit tests from the coverage measurement: <code>#[cfg_attr(coverage_nightly, coverage(off))]</code>

The measurements takes app. 8 minutes.

=== Comparing the results from llvm-cov and tarpaulin ===
Based on commit <code>8f557814f679c30ebd70e181f2a3f996ce0e295c</code>.

{| class="wikitable sortable"
|+ Module Summary Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! Subsystem / Module !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|- style="font-weight:bold; background-color:#f0f0f0;"
| '''TOTAL (All Application Source Files)''' || 71.53% (11216/15681) || 54.48% (4929/9047) || +17.04%
|-
| <code>src/bin/</code> || 0.00% (0/597) || 0.00% (0/457) || +0.00%
|-
| <code>src/database/</code> || 69.73% (1283/1840) || 52.72% (631/1197) || +17.01%
|-
| <code>src/dispatch/</code> || 46.32% (44/95) || 33.80% (24/71) || +12.51%
|-
| <code>src/food/</code> || 79.06% (721/912) || 58.80% (244/415) || +20.26%
|-
| <code>src/launch/</code> || 84.06% (944/1123) || 59.48% (411/691) || +24.58%
|-
| <code>src/mineral/</code> || 88.11% (467/530) || 60.33% (181/300) || +27.78%
|-
| <code>src/mocks/</code> || 58.82% (610/1037) || 55.57% (334/601) || +3.25%
|-
| <code>src/permission/</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/</code> || 77.46% (701/905) || 47.50% (304/640) || +29.96%
|-
| <code>src/relays/</code> || 60.22% (448/744) || 47.58% (216/454) || +12.64%
|-
| <code>src/sensors/</code> || 75.70% (1748/2309) || 54.76% (656/1198) || +20.95%
|-
| <code>src/simulator/</code> || 3.07% (10/326) || 2.05% (4/195) || +1.02%
|-
| <code>src/test_server/</code> || 67.93% (822/1210) || 59.67% (429/719) || +8.27%
|-
| <code>src/thermal/</code> || 88.45% (1019/1152) || 67.96% (437/643) || +20.49%
|-
| <code>src/utilities/</code> || 80.91% (1187/1467) || 75.10% (564/751) || +5.81%
|-
| <code>src/watchmen/</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/</code> || 86.10% (700/813) || 71.18% (331/465) || +14.92%
|}

{| class="wikitable sortable"
|+ Detailed File Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! File Path !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|-
| <code>src/bin/aquarium_client.rs</code> || 0.00% (0/117) || 0.00% (0/98) || +0.00%
|-
| <code>src/bin/aquarium_commissioning.rs</code> || 0.00% (0/426) || 0.00% (0/315) || +0.00%
|-
| <code>src/bin/aquarium_test_server.rs</code> || 0.00% (0/54) || 0.00% (0/44) || +0.00%
|-
| <code>src/database/database_interface_feed_trait.rs</code> || 77.86% (102/131) || 58.06% (54/93) || +19.80%
|-
| <code>src/database/pingable.rs</code> || 44.44% (4/9) || 33.33% (2/6) || +11.11%
|-
| <code>src/database/sql_interface.rs</code> || 65.79% (250/380) || 48.57% (119/245) || +17.22%
|-
| <code>src/database/sql_interface_balling.rs</code> || 69.31% (140/202) || 53.91% (69/128) || +15.40%
|-
| <code>src/database/sql_interface_data.rs</code> || 60.76% (48/79) || 59.62% (31/52) || +1.14%
|-
| <code>src/database/sql_interface_feed.rs</code> || 63.70% (186/292) || 45.00% (90/200) || +18.70%
|-
| <code>src/database/sql_interface_heating_set_vals.rs</code> || 66.12% (80/121) || 37.97% (30/79) || +28.15%
|-
| <code>src/database/sql_interface_heating_stats.rs</code> || 77.65% (139/179) || 67.59% (73/108) || +10.06%
|-
| <code>src/database/sql_interface_heating_stats_data_transfer.rs</code> || 100.00% (7/7) || 100.00% (2/2) || +0.00%
|-
| <code>src/database/sql_interface_midnight.rs</code> || 100.00% (8/8) || 100.00% (4/4) || +0.00%
|-
| <code>src/database/sql_interface_refill.rs</code> || 66.94% (83/124) || 57.14% (48/84) || +9.80%
|-
| <code>src/database/sql_interface_schedule.rs</code> || 85.54% (142/166) || 69.16% (74/107) || +16.38%
|-
| <code>src/database/sql_interface_test_utils.rs</code> || 100.00% (10/10) || 100.00% (5/5) || +0.00%
|-
| <code>src/database/sql_interface_ventilation_set_vals.rs</code> || 63.64% (84/132) || 35.71% (30/84) || +27.92%
|-
| <code>src/dispatch/ipc_message.rs</code> || 0.00% (0/51) || 0.00% (0/41) || +0.00%
|-
| <code>src/dispatch/messaging.rs</code> || 100.00% (44/44) || 80.00% (24/30) || +20.00%
|-
| <code>src/food/feed.rs</code> || 86.40% (305/353) || 62.65% (104/166) || +23.75%
|-
| <code>src/food/feed_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/food/feed_profile.rs</code> || 100.00% (100/100) || 100.00% (4/4) || +0.00%
|-
| <code>src/food/feed_schedule_entry.rs</code> || 97.62% (82/84) || 100.00% (10/10) || -2.38%
|-
| <code>src/food/food_injection.rs</code> || 62.43% (113/181) || 56.64% (64/113) || +5.79%
|-
| <code>src/food/food_injection_actuator_state.rs</code> || 61.11% (11/18) || 54.55% (6/11) || +6.57%
|-
| <code>src/food/food_injection_signals.rs</code> || 62.50% (100/160) || 48.08% (50/104) || +14.42%
|-
| <code>src/launch/config_app.rs</code> || 82.35% (98/119) || 57.14% (44/77) || +25.21%
|-
| <code>src/launch/execution_config.rs</code> || 86.30% (63/73) || 72.34% (34/47) || +13.96%
|-
| <code>src/launch/pid_file.rs</code> || 96.67% (58/60) || 77.14% (27/35) || +19.52%
|-
| <code>src/launch/run.rs</code> || 83.40% (725/869) || 58.74% (306/521) || +24.66%
|-
| <code>src/mineral/balling.rs</code> || 88.08% (340/386) || 61.08% (135/221) || +27.00%
|-
| <code>src/mineral/balling_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/mineral/balling_profile.rs</code> || 100.00% (71/71) || 100.00% (18/18) || +0.00%
|-
| <code>src/mineral/balling_set_val.rs</code> || 77.97% (46/59) || 44.44% (24/54) || +33.53%
|-
| <code>src/mocks/mock_dht.rs</code> || 74.07% (40/54) || 64.71% (22/34) || +9.36%
|-
| <code>src/mocks/mock_food_injection.rs</code> || 83.33% (20/24) || 75.00% (12/16) || +8.33%
|-
| <code>src/mocks/mock_i2c_interface.rs</code> || 32.50% (13/40) || 28.00% (7/25) || +4.50%
|-
| <code>src/mocks/mock_peristaltic_pump.rs</code> || 85.00% (17/20) || 72.73% (8/11) || +12.27%
|-
| <code>src/mocks/mock_relay_manager.rs</code> || 82.50% (33/40) || 75.86% (22/29) || +6.64%
|-
| <code>src/mocks/mock_sql_interface.rs</code> || 66.21% (241/364) || 63.81% (134/210) || +2.40%
|-
| <code>src/mocks/mock_water_injection.rs</code> || 82.61% (19/23) || 75.00% (12/16) || +7.61%
|-
| <code>src/permission/process_privileges.rs</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/recorder.rs</code> || 84.77% (590/696) || 54.12% (269/497) || +30.65%
|-
| <code>src/recorder/recorder_channels.rs</code> || 58.82% (10/17) || 45.45% (5/11) || +13.37%
|-
| <code>src/recorder/recorder_data_frame.rs</code> || 52.66% (101/192) || 22.31% (27/121) || +30.35%
|-
| <code>src/relays/actuator_state.rs</code> || 74.07% (20/27) || 75.00% (15/20) || -0.93%
|-
| <code>src/relays/aquarium_device.rs</code> || 66.67% (14/21) || 68.75% (11/16) || -2.08%
|-
| <code>src/relays/relay_manager.rs</code> || 58.46% (394/674) || 45.43% (179/394) || +13.03%
|-
| <code>src/relays/relay_manager_channels.rs</code> || 90.91% (20/22) || 45.83% (11/24) || +45.08%
|-
| <code>src/sensors/atlas_scientific.rs</code> || 74.77% (329/440) || 55.42% (92/166) || +19.35%
|-
| <code>src/sensors/atlas_scientific_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/dht.rs</code> || 75.00% (105/140) || 53.64% (59/110) || +21.36%
|-
| <code>src/sensors/dht_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/ds18b20.rs</code> || 74.55% (123/165) || 51.09% (47/92) || +23.46%
|-
| <code>src/sensors/ds18b20_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/i2c_interface.rs</code> || 76.54% (362/473) || 57.51% (153/266) || +19.03%
|-
| <code>src/sensors/i2c_interface_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/sensor_manager.rs</code> || 76.10% (761/1000) || 54.34% (282/519) || +21.76%
|-
| <code>src/sensors/sensor_manager_channels.rs</code> || 84.62% (33/39) || 75.00% (9/12) || +9.62%
|-
| <code>src/thermal/heating.rs</code> || 90.96% (332/365) || 68.60% (148/216) || +22.36%
|-
| <code>src/thermal/heating_actuation.rs</code> || 84.47% (87/103) || 67.24% (39/58) || +17.23%
|-
| <code>src/thermal/heating_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/heating_set_vals.rs</code> || 87.50% (35/40) || 64.29% (18/28) || +23.21%
|-
| <code>src/thermal/heating_stats_entry.rs</code> || 94.67% (142/150) || 82.22% (74/90) || +12.44%
|-
| <code>src/thermal/saw_tooth_profile.rs</code> || 100.00% (64/64) || 100.00% (23/23) || +0.00%
|-
| <code>src/thermal/saw_tooth_profile_config.rs</code> || 70.83% (17/24) || 50.00% (7/14) || +20.83%
|-
| <code>src/thermal/temperature_gradient.rs</code> || 100.00% (64/64) || 100.00% (32/32) || +0.00%
|-
| <code>src/thermal/thermal_control_status.rs</code> || 81.25% (26/32) || 58.82% (10/17) || +22.43%
|-
| <code>src/thermal/ventilation.rs</code> || 87.67% (192/219) || 61.16% (74/121) || +26.51%
|-
| <code>src/thermal/ventilation_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/ventilation_set_vals.rs</code> || 58.82% (30/51) || 58.82% (20/34) || +0.00%
|-
| <code>src/utilities/config.rs</code> || 76.99% (830/1078) || 72.84% (437/600) || +4.15%
|-
| <code>src/utilities/spin_sleeper.rs</code> || 79.17% (19/24) || 69.23% (9/13) || +9.94%
|-
| <code>src/utilities/thread_builder.rs</code> || 92.59% (25/27) || 78.57% (11/14) || +14.02%
|-
| <code>src/watchmen/monitors.rs</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/refill.rs</code> || 86.81% (447/515) || 69.45% (216/311) || +17.36%
|-
| <code>src/water/refill_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/water/tank_level_switch.rs</code> || 84.14% (191/227) || 74.47% (105/141) || +9.67%
|-
| <code>src/water/tank_level_switch_signals.rs</code> || 90.36% (75/83) || 86.96% (40/46) || +3.40%
|}

== System tests using the simulator ==
Running the application in simulator mode.

Control application

2026-08-01T06:39:45Z

Uwe: /* Using llvm-cov */

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.

= Requirements =

The requirement are structured in two levels:
* system requirements
* software requirements

The requirements coverage report is generated with the following command: <code>oft trace doc src tests -o Html > doc/req/coverage.html</code>

The linkage of the software requirements to the implementation and related test cases has been reverse engineered using the following two prompts for each function group:

<blockquote>Check all software requirements of thermal.md if you can find the matching implementations and tests.</blockquote>

<blockquote>Now do the reverse: Go through the implementation and test cases in src/sensors and the integration tests in tests/sensors and label every test case and at least every function linking to a matching software requirement from sensors.md.</blockquote>

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

The application makes [[use of an asynchronous runtime for the main application]].

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

= Development environment =
== Install Rust ==
<code>curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh</code>

== Install additional development libraries ==
<code>sudo apt-get install -y libudev-dev pkg-config</code>

== Build time ==
Building the release on a Raspberry Pi 4 takes around 16 minutes.

= Test strategy =
== Unit tests ==
Located within the implementation code files within <code>src</code>.

== Integration tests in test ==
Separated from implementation code to the <code>test</code> folder.

== Code coverage measurement ==
=== Using tarpaulin ===
<code>cargo tarpaulin --features "test-utils" --out Html</code>

The measurement takes app. 22 minutes.

=== Using llvm-cov ===
<code>cargo +nightly llvm-cov --features "test-utils" --html --ignore-filename-regex '(main\.rs|.*_channels\.rs|mock.*\.rs|pingable\.rs|privilege_check\.rs)'</code>

The excluded files contain primarily debug functionality or wrappers without intrinsic logic which distorts the coverage measurement and where adding test cases would be meaningless.

The nightly compiler build needs to be used because the application uses gating to exclude the unit tests from the coverage measurement: <code>#[cfg_attr(coverage_nightly, coverage(off))]</code>

The measurements takes app. 8 minutes.

=== Comparing the results from llvm-cov and tarpaulin ===
Based on commit <code>8f557814f679c30ebd70e181f2a3f996ce0e295c</code>.

{| class="wikitable sortable"
|+ Module Summary Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! Subsystem / Module !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|- style="font-weight:bold; background-color:#f0f0f0;"
| '''TOTAL (All Application Source Files)''' || 71.53% (11216/15681) || 54.48% (4929/9047) || +17.04%
|-
| <code>src/bin/</code> || 0.00% (0/597) || 0.00% (0/457) || +0.00%
|-
| <code>src/database/</code> || 69.73% (1283/1840) || 52.72% (631/1197) || +17.01%
|-
| <code>src/dispatch/</code> || 46.32% (44/95) || 33.80% (24/71) || +12.51%
|-
| <code>src/food/</code> || 79.06% (721/912) || 58.80% (244/415) || +20.26%
|-
| <code>src/launch/</code> || 84.06% (944/1123) || 59.48% (411/691) || +24.58%
|-
| <code>src/mineral/</code> || 88.11% (467/530) || 60.33% (181/300) || +27.78%
|-
| <code>src/mocks/</code> || 58.82% (610/1037) || 55.57% (334/601) || +3.25%
|-
| <code>src/permission/</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/</code> || 77.46% (701/905) || 47.50% (304/640) || +29.96%
|-
| <code>src/relays/</code> || 60.22% (448/744) || 47.58% (216/454) || +12.64%
|-
| <code>src/sensors/</code> || 75.70% (1748/2309) || 54.76% (656/1198) || +20.95%
|-
| <code>src/simulator/</code> || 3.07% (10/326) || 2.05% (4/195) || +1.02%
|-
| <code>src/test_server/</code> || 67.93% (822/1210) || 59.67% (429/719) || +8.27%
|-
| <code>src/thermal/</code> || 88.45% (1019/1152) || 67.96% (437/643) || +20.49%
|-
| <code>src/utilities/</code> || 80.91% (1187/1467) || 75.10% (564/751) || +5.81%
|-
| <code>src/watchmen/</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/</code> || 86.10% (700/813) || 71.18% (331/465) || +14.92%
|}

{| class="wikitable sortable"
|+ Detailed File Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! File Path !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|-
| <code>src/bin/aquarium_client.rs</code> || 0.00% (0/117) || 0.00% (0/98) || +0.00%
|-
| <code>src/bin/aquarium_commissioning.rs</code> || 0.00% (0/426) || 0.00% (0/315) || +0.00%
|-
| <code>src/bin/aquarium_test_server.rs</code> || 0.00% (0/54) || 0.00% (0/44) || +0.00%
|-
| <code>src/database/database_interface_feed_trait.rs</code> || 77.86% (102/131) || 58.06% (54/93) || +19.80%
|-
| <code>src/database/pingable.rs</code> || 44.44% (4/9) || 33.33% (2/6) || +11.11%
|-
| <code>src/database/sql_interface.rs</code> || 65.79% (250/380) || 48.57% (119/245) || +17.22%
|-
| <code>src/database/sql_interface_balling.rs</code> || 69.31% (140/202) || 53.91% (69/128) || +15.40%
|-
| <code>src/database/sql_interface_data.rs</code> || 60.76% (48/79) || 59.62% (31/52) || +1.14%
|-
| <code>src/database/sql_interface_feed.rs</code> || 63.70% (186/292) || 45.00% (90/200) || +18.70%
|-
| <code>src/database/sql_interface_heating_set_vals.rs</code> || 66.12% (80/121) || 37.97% (30/79) || +28.15%
|-
| <code>src/database/sql_interface_heating_stats.rs</code> || 77.65% (139/179) || 67.59% (73/108) || +10.06%
|-
| <code>src/database/sql_interface_heating_stats_data_transfer.rs</code> || 100.00% (7/7) || 100.00% (2/2) || +0.00%
|-
| <code>src/database/sql_interface_midnight.rs</code> || 100.00% (8/8) || 100.00% (4/4) || +0.00%
|-
| <code>src/database/sql_interface_refill.rs</code> || 66.94% (83/124) || 57.14% (48/84) || +9.80%
|-
| <code>src/database/sql_interface_schedule.rs</code> || 85.54% (142/166) || 69.16% (74/107) || +16.38%
|-
| <code>src/database/sql_interface_test_utils.rs</code> || 100.00% (10/10) || 100.00% (5/5) || +0.00%
|-
| <code>src/database/sql_interface_ventilation_set_vals.rs</code> || 63.64% (84/132) || 35.71% (30/84) || +27.92%
|-
| <code>src/dispatch/ipc_message.rs</code> || 0.00% (0/51) || 0.00% (0/41) || +0.00%
|-
| <code>src/dispatch/messaging.rs</code> || 100.00% (44/44) || 80.00% (24/30) || +20.00%
|-
| <code>src/food/feed.rs</code> || 86.40% (305/353) || 62.65% (104/166) || +23.75%
|-
| <code>src/food/feed_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/food/feed_profile.rs</code> || 100.00% (100/100) || 100.00% (4/4) || +0.00%
|-
| <code>src/food/feed_schedule_entry.rs</code> || 97.62% (82/84) || 100.00% (10/10) || -2.38%
|-
| <code>src/food/food_injection.rs</code> || 62.43% (113/181) || 56.64% (64/113) || +5.79%
|-
| <code>src/food/food_injection_actuator_state.rs</code> || 61.11% (11/18) || 54.55% (6/11) || +6.57%
|-
| <code>src/food/food_injection_signals.rs</code> || 62.50% (100/160) || 48.08% (50/104) || +14.42%
|-
| <code>src/launch/config_app.rs</code> || 82.35% (98/119) || 57.14% (44/77) || +25.21%
|-
| <code>src/launch/execution_config.rs</code> || 86.30% (63/73) || 72.34% (34/47) || +13.96%
|-
| <code>src/launch/pid_file.rs</code> || 96.67% (58/60) || 77.14% (27/35) || +19.52%
|-
| <code>src/launch/run.rs</code> || 83.40% (725/869) || 58.74% (306/521) || +24.66%
|-
| <code>src/mineral/balling.rs</code> || 88.08% (340/386) || 61.08% (135/221) || +27.00%
|-
| <code>src/mineral/balling_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/mineral/balling_profile.rs</code> || 100.00% (71/71) || 100.00% (18/18) || +0.00%
|-
| <code>src/mineral/balling_set_val.rs</code> || 77.97% (46/59) || 44.44% (24/54) || +33.53%
|-
| <code>src/mocks/mock_dht.rs</code> || 74.07% (40/54) || 64.71% (22/34) || +9.36%
|-
| <code>src/mocks/mock_food_injection.rs</code> || 83.33% (20/24) || 75.00% (12/16) || +8.33%
|-
| <code>src/mocks/mock_i2c_interface.rs</code> || 32.50% (13/40) || 28.00% (7/25) || +4.50%
|-
| <code>src/mocks/mock_peristaltic_pump.rs</code> || 85.00% (17/20) || 72.73% (8/11) || +12.27%
|-
| <code>src/mocks/mock_relay_manager.rs</code> || 82.50% (33/40) || 75.86% (22/29) || +6.64%
|-
| <code>src/mocks/mock_sql_interface.rs</code> || 66.21% (241/364) || 63.81% (134/210) || +2.40%
|-
| <code>src/mocks/mock_water_injection.rs</code> || 82.61% (19/23) || 75.00% (12/16) || +7.61%
|-
| <code>src/permission/process_privileges.rs</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/recorder.rs</code> || 84.77% (590/696) || 54.12% (269/497) || +30.65%
|-
| <code>src/recorder/recorder_channels.rs</code> || 58.82% (10/17) || 45.45% (5/11) || +13.37%
|-
| <code>src/recorder/recorder_data_frame.rs</code> || 52.66% (101/192) || 22.31% (27/121) || +30.35%
|-
| <code>src/relays/actuator_state.rs</code> || 74.07% (20/27) || 75.00% (15/20) || -0.93%
|-
| <code>src/relays/aquarium_device.rs</code> || 66.67% (14/21) || 68.75% (11/16) || -2.08%
|-
| <code>src/relays/relay_manager.rs</code> || 58.46% (394/674) || 45.43% (179/394) || +13.03%
|-
| <code>src/relays/relay_manager_channels.rs</code> || 90.91% (20/22) || 45.83% (11/24) || +45.08%
|-
| <code>src/sensors/atlas_scientific.rs</code> || 74.77% (329/440) || 55.42% (92/166) || +19.35%
|-
| <code>src/sensors/atlas_scientific_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/dht.rs</code> || 75.00% (105/140) || 53.64% (59/110) || +21.36%
|-
| <code>src/sensors/dht_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/ds18b20.rs</code> || 74.55% (123/165) || 51.09% (47/92) || +23.46%
|-
| <code>src/sensors/ds18b20_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/i2c_interface.rs</code> || 76.54% (362/473) || 57.51% (153/266) || +19.03%
|-
| <code>src/sensors/i2c_interface_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/sensor_manager.rs</code> || 76.10% (761/1000) || 54.34% (282/519) || +21.76%
|-
| <code>src/sensors/sensor_manager_channels.rs</code> || 84.62% (33/39) || 75.00% (9/12) || +9.62%
|-
| <code>src/thermal/heating.rs</code> || 90.96% (332/365) || 68.60% (148/216) || +22.36%
|-
| <code>src/thermal/heating_actuation.rs</code> || 84.47% (87/103) || 67.24% (39/58) || +17.23%
|-
| <code>src/thermal/heating_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/heating_set_vals.rs</code> || 87.50% (35/40) || 64.29% (18/28) || +23.21%
|-
| <code>src/thermal/heating_stats_entry.rs</code> || 94.67% (142/150) || 82.22% (74/90) || +12.44%
|-
| <code>src/thermal/saw_tooth_profile.rs</code> || 100.00% (64/64) || 100.00% (23/23) || +0.00%
|-
| <code>src/thermal/saw_tooth_profile_config.rs</code> || 70.83% (17/24) || 50.00% (7/14) || +20.83%
|-
| <code>src/thermal/temperature_gradient.rs</code> || 100.00% (64/64) || 100.00% (32/32) || +0.00%
|-
| <code>src/thermal/thermal_control_status.rs</code> || 81.25% (26/32) || 58.82% (10/17) || +22.43%
|-
| <code>src/thermal/ventilation.rs</code> || 87.67% (192/219) || 61.16% (74/121) || +26.51%
|-
| <code>src/thermal/ventilation_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/ventilation_set_vals.rs</code> || 58.82% (30/51) || 58.82% (20/34) || +0.00%
|-
| <code>src/utilities/config.rs</code> || 76.99% (830/1078) || 72.84% (437/600) || +4.15%
|-
| <code>src/utilities/spin_sleeper.rs</code> || 79.17% (19/24) || 69.23% (9/13) || +9.94%
|-
| <code>src/utilities/thread_builder.rs</code> || 92.59% (25/27) || 78.57% (11/14) || +14.02%
|-
| <code>src/watchmen/monitors.rs</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/refill.rs</code> || 86.81% (447/515) || 69.45% (216/311) || +17.36%
|-
| <code>src/water/refill_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/water/tank_level_switch.rs</code> || 84.14% (191/227) || 74.47% (105/141) || +9.67%
|-
| <code>src/water/tank_level_switch_signals.rs</code> || 90.36% (75/83) || 86.96% (40/46) || +3.40%
|}

== System tests using the simulator ==
Running the application in simulator mode.

Control application

2026-07-31T17:15:58Z

Uwe: /* Using llvm-cov */

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.

= Requirements =

The requirement are structured in two levels:
* system requirements
* software requirements

The requirements coverage report is generated with the following command: <code>oft trace doc src tests -o Html > doc/req/coverage.html</code>

The linkage of the software requirements to the implementation and related test cases has been reverse engineered using the following two prompts for each function group:

<blockquote>Check all software requirements of thermal.md if you can find the matching implementations and tests.</blockquote>

<blockquote>Now do the reverse: Go through the implementation and test cases in src/sensors and the integration tests in tests/sensors and label every test case and at least every function linking to a matching software requirement from sensors.md.</blockquote>

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

The application makes [[use of an asynchronous runtime for the main application]].

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

= Development environment =
== Install Rust ==
<code>curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh</code>

== Install additional development libraries ==
<code>sudo apt-get install -y libudev-dev pkg-config</code>

== Build time ==
Building the release on a Raspberry Pi 4 takes around 16 minutes.

= Test strategy =
== Unit tests ==
Located within the implementation code files within <code>src</code>.

== Integration tests in test ==
Separated from implementation code to the <code>test</code> folder.

== Code coverage measurement ==
=== Using tarpaulin ===
<code>cargo tarpaulin --features "test-utils" --out Html</code>

The measurement takes app. 22 minutes.

=== Using llvm-cov ===
<code>cargo llvm-cov --features "test-utils" --html --ignore-filename-regex '(main\.rs|.*_channels\.rs|mock.*\.rs|pingable\.rs|privilege_check\.rs)'</code>

The excluded files contain primarily debug functionality or wrappers without intrinsic logic which distorts the coverage measurement and where adding test cases would be meaningless.

The measurements takes app. 8 minutes.

=== Comparing the results from llvm-cov and tarpaulin ===
Based on commit <code>8f557814f679c30ebd70e181f2a3f996ce0e295c</code>.

{| class="wikitable sortable"
|+ Module Summary Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! Subsystem / Module !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|- style="font-weight:bold; background-color:#f0f0f0;"
| '''TOTAL (All Application Source Files)''' || 71.53% (11216/15681) || 54.48% (4929/9047) || +17.04%
|-
| <code>src/bin/</code> || 0.00% (0/597) || 0.00% (0/457) || +0.00%
|-
| <code>src/database/</code> || 69.73% (1283/1840) || 52.72% (631/1197) || +17.01%
|-
| <code>src/dispatch/</code> || 46.32% (44/95) || 33.80% (24/71) || +12.51%
|-
| <code>src/food/</code> || 79.06% (721/912) || 58.80% (244/415) || +20.26%
|-
| <code>src/launch/</code> || 84.06% (944/1123) || 59.48% (411/691) || +24.58%
|-
| <code>src/mineral/</code> || 88.11% (467/530) || 60.33% (181/300) || +27.78%
|-
| <code>src/mocks/</code> || 58.82% (610/1037) || 55.57% (334/601) || +3.25%
|-
| <code>src/permission/</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/</code> || 77.46% (701/905) || 47.50% (304/640) || +29.96%
|-
| <code>src/relays/</code> || 60.22% (448/744) || 47.58% (216/454) || +12.64%
|-
| <code>src/sensors/</code> || 75.70% (1748/2309) || 54.76% (656/1198) || +20.95%
|-
| <code>src/simulator/</code> || 3.07% (10/326) || 2.05% (4/195) || +1.02%
|-
| <code>src/test_server/</code> || 67.93% (822/1210) || 59.67% (429/719) || +8.27%
|-
| <code>src/thermal/</code> || 88.45% (1019/1152) || 67.96% (437/643) || +20.49%
|-
| <code>src/utilities/</code> || 80.91% (1187/1467) || 75.10% (564/751) || +5.81%
|-
| <code>src/watchmen/</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/</code> || 86.10% (700/813) || 71.18% (331/465) || +14.92%
|}

{| class="wikitable sortable"
|+ Detailed File Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! File Path !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|-
| <code>src/bin/aquarium_client.rs</code> || 0.00% (0/117) || 0.00% (0/98) || +0.00%
|-
| <code>src/bin/aquarium_commissioning.rs</code> || 0.00% (0/426) || 0.00% (0/315) || +0.00%
|-
| <code>src/bin/aquarium_test_server.rs</code> || 0.00% (0/54) || 0.00% (0/44) || +0.00%
|-
| <code>src/database/database_interface_feed_trait.rs</code> || 77.86% (102/131) || 58.06% (54/93) || +19.80%
|-
| <code>src/database/pingable.rs</code> || 44.44% (4/9) || 33.33% (2/6) || +11.11%
|-
| <code>src/database/sql_interface.rs</code> || 65.79% (250/380) || 48.57% (119/245) || +17.22%
|-
| <code>src/database/sql_interface_balling.rs</code> || 69.31% (140/202) || 53.91% (69/128) || +15.40%
|-
| <code>src/database/sql_interface_data.rs</code> || 60.76% (48/79) || 59.62% (31/52) || +1.14%
|-
| <code>src/database/sql_interface_feed.rs</code> || 63.70% (186/292) || 45.00% (90/200) || +18.70%
|-
| <code>src/database/sql_interface_heating_set_vals.rs</code> || 66.12% (80/121) || 37.97% (30/79) || +28.15%
|-
| <code>src/database/sql_interface_heating_stats.rs</code> || 77.65% (139/179) || 67.59% (73/108) || +10.06%
|-
| <code>src/database/sql_interface_heating_stats_data_transfer.rs</code> || 100.00% (7/7) || 100.00% (2/2) || +0.00%
|-
| <code>src/database/sql_interface_midnight.rs</code> || 100.00% (8/8) || 100.00% (4/4) || +0.00%
|-
| <code>src/database/sql_interface_refill.rs</code> || 66.94% (83/124) || 57.14% (48/84) || +9.80%
|-
| <code>src/database/sql_interface_schedule.rs</code> || 85.54% (142/166) || 69.16% (74/107) || +16.38%
|-
| <code>src/database/sql_interface_test_utils.rs</code> || 100.00% (10/10) || 100.00% (5/5) || +0.00%
|-
| <code>src/database/sql_interface_ventilation_set_vals.rs</code> || 63.64% (84/132) || 35.71% (30/84) || +27.92%
|-
| <code>src/dispatch/ipc_message.rs</code> || 0.00% (0/51) || 0.00% (0/41) || +0.00%
|-
| <code>src/dispatch/messaging.rs</code> || 100.00% (44/44) || 80.00% (24/30) || +20.00%
|-
| <code>src/food/feed.rs</code> || 86.40% (305/353) || 62.65% (104/166) || +23.75%
|-
| <code>src/food/feed_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/food/feed_profile.rs</code> || 100.00% (100/100) || 100.00% (4/4) || +0.00%
|-
| <code>src/food/feed_schedule_entry.rs</code> || 97.62% (82/84) || 100.00% (10/10) || -2.38%
|-
| <code>src/food/food_injection.rs</code> || 62.43% (113/181) || 56.64% (64/113) || +5.79%
|-
| <code>src/food/food_injection_actuator_state.rs</code> || 61.11% (11/18) || 54.55% (6/11) || +6.57%
|-
| <code>src/food/food_injection_signals.rs</code> || 62.50% (100/160) || 48.08% (50/104) || +14.42%
|-
| <code>src/launch/config_app.rs</code> || 82.35% (98/119) || 57.14% (44/77) || +25.21%
|-
| <code>src/launch/execution_config.rs</code> || 86.30% (63/73) || 72.34% (34/47) || +13.96%
|-
| <code>src/launch/pid_file.rs</code> || 96.67% (58/60) || 77.14% (27/35) || +19.52%
|-
| <code>src/launch/run.rs</code> || 83.40% (725/869) || 58.74% (306/521) || +24.66%
|-
| <code>src/mineral/balling.rs</code> || 88.08% (340/386) || 61.08% (135/221) || +27.00%
|-
| <code>src/mineral/balling_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/mineral/balling_profile.rs</code> || 100.00% (71/71) || 100.00% (18/18) || +0.00%
|-
| <code>src/mineral/balling_set_val.rs</code> || 77.97% (46/59) || 44.44% (24/54) || +33.53%
|-
| <code>src/mocks/mock_dht.rs</code> || 74.07% (40/54) || 64.71% (22/34) || +9.36%
|-
| <code>src/mocks/mock_food_injection.rs</code> || 83.33% (20/24) || 75.00% (12/16) || +8.33%
|-
| <code>src/mocks/mock_i2c_interface.rs</code> || 32.50% (13/40) || 28.00% (7/25) || +4.50%
|-
| <code>src/mocks/mock_peristaltic_pump.rs</code> || 85.00% (17/20) || 72.73% (8/11) || +12.27%
|-
| <code>src/mocks/mock_relay_manager.rs</code> || 82.50% (33/40) || 75.86% (22/29) || +6.64%
|-
| <code>src/mocks/mock_sql_interface.rs</code> || 66.21% (241/364) || 63.81% (134/210) || +2.40%
|-
| <code>src/mocks/mock_water_injection.rs</code> || 82.61% (19/23) || 75.00% (12/16) || +7.61%
|-
| <code>src/permission/process_privileges.rs</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/recorder.rs</code> || 84.77% (590/696) || 54.12% (269/497) || +30.65%
|-
| <code>src/recorder/recorder_channels.rs</code> || 58.82% (10/17) || 45.45% (5/11) || +13.37%
|-
| <code>src/recorder/recorder_data_frame.rs</code> || 52.66% (101/192) || 22.31% (27/121) || +30.35%
|-
| <code>src/relays/actuator_state.rs</code> || 74.07% (20/27) || 75.00% (15/20) || -0.93%
|-
| <code>src/relays/aquarium_device.rs</code> || 66.67% (14/21) || 68.75% (11/16) || -2.08%
|-
| <code>src/relays/relay_manager.rs</code> || 58.46% (394/674) || 45.43% (179/394) || +13.03%
|-
| <code>src/relays/relay_manager_channels.rs</code> || 90.91% (20/22) || 45.83% (11/24) || +45.08%
|-
| <code>src/sensors/atlas_scientific.rs</code> || 74.77% (329/440) || 55.42% (92/166) || +19.35%
|-
| <code>src/sensors/atlas_scientific_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/dht.rs</code> || 75.00% (105/140) || 53.64% (59/110) || +21.36%
|-
| <code>src/sensors/dht_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/ds18b20.rs</code> || 74.55% (123/165) || 51.09% (47/92) || +23.46%
|-
| <code>src/sensors/ds18b20_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/i2c_interface.rs</code> || 76.54% (362/473) || 57.51% (153/266) || +19.03%
|-
| <code>src/sensors/i2c_interface_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/sensor_manager.rs</code> || 76.10% (761/1000) || 54.34% (282/519) || +21.76%
|-
| <code>src/sensors/sensor_manager_channels.rs</code> || 84.62% (33/39) || 75.00% (9/12) || +9.62%
|-
| <code>src/thermal/heating.rs</code> || 90.96% (332/365) || 68.60% (148/216) || +22.36%
|-
| <code>src/thermal/heating_actuation.rs</code> || 84.47% (87/103) || 67.24% (39/58) || +17.23%
|-
| <code>src/thermal/heating_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/heating_set_vals.rs</code> || 87.50% (35/40) || 64.29% (18/28) || +23.21%
|-
| <code>src/thermal/heating_stats_entry.rs</code> || 94.67% (142/150) || 82.22% (74/90) || +12.44%
|-
| <code>src/thermal/saw_tooth_profile.rs</code> || 100.00% (64/64) || 100.00% (23/23) || +0.00%
|-
| <code>src/thermal/saw_tooth_profile_config.rs</code> || 70.83% (17/24) || 50.00% (7/14) || +20.83%
|-
| <code>src/thermal/temperature_gradient.rs</code> || 100.00% (64/64) || 100.00% (32/32) || +0.00%
|-
| <code>src/thermal/thermal_control_status.rs</code> || 81.25% (26/32) || 58.82% (10/17) || +22.43%
|-
| <code>src/thermal/ventilation.rs</code> || 87.67% (192/219) || 61.16% (74/121) || +26.51%
|-
| <code>src/thermal/ventilation_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/ventilation_set_vals.rs</code> || 58.82% (30/51) || 58.82% (20/34) || +0.00%
|-
| <code>src/utilities/config.rs</code> || 76.99% (830/1078) || 72.84% (437/600) || +4.15%
|-
| <code>src/utilities/spin_sleeper.rs</code> || 79.17% (19/24) || 69.23% (9/13) || +9.94%
|-
| <code>src/utilities/thread_builder.rs</code> || 92.59% (25/27) || 78.57% (11/14) || +14.02%
|-
| <code>src/watchmen/monitors.rs</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/refill.rs</code> || 86.81% (447/515) || 69.45% (216/311) || +17.36%
|-
| <code>src/water/refill_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/water/tank_level_switch.rs</code> || 84.14% (191/227) || 74.47% (105/141) || +9.67%
|-
| <code>src/water/tank_level_switch_signals.rs</code> || 90.36% (75/83) || 86.96% (40/46) || +3.40%
|}

== System tests using the simulator ==
Running the application in simulator mode.

Control application

2026-07-31T17:15:34Z

Uwe: /* Using llvm-cov */

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.

= Requirements =

The requirement are structured in two levels:
* system requirements
* software requirements

The requirements coverage report is generated with the following command: <code>oft trace doc src tests -o Html > doc/req/coverage.html</code>

The linkage of the software requirements to the implementation and related test cases has been reverse engineered using the following two prompts for each function group:

<blockquote>Check all software requirements of thermal.md if you can find the matching implementations and tests.</blockquote>

<blockquote>Now do the reverse: Go through the implementation and test cases in src/sensors and the integration tests in tests/sensors and label every test case and at least every function linking to a matching software requirement from sensors.md.</blockquote>

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

The application makes [[use of an asynchronous runtime for the main application]].

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

= Development environment =
== Install Rust ==
<code>curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh</code>

== Install additional development libraries ==
<code>sudo apt-get install -y libudev-dev pkg-config</code>

== Build time ==
Building the release on a Raspberry Pi 4 takes around 16 minutes.

= Test strategy =
== Unit tests ==
Located within the implementation code files within <code>src</code>.

== Integration tests in test ==
Separated from implementation code to the <code>test</code> folder.

== Code coverage measurement ==
=== Using tarpaulin ===
<code>cargo tarpaulin --features "test-utils" --out Html</code>

The measurement takes app. 22 minutes.

=== Using llvm-cov ===
<code>cargo llvm-cov --features "test-utils" --html --ignore-filename-regex '(main\.rs|.*_channels\.rs|mock.*\.rs|pingable\.rs|privilege_check\.rs)'</code>

The excluded files contain primarily debug functionality which distorts the coverage measurement and where adding test cases would be meaningless.

The measurements takes app. 8 minutes.

=== Comparing the results from llvm-cov and tarpaulin ===
Based on commit <code>8f557814f679c30ebd70e181f2a3f996ce0e295c</code>.

{| class="wikitable sortable"
|+ Module Summary Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! Subsystem / Module !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|- style="font-weight:bold; background-color:#f0f0f0;"
| '''TOTAL (All Application Source Files)''' || 71.53% (11216/15681) || 54.48% (4929/9047) || +17.04%
|-
| <code>src/bin/</code> || 0.00% (0/597) || 0.00% (0/457) || +0.00%
|-
| <code>src/database/</code> || 69.73% (1283/1840) || 52.72% (631/1197) || +17.01%
|-
| <code>src/dispatch/</code> || 46.32% (44/95) || 33.80% (24/71) || +12.51%
|-
| <code>src/food/</code> || 79.06% (721/912) || 58.80% (244/415) || +20.26%
|-
| <code>src/launch/</code> || 84.06% (944/1123) || 59.48% (411/691) || +24.58%
|-
| <code>src/mineral/</code> || 88.11% (467/530) || 60.33% (181/300) || +27.78%
|-
| <code>src/mocks/</code> || 58.82% (610/1037) || 55.57% (334/601) || +3.25%
|-
| <code>src/permission/</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/</code> || 77.46% (701/905) || 47.50% (304/640) || +29.96%
|-
| <code>src/relays/</code> || 60.22% (448/744) || 47.58% (216/454) || +12.64%
|-
| <code>src/sensors/</code> || 75.70% (1748/2309) || 54.76% (656/1198) || +20.95%
|-
| <code>src/simulator/</code> || 3.07% (10/326) || 2.05% (4/195) || +1.02%
|-
| <code>src/test_server/</code> || 67.93% (822/1210) || 59.67% (429/719) || +8.27%
|-
| <code>src/thermal/</code> || 88.45% (1019/1152) || 67.96% (437/643) || +20.49%
|-
| <code>src/utilities/</code> || 80.91% (1187/1467) || 75.10% (564/751) || +5.81%
|-
| <code>src/watchmen/</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/</code> || 86.10% (700/813) || 71.18% (331/465) || +14.92%
|}

{| class="wikitable sortable"
|+ Detailed File Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! File Path !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|-
| <code>src/bin/aquarium_client.rs</code> || 0.00% (0/117) || 0.00% (0/98) || +0.00%
|-
| <code>src/bin/aquarium_commissioning.rs</code> || 0.00% (0/426) || 0.00% (0/315) || +0.00%
|-
| <code>src/bin/aquarium_test_server.rs</code> || 0.00% (0/54) || 0.00% (0/44) || +0.00%
|-
| <code>src/database/database_interface_feed_trait.rs</code> || 77.86% (102/131) || 58.06% (54/93) || +19.80%
|-
| <code>src/database/pingable.rs</code> || 44.44% (4/9) || 33.33% (2/6) || +11.11%
|-
| <code>src/database/sql_interface.rs</code> || 65.79% (250/380) || 48.57% (119/245) || +17.22%
|-
| <code>src/database/sql_interface_balling.rs</code> || 69.31% (140/202) || 53.91% (69/128) || +15.40%
|-
| <code>src/database/sql_interface_data.rs</code> || 60.76% (48/79) || 59.62% (31/52) || +1.14%
|-
| <code>src/database/sql_interface_feed.rs</code> || 63.70% (186/292) || 45.00% (90/200) || +18.70%
|-
| <code>src/database/sql_interface_heating_set_vals.rs</code> || 66.12% (80/121) || 37.97% (30/79) || +28.15%
|-
| <code>src/database/sql_interface_heating_stats.rs</code> || 77.65% (139/179) || 67.59% (73/108) || +10.06%
|-
| <code>src/database/sql_interface_heating_stats_data_transfer.rs</code> || 100.00% (7/7) || 100.00% (2/2) || +0.00%
|-
| <code>src/database/sql_interface_midnight.rs</code> || 100.00% (8/8) || 100.00% (4/4) || +0.00%
|-
| <code>src/database/sql_interface_refill.rs</code> || 66.94% (83/124) || 57.14% (48/84) || +9.80%
|-
| <code>src/database/sql_interface_schedule.rs</code> || 85.54% (142/166) || 69.16% (74/107) || +16.38%
|-
| <code>src/database/sql_interface_test_utils.rs</code> || 100.00% (10/10) || 100.00% (5/5) || +0.00%
|-
| <code>src/database/sql_interface_ventilation_set_vals.rs</code> || 63.64% (84/132) || 35.71% (30/84) || +27.92%
|-
| <code>src/dispatch/ipc_message.rs</code> || 0.00% (0/51) || 0.00% (0/41) || +0.00%
|-
| <code>src/dispatch/messaging.rs</code> || 100.00% (44/44) || 80.00% (24/30) || +20.00%
|-
| <code>src/food/feed.rs</code> || 86.40% (305/353) || 62.65% (104/166) || +23.75%
|-
| <code>src/food/feed_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/food/feed_profile.rs</code> || 100.00% (100/100) || 100.00% (4/4) || +0.00%
|-
| <code>src/food/feed_schedule_entry.rs</code> || 97.62% (82/84) || 100.00% (10/10) || -2.38%
|-
| <code>src/food/food_injection.rs</code> || 62.43% (113/181) || 56.64% (64/113) || +5.79%
|-
| <code>src/food/food_injection_actuator_state.rs</code> || 61.11% (11/18) || 54.55% (6/11) || +6.57%
|-
| <code>src/food/food_injection_signals.rs</code> || 62.50% (100/160) || 48.08% (50/104) || +14.42%
|-
| <code>src/launch/config_app.rs</code> || 82.35% (98/119) || 57.14% (44/77) || +25.21%
|-
| <code>src/launch/execution_config.rs</code> || 86.30% (63/73) || 72.34% (34/47) || +13.96%
|-
| <code>src/launch/pid_file.rs</code> || 96.67% (58/60) || 77.14% (27/35) || +19.52%
|-
| <code>src/launch/run.rs</code> || 83.40% (725/869) || 58.74% (306/521) || +24.66%
|-
| <code>src/mineral/balling.rs</code> || 88.08% (340/386) || 61.08% (135/221) || +27.00%
|-
| <code>src/mineral/balling_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/mineral/balling_profile.rs</code> || 100.00% (71/71) || 100.00% (18/18) || +0.00%
|-
| <code>src/mineral/balling_set_val.rs</code> || 77.97% (46/59) || 44.44% (24/54) || +33.53%
|-
| <code>src/mocks/mock_dht.rs</code> || 74.07% (40/54) || 64.71% (22/34) || +9.36%
|-
| <code>src/mocks/mock_food_injection.rs</code> || 83.33% (20/24) || 75.00% (12/16) || +8.33%
|-
| <code>src/mocks/mock_i2c_interface.rs</code> || 32.50% (13/40) || 28.00% (7/25) || +4.50%
|-
| <code>src/mocks/mock_peristaltic_pump.rs</code> || 85.00% (17/20) || 72.73% (8/11) || +12.27%
|-
| <code>src/mocks/mock_relay_manager.rs</code> || 82.50% (33/40) || 75.86% (22/29) || +6.64%
|-
| <code>src/mocks/mock_sql_interface.rs</code> || 66.21% (241/364) || 63.81% (134/210) || +2.40%
|-
| <code>src/mocks/mock_water_injection.rs</code> || 82.61% (19/23) || 75.00% (12/16) || +7.61%
|-
| <code>src/permission/process_privileges.rs</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/recorder.rs</code> || 84.77% (590/696) || 54.12% (269/497) || +30.65%
|-
| <code>src/recorder/recorder_channels.rs</code> || 58.82% (10/17) || 45.45% (5/11) || +13.37%
|-
| <code>src/recorder/recorder_data_frame.rs</code> || 52.66% (101/192) || 22.31% (27/121) || +30.35%
|-
| <code>src/relays/actuator_state.rs</code> || 74.07% (20/27) || 75.00% (15/20) || -0.93%
|-
| <code>src/relays/aquarium_device.rs</code> || 66.67% (14/21) || 68.75% (11/16) || -2.08%
|-
| <code>src/relays/relay_manager.rs</code> || 58.46% (394/674) || 45.43% (179/394) || +13.03%
|-
| <code>src/relays/relay_manager_channels.rs</code> || 90.91% (20/22) || 45.83% (11/24) || +45.08%
|-
| <code>src/sensors/atlas_scientific.rs</code> || 74.77% (329/440) || 55.42% (92/166) || +19.35%
|-
| <code>src/sensors/atlas_scientific_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/dht.rs</code> || 75.00% (105/140) || 53.64% (59/110) || +21.36%
|-
| <code>src/sensors/dht_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/ds18b20.rs</code> || 74.55% (123/165) || 51.09% (47/92) || +23.46%
|-
| <code>src/sensors/ds18b20_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/i2c_interface.rs</code> || 76.54% (362/473) || 57.51% (153/266) || +19.03%
|-
| <code>src/sensors/i2c_interface_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/sensor_manager.rs</code> || 76.10% (761/1000) || 54.34% (282/519) || +21.76%
|-
| <code>src/sensors/sensor_manager_channels.rs</code> || 84.62% (33/39) || 75.00% (9/12) || +9.62%
|-
| <code>src/thermal/heating.rs</code> || 90.96% (332/365) || 68.60% (148/216) || +22.36%
|-
| <code>src/thermal/heating_actuation.rs</code> || 84.47% (87/103) || 67.24% (39/58) || +17.23%
|-
| <code>src/thermal/heating_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/heating_set_vals.rs</code> || 87.50% (35/40) || 64.29% (18/28) || +23.21%
|-
| <code>src/thermal/heating_stats_entry.rs</code> || 94.67% (142/150) || 82.22% (74/90) || +12.44%
|-
| <code>src/thermal/saw_tooth_profile.rs</code> || 100.00% (64/64) || 100.00% (23/23) || +0.00%
|-
| <code>src/thermal/saw_tooth_profile_config.rs</code> || 70.83% (17/24) || 50.00% (7/14) || +20.83%
|-
| <code>src/thermal/temperature_gradient.rs</code> || 100.00% (64/64) || 100.00% (32/32) || +0.00%
|-
| <code>src/thermal/thermal_control_status.rs</code> || 81.25% (26/32) || 58.82% (10/17) || +22.43%
|-
| <code>src/thermal/ventilation.rs</code> || 87.67% (192/219) || 61.16% (74/121) || +26.51%
|-
| <code>src/thermal/ventilation_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/ventilation_set_vals.rs</code> || 58.82% (30/51) || 58.82% (20/34) || +0.00%
|-
| <code>src/utilities/config.rs</code> || 76.99% (830/1078) || 72.84% (437/600) || +4.15%
|-
| <code>src/utilities/spin_sleeper.rs</code> || 79.17% (19/24) || 69.23% (9/13) || +9.94%
|-
| <code>src/utilities/thread_builder.rs</code> || 92.59% (25/27) || 78.57% (11/14) || +14.02%
|-
| <code>src/watchmen/monitors.rs</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/refill.rs</code> || 86.81% (447/515) || 69.45% (216/311) || +17.36%
|-
| <code>src/water/refill_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/water/tank_level_switch.rs</code> || 84.14% (191/227) || 74.47% (105/141) || +9.67%
|-
| <code>src/water/tank_level_switch_signals.rs</code> || 90.36% (75/83) || 86.96% (40/46) || +3.40%
|}

== System tests using the simulator ==
Running the application in simulator mode.

Control application

2026-07-31T06:18:08Z

Uwe: /* Code coverage measurement */

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.

= Requirements =

The requirement are structured in two levels:
* system requirements
* software requirements

The requirements coverage report is generated with the following command: <code>oft trace doc src tests -o Html > doc/req/coverage.html</code>

The linkage of the software requirements to the implementation and related test cases has been reverse engineered using the following two prompts for each function group:

<blockquote>Check all software requirements of thermal.md if you can find the matching implementations and tests.</blockquote>

<blockquote>Now do the reverse: Go through the implementation and test cases in src/sensors and the integration tests in tests/sensors and label every test case and at least every function linking to a matching software requirement from sensors.md.</blockquote>

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

The application makes [[use of an asynchronous runtime for the main application]].

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

= Development environment =
== Install Rust ==
<code>curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh</code>

== Install additional development libraries ==
<code>sudo apt-get install -y libudev-dev pkg-config</code>

== Build time ==
Building the release on a Raspberry Pi 4 takes around 16 minutes.

= Test strategy =
== Unit tests ==
Located within the implementation code files within <code>src</code>.

== Integration tests in test ==
Separated from implementation code to the <code>test</code> folder.

== Code coverage measurement ==
=== Using tarpaulin ===
<code>cargo tarpaulin --features "test-utils" --out Html</code>

The measurement takes app. 22 minutes.

=== Using llvm-cov ===
<code>cargo llvm-cov --features "test-utils" --html --ignore-filename-regex '(main\.rs|.*_channels\.rs|mock.*\.rs|pingable\.rs)'</code>

The excluded files contain primarily debug functionality which distorts the coverage measurement and where adding test cases would be meaningless.

The measurements takes app. 8 minutes.
=== Comparing the results from llvm-cov and tarpaulin ===
Based on commit <code>8f557814f679c30ebd70e181f2a3f996ce0e295c</code>.

{| class="wikitable sortable"
|+ Module Summary Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! Subsystem / Module !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|- style="font-weight:bold; background-color:#f0f0f0;"
| '''TOTAL (All Application Source Files)''' || 71.53% (11216/15681) || 54.48% (4929/9047) || +17.04%
|-
| <code>src/bin/</code> || 0.00% (0/597) || 0.00% (0/457) || +0.00%
|-
| <code>src/database/</code> || 69.73% (1283/1840) || 52.72% (631/1197) || +17.01%
|-
| <code>src/dispatch/</code> || 46.32% (44/95) || 33.80% (24/71) || +12.51%
|-
| <code>src/food/</code> || 79.06% (721/912) || 58.80% (244/415) || +20.26%
|-
| <code>src/launch/</code> || 84.06% (944/1123) || 59.48% (411/691) || +24.58%
|-
| <code>src/mineral/</code> || 88.11% (467/530) || 60.33% (181/300) || +27.78%
|-
| <code>src/mocks/</code> || 58.82% (610/1037) || 55.57% (334/601) || +3.25%
|-
| <code>src/permission/</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/</code> || 77.46% (701/905) || 47.50% (304/640) || +29.96%
|-
| <code>src/relays/</code> || 60.22% (448/744) || 47.58% (216/454) || +12.64%
|-
| <code>src/sensors/</code> || 75.70% (1748/2309) || 54.76% (656/1198) || +20.95%
|-
| <code>src/simulator/</code> || 3.07% (10/326) || 2.05% (4/195) || +1.02%
|-
| <code>src/test_server/</code> || 67.93% (822/1210) || 59.67% (429/719) || +8.27%
|-
| <code>src/thermal/</code> || 88.45% (1019/1152) || 67.96% (437/643) || +20.49%
|-
| <code>src/utilities/</code> || 80.91% (1187/1467) || 75.10% (564/751) || +5.81%
|-
| <code>src/watchmen/</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/</code> || 86.10% (700/813) || 71.18% (331/465) || +14.92%
|}

{| class="wikitable sortable"
|+ Detailed File Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! File Path !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|-
| <code>src/bin/aquarium_client.rs</code> || 0.00% (0/117) || 0.00% (0/98) || +0.00%
|-
| <code>src/bin/aquarium_commissioning.rs</code> || 0.00% (0/426) || 0.00% (0/315) || +0.00%
|-
| <code>src/bin/aquarium_test_server.rs</code> || 0.00% (0/54) || 0.00% (0/44) || +0.00%
|-
| <code>src/database/database_interface_feed_trait.rs</code> || 77.86% (102/131) || 58.06% (54/93) || +19.80%
|-
| <code>src/database/pingable.rs</code> || 44.44% (4/9) || 33.33% (2/6) || +11.11%
|-
| <code>src/database/sql_interface.rs</code> || 65.79% (250/380) || 48.57% (119/245) || +17.22%
|-
| <code>src/database/sql_interface_balling.rs</code> || 69.31% (140/202) || 53.91% (69/128) || +15.40%
|-
| <code>src/database/sql_interface_data.rs</code> || 60.76% (48/79) || 59.62% (31/52) || +1.14%
|-
| <code>src/database/sql_interface_feed.rs</code> || 63.70% (186/292) || 45.00% (90/200) || +18.70%
|-
| <code>src/database/sql_interface_heating_set_vals.rs</code> || 66.12% (80/121) || 37.97% (30/79) || +28.15%
|-
| <code>src/database/sql_interface_heating_stats.rs</code> || 77.65% (139/179) || 67.59% (73/108) || +10.06%
|-
| <code>src/database/sql_interface_heating_stats_data_transfer.rs</code> || 100.00% (7/7) || 100.00% (2/2) || +0.00%
|-
| <code>src/database/sql_interface_midnight.rs</code> || 100.00% (8/8) || 100.00% (4/4) || +0.00%
|-
| <code>src/database/sql_interface_refill.rs</code> || 66.94% (83/124) || 57.14% (48/84) || +9.80%
|-
| <code>src/database/sql_interface_schedule.rs</code> || 85.54% (142/166) || 69.16% (74/107) || +16.38%
|-
| <code>src/database/sql_interface_test_utils.rs</code> || 100.00% (10/10) || 100.00% (5/5) || +0.00%
|-
| <code>src/database/sql_interface_ventilation_set_vals.rs</code> || 63.64% (84/132) || 35.71% (30/84) || +27.92%
|-
| <code>src/dispatch/ipc_message.rs</code> || 0.00% (0/51) || 0.00% (0/41) || +0.00%
|-
| <code>src/dispatch/messaging.rs</code> || 100.00% (44/44) || 80.00% (24/30) || +20.00%
|-
| <code>src/food/feed.rs</code> || 86.40% (305/353) || 62.65% (104/166) || +23.75%
|-
| <code>src/food/feed_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/food/feed_profile.rs</code> || 100.00% (100/100) || 100.00% (4/4) || +0.00%
|-
| <code>src/food/feed_schedule_entry.rs</code> || 97.62% (82/84) || 100.00% (10/10) || -2.38%
|-
| <code>src/food/food_injection.rs</code> || 62.43% (113/181) || 56.64% (64/113) || +5.79%
|-
| <code>src/food/food_injection_actuator_state.rs</code> || 61.11% (11/18) || 54.55% (6/11) || +6.57%
|-
| <code>src/food/food_injection_signals.rs</code> || 62.50% (100/160) || 48.08% (50/104) || +14.42%
|-
| <code>src/launch/config_app.rs</code> || 82.35% (98/119) || 57.14% (44/77) || +25.21%
|-
| <code>src/launch/execution_config.rs</code> || 86.30% (63/73) || 72.34% (34/47) || +13.96%
|-
| <code>src/launch/pid_file.rs</code> || 96.67% (58/60) || 77.14% (27/35) || +19.52%
|-
| <code>src/launch/run.rs</code> || 83.40% (725/869) || 58.74% (306/521) || +24.66%
|-
| <code>src/mineral/balling.rs</code> || 88.08% (340/386) || 61.08% (135/221) || +27.00%
|-
| <code>src/mineral/balling_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/mineral/balling_profile.rs</code> || 100.00% (71/71) || 100.00% (18/18) || +0.00%
|-
| <code>src/mineral/balling_set_val.rs</code> || 77.97% (46/59) || 44.44% (24/54) || +33.53%
|-
| <code>src/mocks/mock_dht.rs</code> || 74.07% (40/54) || 64.71% (22/34) || +9.36%
|-
| <code>src/mocks/mock_food_injection.rs</code> || 83.33% (20/24) || 75.00% (12/16) || +8.33%
|-
| <code>src/mocks/mock_i2c_interface.rs</code> || 32.50% (13/40) || 28.00% (7/25) || +4.50%
|-
| <code>src/mocks/mock_peristaltic_pump.rs</code> || 85.00% (17/20) || 72.73% (8/11) || +12.27%
|-
| <code>src/mocks/mock_relay_manager.rs</code> || 82.50% (33/40) || 75.86% (22/29) || +6.64%
|-
| <code>src/mocks/mock_sql_interface.rs</code> || 66.21% (241/364) || 63.81% (134/210) || +2.40%
|-
| <code>src/mocks/mock_water_injection.rs</code> || 82.61% (19/23) || 75.00% (12/16) || +7.61%
|-
| <code>src/permission/process_privileges.rs</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/recorder.rs</code> || 84.77% (590/696) || 54.12% (269/497) || +30.65%
|-
| <code>src/recorder/recorder_channels.rs</code> || 58.82% (10/17) || 45.45% (5/11) || +13.37%
|-
| <code>src/recorder/recorder_data_frame.rs</code> || 52.66% (101/192) || 22.31% (27/121) || +30.35%
|-
| <code>src/relays/actuator_state.rs</code> || 74.07% (20/27) || 75.00% (15/20) || -0.93%
|-
| <code>src/relays/aquarium_device.rs</code> || 66.67% (14/21) || 68.75% (11/16) || -2.08%
|-
| <code>src/relays/relay_manager.rs</code> || 58.46% (394/674) || 45.43% (179/394) || +13.03%
|-
| <code>src/relays/relay_manager_channels.rs</code> || 90.91% (20/22) || 45.83% (11/24) || +45.08%
|-
| <code>src/sensors/atlas_scientific.rs</code> || 74.77% (329/440) || 55.42% (92/166) || +19.35%
|-
| <code>src/sensors/atlas_scientific_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/dht.rs</code> || 75.00% (105/140) || 53.64% (59/110) || +21.36%
|-
| <code>src/sensors/dht_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/ds18b20.rs</code> || 74.55% (123/165) || 51.09% (47/92) || +23.46%
|-
| <code>src/sensors/ds18b20_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/i2c_interface.rs</code> || 76.54% (362/473) || 57.51% (153/266) || +19.03%
|-
| <code>src/sensors/i2c_interface_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/sensor_manager.rs</code> || 76.10% (761/1000) || 54.34% (282/519) || +21.76%
|-
| <code>src/sensors/sensor_manager_channels.rs</code> || 84.62% (33/39) || 75.00% (9/12) || +9.62%
|-
| <code>src/thermal/heating.rs</code> || 90.96% (332/365) || 68.60% (148/216) || +22.36%
|-
| <code>src/thermal/heating_actuation.rs</code> || 84.47% (87/103) || 67.24% (39/58) || +17.23%
|-
| <code>src/thermal/heating_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/heating_set_vals.rs</code> || 87.50% (35/40) || 64.29% (18/28) || +23.21%
|-
| <code>src/thermal/heating_stats_entry.rs</code> || 94.67% (142/150) || 82.22% (74/90) || +12.44%
|-
| <code>src/thermal/saw_tooth_profile.rs</code> || 100.00% (64/64) || 100.00% (23/23) || +0.00%
|-
| <code>src/thermal/saw_tooth_profile_config.rs</code> || 70.83% (17/24) || 50.00% (7/14) || +20.83%
|-
| <code>src/thermal/temperature_gradient.rs</code> || 100.00% (64/64) || 100.00% (32/32) || +0.00%
|-
| <code>src/thermal/thermal_control_status.rs</code> || 81.25% (26/32) || 58.82% (10/17) || +22.43%
|-
| <code>src/thermal/ventilation.rs</code> || 87.67% (192/219) || 61.16% (74/121) || +26.51%
|-
| <code>src/thermal/ventilation_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/ventilation_set_vals.rs</code> || 58.82% (30/51) || 58.82% (20/34) || +0.00%
|-
| <code>src/utilities/config.rs</code> || 76.99% (830/1078) || 72.84% (437/600) || +4.15%
|-
| <code>src/utilities/spin_sleeper.rs</code> || 79.17% (19/24) || 69.23% (9/13) || +9.94%
|-
| <code>src/utilities/thread_builder.rs</code> || 92.59% (25/27) || 78.57% (11/14) || +14.02%
|-
| <code>src/watchmen/monitors.rs</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/refill.rs</code> || 86.81% (447/515) || 69.45% (216/311) || +17.36%
|-
| <code>src/water/refill_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/water/tank_level_switch.rs</code> || 84.14% (191/227) || 74.47% (105/141) || +9.67%
|-
| <code>src/water/tank_level_switch_signals.rs</code> || 90.36% (75/83) || 86.96% (40/46) || +3.40%
|}

== System tests using the simulator ==
Running the application in simulator mode.

Control application

2026-07-26T06:43:49Z

Uwe: /* Requirements */

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.

= Requirements =

The requirement are structured in two levels:
* system requirements
* software requirements

The requirements coverage report is generated with the following command: <code>oft trace doc src tests -o Html > doc/req/coverage.html</code>

The linkage of the software requirements to the implementation and related test cases has been reverse engineered using the following two prompts for each function group:

<blockquote>Check all software requirements of thermal.md if you can find the matching implementations and tests.</blockquote>

<blockquote>Now do the reverse: Go through the implementation and test cases in src/sensors and the integration tests in tests/sensors and label every test case and at least every function linking to a matching software requirement from sensors.md.</blockquote>

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

The application makes [[use of an asynchronous runtime for the main application]].

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

= Development environment =
== Install Rust ==
<code>curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh</code>

== Install additional development libraries ==
<code>sudo apt-get install -y libudev-dev pkg-config</code>

== Build time ==
Building the release on a Raspberry Pi 4 takes around 16 minutes.

= Test strategy =
== Unit tests ==
Located within the implementation code files within <code>src</code>.

== Integration tests in test ==
Separated from implementation code to the <code>test</code> folder.

== Code coverage measurement ==
=== Using tarpaulin ===
<code>cargo tarpaulin --features "test-utils" --out Html</code>

The measurement takes app. 22 minutes.

=== Using llvm-cov ===
<code>cargo llvm-cov --features "test-utils" --html </code>

The measurements takes app. 8 minutes.
=== Comparing the results from llvm-cov and tarpaulin ===
Based on commit <code>8f557814f679c30ebd70e181f2a3f996ce0e295c</code>.

{| class="wikitable sortable"
|+ Module Summary Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! Subsystem / Module !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|- style="font-weight:bold; background-color:#f0f0f0;"
| '''TOTAL (All Application Source Files)''' || 71.53% (11216/15681) || 54.48% (4929/9047) || +17.04%
|-
| <code>src/bin/</code> || 0.00% (0/597) || 0.00% (0/457) || +0.00%
|-
| <code>src/database/</code> || 69.73% (1283/1840) || 52.72% (631/1197) || +17.01%
|-
| <code>src/dispatch/</code> || 46.32% (44/95) || 33.80% (24/71) || +12.51%
|-
| <code>src/food/</code> || 79.06% (721/912) || 58.80% (244/415) || +20.26%
|-
| <code>src/launch/</code> || 84.06% (944/1123) || 59.48% (411/691) || +24.58%
|-
| <code>src/mineral/</code> || 88.11% (467/530) || 60.33% (181/300) || +27.78%
|-
| <code>src/mocks/</code> || 58.82% (610/1037) || 55.57% (334/601) || +3.25%
|-
| <code>src/permission/</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/</code> || 77.46% (701/905) || 47.50% (304/640) || +29.96%
|-
| <code>src/relays/</code> || 60.22% (448/744) || 47.58% (216/454) || +12.64%
|-
| <code>src/sensors/</code> || 75.70% (1748/2309) || 54.76% (656/1198) || +20.95%
|-
| <code>src/simulator/</code> || 3.07% (10/326) || 2.05% (4/195) || +1.02%
|-
| <code>src/test_server/</code> || 67.93% (822/1210) || 59.67% (429/719) || +8.27%
|-
| <code>src/thermal/</code> || 88.45% (1019/1152) || 67.96% (437/643) || +20.49%
|-
| <code>src/utilities/</code> || 80.91% (1187/1467) || 75.10% (564/751) || +5.81%
|-
| <code>src/watchmen/</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/</code> || 86.10% (700/813) || 71.18% (331/465) || +14.92%
|}

{| class="wikitable sortable"
|+ Detailed File Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! File Path !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|-
| <code>src/bin/aquarium_client.rs</code> || 0.00% (0/117) || 0.00% (0/98) || +0.00%
|-
| <code>src/bin/aquarium_commissioning.rs</code> || 0.00% (0/426) || 0.00% (0/315) || +0.00%
|-
| <code>src/bin/aquarium_test_server.rs</code> || 0.00% (0/54) || 0.00% (0/44) || +0.00%
|-
| <code>src/database/database_interface_feed_trait.rs</code> || 77.86% (102/131) || 58.06% (54/93) || +19.80%
|-
| <code>src/database/pingable.rs</code> || 44.44% (4/9) || 33.33% (2/6) || +11.11%
|-
| <code>src/database/sql_interface.rs</code> || 65.79% (250/380) || 48.57% (119/245) || +17.22%
|-
| <code>src/database/sql_interface_balling.rs</code> || 69.31% (140/202) || 53.91% (69/128) || +15.40%
|-
| <code>src/database/sql_interface_data.rs</code> || 60.76% (48/79) || 59.62% (31/52) || +1.14%
|-
| <code>src/database/sql_interface_feed.rs</code> || 63.70% (186/292) || 45.00% (90/200) || +18.70%
|-
| <code>src/database/sql_interface_heating_set_vals.rs</code> || 66.12% (80/121) || 37.97% (30/79) || +28.15%
|-
| <code>src/database/sql_interface_heating_stats.rs</code> || 77.65% (139/179) || 67.59% (73/108) || +10.06%
|-
| <code>src/database/sql_interface_heating_stats_data_transfer.rs</code> || 100.00% (7/7) || 100.00% (2/2) || +0.00%
|-
| <code>src/database/sql_interface_midnight.rs</code> || 100.00% (8/8) || 100.00% (4/4) || +0.00%
|-
| <code>src/database/sql_interface_refill.rs</code> || 66.94% (83/124) || 57.14% (48/84) || +9.80%
|-
| <code>src/database/sql_interface_schedule.rs</code> || 85.54% (142/166) || 69.16% (74/107) || +16.38%
|-
| <code>src/database/sql_interface_test_utils.rs</code> || 100.00% (10/10) || 100.00% (5/5) || +0.00%
|-
| <code>src/database/sql_interface_ventilation_set_vals.rs</code> || 63.64% (84/132) || 35.71% (30/84) || +27.92%
|-
| <code>src/dispatch/ipc_message.rs</code> || 0.00% (0/51) || 0.00% (0/41) || +0.00%
|-
| <code>src/dispatch/messaging.rs</code> || 100.00% (44/44) || 80.00% (24/30) || +20.00%
|-
| <code>src/food/feed.rs</code> || 86.40% (305/353) || 62.65% (104/166) || +23.75%
|-
| <code>src/food/feed_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/food/feed_profile.rs</code> || 100.00% (100/100) || 100.00% (4/4) || +0.00%
|-
| <code>src/food/feed_schedule_entry.rs</code> || 97.62% (82/84) || 100.00% (10/10) || -2.38%
|-
| <code>src/food/food_injection.rs</code> || 62.43% (113/181) || 56.64% (64/113) || +5.79%
|-
| <code>src/food/food_injection_actuator_state.rs</code> || 61.11% (11/18) || 54.55% (6/11) || +6.57%
|-
| <code>src/food/food_injection_signals.rs</code> || 62.50% (100/160) || 48.08% (50/104) || +14.42%
|-
| <code>src/launch/config_app.rs</code> || 82.35% (98/119) || 57.14% (44/77) || +25.21%
|-
| <code>src/launch/execution_config.rs</code> || 86.30% (63/73) || 72.34% (34/47) || +13.96%
|-
| <code>src/launch/pid_file.rs</code> || 96.67% (58/60) || 77.14% (27/35) || +19.52%
|-
| <code>src/launch/run.rs</code> || 83.40% (725/869) || 58.74% (306/521) || +24.66%
|-
| <code>src/mineral/balling.rs</code> || 88.08% (340/386) || 61.08% (135/221) || +27.00%
|-
| <code>src/mineral/balling_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/mineral/balling_profile.rs</code> || 100.00% (71/71) || 100.00% (18/18) || +0.00%
|-
| <code>src/mineral/balling_set_val.rs</code> || 77.97% (46/59) || 44.44% (24/54) || +33.53%
|-
| <code>src/mocks/mock_dht.rs</code> || 74.07% (40/54) || 64.71% (22/34) || +9.36%
|-
| <code>src/mocks/mock_food_injection.rs</code> || 83.33% (20/24) || 75.00% (12/16) || +8.33%
|-
| <code>src/mocks/mock_i2c_interface.rs</code> || 32.50% (13/40) || 28.00% (7/25) || +4.50%
|-
| <code>src/mocks/mock_peristaltic_pump.rs</code> || 85.00% (17/20) || 72.73% (8/11) || +12.27%
|-
| <code>src/mocks/mock_relay_manager.rs</code> || 82.50% (33/40) || 75.86% (22/29) || +6.64%
|-
| <code>src/mocks/mock_sql_interface.rs</code> || 66.21% (241/364) || 63.81% (134/210) || +2.40%
|-
| <code>src/mocks/mock_water_injection.rs</code> || 82.61% (19/23) || 75.00% (12/16) || +7.61%
|-
| <code>src/permission/process_privileges.rs</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/recorder.rs</code> || 84.77% (590/696) || 54.12% (269/497) || +30.65%
|-
| <code>src/recorder/recorder_channels.rs</code> || 58.82% (10/17) || 45.45% (5/11) || +13.37%
|-
| <code>src/recorder/recorder_data_frame.rs</code> || 52.66% (101/192) || 22.31% (27/121) || +30.35%
|-
| <code>src/relays/actuator_state.rs</code> || 74.07% (20/27) || 75.00% (15/20) || -0.93%
|-
| <code>src/relays/aquarium_device.rs</code> || 66.67% (14/21) || 68.75% (11/16) || -2.08%
|-
| <code>src/relays/relay_manager.rs</code> || 58.46% (394/674) || 45.43% (179/394) || +13.03%
|-
| <code>src/relays/relay_manager_channels.rs</code> || 90.91% (20/22) || 45.83% (11/24) || +45.08%
|-
| <code>src/sensors/atlas_scientific.rs</code> || 74.77% (329/440) || 55.42% (92/166) || +19.35%
|-
| <code>src/sensors/atlas_scientific_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/dht.rs</code> || 75.00% (105/140) || 53.64% (59/110) || +21.36%
|-
| <code>src/sensors/dht_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/ds18b20.rs</code> || 74.55% (123/165) || 51.09% (47/92) || +23.46%
|-
| <code>src/sensors/ds18b20_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/i2c_interface.rs</code> || 76.54% (362/473) || 57.51% (153/266) || +19.03%
|-
| <code>src/sensors/i2c_interface_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/sensor_manager.rs</code> || 76.10% (761/1000) || 54.34% (282/519) || +21.76%
|-
| <code>src/sensors/sensor_manager_channels.rs</code> || 84.62% (33/39) || 75.00% (9/12) || +9.62%
|-
| <code>src/thermal/heating.rs</code> || 90.96% (332/365) || 68.60% (148/216) || +22.36%
|-
| <code>src/thermal/heating_actuation.rs</code> || 84.47% (87/103) || 67.24% (39/58) || +17.23%
|-
| <code>src/thermal/heating_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/heating_set_vals.rs</code> || 87.50% (35/40) || 64.29% (18/28) || +23.21%
|-
| <code>src/thermal/heating_stats_entry.rs</code> || 94.67% (142/150) || 82.22% (74/90) || +12.44%
|-
| <code>src/thermal/saw_tooth_profile.rs</code> || 100.00% (64/64) || 100.00% (23/23) || +0.00%
|-
| <code>src/thermal/saw_tooth_profile_config.rs</code> || 70.83% (17/24) || 50.00% (7/14) || +20.83%
|-
| <code>src/thermal/temperature_gradient.rs</code> || 100.00% (64/64) || 100.00% (32/32) || +0.00%
|-
| <code>src/thermal/thermal_control_status.rs</code> || 81.25% (26/32) || 58.82% (10/17) || +22.43%
|-
| <code>src/thermal/ventilation.rs</code> || 87.67% (192/219) || 61.16% (74/121) || +26.51%
|-
| <code>src/thermal/ventilation_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/ventilation_set_vals.rs</code> || 58.82% (30/51) || 58.82% (20/34) || +0.00%
|-
| <code>src/utilities/config.rs</code> || 76.99% (830/1078) || 72.84% (437/600) || +4.15%
|-
| <code>src/utilities/spin_sleeper.rs</code> || 79.17% (19/24) || 69.23% (9/13) || +9.94%
|-
| <code>src/utilities/thread_builder.rs</code> || 92.59% (25/27) || 78.57% (11/14) || +14.02%
|-
| <code>src/watchmen/monitors.rs</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/refill.rs</code> || 86.81% (447/515) || 69.45% (216/311) || +17.36%
|-
| <code>src/water/refill_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/water/tank_level_switch.rs</code> || 84.14% (191/227) || 74.47% (105/141) || +9.67%
|-
| <code>src/water/tank_level_switch_signals.rs</code> || 90.36% (75/83) || 86.96% (40/46) || +3.40%
|}

== System tests using the simulator ==
Running the application in simulator mode.

Control application

2026-07-26T06:41:46Z

Uwe: /* Requirements */

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.

= Requirements =

The requirement are structured in two levels:
* system requirements
* software requirements

The linkage of the software requirements to the implementation and related test cases has been reverse engineered using the following two prompts for each function group:

<blockquote>Check all software requirements of thermal.md if you can find the matching implementations and tests.</blockquote>

<blockquote>Now do the reverse: Go through the implementation and test cases in src/sensors and the integration tests in tests/sensors and label every test case and at least every function linking to a matching software requirement from sensors.md.</blockquote>

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

The application makes [[use of an asynchronous runtime for the main application]].

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

= Development environment =
== Install Rust ==
<code>curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh</code>

== Install additional development libraries ==
<code>sudo apt-get install -y libudev-dev pkg-config</code>

== Build time ==
Building the release on a Raspberry Pi 4 takes around 16 minutes.

= Test strategy =
== Unit tests ==
Located within the implementation code files within <code>src</code>.

== Integration tests in test ==
Separated from implementation code to the <code>test</code> folder.

== Code coverage measurement ==
=== Using tarpaulin ===
<code>cargo tarpaulin --features "test-utils" --out Html</code>

The measurement takes app. 22 minutes.

=== Using llvm-cov ===
<code>cargo llvm-cov --features "test-utils" --html </code>

The measurements takes app. 8 minutes.
=== Comparing the results from llvm-cov and tarpaulin ===
Based on commit <code>8f557814f679c30ebd70e181f2a3f996ce0e295c</code>.

{| class="wikitable sortable"
|+ Module Summary Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! Subsystem / Module !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|- style="font-weight:bold; background-color:#f0f0f0;"
| '''TOTAL (All Application Source Files)''' || 71.53% (11216/15681) || 54.48% (4929/9047) || +17.04%
|-
| <code>src/bin/</code> || 0.00% (0/597) || 0.00% (0/457) || +0.00%
|-
| <code>src/database/</code> || 69.73% (1283/1840) || 52.72% (631/1197) || +17.01%
|-
| <code>src/dispatch/</code> || 46.32% (44/95) || 33.80% (24/71) || +12.51%
|-
| <code>src/food/</code> || 79.06% (721/912) || 58.80% (244/415) || +20.26%
|-
| <code>src/launch/</code> || 84.06% (944/1123) || 59.48% (411/691) || +24.58%
|-
| <code>src/mineral/</code> || 88.11% (467/530) || 60.33% (181/300) || +27.78%
|-
| <code>src/mocks/</code> || 58.82% (610/1037) || 55.57% (334/601) || +3.25%
|-
| <code>src/permission/</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/</code> || 77.46% (701/905) || 47.50% (304/640) || +29.96%
|-
| <code>src/relays/</code> || 60.22% (448/744) || 47.58% (216/454) || +12.64%
|-
| <code>src/sensors/</code> || 75.70% (1748/2309) || 54.76% (656/1198) || +20.95%
|-
| <code>src/simulator/</code> || 3.07% (10/326) || 2.05% (4/195) || +1.02%
|-
| <code>src/test_server/</code> || 67.93% (822/1210) || 59.67% (429/719) || +8.27%
|-
| <code>src/thermal/</code> || 88.45% (1019/1152) || 67.96% (437/643) || +20.49%
|-
| <code>src/utilities/</code> || 80.91% (1187/1467) || 75.10% (564/751) || +5.81%
|-
| <code>src/watchmen/</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/</code> || 86.10% (700/813) || 71.18% (331/465) || +14.92%
|}

{| class="wikitable sortable"
|+ Detailed File Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! File Path !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|-
| <code>src/bin/aquarium_client.rs</code> || 0.00% (0/117) || 0.00% (0/98) || +0.00%
|-
| <code>src/bin/aquarium_commissioning.rs</code> || 0.00% (0/426) || 0.00% (0/315) || +0.00%
|-
| <code>src/bin/aquarium_test_server.rs</code> || 0.00% (0/54) || 0.00% (0/44) || +0.00%
|-
| <code>src/database/database_interface_feed_trait.rs</code> || 77.86% (102/131) || 58.06% (54/93) || +19.80%
|-
| <code>src/database/pingable.rs</code> || 44.44% (4/9) || 33.33% (2/6) || +11.11%
|-
| <code>src/database/sql_interface.rs</code> || 65.79% (250/380) || 48.57% (119/245) || +17.22%
|-
| <code>src/database/sql_interface_balling.rs</code> || 69.31% (140/202) || 53.91% (69/128) || +15.40%
|-
| <code>src/database/sql_interface_data.rs</code> || 60.76% (48/79) || 59.62% (31/52) || +1.14%
|-
| <code>src/database/sql_interface_feed.rs</code> || 63.70% (186/292) || 45.00% (90/200) || +18.70%
|-
| <code>src/database/sql_interface_heating_set_vals.rs</code> || 66.12% (80/121) || 37.97% (30/79) || +28.15%
|-
| <code>src/database/sql_interface_heating_stats.rs</code> || 77.65% (139/179) || 67.59% (73/108) || +10.06%
|-
| <code>src/database/sql_interface_heating_stats_data_transfer.rs</code> || 100.00% (7/7) || 100.00% (2/2) || +0.00%
|-
| <code>src/database/sql_interface_midnight.rs</code> || 100.00% (8/8) || 100.00% (4/4) || +0.00%
|-
| <code>src/database/sql_interface_refill.rs</code> || 66.94% (83/124) || 57.14% (48/84) || +9.80%
|-
| <code>src/database/sql_interface_schedule.rs</code> || 85.54% (142/166) || 69.16% (74/107) || +16.38%
|-
| <code>src/database/sql_interface_test_utils.rs</code> || 100.00% (10/10) || 100.00% (5/5) || +0.00%
|-
| <code>src/database/sql_interface_ventilation_set_vals.rs</code> || 63.64% (84/132) || 35.71% (30/84) || +27.92%
|-
| <code>src/dispatch/ipc_message.rs</code> || 0.00% (0/51) || 0.00% (0/41) || +0.00%
|-
| <code>src/dispatch/messaging.rs</code> || 100.00% (44/44) || 80.00% (24/30) || +20.00%
|-
| <code>src/food/feed.rs</code> || 86.40% (305/353) || 62.65% (104/166) || +23.75%
|-
| <code>src/food/feed_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/food/feed_profile.rs</code> || 100.00% (100/100) || 100.00% (4/4) || +0.00%
|-
| <code>src/food/feed_schedule_entry.rs</code> || 97.62% (82/84) || 100.00% (10/10) || -2.38%
|-
| <code>src/food/food_injection.rs</code> || 62.43% (113/181) || 56.64% (64/113) || +5.79%
|-
| <code>src/food/food_injection_actuator_state.rs</code> || 61.11% (11/18) || 54.55% (6/11) || +6.57%
|-
| <code>src/food/food_injection_signals.rs</code> || 62.50% (100/160) || 48.08% (50/104) || +14.42%
|-
| <code>src/launch/config_app.rs</code> || 82.35% (98/119) || 57.14% (44/77) || +25.21%
|-
| <code>src/launch/execution_config.rs</code> || 86.30% (63/73) || 72.34% (34/47) || +13.96%
|-
| <code>src/launch/pid_file.rs</code> || 96.67% (58/60) || 77.14% (27/35) || +19.52%
|-
| <code>src/launch/run.rs</code> || 83.40% (725/869) || 58.74% (306/521) || +24.66%
|-
| <code>src/mineral/balling.rs</code> || 88.08% (340/386) || 61.08% (135/221) || +27.00%
|-
| <code>src/mineral/balling_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/mineral/balling_profile.rs</code> || 100.00% (71/71) || 100.00% (18/18) || +0.00%
|-
| <code>src/mineral/balling_set_val.rs</code> || 77.97% (46/59) || 44.44% (24/54) || +33.53%
|-
| <code>src/mocks/mock_dht.rs</code> || 74.07% (40/54) || 64.71% (22/34) || +9.36%
|-
| <code>src/mocks/mock_food_injection.rs</code> || 83.33% (20/24) || 75.00% (12/16) || +8.33%
|-
| <code>src/mocks/mock_i2c_interface.rs</code> || 32.50% (13/40) || 28.00% (7/25) || +4.50%
|-
| <code>src/mocks/mock_peristaltic_pump.rs</code> || 85.00% (17/20) || 72.73% (8/11) || +12.27%
|-
| <code>src/mocks/mock_relay_manager.rs</code> || 82.50% (33/40) || 75.86% (22/29) || +6.64%
|-
| <code>src/mocks/mock_sql_interface.rs</code> || 66.21% (241/364) || 63.81% (134/210) || +2.40%
|-
| <code>src/mocks/mock_water_injection.rs</code> || 82.61% (19/23) || 75.00% (12/16) || +7.61%
|-
| <code>src/permission/process_privileges.rs</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/recorder.rs</code> || 84.77% (590/696) || 54.12% (269/497) || +30.65%
|-
| <code>src/recorder/recorder_channels.rs</code> || 58.82% (10/17) || 45.45% (5/11) || +13.37%
|-
| <code>src/recorder/recorder_data_frame.rs</code> || 52.66% (101/192) || 22.31% (27/121) || +30.35%
|-
| <code>src/relays/actuator_state.rs</code> || 74.07% (20/27) || 75.00% (15/20) || -0.93%
|-
| <code>src/relays/aquarium_device.rs</code> || 66.67% (14/21) || 68.75% (11/16) || -2.08%
|-
| <code>src/relays/relay_manager.rs</code> || 58.46% (394/674) || 45.43% (179/394) || +13.03%
|-
| <code>src/relays/relay_manager_channels.rs</code> || 90.91% (20/22) || 45.83% (11/24) || +45.08%
|-
| <code>src/sensors/atlas_scientific.rs</code> || 74.77% (329/440) || 55.42% (92/166) || +19.35%
|-
| <code>src/sensors/atlas_scientific_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/dht.rs</code> || 75.00% (105/140) || 53.64% (59/110) || +21.36%
|-
| <code>src/sensors/dht_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/ds18b20.rs</code> || 74.55% (123/165) || 51.09% (47/92) || +23.46%
|-
| <code>src/sensors/ds18b20_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/i2c_interface.rs</code> || 76.54% (362/473) || 57.51% (153/266) || +19.03%
|-
| <code>src/sensors/i2c_interface_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/sensor_manager.rs</code> || 76.10% (761/1000) || 54.34% (282/519) || +21.76%
|-
| <code>src/sensors/sensor_manager_channels.rs</code> || 84.62% (33/39) || 75.00% (9/12) || +9.62%
|-
| <code>src/thermal/heating.rs</code> || 90.96% (332/365) || 68.60% (148/216) || +22.36%
|-
| <code>src/thermal/heating_actuation.rs</code> || 84.47% (87/103) || 67.24% (39/58) || +17.23%
|-
| <code>src/thermal/heating_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/heating_set_vals.rs</code> || 87.50% (35/40) || 64.29% (18/28) || +23.21%
|-
| <code>src/thermal/heating_stats_entry.rs</code> || 94.67% (142/150) || 82.22% (74/90) || +12.44%
|-
| <code>src/thermal/saw_tooth_profile.rs</code> || 100.00% (64/64) || 100.00% (23/23) || +0.00%
|-
| <code>src/thermal/saw_tooth_profile_config.rs</code> || 70.83% (17/24) || 50.00% (7/14) || +20.83%
|-
| <code>src/thermal/temperature_gradient.rs</code> || 100.00% (64/64) || 100.00% (32/32) || +0.00%
|-
| <code>src/thermal/thermal_control_status.rs</code> || 81.25% (26/32) || 58.82% (10/17) || +22.43%
|-
| <code>src/thermal/ventilation.rs</code> || 87.67% (192/219) || 61.16% (74/121) || +26.51%
|-
| <code>src/thermal/ventilation_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/ventilation_set_vals.rs</code> || 58.82% (30/51) || 58.82% (20/34) || +0.00%
|-
| <code>src/utilities/config.rs</code> || 76.99% (830/1078) || 72.84% (437/600) || +4.15%
|-
| <code>src/utilities/spin_sleeper.rs</code> || 79.17% (19/24) || 69.23% (9/13) || +9.94%
|-
| <code>src/utilities/thread_builder.rs</code> || 92.59% (25/27) || 78.57% (11/14) || +14.02%
|-
| <code>src/watchmen/monitors.rs</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/refill.rs</code> || 86.81% (447/515) || 69.45% (216/311) || +17.36%
|-
| <code>src/water/refill_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/water/tank_level_switch.rs</code> || 84.14% (191/227) || 74.47% (105/141) || +9.67%
|-
| <code>src/water/tank_level_switch_signals.rs</code> || 90.36% (75/83) || 86.96% (40/46) || +3.40%
|}

== System tests using the simulator ==
Running the application in simulator mode.

Control application

2026-07-26T06:38:59Z

Uwe: /* Requirements */

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.

= Requirements =

The linkage of the software requirements to the implementation and related test cases has been reverse engineered using the following two prompts for each function group:

<blockquote>Check all software requirements of thermal.md if you can find the matching implementations and tests.</blockquote>

<blockquote>Now do the reverse: Go through the implementation and test cases in src/sensors and the integration tests in tests/sensors and label every test case and at least every function linking to a matching software requirement from sensors.md.</blockquote>

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

The application makes [[use of an asynchronous runtime for the main application]].

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

= Development environment =
== Install Rust ==
<code>curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh</code>

== Install additional development libraries ==
<code>sudo apt-get install -y libudev-dev pkg-config</code>

== Build time ==
Building the release on a Raspberry Pi 4 takes around 16 minutes.

= Test strategy =
== Unit tests ==
Located within the implementation code files within <code>src</code>.

== Integration tests in test ==
Separated from implementation code to the <code>test</code> folder.

== Code coverage measurement ==
=== Using tarpaulin ===
<code>cargo tarpaulin --features "test-utils" --out Html</code>

The measurement takes app. 22 minutes.

=== Using llvm-cov ===
<code>cargo llvm-cov --features "test-utils" --html </code>

The measurements takes app. 8 minutes.
=== Comparing the results from llvm-cov and tarpaulin ===
Based on commit <code>8f557814f679c30ebd70e181f2a3f996ce0e295c</code>.

{| class="wikitable sortable"
|+ Module Summary Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! Subsystem / Module !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|- style="font-weight:bold; background-color:#f0f0f0;"
| '''TOTAL (All Application Source Files)''' || 71.53% (11216/15681) || 54.48% (4929/9047) || +17.04%
|-
| <code>src/bin/</code> || 0.00% (0/597) || 0.00% (0/457) || +0.00%
|-
| <code>src/database/</code> || 69.73% (1283/1840) || 52.72% (631/1197) || +17.01%
|-
| <code>src/dispatch/</code> || 46.32% (44/95) || 33.80% (24/71) || +12.51%
|-
| <code>src/food/</code> || 79.06% (721/912) || 58.80% (244/415) || +20.26%
|-
| <code>src/launch/</code> || 84.06% (944/1123) || 59.48% (411/691) || +24.58%
|-
| <code>src/mineral/</code> || 88.11% (467/530) || 60.33% (181/300) || +27.78%
|-
| <code>src/mocks/</code> || 58.82% (610/1037) || 55.57% (334/601) || +3.25%
|-
| <code>src/permission/</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/</code> || 77.46% (701/905) || 47.50% (304/640) || +29.96%
|-
| <code>src/relays/</code> || 60.22% (448/744) || 47.58% (216/454) || +12.64%
|-
| <code>src/sensors/</code> || 75.70% (1748/2309) || 54.76% (656/1198) || +20.95%
|-
| <code>src/simulator/</code> || 3.07% (10/326) || 2.05% (4/195) || +1.02%
|-
| <code>src/test_server/</code> || 67.93% (822/1210) || 59.67% (429/719) || +8.27%
|-
| <code>src/thermal/</code> || 88.45% (1019/1152) || 67.96% (437/643) || +20.49%
|-
| <code>src/utilities/</code> || 80.91% (1187/1467) || 75.10% (564/751) || +5.81%
|-
| <code>src/watchmen/</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/</code> || 86.10% (700/813) || 71.18% (331/465) || +14.92%
|}

{| class="wikitable sortable"
|+ Detailed File Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! File Path !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|-
| <code>src/bin/aquarium_client.rs</code> || 0.00% (0/117) || 0.00% (0/98) || +0.00%
|-
| <code>src/bin/aquarium_commissioning.rs</code> || 0.00% (0/426) || 0.00% (0/315) || +0.00%
|-
| <code>src/bin/aquarium_test_server.rs</code> || 0.00% (0/54) || 0.00% (0/44) || +0.00%
|-
| <code>src/database/database_interface_feed_trait.rs</code> || 77.86% (102/131) || 58.06% (54/93) || +19.80%
|-
| <code>src/database/pingable.rs</code> || 44.44% (4/9) || 33.33% (2/6) || +11.11%
|-
| <code>src/database/sql_interface.rs</code> || 65.79% (250/380) || 48.57% (119/245) || +17.22%
|-
| <code>src/database/sql_interface_balling.rs</code> || 69.31% (140/202) || 53.91% (69/128) || +15.40%
|-
| <code>src/database/sql_interface_data.rs</code> || 60.76% (48/79) || 59.62% (31/52) || +1.14%
|-
| <code>src/database/sql_interface_feed.rs</code> || 63.70% (186/292) || 45.00% (90/200) || +18.70%
|-
| <code>src/database/sql_interface_heating_set_vals.rs</code> || 66.12% (80/121) || 37.97% (30/79) || +28.15%
|-
| <code>src/database/sql_interface_heating_stats.rs</code> || 77.65% (139/179) || 67.59% (73/108) || +10.06%
|-
| <code>src/database/sql_interface_heating_stats_data_transfer.rs</code> || 100.00% (7/7) || 100.00% (2/2) || +0.00%
|-
| <code>src/database/sql_interface_midnight.rs</code> || 100.00% (8/8) || 100.00% (4/4) || +0.00%
|-
| <code>src/database/sql_interface_refill.rs</code> || 66.94% (83/124) || 57.14% (48/84) || +9.80%
|-
| <code>src/database/sql_interface_schedule.rs</code> || 85.54% (142/166) || 69.16% (74/107) || +16.38%
|-
| <code>src/database/sql_interface_test_utils.rs</code> || 100.00% (10/10) || 100.00% (5/5) || +0.00%
|-
| <code>src/database/sql_interface_ventilation_set_vals.rs</code> || 63.64% (84/132) || 35.71% (30/84) || +27.92%
|-
| <code>src/dispatch/ipc_message.rs</code> || 0.00% (0/51) || 0.00% (0/41) || +0.00%
|-
| <code>src/dispatch/messaging.rs</code> || 100.00% (44/44) || 80.00% (24/30) || +20.00%
|-
| <code>src/food/feed.rs</code> || 86.40% (305/353) || 62.65% (104/166) || +23.75%
|-
| <code>src/food/feed_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/food/feed_profile.rs</code> || 100.00% (100/100) || 100.00% (4/4) || +0.00%
|-
| <code>src/food/feed_schedule_entry.rs</code> || 97.62% (82/84) || 100.00% (10/10) || -2.38%
|-
| <code>src/food/food_injection.rs</code> || 62.43% (113/181) || 56.64% (64/113) || +5.79%
|-
| <code>src/food/food_injection_actuator_state.rs</code> || 61.11% (11/18) || 54.55% (6/11) || +6.57%
|-
| <code>src/food/food_injection_signals.rs</code> || 62.50% (100/160) || 48.08% (50/104) || +14.42%
|-
| <code>src/launch/config_app.rs</code> || 82.35% (98/119) || 57.14% (44/77) || +25.21%
|-
| <code>src/launch/execution_config.rs</code> || 86.30% (63/73) || 72.34% (34/47) || +13.96%
|-
| <code>src/launch/pid_file.rs</code> || 96.67% (58/60) || 77.14% (27/35) || +19.52%
|-
| <code>src/launch/run.rs</code> || 83.40% (725/869) || 58.74% (306/521) || +24.66%
|-
| <code>src/mineral/balling.rs</code> || 88.08% (340/386) || 61.08% (135/221) || +27.00%
|-
| <code>src/mineral/balling_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/mineral/balling_profile.rs</code> || 100.00% (71/71) || 100.00% (18/18) || +0.00%
|-
| <code>src/mineral/balling_set_val.rs</code> || 77.97% (46/59) || 44.44% (24/54) || +33.53%
|-
| <code>src/mocks/mock_dht.rs</code> || 74.07% (40/54) || 64.71% (22/34) || +9.36%
|-
| <code>src/mocks/mock_food_injection.rs</code> || 83.33% (20/24) || 75.00% (12/16) || +8.33%
|-
| <code>src/mocks/mock_i2c_interface.rs</code> || 32.50% (13/40) || 28.00% (7/25) || +4.50%
|-
| <code>src/mocks/mock_peristaltic_pump.rs</code> || 85.00% (17/20) || 72.73% (8/11) || +12.27%
|-
| <code>src/mocks/mock_relay_manager.rs</code> || 82.50% (33/40) || 75.86% (22/29) || +6.64%
|-
| <code>src/mocks/mock_sql_interface.rs</code> || 66.21% (241/364) || 63.81% (134/210) || +2.40%
|-
| <code>src/mocks/mock_water_injection.rs</code> || 82.61% (19/23) || 75.00% (12/16) || +7.61%
|-
| <code>src/permission/process_privileges.rs</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/recorder.rs</code> || 84.77% (590/696) || 54.12% (269/497) || +30.65%
|-
| <code>src/recorder/recorder_channels.rs</code> || 58.82% (10/17) || 45.45% (5/11) || +13.37%
|-
| <code>src/recorder/recorder_data_frame.rs</code> || 52.66% (101/192) || 22.31% (27/121) || +30.35%
|-
| <code>src/relays/actuator_state.rs</code> || 74.07% (20/27) || 75.00% (15/20) || -0.93%
|-
| <code>src/relays/aquarium_device.rs</code> || 66.67% (14/21) || 68.75% (11/16) || -2.08%
|-
| <code>src/relays/relay_manager.rs</code> || 58.46% (394/674) || 45.43% (179/394) || +13.03%
|-
| <code>src/relays/relay_manager_channels.rs</code> || 90.91% (20/22) || 45.83% (11/24) || +45.08%
|-
| <code>src/sensors/atlas_scientific.rs</code> || 74.77% (329/440) || 55.42% (92/166) || +19.35%
|-
| <code>src/sensors/atlas_scientific_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/dht.rs</code> || 75.00% (105/140) || 53.64% (59/110) || +21.36%
|-
| <code>src/sensors/dht_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/ds18b20.rs</code> || 74.55% (123/165) || 51.09% (47/92) || +23.46%
|-
| <code>src/sensors/ds18b20_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/i2c_interface.rs</code> || 76.54% (362/473) || 57.51% (153/266) || +19.03%
|-
| <code>src/sensors/i2c_interface_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/sensor_manager.rs</code> || 76.10% (761/1000) || 54.34% (282/519) || +21.76%
|-
| <code>src/sensors/sensor_manager_channels.rs</code> || 84.62% (33/39) || 75.00% (9/12) || +9.62%
|-
| <code>src/thermal/heating.rs</code> || 90.96% (332/365) || 68.60% (148/216) || +22.36%
|-
| <code>src/thermal/heating_actuation.rs</code> || 84.47% (87/103) || 67.24% (39/58) || +17.23%
|-
| <code>src/thermal/heating_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/heating_set_vals.rs</code> || 87.50% (35/40) || 64.29% (18/28) || +23.21%
|-
| <code>src/thermal/heating_stats_entry.rs</code> || 94.67% (142/150) || 82.22% (74/90) || +12.44%
|-
| <code>src/thermal/saw_tooth_profile.rs</code> || 100.00% (64/64) || 100.00% (23/23) || +0.00%
|-
| <code>src/thermal/saw_tooth_profile_config.rs</code> || 70.83% (17/24) || 50.00% (7/14) || +20.83%
|-
| <code>src/thermal/temperature_gradient.rs</code> || 100.00% (64/64) || 100.00% (32/32) || +0.00%
|-
| <code>src/thermal/thermal_control_status.rs</code> || 81.25% (26/32) || 58.82% (10/17) || +22.43%
|-
| <code>src/thermal/ventilation.rs</code> || 87.67% (192/219) || 61.16% (74/121) || +26.51%
|-
| <code>src/thermal/ventilation_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/ventilation_set_vals.rs</code> || 58.82% (30/51) || 58.82% (20/34) || +0.00%
|-
| <code>src/utilities/config.rs</code> || 76.99% (830/1078) || 72.84% (437/600) || +4.15%
|-
| <code>src/utilities/spin_sleeper.rs</code> || 79.17% (19/24) || 69.23% (9/13) || +9.94%
|-
| <code>src/utilities/thread_builder.rs</code> || 92.59% (25/27) || 78.57% (11/14) || +14.02%
|-
| <code>src/watchmen/monitors.rs</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/refill.rs</code> || 86.81% (447/515) || 69.45% (216/311) || +17.36%
|-
| <code>src/water/refill_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/water/tank_level_switch.rs</code> || 84.14% (191/227) || 74.47% (105/141) || +9.67%
|-
| <code>src/water/tank_level_switch_signals.rs</code> || 90.36% (75/83) || 86.96% (40/46) || +3.40%
|}

== System tests using the simulator ==
Running the application in simulator mode.

Control application

2026-07-26T06:34:14Z

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.

= Requirements =

<quote>Now do the reverse: Go through the implementation and test cases in src/sensors and the integration tests in tests/sensors and label every test case and at least every function linking to a matching software requirement from sensors.md.</quote>

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

The application makes [[use of an asynchronous runtime for the main application]].

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

= Development environment =
== Install Rust ==
<code>curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh</code>

== Install additional development libraries ==
<code>sudo apt-get install -y libudev-dev pkg-config</code>

== Build time ==
Building the release on a Raspberry Pi 4 takes around 16 minutes.

= Test strategy =
== Unit tests ==
Located within the implementation code files within <code>src</code>.

== Integration tests in test ==
Separated from implementation code to the <code>test</code> folder.

== Code coverage measurement ==
=== Using tarpaulin ===
<code>cargo tarpaulin --features "test-utils" --out Html</code>

The measurement takes app. 22 minutes.

=== Using llvm-cov ===
<code>cargo llvm-cov --features "test-utils" --html </code>

The measurements takes app. 8 minutes.
=== Comparing the results from llvm-cov and tarpaulin ===
Based on commit <code>8f557814f679c30ebd70e181f2a3f996ce0e295c</code>.

{| class="wikitable sortable"
|+ Module Summary Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! Subsystem / Module !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|- style="font-weight:bold; background-color:#f0f0f0;"
| '''TOTAL (All Application Source Files)''' || 71.53% (11216/15681) || 54.48% (4929/9047) || +17.04%
|-
| <code>src/bin/</code> || 0.00% (0/597) || 0.00% (0/457) || +0.00%
|-
| <code>src/database/</code> || 69.73% (1283/1840) || 52.72% (631/1197) || +17.01%
|-
| <code>src/dispatch/</code> || 46.32% (44/95) || 33.80% (24/71) || +12.51%
|-
| <code>src/food/</code> || 79.06% (721/912) || 58.80% (244/415) || +20.26%
|-
| <code>src/launch/</code> || 84.06% (944/1123) || 59.48% (411/691) || +24.58%
|-
| <code>src/mineral/</code> || 88.11% (467/530) || 60.33% (181/300) || +27.78%
|-
| <code>src/mocks/</code> || 58.82% (610/1037) || 55.57% (334/601) || +3.25%
|-
| <code>src/permission/</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/</code> || 77.46% (701/905) || 47.50% (304/640) || +29.96%
|-
| <code>src/relays/</code> || 60.22% (448/744) || 47.58% (216/454) || +12.64%
|-
| <code>src/sensors/</code> || 75.70% (1748/2309) || 54.76% (656/1198) || +20.95%
|-
| <code>src/simulator/</code> || 3.07% (10/326) || 2.05% (4/195) || +1.02%
|-
| <code>src/test_server/</code> || 67.93% (822/1210) || 59.67% (429/719) || +8.27%
|-
| <code>src/thermal/</code> || 88.45% (1019/1152) || 67.96% (437/643) || +20.49%
|-
| <code>src/utilities/</code> || 80.91% (1187/1467) || 75.10% (564/751) || +5.81%
|-
| <code>src/watchmen/</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/</code> || 86.10% (700/813) || 71.18% (331/465) || +14.92%
|}

{| class="wikitable sortable"
|+ Detailed File Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! File Path !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|-
| <code>src/bin/aquarium_client.rs</code> || 0.00% (0/117) || 0.00% (0/98) || +0.00%
|-
| <code>src/bin/aquarium_commissioning.rs</code> || 0.00% (0/426) || 0.00% (0/315) || +0.00%
|-
| <code>src/bin/aquarium_test_server.rs</code> || 0.00% (0/54) || 0.00% (0/44) || +0.00%
|-
| <code>src/database/database_interface_feed_trait.rs</code> || 77.86% (102/131) || 58.06% (54/93) || +19.80%
|-
| <code>src/database/pingable.rs</code> || 44.44% (4/9) || 33.33% (2/6) || +11.11%
|-
| <code>src/database/sql_interface.rs</code> || 65.79% (250/380) || 48.57% (119/245) || +17.22%
|-
| <code>src/database/sql_interface_balling.rs</code> || 69.31% (140/202) || 53.91% (69/128) || +15.40%
|-
| <code>src/database/sql_interface_data.rs</code> || 60.76% (48/79) || 59.62% (31/52) || +1.14%
|-
| <code>src/database/sql_interface_feed.rs</code> || 63.70% (186/292) || 45.00% (90/200) || +18.70%
|-
| <code>src/database/sql_interface_heating_set_vals.rs</code> || 66.12% (80/121) || 37.97% (30/79) || +28.15%
|-
| <code>src/database/sql_interface_heating_stats.rs</code> || 77.65% (139/179) || 67.59% (73/108) || +10.06%
|-
| <code>src/database/sql_interface_heating_stats_data_transfer.rs</code> || 100.00% (7/7) || 100.00% (2/2) || +0.00%
|-
| <code>src/database/sql_interface_midnight.rs</code> || 100.00% (8/8) || 100.00% (4/4) || +0.00%
|-
| <code>src/database/sql_interface_refill.rs</code> || 66.94% (83/124) || 57.14% (48/84) || +9.80%
|-
| <code>src/database/sql_interface_schedule.rs</code> || 85.54% (142/166) || 69.16% (74/107) || +16.38%
|-
| <code>src/database/sql_interface_test_utils.rs</code> || 100.00% (10/10) || 100.00% (5/5) || +0.00%
|-
| <code>src/database/sql_interface_ventilation_set_vals.rs</code> || 63.64% (84/132) || 35.71% (30/84) || +27.92%
|-
| <code>src/dispatch/ipc_message.rs</code> || 0.00% (0/51) || 0.00% (0/41) || +0.00%
|-
| <code>src/dispatch/messaging.rs</code> || 100.00% (44/44) || 80.00% (24/30) || +20.00%
|-
| <code>src/food/feed.rs</code> || 86.40% (305/353) || 62.65% (104/166) || +23.75%
|-
| <code>src/food/feed_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/food/feed_profile.rs</code> || 100.00% (100/100) || 100.00% (4/4) || +0.00%
|-
| <code>src/food/feed_schedule_entry.rs</code> || 97.62% (82/84) || 100.00% (10/10) || -2.38%
|-
| <code>src/food/food_injection.rs</code> || 62.43% (113/181) || 56.64% (64/113) || +5.79%
|-
| <code>src/food/food_injection_actuator_state.rs</code> || 61.11% (11/18) || 54.55% (6/11) || +6.57%
|-
| <code>src/food/food_injection_signals.rs</code> || 62.50% (100/160) || 48.08% (50/104) || +14.42%
|-
| <code>src/launch/config_app.rs</code> || 82.35% (98/119) || 57.14% (44/77) || +25.21%
|-
| <code>src/launch/execution_config.rs</code> || 86.30% (63/73) || 72.34% (34/47) || +13.96%
|-
| <code>src/launch/pid_file.rs</code> || 96.67% (58/60) || 77.14% (27/35) || +19.52%
|-
| <code>src/launch/run.rs</code> || 83.40% (725/869) || 58.74% (306/521) || +24.66%
|-
| <code>src/mineral/balling.rs</code> || 88.08% (340/386) || 61.08% (135/221) || +27.00%
|-
| <code>src/mineral/balling_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/mineral/balling_profile.rs</code> || 100.00% (71/71) || 100.00% (18/18) || +0.00%
|-
| <code>src/mineral/balling_set_val.rs</code> || 77.97% (46/59) || 44.44% (24/54) || +33.53%
|-
| <code>src/mocks/mock_dht.rs</code> || 74.07% (40/54) || 64.71% (22/34) || +9.36%
|-
| <code>src/mocks/mock_food_injection.rs</code> || 83.33% (20/24) || 75.00% (12/16) || +8.33%
|-
| <code>src/mocks/mock_i2c_interface.rs</code> || 32.50% (13/40) || 28.00% (7/25) || +4.50%
|-
| <code>src/mocks/mock_peristaltic_pump.rs</code> || 85.00% (17/20) || 72.73% (8/11) || +12.27%
|-
| <code>src/mocks/mock_relay_manager.rs</code> || 82.50% (33/40) || 75.86% (22/29) || +6.64%
|-
| <code>src/mocks/mock_sql_interface.rs</code> || 66.21% (241/364) || 63.81% (134/210) || +2.40%
|-
| <code>src/mocks/mock_water_injection.rs</code> || 82.61% (19/23) || 75.00% (12/16) || +7.61%
|-
| <code>src/permission/process_privileges.rs</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/recorder.rs</code> || 84.77% (590/696) || 54.12% (269/497) || +30.65%
|-
| <code>src/recorder/recorder_channels.rs</code> || 58.82% (10/17) || 45.45% (5/11) || +13.37%
|-
| <code>src/recorder/recorder_data_frame.rs</code> || 52.66% (101/192) || 22.31% (27/121) || +30.35%
|-
| <code>src/relays/actuator_state.rs</code> || 74.07% (20/27) || 75.00% (15/20) || -0.93%
|-
| <code>src/relays/aquarium_device.rs</code> || 66.67% (14/21) || 68.75% (11/16) || -2.08%
|-
| <code>src/relays/relay_manager.rs</code> || 58.46% (394/674) || 45.43% (179/394) || +13.03%
|-
| <code>src/relays/relay_manager_channels.rs</code> || 90.91% (20/22) || 45.83% (11/24) || +45.08%
|-
| <code>src/sensors/atlas_scientific.rs</code> || 74.77% (329/440) || 55.42% (92/166) || +19.35%
|-
| <code>src/sensors/atlas_scientific_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/dht.rs</code> || 75.00% (105/140) || 53.64% (59/110) || +21.36%
|-
| <code>src/sensors/dht_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/ds18b20.rs</code> || 74.55% (123/165) || 51.09% (47/92) || +23.46%
|-
| <code>src/sensors/ds18b20_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/i2c_interface.rs</code> || 76.54% (362/473) || 57.51% (153/266) || +19.03%
|-
| <code>src/sensors/i2c_interface_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/sensor_manager.rs</code> || 76.10% (761/1000) || 54.34% (282/519) || +21.76%
|-
| <code>src/sensors/sensor_manager_channels.rs</code> || 84.62% (33/39) || 75.00% (9/12) || +9.62%
|-
| <code>src/thermal/heating.rs</code> || 90.96% (332/365) || 68.60% (148/216) || +22.36%
|-
| <code>src/thermal/heating_actuation.rs</code> || 84.47% (87/103) || 67.24% (39/58) || +17.23%
|-
| <code>src/thermal/heating_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/heating_set_vals.rs</code> || 87.50% (35/40) || 64.29% (18/28) || +23.21%
|-
| <code>src/thermal/heating_stats_entry.rs</code> || 94.67% (142/150) || 82.22% (74/90) || +12.44%
|-
| <code>src/thermal/saw_tooth_profile.rs</code> || 100.00% (64/64) || 100.00% (23/23) || +0.00%
|-
| <code>src/thermal/saw_tooth_profile_config.rs</code> || 70.83% (17/24) || 50.00% (7/14) || +20.83%
|-
| <code>src/thermal/temperature_gradient.rs</code> || 100.00% (64/64) || 100.00% (32/32) || +0.00%
|-
| <code>src/thermal/thermal_control_status.rs</code> || 81.25% (26/32) || 58.82% (10/17) || +22.43%
|-
| <code>src/thermal/ventilation.rs</code> || 87.67% (192/219) || 61.16% (74/121) || +26.51%
|-
| <code>src/thermal/ventilation_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/ventilation_set_vals.rs</code> || 58.82% (30/51) || 58.82% (20/34) || +0.00%
|-
| <code>src/utilities/config.rs</code> || 76.99% (830/1078) || 72.84% (437/600) || +4.15%
|-
| <code>src/utilities/spin_sleeper.rs</code> || 79.17% (19/24) || 69.23% (9/13) || +9.94%
|-
| <code>src/utilities/thread_builder.rs</code> || 92.59% (25/27) || 78.57% (11/14) || +14.02%
|-
| <code>src/watchmen/monitors.rs</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/refill.rs</code> || 86.81% (447/515) || 69.45% (216/311) || +17.36%
|-
| <code>src/water/refill_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/water/tank_level_switch.rs</code> || 84.14% (191/227) || 74.47% (105/141) || +9.67%
|-
| <code>src/water/tank_level_switch_signals.rs</code> || 90.36% (75/83) || 86.96% (40/46) || +3.40%
|}

== System tests using the simulator ==
Running the application in simulator mode.

Control application

2026-07-25T09:53:29Z

Uwe: /* Comparing the results from llvm-cov and tarpaulin */

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.

The application makes [[use of an asynchronous runtime for the main application]].

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

= Development environment =
== Install Rust ==
<code>curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh</code>

== Install additional development libraries ==
<code>sudo apt-get install -y libudev-dev pkg-config</code>

== Build time ==
Building the release on a Raspberry Pi 4 takes around 16 minutes.

= Test strategy =
== Unit tests ==
Located within the implementation code files within <code>src</code>.

== Integration tests in test ==
Separated from implementation code to the <code>test</code> folder.

== Code coverage measurement ==
=== Using tarpaulin ===
<code>cargo tarpaulin --features "test-utils" --out Html</code>

The measurement takes app. 22 minutes.

=== Using llvm-cov ===
<code>cargo llvm-cov --features "test-utils" --html </code>

The measurements takes app. 8 minutes.
=== Comparing the results from llvm-cov and tarpaulin ===
Based on commit <code>8f557814f679c30ebd70e181f2a3f996ce0e295c</code>.

{| class="wikitable sortable"
|+ Module Summary Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! Subsystem / Module !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|- style="font-weight:bold; background-color:#f0f0f0;"
| '''TOTAL (All Application Source Files)''' || 71.53% (11216/15681) || 54.48% (4929/9047) || +17.04%
|-
| <code>src/bin/</code> || 0.00% (0/597) || 0.00% (0/457) || +0.00%
|-
| <code>src/database/</code> || 69.73% (1283/1840) || 52.72% (631/1197) || +17.01%
|-
| <code>src/dispatch/</code> || 46.32% (44/95) || 33.80% (24/71) || +12.51%
|-
| <code>src/food/</code> || 79.06% (721/912) || 58.80% (244/415) || +20.26%
|-
| <code>src/launch/</code> || 84.06% (944/1123) || 59.48% (411/691) || +24.58%
|-
| <code>src/mineral/</code> || 88.11% (467/530) || 60.33% (181/300) || +27.78%
|-
| <code>src/mocks/</code> || 58.82% (610/1037) || 55.57% (334/601) || +3.25%
|-
| <code>src/permission/</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/</code> || 77.46% (701/905) || 47.50% (304/640) || +29.96%
|-
| <code>src/relays/</code> || 60.22% (448/744) || 47.58% (216/454) || +12.64%
|-
| <code>src/sensors/</code> || 75.70% (1748/2309) || 54.76% (656/1198) || +20.95%
|-
| <code>src/simulator/</code> || 3.07% (10/326) || 2.05% (4/195) || +1.02%
|-
| <code>src/test_server/</code> || 67.93% (822/1210) || 59.67% (429/719) || +8.27%
|-
| <code>src/thermal/</code> || 88.45% (1019/1152) || 67.96% (437/643) || +20.49%
|-
| <code>src/utilities/</code> || 80.91% (1187/1467) || 75.10% (564/751) || +5.81%
|-
| <code>src/watchmen/</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/</code> || 86.10% (700/813) || 71.18% (331/465) || +14.92%
|}

{| class="wikitable sortable"
|+ Detailed File Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! File Path !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|-
| <code>src/bin/aquarium_client.rs</code> || 0.00% (0/117) || 0.00% (0/98) || +0.00%
|-
| <code>src/bin/aquarium_commissioning.rs</code> || 0.00% (0/426) || 0.00% (0/315) || +0.00%
|-
| <code>src/bin/aquarium_test_server.rs</code> || 0.00% (0/54) || 0.00% (0/44) || +0.00%
|-
| <code>src/database/database_interface_feed_trait.rs</code> || 77.86% (102/131) || 58.06% (54/93) || +19.80%
|-
| <code>src/database/pingable.rs</code> || 44.44% (4/9) || 33.33% (2/6) || +11.11%
|-
| <code>src/database/sql_interface.rs</code> || 65.79% (250/380) || 48.57% (119/245) || +17.22%
|-
| <code>src/database/sql_interface_balling.rs</code> || 69.31% (140/202) || 53.91% (69/128) || +15.40%
|-
| <code>src/database/sql_interface_data.rs</code> || 60.76% (48/79) || 59.62% (31/52) || +1.14%
|-
| <code>src/database/sql_interface_feed.rs</code> || 63.70% (186/292) || 45.00% (90/200) || +18.70%
|-
| <code>src/database/sql_interface_heating_set_vals.rs</code> || 66.12% (80/121) || 37.97% (30/79) || +28.15%
|-
| <code>src/database/sql_interface_heating_stats.rs</code> || 77.65% (139/179) || 67.59% (73/108) || +10.06%
|-
| <code>src/database/sql_interface_heating_stats_data_transfer.rs</code> || 100.00% (7/7) || 100.00% (2/2) || +0.00%
|-
| <code>src/database/sql_interface_midnight.rs</code> || 100.00% (8/8) || 100.00% (4/4) || +0.00%
|-
| <code>src/database/sql_interface_refill.rs</code> || 66.94% (83/124) || 57.14% (48/84) || +9.80%
|-
| <code>src/database/sql_interface_schedule.rs</code> || 85.54% (142/166) || 69.16% (74/107) || +16.38%
|-
| <code>src/database/sql_interface_test_utils.rs</code> || 100.00% (10/10) || 100.00% (5/5) || +0.00%
|-
| <code>src/database/sql_interface_ventilation_set_vals.rs</code> || 63.64% (84/132) || 35.71% (30/84) || +27.92%
|-
| <code>src/dispatch/ipc_message.rs</code> || 0.00% (0/51) || 0.00% (0/41) || +0.00%
|-
| <code>src/dispatch/messaging.rs</code> || 100.00% (44/44) || 80.00% (24/30) || +20.00%
|-
| <code>src/food/feed.rs</code> || 86.40% (305/353) || 62.65% (104/166) || +23.75%
|-
| <code>src/food/feed_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/food/feed_profile.rs</code> || 100.00% (100/100) || 100.00% (4/4) || +0.00%
|-
| <code>src/food/feed_schedule_entry.rs</code> || 97.62% (82/84) || 100.00% (10/10) || -2.38%
|-
| <code>src/food/food_injection.rs</code> || 62.43% (113/181) || 56.64% (64/113) || +5.79%
|-
| <code>src/food/food_injection_actuator_state.rs</code> || 61.11% (11/18) || 54.55% (6/11) || +6.57%
|-
| <code>src/food/food_injection_signals.rs</code> || 62.50% (100/160) || 48.08% (50/104) || +14.42%
|-
| <code>src/launch/config_app.rs</code> || 82.35% (98/119) || 57.14% (44/77) || +25.21%
|-
| <code>src/launch/execution_config.rs</code> || 86.30% (63/73) || 72.34% (34/47) || +13.96%
|-
| <code>src/launch/pid_file.rs</code> || 96.67% (58/60) || 77.14% (27/35) || +19.52%
|-
| <code>src/launch/run.rs</code> || 83.40% (725/869) || 58.74% (306/521) || +24.66%
|-
| <code>src/mineral/balling.rs</code> || 88.08% (340/386) || 61.08% (135/221) || +27.00%
|-
| <code>src/mineral/balling_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/mineral/balling_profile.rs</code> || 100.00% (71/71) || 100.00% (18/18) || +0.00%
|-
| <code>src/mineral/balling_set_val.rs</code> || 77.97% (46/59) || 44.44% (24/54) || +33.53%
|-
| <code>src/mocks/mock_dht.rs</code> || 74.07% (40/54) || 64.71% (22/34) || +9.36%
|-
| <code>src/mocks/mock_food_injection.rs</code> || 83.33% (20/24) || 75.00% (12/16) || +8.33%
|-
| <code>src/mocks/mock_i2c_interface.rs</code> || 32.50% (13/40) || 28.00% (7/25) || +4.50%
|-
| <code>src/mocks/mock_peristaltic_pump.rs</code> || 85.00% (17/20) || 72.73% (8/11) || +12.27%
|-
| <code>src/mocks/mock_relay_manager.rs</code> || 82.50% (33/40) || 75.86% (22/29) || +6.64%
|-
| <code>src/mocks/mock_sql_interface.rs</code> || 66.21% (241/364) || 63.81% (134/210) || +2.40%
|-
| <code>src/mocks/mock_water_injection.rs</code> || 82.61% (19/23) || 75.00% (12/16) || +7.61%
|-
| <code>src/permission/process_privileges.rs</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/recorder.rs</code> || 84.77% (590/696) || 54.12% (269/497) || +30.65%
|-
| <code>src/recorder/recorder_channels.rs</code> || 58.82% (10/17) || 45.45% (5/11) || +13.37%
|-
| <code>src/recorder/recorder_data_frame.rs</code> || 52.66% (101/192) || 22.31% (27/121) || +30.35%
|-
| <code>src/relays/actuator_state.rs</code> || 74.07% (20/27) || 75.00% (15/20) || -0.93%
|-
| <code>src/relays/aquarium_device.rs</code> || 66.67% (14/21) || 68.75% (11/16) || -2.08%
|-
| <code>src/relays/relay_manager.rs</code> || 58.46% (394/674) || 45.43% (179/394) || +13.03%
|-
| <code>src/relays/relay_manager_channels.rs</code> || 90.91% (20/22) || 45.83% (11/24) || +45.08%
|-
| <code>src/sensors/atlas_scientific.rs</code> || 74.77% (329/440) || 55.42% (92/166) || +19.35%
|-
| <code>src/sensors/atlas_scientific_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/dht.rs</code> || 75.00% (105/140) || 53.64% (59/110) || +21.36%
|-
| <code>src/sensors/dht_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/ds18b20.rs</code> || 74.55% (123/165) || 51.09% (47/92) || +23.46%
|-
| <code>src/sensors/ds18b20_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/i2c_interface.rs</code> || 76.54% (362/473) || 57.51% (153/266) || +19.03%
|-
| <code>src/sensors/i2c_interface_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/sensor_manager.rs</code> || 76.10% (761/1000) || 54.34% (282/519) || +21.76%
|-
| <code>src/sensors/sensor_manager_channels.rs</code> || 84.62% (33/39) || 75.00% (9/12) || +9.62%
|-
| <code>src/thermal/heating.rs</code> || 90.96% (332/365) || 68.60% (148/216) || +22.36%
|-
| <code>src/thermal/heating_actuation.rs</code> || 84.47% (87/103) || 67.24% (39/58) || +17.23%
|-
| <code>src/thermal/heating_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/heating_set_vals.rs</code> || 87.50% (35/40) || 64.29% (18/28) || +23.21%
|-
| <code>src/thermal/heating_stats_entry.rs</code> || 94.67% (142/150) || 82.22% (74/90) || +12.44%
|-
| <code>src/thermal/saw_tooth_profile.rs</code> || 100.00% (64/64) || 100.00% (23/23) || +0.00%
|-
| <code>src/thermal/saw_tooth_profile_config.rs</code> || 70.83% (17/24) || 50.00% (7/14) || +20.83%
|-
| <code>src/thermal/temperature_gradient.rs</code> || 100.00% (64/64) || 100.00% (32/32) || +0.00%
|-
| <code>src/thermal/thermal_control_status.rs</code> || 81.25% (26/32) || 58.82% (10/17) || +22.43%
|-
| <code>src/thermal/ventilation.rs</code> || 87.67% (192/219) || 61.16% (74/121) || +26.51%
|-
| <code>src/thermal/ventilation_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/ventilation_set_vals.rs</code> || 58.82% (30/51) || 58.82% (20/34) || +0.00%
|-
| <code>src/utilities/config.rs</code> || 76.99% (830/1078) || 72.84% (437/600) || +4.15%
|-
| <code>src/utilities/spin_sleeper.rs</code> || 79.17% (19/24) || 69.23% (9/13) || +9.94%
|-
| <code>src/utilities/thread_builder.rs</code> || 92.59% (25/27) || 78.57% (11/14) || +14.02%
|-
| <code>src/watchmen/monitors.rs</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/refill.rs</code> || 86.81% (447/515) || 69.45% (216/311) || +17.36%
|-
| <code>src/water/refill_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/water/tank_level_switch.rs</code> || 84.14% (191/227) || 74.47% (105/141) || +9.67%
|-
| <code>src/water/tank_level_switch_signals.rs</code> || 90.36% (75/83) || 86.96% (40/46) || +3.40%
|}

== System tests using the simulator ==
Running the application in simulator mode.

Control application

2026-07-25T09:52:23Z

Uwe: /* Comparing the results from llvm-cov and tarpaulin */

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.

The application makes [[use of an asynchronous runtime for the main application]].

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

= Development environment =
== Install Rust ==
<code>curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh</code>

== Install additional development libraries ==
<code>sudo apt-get install -y libudev-dev pkg-config</code>

== Build time ==
Building the release on a Raspberry Pi 4 takes around 16 minutes.

= Test strategy =
== Unit tests ==
Located within the implementation code files within <code>src</code>.

== Integration tests in test ==
Separated from implementation code to the <code>test</code> folder.

== Code coverage measurement ==
=== Using tarpaulin ===
<code>cargo tarpaulin --features "test-utils" --out Html</code>

The measurement takes app. 22 minutes.

=== Using llvm-cov ===
<code>cargo llvm-cov --features "test-utils" --html </code>

The measurements takes app. 8 minutes.
=== Comparing the results from llvm-cov and tarpaulin ===
{| class="wikitable sortable"
|+ Module Summary Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! Subsystem / Module !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|- style="font-weight:bold; background-color:#f0f0f0;"
| '''TOTAL (All Application Source Files)''' || 71.53% (11216/15681) || 54.48% (4929/9047) || +17.04%
|-
| <code>src/bin/</code> || 0.00% (0/597) || 0.00% (0/457) || +0.00%
|-
| <code>src/database/</code> || 69.73% (1283/1840) || 52.72% (631/1197) || +17.01%
|-
| <code>src/dispatch/</code> || 46.32% (44/95) || 33.80% (24/71) || +12.51%
|-
| <code>src/food/</code> || 79.06% (721/912) || 58.80% (244/415) || +20.26%
|-
| <code>src/launch/</code> || 84.06% (944/1123) || 59.48% (411/691) || +24.58%
|-
| <code>src/mineral/</code> || 88.11% (467/530) || 60.33% (181/300) || +27.78%
|-
| <code>src/mocks/</code> || 58.82% (610/1037) || 55.57% (334/601) || +3.25%
|-
| <code>src/permission/</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/</code> || 77.46% (701/905) || 47.50% (304/640) || +29.96%
|-
| <code>src/relays/</code> || 60.22% (448/744) || 47.58% (216/454) || +12.64%
|-
| <code>src/sensors/</code> || 75.70% (1748/2309) || 54.76% (656/1198) || +20.95%
|-
| <code>src/simulator/</code> || 3.07% (10/326) || 2.05% (4/195) || +1.02%
|-
| <code>src/test_server/</code> || 67.93% (822/1210) || 59.67% (429/719) || +8.27%
|-
| <code>src/thermal/</code> || 88.45% (1019/1152) || 67.96% (437/643) || +20.49%
|-
| <code>src/utilities/</code> || 80.91% (1187/1467) || 75.10% (564/751) || +5.81%
|-
| <code>src/watchmen/</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/</code> || 86.10% (700/813) || 71.18% (331/465) || +14.92%
|}

{| class="wikitable sortable"
|+ Detailed File Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! File Path !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|-
| <code>src/bin/aquarium_client.rs</code> || 0.00% (0/117) || 0.00% (0/98) || +0.00%
|-
| <code>src/bin/aquarium_commissioning.rs</code> || 0.00% (0/426) || 0.00% (0/315) || +0.00%
|-
| <code>src/bin/aquarium_test_server.rs</code> || 0.00% (0/54) || 0.00% (0/44) || +0.00%
|-
| <code>src/database/database_interface_feed_trait.rs</code> || 77.86% (102/131) || 58.06% (54/93) || +19.80%
|-
| <code>src/database/pingable.rs</code> || 44.44% (4/9) || 33.33% (2/6) || +11.11%
|-
| <code>src/database/sql_interface.rs</code> || 65.79% (250/380) || 48.57% (119/245) || +17.22%
|-
| <code>src/database/sql_interface_balling.rs</code> || 69.31% (140/202) || 53.91% (69/128) || +15.40%
|-
| <code>src/database/sql_interface_data.rs</code> || 60.76% (48/79) || 59.62% (31/52) || +1.14%
|-
| <code>src/database/sql_interface_feed.rs</code> || 63.70% (186/292) || 45.00% (90/200) || +18.70%
|-
| <code>src/database/sql_interface_heating_set_vals.rs</code> || 66.12% (80/121) || 37.97% (30/79) || +28.15%
|-
| <code>src/database/sql_interface_heating_stats.rs</code> || 77.65% (139/179) || 67.59% (73/108) || +10.06%
|-
| <code>src/database/sql_interface_heating_stats_data_transfer.rs</code> || 100.00% (7/7) || 100.00% (2/2) || +0.00%
|-
| <code>src/database/sql_interface_midnight.rs</code> || 100.00% (8/8) || 100.00% (4/4) || +0.00%
|-
| <code>src/database/sql_interface_refill.rs</code> || 66.94% (83/124) || 57.14% (48/84) || +9.80%
|-
| <code>src/database/sql_interface_schedule.rs</code> || 85.54% (142/166) || 69.16% (74/107) || +16.38%
|-
| <code>src/database/sql_interface_test_utils.rs</code> || 100.00% (10/10) || 100.00% (5/5) || +0.00%
|-
| <code>src/database/sql_interface_ventilation_set_vals.rs</code> || 63.64% (84/132) || 35.71% (30/84) || +27.92%
|-
| <code>src/dispatch/ipc_message.rs</code> || 0.00% (0/51) || 0.00% (0/41) || +0.00%
|-
| <code>src/dispatch/messaging.rs</code> || 100.00% (44/44) || 80.00% (24/30) || +20.00%
|-
| <code>src/food/feed.rs</code> || 86.40% (305/353) || 62.65% (104/166) || +23.75%
|-
| <code>src/food/feed_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/food/feed_profile.rs</code> || 100.00% (100/100) || 100.00% (4/4) || +0.00%
|-
| <code>src/food/feed_schedule_entry.rs</code> || 97.62% (82/84) || 100.00% (10/10) || -2.38%
|-
| <code>src/food/food_injection.rs</code> || 62.43% (113/181) || 56.64% (64/113) || +5.79%
|-
| <code>src/food/food_injection_actuator_state.rs</code> || 61.11% (11/18) || 54.55% (6/11) || +6.57%
|-
| <code>src/food/food_injection_signals.rs</code> || 62.50% (100/160) || 48.08% (50/104) || +14.42%
|-
| <code>src/launch/config_app.rs</code> || 82.35% (98/119) || 57.14% (44/77) || +25.21%
|-
| <code>src/launch/execution_config.rs</code> || 86.30% (63/73) || 72.34% (34/47) || +13.96%
|-
| <code>src/launch/pid_file.rs</code> || 96.67% (58/60) || 77.14% (27/35) || +19.52%
|-
| <code>src/launch/run.rs</code> || 83.40% (725/869) || 58.74% (306/521) || +24.66%
|-
| <code>src/mineral/balling.rs</code> || 88.08% (340/386) || 61.08% (135/221) || +27.00%
|-
| <code>src/mineral/balling_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/mineral/balling_profile.rs</code> || 100.00% (71/71) || 100.00% (18/18) || +0.00%
|-
| <code>src/mineral/balling_set_val.rs</code> || 77.97% (46/59) || 44.44% (24/54) || +33.53%
|-
| <code>src/mocks/mock_dht.rs</code> || 74.07% (40/54) || 64.71% (22/34) || +9.36%
|-
| <code>src/mocks/mock_food_injection.rs</code> || 83.33% (20/24) || 75.00% (12/16) || +8.33%
|-
| <code>src/mocks/mock_i2c_interface.rs</code> || 32.50% (13/40) || 28.00% (7/25) || +4.50%
|-
| <code>src/mocks/mock_peristaltic_pump.rs</code> || 85.00% (17/20) || 72.73% (8/11) || +12.27%
|-
| <code>src/mocks/mock_relay_manager.rs</code> || 82.50% (33/40) || 75.86% (22/29) || +6.64%
|-
| <code>src/mocks/mock_sql_interface.rs</code> || 66.21% (241/364) || 63.81% (134/210) || +2.40%
|-
| <code>src/mocks/mock_water_injection.rs</code> || 82.61% (19/23) || 75.00% (12/16) || +7.61%
|-
| <code>src/permission/process_privileges.rs</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/recorder.rs</code> || 84.77% (590/696) || 54.12% (269/497) || +30.65%
|-
| <code>src/recorder/recorder_channels.rs</code> || 58.82% (10/17) || 45.45% (5/11) || +13.37%
|-
| <code>src/recorder/recorder_data_frame.rs</code> || 52.66% (101/192) || 22.31% (27/121) || +30.35%
|-
| <code>src/relays/actuator_state.rs</code> || 74.07% (20/27) || 75.00% (15/20) || -0.93%
|-
| <code>src/relays/aquarium_device.rs</code> || 66.67% (14/21) || 68.75% (11/16) || -2.08%
|-
| <code>src/relays/relay_manager.rs</code> || 58.46% (394/674) || 45.43% (179/394) || +13.03%
|-
| <code>src/relays/relay_manager_channels.rs</code> || 90.91% (20/22) || 45.83% (11/24) || +45.08%
|-
| <code>src/sensors/atlas_scientific.rs</code> || 74.77% (329/440) || 55.42% (92/166) || +19.35%
|-
| <code>src/sensors/atlas_scientific_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/dht.rs</code> || 75.00% (105/140) || 53.64% (59/110) || +21.36%
|-
| <code>src/sensors/dht_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/ds18b20.rs</code> || 74.55% (123/165) || 51.09% (47/92) || +23.46%
|-
| <code>src/sensors/ds18b20_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/i2c_interface.rs</code> || 76.54% (362/473) || 57.51% (153/266) || +19.03%
|-
| <code>src/sensors/i2c_interface_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/sensor_manager.rs</code> || 76.10% (761/1000) || 54.34% (282/519) || +21.76%
|-
| <code>src/sensors/sensor_manager_channels.rs</code> || 84.62% (33/39) || 75.00% (9/12) || +9.62%
|-
| <code>src/thermal/heating.rs</code> || 90.96% (332/365) || 68.60% (148/216) || +22.36%
|-
| <code>src/thermal/heating_actuation.rs</code> || 84.47% (87/103) || 67.24% (39/58) || +17.23%
|-
| <code>src/thermal/heating_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/heating_set_vals.rs</code> || 87.50% (35/40) || 64.29% (18/28) || +23.21%
|-
| <code>src/thermal/heating_stats_entry.rs</code> || 94.67% (142/150) || 82.22% (74/90) || +12.44%
|-
| <code>src/thermal/saw_tooth_profile.rs</code> || 100.00% (64/64) || 100.00% (23/23) || +0.00%
|-
| <code>src/thermal/saw_tooth_profile_config.rs</code> || 70.83% (17/24) || 50.00% (7/14) || +20.83%
|-
| <code>src/thermal/temperature_gradient.rs</code> || 100.00% (64/64) || 100.00% (32/32) || +0.00%
|-
| <code>src/thermal/thermal_control_status.rs</code> || 81.25% (26/32) || 58.82% (10/17) || +22.43%
|-
| <code>src/thermal/ventilation.rs</code> || 87.67% (192/219) || 61.16% (74/121) || +26.51%
|-
| <code>src/thermal/ventilation_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/ventilation_set_vals.rs</code> || 58.82% (30/51) || 58.82% (20/34) || +0.00%
|-
| <code>src/utilities/config.rs</code> || 76.99% (830/1078) || 72.84% (437/600) || +4.15%
|-
| <code>src/utilities/spin_sleeper.rs</code> || 79.17% (19/24) || 69.23% (9/13) || +9.94%
|-
| <code>src/utilities/thread_builder.rs</code> || 92.59% (25/27) || 78.57% (11/14) || +14.02%
|-
| <code>src/watchmen/monitors.rs</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/refill.rs</code> || 86.81% (447/515) || 69.45% (216/311) || +17.36%
|-
| <code>src/water/refill_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/water/tank_level_switch.rs</code> || 84.14% (191/227) || 74.47% (105/141) || +9.67%
|-
| <code>src/water/tank_level_switch_signals.rs</code> || 90.36% (75/83) || 86.96% (40/46) || +3.40%
|}

== System tests using the simulator ==
Running the application in simulator mode.

Control application

2026-07-25T09:45:59Z

Uwe: /* Comparing the results from llvm-cov and tarpaulin */

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.

The application makes [[use of an asynchronous runtime for the main application]].

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

= Development environment =
== Install Rust ==
<code>curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh</code>

== Install additional development libraries ==
<code>sudo apt-get install -y libudev-dev pkg-config</code>

== Build time ==
Building the release on a Raspberry Pi 4 takes around 16 minutes.

= Test strategy =
== Unit tests ==
Located within the implementation code files within <code>src</code>.

== Integration tests in test ==
Separated from implementation code to the <code>test</code> folder.

== Code coverage measurement ==
=== Using tarpaulin ===
<code>cargo tarpaulin --features "test-utils" --out Html</code>

The measurement takes app. 22 minutes.

=== Using llvm-cov ===
<code>cargo llvm-cov --features "test-utils" --html </code>

The measurements takes app. 8 minutes.
=== Comparing the results from llvm-cov and tarpaulin ===
==== Coverage Summary by Subsystem / Module ====
{| class="wikitable sortable"
|+ Module Summary Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! Subsystem / Module !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|- style="font-weight:bold; background-color:#f0f0f0;"
| '''TOTAL (All Application Source Files)''' || 71.53% (11216/15681) || 54.48% (4929/9047) || +17.04%
|-
| <code>src/bin/</code> || 0.00% (0/597) || 0.00% (0/457) || +0.00%
|-
| <code>src/database/</code> || 69.73% (1283/1840) || 52.72% (631/1197) || +17.01%
|-
| <code>src/dispatch/</code> || 46.32% (44/95) || 33.80% (24/71) || +12.51%
|-
| <code>src/food/</code> || 79.06% (721/912) || 58.80% (244/415) || +20.26%
|-
| <code>src/launch/</code> || 84.06% (944/1123) || 59.48% (411/691) || +24.58%
|-
| <code>src/mineral/</code> || 88.11% (467/530) || 60.33% (181/300) || +27.78%
|-
| <code>src/mocks/</code> || 58.82% (610/1037) || 55.57% (334/601) || +3.25%
|-
| <code>src/permission/</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/</code> || 77.46% (701/905) || 47.50% (304/640) || +29.96%
|-
| <code>src/relays/</code> || 60.22% (448/744) || 47.58% (216/454) || +12.64%
|-
| <code>src/sensors/</code> || 75.70% (1748/2309) || 54.76% (656/1198) || +20.95%
|-
| <code>src/simulator/</code> || 3.07% (10/326) || 2.05% (4/195) || +1.02%
|-
| <code>src/test_server/</code> || 67.93% (822/1210) || 59.67% (429/719) || +8.27%
|-
| <code>src/thermal/</code> || 88.45% (1019/1152) || 67.96% (437/643) || +20.49%
|-
| <code>src/utilities/</code> || 80.91% (1187/1467) || 75.10% (564/751) || +5.81%
|-
| <code>src/watchmen/</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/</code> || 86.10% (700/813) || 71.18% (331/465) || +14.92%
|}

==== Detailed Coverage Comparison by File ====
{| class="wikitable sortable"
|+ Detailed File Comparison: llvm-cov vs. tarpaulin (Line Coverage)
|-
! File Path !! llvm-cov Line Coverage !! tarpaulin Line Coverage !! Difference (% pts)
|-
| <code>src/bin/aquarium_client.rs</code> || 0.00% (0/117) || 0.00% (0/98) || +0.00%
|-
| <code>src/bin/aquarium_commissioning.rs</code> || 0.00% (0/426) || 0.00% (0/315) || +0.00%
|-
| <code>src/bin/aquarium_test_server.rs</code> || 0.00% (0/54) || 0.00% (0/44) || +0.00%
|-
| <code>src/database/database_interface_feed_trait.rs</code> || 77.86% (102/131) || 58.06% (54/93) || +19.80%
|-
| <code>src/database/pingable.rs</code> || 44.44% (4/9) || 33.33% (2/6) || +11.11%
|-
| <code>src/database/sql_interface.rs</code> || 65.79% (250/380) || 48.57% (119/245) || +17.22%
|-
| <code>src/database/sql_interface_balling.rs</code> || 69.31% (140/202) || 53.91% (69/128) || +15.40%
|-
| <code>src/database/sql_interface_data.rs</code> || 60.76% (48/79) || 59.62% (31/52) || +1.14%
|-
| <code>src/database/sql_interface_feed.rs</code> || 63.70% (186/292) || 45.00% (90/200) || +18.70%
|-
| <code>src/database/sql_interface_heating_set_vals.rs</code> || 66.12% (80/121) || 37.97% (30/79) || +28.15%
|-
| <code>src/database/sql_interface_heating_stats.rs</code> || 77.65% (139/179) || 67.59% (73/108) || +10.06%
|-
| <code>src/database/sql_interface_heating_stats_data_transfer.rs</code> || 100.00% (7/7) || 100.00% (2/2) || +0.00%
|-
| <code>src/database/sql_interface_midnight.rs</code> || 100.00% (8/8) || 100.00% (4/4) || +0.00%
|-
| <code>src/database/sql_interface_refill.rs</code> || 66.94% (83/124) || 57.14% (48/84) || +9.80%
|-
| <code>src/database/sql_interface_schedule.rs</code> || 85.54% (142/166) || 69.16% (74/107) || +16.38%
|-
| <code>src/database/sql_interface_test_utils.rs</code> || 100.00% (10/10) || 100.00% (5/5) || +0.00%
|-
| <code>src/database/sql_interface_ventilation_set_vals.rs</code> || 63.64% (84/132) || 35.71% (30/84) || +27.92%
|-
| <code>src/dispatch/ipc_message.rs</code> || 0.00% (0/51) || 0.00% (0/41) || +0.00%
|-
| <code>src/dispatch/messaging.rs</code> || 100.00% (44/44) || 80.00% (24/30) || +20.00%
|-
| <code>src/food/feed.rs</code> || 86.40% (305/353) || 62.65% (104/166) || +23.75%
|-
| <code>src/food/feed_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/food/feed_profile.rs</code> || 100.00% (100/100) || 100.00% (4/4) || +0.00%
|-
| <code>src/food/feed_schedule_entry.rs</code> || 97.62% (82/84) || 100.00% (10/10) || -2.38%
|-
| <code>src/food/food_injection.rs</code> || 62.43% (113/181) || 56.64% (64/113) || +5.79%
|-
| <code>src/food/food_injection_actuator_state.rs</code> || 61.11% (11/18) || 54.55% (6/11) || +6.57%
|-
| <code>src/food/food_injection_signals.rs</code> || 62.50% (100/160) || 48.08% (50/104) || +14.42%
|-
| <code>src/launch/config_app.rs</code> || 82.35% (98/119) || 57.14% (44/77) || +25.21%
|-
| <code>src/launch/execution_config.rs</code> || 86.30% (63/73) || 72.34% (34/47) || +13.96%
|-
| <code>src/launch/pid_file.rs</code> || 96.67% (58/60) || 77.14% (27/35) || +19.52%
|-
| <code>src/launch/run.rs</code> || 83.40% (725/869) || 58.74% (306/521) || +24.66%
|-
| <code>src/mineral/balling.rs</code> || 88.08% (340/386) || 61.08% (135/221) || +27.00%
|-
| <code>src/mineral/balling_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/mineral/balling_profile.rs</code> || 100.00% (71/71) || 100.00% (18/18) || +0.00%
|-
| <code>src/mineral/balling_set_val.rs</code> || 77.97% (46/59) || 44.44% (24/54) || +33.53%
|-
| <code>src/mocks/mock_dht.rs</code> || 74.07% (40/54) || 64.71% (22/34) || +9.36%
|-
| <code>src/mocks/mock_food_injection.rs</code> || 83.33% (20/24) || 75.00% (12/16) || +8.33%
|-
| <code>src/mocks/mock_i2c_interface.rs</code> || 32.50% (13/40) || 28.00% (7/25) || +4.50%
|-
| <code>src/mocks/mock_peristaltic_pump.rs</code> || 85.00% (17/20) || 72.73% (8/11) || +12.27%
|-
| <code>src/mocks/mock_relay_manager.rs</code> || 82.50% (33/40) || 75.86% (22/29) || +6.64%
|-
| <code>src/mocks/mock_sql_interface.rs</code> || 66.21% (241/364) || 63.81% (134/210) || +2.40%
|-
| <code>src/mocks/mock_water_injection.rs</code> || 82.61% (19/23) || 75.00% (12/16) || +7.61%
|-
| <code>src/permission/process_privileges.rs</code> || 94.25% (377/400) || 81.58% (93/114) || +12.67%
|-
| <code>src/recorder/recorder.rs</code> || 84.77% (590/696) || 54.12% (269/497) || +30.65%
|-
| <code>src/recorder/recorder_channels.rs</code> || 58.82% (10/17) || 45.45% (5/11) || +13.37%
|-
| <code>src/recorder/recorder_data_frame.rs</code> || 52.66% (101/192) || 22.31% (27/121) || +30.35%
|-
| <code>src/relays/actuator_state.rs</code> || 74.07% (20/27) || 75.00% (15/20) || -0.93%
|-
| <code>src/relays/aquarium_device.rs</code> || 66.67% (14/21) || 68.75% (11/16) || -2.08%
|-
| <code>src/relays/relay_manager.rs</code> || 58.46% (394/674) || 45.43% (179/394) || +13.03%
|-
| <code>src/relays/relay_manager_channels.rs</code> || 90.91% (20/22) || 45.83% (11/24) || +45.08%
|-
| <code>src/sensors/atlas_scientific.rs</code> || 74.77% (329/440) || 55.42% (92/166) || +19.35%
|-
| <code>src/sensors/atlas_scientific_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/dht.rs</code> || 75.00% (105/140) || 53.64% (59/110) || +21.36%
|-
| <code>src/sensors/dht_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/ds18b20.rs</code> || 74.55% (123/165) || 51.09% (47/92) || +23.46%
|-
| <code>src/sensors/ds18b20_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/i2c_interface.rs</code> || 76.54% (362/473) || 57.51% (153/266) || +19.03%
|-
| <code>src/sensors/i2c_interface_channels.rs</code> || 69.23% (9/13) || 50.00% (3/6) || +19.23%
|-
| <code>src/sensors/sensor_manager.rs</code> || 76.10% (761/1000) || 54.34% (282/519) || +21.76%
|-
| <code>src/sensors/sensor_manager_channels.rs</code> || 84.62% (33/39) || 75.00% (9/12) || +9.62%
|-
| <code>src/thermal/heating.rs</code> || 90.96% (332/365) || 68.60% (148/216) || +22.36%
|-
| <code>src/thermal/heating_actuation.rs</code> || 84.47% (87/103) || 67.24% (39/58) || +17.23%
|-
| <code>src/thermal/heating_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/heating_set_vals.rs</code> || 87.50% (35/40) || 64.29% (18/28) || +23.21%
|-
| <code>src/thermal/heating_stats_entry.rs</code> || 94.67% (142/150) || 82.22% (74/90) || +12.44%
|-
| <code>src/thermal/saw_tooth_profile.rs</code> || 100.00% (64/64) || 100.00% (23/23) || +0.00%
|-
| <code>src/thermal/saw_tooth_profile_config.rs</code> || 70.83% (17/24) || 50.00% (7/14) || +20.83%
|-
| <code>src/thermal/temperature_gradient.rs</code> || 100.00% (64/64) || 100.00% (32/32) || +0.00%
|-
| <code>src/thermal/thermal_control_status.rs</code> || 81.25% (26/32) || 58.82% (10/17) || +22.43%
|-
| <code>src/thermal/ventilation.rs</code> || 87.67% (192/219) || 61.16% (74/121) || +26.51%
|-
| <code>src/thermal/ventilation_channels.rs</code> || 75.00% (15/20) || 50.00% (5/10) || +25.00%
|-
| <code>src/thermal/ventilation_set_vals.rs</code> || 58.82% (30/51) || 58.82% (20/34) || +0.00%
|-
| <code>src/utilities/config.rs</code> || 76.99% (830/1078) || 72.84% (437/600) || +4.15%
|-
| <code>src/utilities/spin_sleeper.rs</code> || 79.17% (19/24) || 69.23% (9/13) || +9.94%
|-
| <code>src/utilities/thread_builder.rs</code> || 92.59% (25/27) || 78.57% (11/14) || +14.02%
|-
| <code>src/watchmen/monitors.rs</code> || 64.29% (135/210) || 54.69% (70/128) || +9.60%
|-
| <code>src/water/refill.rs</code> || 86.81% (447/515) || 69.45% (216/311) || +17.36%
|-
| <code>src/water/refill_channels.rs</code> || 71.43% (10/14) || 57.14% (4/7) || +14.29%
|-
| <code>src/water/tank_level_switch.rs</code> || 84.14% (191/227) || 74.47% (105/141) || +9.67%
|-
| <code>src/water/tank_level_switch_signals.rs</code> || 90.36% (75/83) || 86.96% (40/46) || +3.40%
|}

== System tests using the simulator ==
Running the application in simulator mode.

Control application

2026-07-25T09:36:13Z

Uwe: /* Code coverage measurement */

Control application

2026-07-25T09:30:31Z

Uwe: /* Using tarpaulin */

Control application

2026-07-25T09:30:20Z

Uwe: /* Using tarpaulin */

Control application

2026-07-25T09:17:53Z

Uwe: /* Code coverage measurement */

Control application

2026-07-25T09:03:35Z

Uwe: /* Using llvm-cov */

Control application

2026-07-25T08:37:35Z

Uwe: /* Using llvm-cov */

Control application

2026-07-25T08:37:00Z

Uwe: /* Using llvm-cov */

Control application

2026-07-25T08:36:48Z

Uwe: /* Integration tests in test */

Control application

2026-07-25T08:36:36Z

Uwe: /* = Integration tests in test */

Control application

2026-07-25T08:36:25Z

Uwe:

Control application

2026-07-24T06:19:05Z

Uwe: /* Development environment */

Event-based deletion of old database entries

2026-07-24T05:58:36Z

Uwe: /* User privileges */

== Problem description ==
Over time, the size of the following four tables grows: <code>refill</code>, <code>ballingdosinglog</code>, <code>feedlog</code>, <code>data</code>.

You can query the size in the database with the following commands:

<pre>
MariaDB [aquarium]> select count(*) from refill;
+----------+
| count(*) |
+----------+
| 689 |
+----------+
1 row in set (0.001 sec)

MariaDB [aquarium]> select count(*) from ballingdosinglog;
+----------+
| count(*) |
+----------+
| 13362 |
+----------+
1 row in set (0.018 sec)

MariaDB [aquarium]> select count(*) from feedlog;
+----------+
| count(*) |
+----------+
| 263 |
+----------+
1 row in set (0.001 sec)

MariaDB [aquarium]> select count(*) from data;
+----------+
| count(*) |
+----------+
| 213043 |
+----------+
1 row in set (0.166 sec)

</pre>

Excessive database size impacts the performance and hence the stability of the aquarium control.
For this reason, the size needs to be limited by deleting old entries.

== Configuration of MariaDb ==
Activate the event scheduler by adding the two last lines of below example to MariaDb configuration file (usually <code>/etc/mysql/my.cnf</code> or <code>/etc/mysql/mariadb.conf.d/50-server.cnf</code>).

<pre>
# The MariaDB configuration file
#
# The MariaDB/MySQL tools read configuration files in the following order:
# 1. "/etc/mysql/mariadb.cnf" (this file) to set global defaults,
# 2. "/etc/mysql/conf.d/*.cnf" to set global options.
# 3. "/etc/mysql/mariadb.conf.d/*.cnf" to set MariaDB-only options.
# 4. "~/.my.cnf" to set user-specific options.
#
# If the same option is defined multiple times, the last one will apply.
#
# One can use all long options that the program supports.
# Run program with --help to get a list of available options and with
# --print-defaults to see which it would actually understand and use.

#
# This group is read both both by the client and the server
# use it for options that affect everything
#
[client-server]

# Import all .cnf files from configuration directory
!includedir /etc/mysql/conf.d/
!includedir /etc/mysql/mariadb.conf.d/

[mysqld]
event_scheduler=ON
</pre>

You can check the status of the event schedule by running the query <code>SHOW VARIABLES LIKE 'event_scheduler';</code>
<pre>
MariaDB [(none)]> SHOW VARIABLES LIKE 'event_scheduler';
+-----------------+-------+
| Variable_name | Value |
+-----------------+-------+
| event_scheduler | ON |
+-----------------+-------+
1 row in set (0.002 sec)
</pre>

== User privileges ==
Check if your database user account has sufficient privileges by running <code>SHOW GRANTS FOR user@localhost;</code>.

You can assign specific privilege for executing events by running:

<code>GRANT EVENT ON `your_database_name`.* TO 'your_username'@'localhost';</code>

and

<code>GRANT EXECUTE ON `your_database_name`.* TO 'your_username'@'localhost';</code>

and

<code>GRANT SUPER ON *.* TO 'your_username'@'localhost';</code>

and

<code>FLUSH PRIVILEGES;</code>.

== Restart of MariaDb ==
In the terminal, execute <code>sudo systemctl restart mariadb</code>.

== Status of MariaDb ==
In the terminal, execute <code>sudo systemctl status mariadb</code>.

The output should look similar to the following:

<pre>
● mariadb.service - MariaDB 10.3.39 database server
Loaded: loaded (/lib/systemd/system/mariadb.service; enabled; vendor preset: enabled)
Active: active (running) since Sat 2025-08-02 08:00:18 CEST; 1h 14min ago
Docs: man:mysqld(8)
https://mariadb.com/kb/en/library/systemd/
Process: 32624 ExecStartPre=/usr/bin/install -m 755 -o mysql -g root -d /var/run/mysqld (code=exited, status=0/SUCCESS)
Process: 32625 ExecStartPre=/bin/sh -c systemctl unset-environment _WSREP_START_POSITION (code=exited, status=0/SUCCESS)
Process: 32627 ExecStartPre=/bin/sh -c [ ! -e /usr/bin/galera_recovery ] && VAR= || VAR=`cd /usr/bin/..; /usr/bin/galera_recovery`; [ $? -eq 0 ] && systemctl set-environment _WSREP_START_POSITION=$VAR || exit 1 (code=exited, status=0/SUCCESS)
Process: 32717 ExecStartPost=/bin/sh -c systemctl unset-environment _WSREP_START_POSITION (code=exited, status=0/SUCCESS)
Process: 32719 ExecStartPost=/etc/mysql/debian-start (code=exited, status=0/SUCCESS)
Main PID: 32681 (mysqld)
Status: "Taking your SQL requests now..."
Tasks: 42 (limit: 1592)
CGroup: /system.slice/mariadb.service
└─32681 /usr/sbin/mysqld

Aug 02 08:00:17 raspberrypi systemd[1]: Starting MariaDB 10.3.39 database server...
Aug 02 08:00:18 raspberrypi systemd[1]: Started MariaDB 10.3.39 database server.
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32721]: Upgrading MySQL tables if necessary.
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: /usr/bin/mysql_upgrade: the '--basedir' option is always ignored
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: Looking for 'mysql' as: /usr/bin/mysql
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: Looking for 'mysqlcheck' as: /usr/bin/mysqlcheck
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: This installation of MariaDB is already upgraded to 10.3.39-MariaDB.
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: There is no need to run mysql_upgrade again for 10.3.39-MariaDB.
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: You can use --force if you still want to run mysql_upgrade
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32732]: Checking for insecure root accounts.
</pre>

== Adding events ==
The repository of the database contains a script <code>aquariumcontrol_database_cleanup_setup.sh</code>.
The script will set up the cleanup for the following tables:
{| class="wikitable"
|+ Configuration of retention period
! table name !! default period in days
|-
| balling_log || 60
|-
| data || 30
|-
| feed_log || 90
|-
| refill_log || 60
|-
| heating_stats || 1000
|}

== View events in MariaDb ==
You can display the configured events using <code>show events;</code>.

<pre>
MariaDB [aquarium]> show events;
+----------+----------------------------------+--------------------+-----------+-----------+------------+----------------+----------------+---------------------+------+---------+------------+----------------------+----------------------+--------------------+
| Db | Name | Definer | Time zone | Type | Execute at | Interval value | Interval field | Starts | Ends | Status | Originator | character_set_client | collation_connection | Database Collation |
+----------+----------------------------------+--------------------+-----------+-----------+------------+----------------+----------------+---------------------+------+---------+------------+----------------------+----------------------+--------------------+
| aquarium | cleanup_old_ballingdosinglog_60d | aquarium@localhost | SYSTEM | RECURRING | NULL | 1 | DAY | 2025-08-02 07:57:19 | NULL | ENABLED | 1 | utf8mb4 | utf8mb4_general_ci | utf8mb4_general_ci |
| aquarium | cleanup_old_data_30d | aquarium@localhost | SYSTEM | RECURRING | NULL | 1 | DAY | 2025-08-02 07:57:19 | NULL | ENABLED | 1 | utf8mb4 | utf8mb4_general_ci | utf8mb4_general_ci |
| aquarium | cleanup_old_feedlog_90d | aquarium@localhost | SYSTEM | RECURRING | NULL | 1 | DAY | 2025-08-02 07:57:19 | NULL | ENABLED | 1 | utf8mb4 | utf8mb4_general_ci | utf8mb4_general_ci |
| aquarium | cleanup_old_refill_60d | aquarium@localhost | SYSTEM | RECURRING | NULL | 1 | DAY | 2025-08-02 07:57:19 | NULL | ENABLED | 1 | utf8mb4 | utf8mb4_general_ci | utf8mb4_general_ci |
+----------+----------------------------------+--------------------+-----------+-----------+------------+----------------+----------------+---------------------+------+---------+------------+----------------------+----------------------+--------------------+
4 rows in set (0.002 sec)
</pre>

Event-based deletion of old database entries

2026-07-24T05:49:17Z

Uwe: /* User privileges */

== Problem description ==
Over time, the size of the following four tables grows: <code>refill</code>, <code>ballingdosinglog</code>, <code>feedlog</code>, <code>data</code>.

You can query the size in the database with the following commands:

<pre>
MariaDB [aquarium]> select count(*) from refill;
+----------+
| count(*) |
+----------+
| 689 |
+----------+
1 row in set (0.001 sec)

MariaDB [aquarium]> select count(*) from ballingdosinglog;
+----------+
| count(*) |
+----------+
| 13362 |
+----------+
1 row in set (0.018 sec)

MariaDB [aquarium]> select count(*) from feedlog;
+----------+
| count(*) |
+----------+
| 263 |
+----------+
1 row in set (0.001 sec)

MariaDB [aquarium]> select count(*) from data;
+----------+
| count(*) |
+----------+
| 213043 |
+----------+
1 row in set (0.166 sec)

</pre>

Excessive database size impacts the performance and hence the stability of the aquarium control.
For this reason, the size needs to be limited by deleting old entries.

== Configuration of MariaDb ==
Activate the event scheduler by adding the two last lines of below example to MariaDb configuration file (usually <code>/etc/mysql/my.cnf</code> or <code>/etc/mysql/mariadb.conf.d/50-server.cnf</code>).

<pre>
# The MariaDB configuration file
#
# The MariaDB/MySQL tools read configuration files in the following order:
# 1. "/etc/mysql/mariadb.cnf" (this file) to set global defaults,
# 2. "/etc/mysql/conf.d/*.cnf" to set global options.
# 3. "/etc/mysql/mariadb.conf.d/*.cnf" to set MariaDB-only options.
# 4. "~/.my.cnf" to set user-specific options.
#
# If the same option is defined multiple times, the last one will apply.
#
# One can use all long options that the program supports.
# Run program with --help to get a list of available options and with
# --print-defaults to see which it would actually understand and use.

#
# This group is read both both by the client and the server
# use it for options that affect everything
#
[client-server]

# Import all .cnf files from configuration directory
!includedir /etc/mysql/conf.d/
!includedir /etc/mysql/mariadb.conf.d/

[mysqld]
event_scheduler=ON
</pre>

You can check the status of the event schedule by running the query <code>SHOW VARIABLES LIKE 'event_scheduler';</code>
<pre>
MariaDB [(none)]> SHOW VARIABLES LIKE 'event_scheduler';
+-----------------+-------+
| Variable_name | Value |
+-----------------+-------+
| event_scheduler | ON |
+-----------------+-------+
1 row in set (0.002 sec)
</pre>

== User privileges ==
Check if your database user account has sufficient privileges by running <code>SHOW GRANTS FOR user@localhost;</code>.

You can assign specific privilege for executing events by running:

<code>GRANT EVENT ON `your_database_name`.* TO 'your_username'@'localhost';</code>.

and

<code>GRANT EXECUTE ON `your_database_name`.* TO 'your_username'@'localhost';</code>.

Alternatively, you can assign all privileges to your database user account by running <code>GRANT ALL PRIVILEGES ON `your_database_name`.* TO 'your_username'@'localhost';</code>.

In both cases, run additionally <code>FLUSH PRIVILEGES;</code>.

== Restart of MariaDb ==
In the terminal, execute <code>sudo systemctl restart mariadb</code>.

== Status of MariaDb ==
In the terminal, execute <code>sudo systemctl status mariadb</code>.

The output should look similar to the following:

<pre>
● mariadb.service - MariaDB 10.3.39 database server
Loaded: loaded (/lib/systemd/system/mariadb.service; enabled; vendor preset: enabled)
Active: active (running) since Sat 2025-08-02 08:00:18 CEST; 1h 14min ago
Docs: man:mysqld(8)
https://mariadb.com/kb/en/library/systemd/
Process: 32624 ExecStartPre=/usr/bin/install -m 755 -o mysql -g root -d /var/run/mysqld (code=exited, status=0/SUCCESS)
Process: 32625 ExecStartPre=/bin/sh -c systemctl unset-environment _WSREP_START_POSITION (code=exited, status=0/SUCCESS)
Process: 32627 ExecStartPre=/bin/sh -c [ ! -e /usr/bin/galera_recovery ] && VAR= || VAR=`cd /usr/bin/..; /usr/bin/galera_recovery`; [ $? -eq 0 ] && systemctl set-environment _WSREP_START_POSITION=$VAR || exit 1 (code=exited, status=0/SUCCESS)
Process: 32717 ExecStartPost=/bin/sh -c systemctl unset-environment _WSREP_START_POSITION (code=exited, status=0/SUCCESS)
Process: 32719 ExecStartPost=/etc/mysql/debian-start (code=exited, status=0/SUCCESS)
Main PID: 32681 (mysqld)
Status: "Taking your SQL requests now..."
Tasks: 42 (limit: 1592)
CGroup: /system.slice/mariadb.service
└─32681 /usr/sbin/mysqld

Aug 02 08:00:17 raspberrypi systemd[1]: Starting MariaDB 10.3.39 database server...
Aug 02 08:00:18 raspberrypi systemd[1]: Started MariaDB 10.3.39 database server.
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32721]: Upgrading MySQL tables if necessary.
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: /usr/bin/mysql_upgrade: the '--basedir' option is always ignored
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: Looking for 'mysql' as: /usr/bin/mysql
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: Looking for 'mysqlcheck' as: /usr/bin/mysqlcheck
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: This installation of MariaDB is already upgraded to 10.3.39-MariaDB.
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: There is no need to run mysql_upgrade again for 10.3.39-MariaDB.
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: You can use --force if you still want to run mysql_upgrade
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32732]: Checking for insecure root accounts.
</pre>

== Adding events ==
The repository of the database contains a script <code>aquariumcontrol_database_cleanup_setup.sh</code>.
The script will set up the cleanup for the following tables:
{| class="wikitable"
|+ Configuration of retention period
! table name !! default period in days
|-
| balling_log || 60
|-
| data || 30
|-
| feed_log || 90
|-
| refill_log || 60
|-
| heating_stats || 1000
|}

== View events in MariaDb ==
You can display the configured events using <code>show events;</code>.

<pre>
MariaDB [aquarium]> show events;
+----------+----------------------------------+--------------------+-----------+-----------+------------+----------------+----------------+---------------------+------+---------+------------+----------------------+----------------------+--------------------+
| Db | Name | Definer | Time zone | Type | Execute at | Interval value | Interval field | Starts | Ends | Status | Originator | character_set_client | collation_connection | Database Collation |
+----------+----------------------------------+--------------------+-----------+-----------+------------+----------------+----------------+---------------------+------+---------+------------+----------------------+----------------------+--------------------+
| aquarium | cleanup_old_ballingdosinglog_60d | aquarium@localhost | SYSTEM | RECURRING | NULL | 1 | DAY | 2025-08-02 07:57:19 | NULL | ENABLED | 1 | utf8mb4 | utf8mb4_general_ci | utf8mb4_general_ci |
| aquarium | cleanup_old_data_30d | aquarium@localhost | SYSTEM | RECURRING | NULL | 1 | DAY | 2025-08-02 07:57:19 | NULL | ENABLED | 1 | utf8mb4 | utf8mb4_general_ci | utf8mb4_general_ci |
| aquarium | cleanup_old_feedlog_90d | aquarium@localhost | SYSTEM | RECURRING | NULL | 1 | DAY | 2025-08-02 07:57:19 | NULL | ENABLED | 1 | utf8mb4 | utf8mb4_general_ci | utf8mb4_general_ci |
| aquarium | cleanup_old_refill_60d | aquarium@localhost | SYSTEM | RECURRING | NULL | 1 | DAY | 2025-08-02 07:57:19 | NULL | ENABLED | 1 | utf8mb4 | utf8mb4_general_ci | utf8mb4_general_ci |
+----------+----------------------------------+--------------------+-----------+-----------+------------+----------------+----------------+---------------------+------+---------+------------+----------------------+----------------------+--------------------+
4 rows in set (0.002 sec)
</pre>

Event-based deletion of old database entries

2026-07-24T05:41:05Z

Uwe: /* Adding events */

== Problem description ==
Over time, the size of the following four tables grows: <code>refill</code>, <code>ballingdosinglog</code>, <code>feedlog</code>, <code>data</code>.

You can query the size in the database with the following commands:

<pre>
MariaDB [aquarium]> select count(*) from refill;
+----------+
| count(*) |
+----------+
| 689 |
+----------+
1 row in set (0.001 sec)

MariaDB [aquarium]> select count(*) from ballingdosinglog;
+----------+
| count(*) |
+----------+
| 13362 |
+----------+
1 row in set (0.018 sec)

MariaDB [aquarium]> select count(*) from feedlog;
+----------+
| count(*) |
+----------+
| 263 |
+----------+
1 row in set (0.001 sec)

MariaDB [aquarium]> select count(*) from data;
+----------+
| count(*) |
+----------+
| 213043 |
+----------+
1 row in set (0.166 sec)

</pre>

Excessive database size impacts the performance and hence the stability of the aquarium control.
For this reason, the size needs to be limited by deleting old entries.

== Configuration of MariaDb ==
Activate the event scheduler by adding the two last lines of below example to MariaDb configuration file (usually <code>/etc/mysql/my.cnf</code> or <code>/etc/mysql/mariadb.conf.d/50-server.cnf</code>).

<pre>
# The MariaDB configuration file
#
# The MariaDB/MySQL tools read configuration files in the following order:
# 1. "/etc/mysql/mariadb.cnf" (this file) to set global defaults,
# 2. "/etc/mysql/conf.d/*.cnf" to set global options.
# 3. "/etc/mysql/mariadb.conf.d/*.cnf" to set MariaDB-only options.
# 4. "~/.my.cnf" to set user-specific options.
#
# If the same option is defined multiple times, the last one will apply.
#
# One can use all long options that the program supports.
# Run program with --help to get a list of available options and with
# --print-defaults to see which it would actually understand and use.

#
# This group is read both both by the client and the server
# use it for options that affect everything
#
[client-server]

# Import all .cnf files from configuration directory
!includedir /etc/mysql/conf.d/
!includedir /etc/mysql/mariadb.conf.d/

[mysqld]
event_scheduler=ON
</pre>

You can check the status of the event schedule by running the query <code>SHOW VARIABLES LIKE 'event_scheduler';</code>
<pre>
MariaDB [(none)]> SHOW VARIABLES LIKE 'event_scheduler';
+-----------------+-------+
| Variable_name | Value |
+-----------------+-------+
| event_scheduler | ON |
+-----------------+-------+
1 row in set (0.002 sec)
</pre>

== User privileges ==
Check if your database user account has sufficient privileges by running <code>show grants for user@localhost;</code>.

You can assign specific privilege for executing events by running <code>GRANT ALL PRIVILEGES ON `your_database_name`.* TO 'your_username'@'localhost';</code>.

Alternatively, you can assign all privileges to your database user account by running <code>GRANT ALL PRIVILEGES ON `your_database_name`.* TO 'your_username'@'localhost';</code>.

In both cases, run additionally <code>FLUSH PRIVILEGES;</code>.

== Restart of MariaDb ==
In the terminal, execute <code>sudo systemctl restart mariadb</code>.

== Status of MariaDb ==
In the terminal, execute <code>sudo systemctl status mariadb</code>.

The output should look similar to the following:

<pre>
● mariadb.service - MariaDB 10.3.39 database server
Loaded: loaded (/lib/systemd/system/mariadb.service; enabled; vendor preset: enabled)
Active: active (running) since Sat 2025-08-02 08:00:18 CEST; 1h 14min ago
Docs: man:mysqld(8)
https://mariadb.com/kb/en/library/systemd/
Process: 32624 ExecStartPre=/usr/bin/install -m 755 -o mysql -g root -d /var/run/mysqld (code=exited, status=0/SUCCESS)
Process: 32625 ExecStartPre=/bin/sh -c systemctl unset-environment _WSREP_START_POSITION (code=exited, status=0/SUCCESS)
Process: 32627 ExecStartPre=/bin/sh -c [ ! -e /usr/bin/galera_recovery ] && VAR= || VAR=`cd /usr/bin/..; /usr/bin/galera_recovery`; [ $? -eq 0 ] && systemctl set-environment _WSREP_START_POSITION=$VAR || exit 1 (code=exited, status=0/SUCCESS)
Process: 32717 ExecStartPost=/bin/sh -c systemctl unset-environment _WSREP_START_POSITION (code=exited, status=0/SUCCESS)
Process: 32719 ExecStartPost=/etc/mysql/debian-start (code=exited, status=0/SUCCESS)
Main PID: 32681 (mysqld)
Status: "Taking your SQL requests now..."
Tasks: 42 (limit: 1592)
CGroup: /system.slice/mariadb.service
└─32681 /usr/sbin/mysqld

Aug 02 08:00:17 raspberrypi systemd[1]: Starting MariaDB 10.3.39 database server...
Aug 02 08:00:18 raspberrypi systemd[1]: Started MariaDB 10.3.39 database server.
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32721]: Upgrading MySQL tables if necessary.
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: /usr/bin/mysql_upgrade: the '--basedir' option is always ignored
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: Looking for 'mysql' as: /usr/bin/mysql
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: Looking for 'mysqlcheck' as: /usr/bin/mysqlcheck
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: This installation of MariaDB is already upgraded to 10.3.39-MariaDB.
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: There is no need to run mysql_upgrade again for 10.3.39-MariaDB.
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: You can use --force if you still want to run mysql_upgrade
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32732]: Checking for insecure root accounts.
</pre>

== Adding events ==
The repository of the database contains a script <code>aquariumcontrol_database_cleanup_setup.sh</code>.
The script will set up the cleanup for the following tables:
{| class="wikitable"
|+ Configuration of retention period
! table name !! default period in days
|-
| balling_log || 60
|-
| data || 30
|-
| feed_log || 90
|-
| refill_log || 60
|-
| heating_stats || 1000
|}

== View events in MariaDb ==
You can display the configured events using <code>show events;</code>.

<pre>
MariaDB [aquarium]> show events;
+----------+----------------------------------+--------------------+-----------+-----------+------------+----------------+----------------+---------------------+------+---------+------------+----------------------+----------------------+--------------------+
| Db | Name | Definer | Time zone | Type | Execute at | Interval value | Interval field | Starts | Ends | Status | Originator | character_set_client | collation_connection | Database Collation |
+----------+----------------------------------+--------------------+-----------+-----------+------------+----------------+----------------+---------------------+------+---------+------------+----------------------+----------------------+--------------------+
| aquarium | cleanup_old_ballingdosinglog_60d | aquarium@localhost | SYSTEM | RECURRING | NULL | 1 | DAY | 2025-08-02 07:57:19 | NULL | ENABLED | 1 | utf8mb4 | utf8mb4_general_ci | utf8mb4_general_ci |
| aquarium | cleanup_old_data_30d | aquarium@localhost | SYSTEM | RECURRING | NULL | 1 | DAY | 2025-08-02 07:57:19 | NULL | ENABLED | 1 | utf8mb4 | utf8mb4_general_ci | utf8mb4_general_ci |
| aquarium | cleanup_old_feedlog_90d | aquarium@localhost | SYSTEM | RECURRING | NULL | 1 | DAY | 2025-08-02 07:57:19 | NULL | ENABLED | 1 | utf8mb4 | utf8mb4_general_ci | utf8mb4_general_ci |
| aquarium | cleanup_old_refill_60d | aquarium@localhost | SYSTEM | RECURRING | NULL | 1 | DAY | 2025-08-02 07:57:19 | NULL | ENABLED | 1 | utf8mb4 | utf8mb4_general_ci | utf8mb4_general_ci |
+----------+----------------------------------+--------------------+-----------+-----------+------------+----------------+----------------+---------------------+------+---------+------------+----------------------+----------------------+--------------------+
4 rows in set (0.002 sec)
</pre>

Event-based deletion of old database entries

2026-07-24T05:38:52Z

Uwe: /* Configuration of MariaDb */

== Problem description ==
Over time, the size of the following four tables grows: <code>refill</code>, <code>ballingdosinglog</code>, <code>feedlog</code>, <code>data</code>.

You can query the size in the database with the following commands:

<pre>
MariaDB [aquarium]> select count(*) from refill;
+----------+
| count(*) |
+----------+
| 689 |
+----------+
1 row in set (0.001 sec)

MariaDB [aquarium]> select count(*) from ballingdosinglog;
+----------+
| count(*) |
+----------+
| 13362 |
+----------+
1 row in set (0.018 sec)

MariaDB [aquarium]> select count(*) from feedlog;
+----------+
| count(*) |
+----------+
| 263 |
+----------+
1 row in set (0.001 sec)

MariaDB [aquarium]> select count(*) from data;
+----------+
| count(*) |
+----------+
| 213043 |
+----------+
1 row in set (0.166 sec)

</pre>

Excessive database size impacts the performance and hence the stability of the aquarium control.
For this reason, the size needs to be limited by deleting old entries.

== Configuration of MariaDb ==
Activate the event scheduler by adding the two last lines of below example to MariaDb configuration file (usually <code>/etc/mysql/my.cnf</code> or <code>/etc/mysql/mariadb.conf.d/50-server.cnf</code>).

<pre>
# The MariaDB configuration file
#
# The MariaDB/MySQL tools read configuration files in the following order:
# 1. "/etc/mysql/mariadb.cnf" (this file) to set global defaults,
# 2. "/etc/mysql/conf.d/*.cnf" to set global options.
# 3. "/etc/mysql/mariadb.conf.d/*.cnf" to set MariaDB-only options.
# 4. "~/.my.cnf" to set user-specific options.
#
# If the same option is defined multiple times, the last one will apply.
#
# One can use all long options that the program supports.
# Run program with --help to get a list of available options and with
# --print-defaults to see which it would actually understand and use.

#
# This group is read both both by the client and the server
# use it for options that affect everything
#
[client-server]

# Import all .cnf files from configuration directory
!includedir /etc/mysql/conf.d/
!includedir /etc/mysql/mariadb.conf.d/

[mysqld]
event_scheduler=ON
</pre>

You can check the status of the event schedule by running the query <code>SHOW VARIABLES LIKE 'event_scheduler';</code>
<pre>
MariaDB [(none)]> SHOW VARIABLES LIKE 'event_scheduler';
+-----------------+-------+
| Variable_name | Value |
+-----------------+-------+
| event_scheduler | ON |
+-----------------+-------+
1 row in set (0.002 sec)
</pre>

== User privileges ==
Check if your database user account has sufficient privileges by running <code>show grants for user@localhost;</code>.

You can assign specific privilege for executing events by running <code>GRANT ALL PRIVILEGES ON `your_database_name`.* TO 'your_username'@'localhost';</code>.

Alternatively, you can assign all privileges to your database user account by running <code>GRANT ALL PRIVILEGES ON `your_database_name`.* TO 'your_username'@'localhost';</code>.

In both cases, run additionally <code>FLUSH PRIVILEGES;</code>.

== Restart of MariaDb ==
In the terminal, execute <code>sudo systemctl restart mariadb</code>.

== Status of MariaDb ==
In the terminal, execute <code>sudo systemctl status mariadb</code>.

The output should look similar to the following:

<pre>
● mariadb.service - MariaDB 10.3.39 database server
Loaded: loaded (/lib/systemd/system/mariadb.service; enabled; vendor preset: enabled)
Active: active (running) since Sat 2025-08-02 08:00:18 CEST; 1h 14min ago
Docs: man:mysqld(8)
https://mariadb.com/kb/en/library/systemd/
Process: 32624 ExecStartPre=/usr/bin/install -m 755 -o mysql -g root -d /var/run/mysqld (code=exited, status=0/SUCCESS)
Process: 32625 ExecStartPre=/bin/sh -c systemctl unset-environment _WSREP_START_POSITION (code=exited, status=0/SUCCESS)
Process: 32627 ExecStartPre=/bin/sh -c [ ! -e /usr/bin/galera_recovery ] && VAR= || VAR=`cd /usr/bin/..; /usr/bin/galera_recovery`; [ $? -eq 0 ] && systemctl set-environment _WSREP_START_POSITION=$VAR || exit 1 (code=exited, status=0/SUCCESS)
Process: 32717 ExecStartPost=/bin/sh -c systemctl unset-environment _WSREP_START_POSITION (code=exited, status=0/SUCCESS)
Process: 32719 ExecStartPost=/etc/mysql/debian-start (code=exited, status=0/SUCCESS)
Main PID: 32681 (mysqld)
Status: "Taking your SQL requests now..."
Tasks: 42 (limit: 1592)
CGroup: /system.slice/mariadb.service
└─32681 /usr/sbin/mysqld

Aug 02 08:00:17 raspberrypi systemd[1]: Starting MariaDB 10.3.39 database server...
Aug 02 08:00:18 raspberrypi systemd[1]: Started MariaDB 10.3.39 database server.
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32721]: Upgrading MySQL tables if necessary.
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: /usr/bin/mysql_upgrade: the '--basedir' option is always ignored
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: Looking for 'mysql' as: /usr/bin/mysql
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: Looking for 'mysqlcheck' as: /usr/bin/mysqlcheck
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: This installation of MariaDB is already upgraded to 10.3.39-MariaDB.
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: There is no need to run mysql_upgrade again for 10.3.39-MariaDB.
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32724]: You can use --force if you still want to run mysql_upgrade
Aug 02 08:00:18 raspberrypi /etc/mysql/debian-start[32732]: Checking for insecure root accounts.
</pre>

== Adding events ==
The repository of the database contains a script <code>database_cleanup_setup.sh</code>.
The script will set up the cleanup for the following tables:
{| class="wikitable"
|+ Configuration of retention period
! table name !! default period in days
|-
| balling_log || 60
|-
| data || 30
|-
| feed_log || 90
|-
| refill_log || 60
|-
| heating_stats || 1000
|}

== View events in MariaDb ==
You can display the configured events using <code>show events;</code>.

<pre>
MariaDB [aquarium]> show events;
+----------+----------------------------------+--------------------+-----------+-----------+------------+----------------+----------------+---------------------+------+---------+------------+----------------------+----------------------+--------------------+
| Db | Name | Definer | Time zone | Type | Execute at | Interval value | Interval field | Starts | Ends | Status | Originator | character_set_client | collation_connection | Database Collation |
+----------+----------------------------------+--------------------+-----------+-----------+------------+----------------+----------------+---------------------+------+---------+------------+----------------------+----------------------+--------------------+
| aquarium | cleanup_old_ballingdosinglog_60d | aquarium@localhost | SYSTEM | RECURRING | NULL | 1 | DAY | 2025-08-02 07:57:19 | NULL | ENABLED | 1 | utf8mb4 | utf8mb4_general_ci | utf8mb4_general_ci |
| aquarium | cleanup_old_data_30d | aquarium@localhost | SYSTEM | RECURRING | NULL | 1 | DAY | 2025-08-02 07:57:19 | NULL | ENABLED | 1 | utf8mb4 | utf8mb4_general_ci | utf8mb4_general_ci |
| aquarium | cleanup_old_feedlog_90d | aquarium@localhost | SYSTEM | RECURRING | NULL | 1 | DAY | 2025-08-02 07:57:19 | NULL | ENABLED | 1 | utf8mb4 | utf8mb4_general_ci | utf8mb4_general_ci |
| aquarium | cleanup_old_refill_60d | aquarium@localhost | SYSTEM | RECURRING | NULL | 1 | DAY | 2025-08-02 07:57:19 | NULL | ENABLED | 1 | utf8mb4 | utf8mb4_general_ci | utf8mb4_general_ci |
+----------+----------------------------------+--------------------+-----------+-----------+------------+----------------+----------------+---------------------+------+---------+------------+----------------------+----------------------+--------------------+
4 rows in set (0.002 sec)
</pre>

SQL database

2026-07-18T17:08:31Z

Uwe: /* Configuration of connection timeout */

The control application uses a MySQL database for persistent storing of states and logging of activities as well as storage of input data.

The SQL database is also the main interface between the control application and the outside world (webpage, Apps).

The empty SQL dump of the databases are stored in the bitbucket repository:
git clone https://in-dubio@bitbucket.org/in-dubio/aquarium-database.git

As of December 2024, the databases are empty.
The databases for the tests are emptied and filled programmatically by the test cases before the execution of each test case.
The high number of test databases shall allow maximum parallelisation of the test case execution which takes several minutes.

After cloning the database repository, first create the test databases with the statement provided in <code>create_databases.sql</code>.
You might want to consider using different accounts for the databases between normal operation and test execution. The account data (user and password) are stated in the .toml configuration files.

Second, create the user(s): <code>CREATE USER aquarium@localhost;</code>
Set a password for the user with <code>ALTER USER 'aquarium'@'localhost' IDENTIFIED BY 'password';</code>
The combination of user and password in the .toml configuration file(s) must match with the provided password.

Next, import the database dumps into the database using <code>import_databases.sh</code>

Then, grant the access to the user(s) using <code>grant_access_rights.sql</code>

For operating the control, the SQL database must include the Balling dosing configuration of those pumps which are activated in the .toml configuration file.
The table <code>ballingsetvals</code> for the configuration of the Balling dosing pumps has the following structure:
<pre>
+--------------+-------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+--------------+-------------+------+-----+---------+-------+
| pumpid | int(11) | NO | | NULL | |
| dosingspeed | float | NO | | NULL | |
| dosingvolume | float | NO | | NULL | |
| label | varchar(10) | NO | | NULL | |
+--------------+-------------+------+-----+---------+-------+
</pre>

You can insert values as follows:
<code>
INSERT INTO ballingsetvals VALUES(1, 1.0, 0.5, "KH");
</code>

For stable operation of the database in the longterm, it is paramount to limit the database size.
This requires deletion of old entries. MariaDb offers the functionality of event scheduling.
The [[Event-based deletion of old database entries|event based deletion of old database entries]] needs to be setup by the user.

== Script-based setup of the database ==
The repository provides a script which conducts terminal-based communication with the user to fill the database.

=== Credentials for script-based setup of the database ===
Optionally, the user can provide credentials for accessing the database (by default, root privileges allow modification of all MariaDB databases).

The script checks if the provided credentials are valid.

=== Script-based setup of the user data ===
Optionally, the user can setup the user configuration in the table <code>users</code>.

The script offers the user the possibility to erase all existing user data.

The script repeatedly asks the user if he wishes to add user data.

For each entry that is added in the <code>users</code> table, the script asks the name stored in the column <code>name</code>.

The name must comply with a simple pattern: Only letters a-z and numbers are allowed - no special characters, no space.

If the name already exists, the script asks the user if he wishes to overwrite the data.

The script asks for the password that shall be used for the entry in the table.
The script stores a <code>bcrypt</code> hash in the column <code>password</code>.

=== Script-based setup of the Balling dosing configuration ===
Optionally, the user can setup the Balling mineral dosing configuration in the table <code>balling_set_vals</code>.

The script offers the user the possibility to erase all existing Balling dosing configuration.

The user can modify any pump configuration identified by the pump id which ranges from one to four.

Alternatively, the user can leave the configuration of a specific pump empty.

If there is an existing entry in the balling dosing configuration, the script asks the user if he wishes to overwrite this entry.

=== Script-based setup of the heating set values ===
Optionally, the user can setup the heating control in the table <code>heating_set_vals</code>.

If there is existing data in the table, the script asks the user if the data shall be erased.

The script asks the user for the temperature value to switch off the heating stored in the column <code>heating_switch_off_temp</code> and the temperature value to switch on the heating stored in the column <code>heating_switch_on_temp</code>.

The script checks if the value provided by the user for <code>heating_switch_off_temp</code> is higher than the value provided by the user for <code>heating_switch_on_temp</code>. If this is not the case, the script repeats the sequence for entering the data.

=== Script-based setup of the ventilation set values ===
Optionally, the user can setup the ventilation control in the table <code>ventilation_set_vals</code>.

If there is existing data in the table, the script asks the user if the data shall be erased.

The script asks the user for the temperature value to switch off the ventilation stored in the column <code>ventilation_switch_off_temp</code> and the temperature value to switch on the ventilation stored in the column <code>ventilation_switch_on_temp</code>.

The script checks if the value provided by the user for <code>ventilation_switch_off_temp</code> is lower than the value provided by the user for <code>ventilation_switch_on_temp</code>. If this is not the case, the script repeats the sequence for entering the data.

=== Script-based setup of the actuator schedule ===
Optionally, the user can request to setup a default actuator schedule in the table <code>schedule</code>.

If there is existing data in the table, the script asks the user if the data shall be erased.

The script creates the following entries:

{| class="wikitable" style="margin:auto"
|+ Default actuator schedule
|-
! schedule_type !! start_time !! stop_time !! is_active
|-
| balling || 0:00 || 23:59 || 0
|-
| refill || 0:00 || 23:59 || 0
|-
| ventilation || 0:00 || 23:59 || 0
|-
| heating || 0:00 || 23:59 || 0
|}

=== Configuration of connection timeout ===
Edit the file <code>/etc/mysql/mariadb.conf.d/50-server.cnf</code> and add <code>wait_timeout = 10000</code> at the bottom of the <code>[mysqld]</code> block.

Restart the database afterwards with <code>sudo systemctl restart mariadb</code>.

This avoids connection timeouts. The application checks this configuration during startup.

You can verify the change with the SQL command <code>SHOW VARIABLES LIKE '%timeout%';</code>.

SQL database

2026-07-18T17:07:02Z

Uwe:

The control application uses a MySQL database for persistent storing of states and logging of activities as well as storage of input data.

The SQL database is also the main interface between the control application and the outside world (webpage, Apps).

The empty SQL dump of the databases are stored in the bitbucket repository:
git clone https://in-dubio@bitbucket.org/in-dubio/aquarium-database.git

As of December 2024, the databases are empty.
The databases for the tests are emptied and filled programmatically by the test cases before the execution of each test case.
The high number of test databases shall allow maximum parallelisation of the test case execution which takes several minutes.

After cloning the database repository, first create the test databases with the statement provided in <code>create_databases.sql</code>.
You might want to consider using different accounts for the databases between normal operation and test execution. The account data (user and password) are stated in the .toml configuration files.

Second, create the user(s): <code>CREATE USER aquarium@localhost;</code>
Set a password for the user with <code>ALTER USER 'aquarium'@'localhost' IDENTIFIED BY 'password';</code>
The combination of user and password in the .toml configuration file(s) must match with the provided password.

Next, import the database dumps into the database using <code>import_databases.sh</code>

Then, grant the access to the user(s) using <code>grant_access_rights.sql</code>

For operating the control, the SQL database must include the Balling dosing configuration of those pumps which are activated in the .toml configuration file.
The table <code>ballingsetvals</code> for the configuration of the Balling dosing pumps has the following structure:
<pre>
+--------------+-------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+--------------+-------------+------+-----+---------+-------+
| pumpid | int(11) | NO | | NULL | |
| dosingspeed | float | NO | | NULL | |
| dosingvolume | float | NO | | NULL | |
| label | varchar(10) | NO | | NULL | |
+--------------+-------------+------+-----+---------+-------+
</pre>

You can insert values as follows:
<code>
INSERT INTO ballingsetvals VALUES(1, 1.0, 0.5, "KH");
</code>

For stable operation of the database in the longterm, it is paramount to limit the database size.
This requires deletion of old entries. MariaDb offers the functionality of event scheduling.
The [[Event-based deletion of old database entries|event based deletion of old database entries]] needs to be setup by the user.

== Script-based setup of the database ==
The repository provides a script which conducts terminal-based communication with the user to fill the database.

=== Credentials for script-based setup of the database ===
Optionally, the user can provide credentials for accessing the database (by default, root privileges allow modification of all MariaDB databases).

The script checks if the provided credentials are valid.

=== Script-based setup of the user data ===
Optionally, the user can setup the user configuration in the table <code>users</code>.

The script offers the user the possibility to erase all existing user data.

The script repeatedly asks the user if he wishes to add user data.

For each entry that is added in the <code>users</code> table, the script asks the name stored in the column <code>name</code>.

The name must comply with a simple pattern: Only letters a-z and numbers are allowed - no special characters, no space.

If the name already exists, the script asks the user if he wishes to overwrite the data.

The script asks for the password that shall be used for the entry in the table.
The script stores a <code>bcrypt</code> hash in the column <code>password</code>.

=== Script-based setup of the Balling dosing configuration ===
Optionally, the user can setup the Balling mineral dosing configuration in the table <code>balling_set_vals</code>.

The script offers the user the possibility to erase all existing Balling dosing configuration.

The user can modify any pump configuration identified by the pump id which ranges from one to four.

Alternatively, the user can leave the configuration of a specific pump empty.

If there is an existing entry in the balling dosing configuration, the script asks the user if he wishes to overwrite this entry.

=== Script-based setup of the heating set values ===
Optionally, the user can setup the heating control in the table <code>heating_set_vals</code>.

If there is existing data in the table, the script asks the user if the data shall be erased.

The script asks the user for the temperature value to switch off the heating stored in the column <code>heating_switch_off_temp</code> and the temperature value to switch on the heating stored in the column <code>heating_switch_on_temp</code>.

The script checks if the value provided by the user for <code>heating_switch_off_temp</code> is higher than the value provided by the user for <code>heating_switch_on_temp</code>. If this is not the case, the script repeats the sequence for entering the data.

=== Script-based setup of the ventilation set values ===
Optionally, the user can setup the ventilation control in the table <code>ventilation_set_vals</code>.

If there is existing data in the table, the script asks the user if the data shall be erased.

The script asks the user for the temperature value to switch off the ventilation stored in the column <code>ventilation_switch_off_temp</code> and the temperature value to switch on the ventilation stored in the column <code>ventilation_switch_on_temp</code>.

The script checks if the value provided by the user for <code>ventilation_switch_off_temp</code> is lower than the value provided by the user for <code>ventilation_switch_on_temp</code>. If this is not the case, the script repeats the sequence for entering the data.

=== Script-based setup of the actuator schedule ===
Optionally, the user can request to setup a default actuator schedule in the table <code>schedule</code>.

If there is existing data in the table, the script asks the user if the data shall be erased.

The script creates the following entries:

{| class="wikitable" style="margin:auto"
|+ Default actuator schedule
|-
! schedule_type !! start_time !! stop_time !! is_active
|-
| balling || 0:00 || 23:59 || 0
|-
| refill || 0:00 || 23:59 || 0
|-
| ventilation || 0:00 || 23:59 || 0
|-
| heating || 0:00 || 23:59 || 0
|}

=== Configuration of connection timeout ===
Edit the file <code>/etc/mysql/mariadb.conf.d/50-server.cnf</code> and add <code>wait_timeout = 10000</code>.

This avoids connection timeouts. The application checks this configuration during startup.

SQL database

2026-07-18T17:06:46Z

Uwe:

The control application uses a MySQL database for persistent storing of states and logging of activities as well as storage of input data.

The SQL database is also the main interface between the control application and the outside world (webpage, Apps).

The empty SQL dump of the databases are stored in the bitbucket repository:
git clone https://in-dubio@bitbucket.org/in-dubio/aquarium-database.git

As of December 2024, the databases are empty.
The databases for the tests are emptied and filled programmatically by the test cases before the execution of each test case.
The high number of test databases shall allow maximum parallelisation of the test case execution which takes several minutes.

After cloning the database repository, first create the test databases with the statement provided in <code>create_databases.sql</code>.
You might want to consider using different accounts for the databases between normal operation and test execution. The account data (user and password) are stated in the .toml configuration files.

Second, create the user(s): <code>CREATE USER aquarium@localhost;</code>
Set a password for the user with <code>ALTER USER 'aquarium'@'localhost' IDENTIFIED BY 'password';</code>
The combination of user and password in the .toml configuration file(s) must match with the provided password.

Next, import the database dumps into the database using <code>import_databases.sh</code>

Then, grant the access to the user(s) using <code>grant_access_rights.sql</code>

For operating the control, the SQL database must include the Balling dosing configuration of those pumps which are activated in the .toml configuration file.
The table <code>ballingsetvals</code> for the configuration of the Balling dosing pumps has the following structure:
<pre>
+--------------+-------------+------+-----+---------+-------+
| Field | Type | Null | Key | Default | Extra |
+--------------+-------------+------+-----+---------+-------+
| pumpid | int(11) | NO | | NULL | |
| dosingspeed | float | NO | | NULL | |
| dosingvolume | float | NO | | NULL | |
| label | varchar(10) | NO | | NULL | |
+--------------+-------------+------+-----+---------+-------+
</pre>

You can insert values as follows:
<code>
INSERT INTO ballingsetvals VALUES(1, 1.0, 0.5, "KH");
</code>

For stable operation of the database in the longterm, it is paramount to limit the database size.
This requires deletion of old entries. MariaDb offers the functionality of event scheduling.
The [[Event-based deletion of old database entries|event based deletion of old database entries]] needs to be setup by the user.

== Script-based setup of the database ==
The repository provides a script which conducts terminal-based communication with the user to fill the database.

=== Credentials for script-based setup of the database ===
Optionally, the user can provide credentials for accessing the database (by default, root privileges allow modification of all MariaDB databases).

The script checks if the provided credentials are valid.

=== Script-based setup of the user data ===
Optionally, the user can setup the user configuration in the table <code>users</code>.

The script offers the user the possibility to erase all existing user data.

The script repeatedly asks the user if he wishes to add user data.

For each entry that is added in the <code>users</code> table, the script asks the name stored in the column <code>name</code>.

The name must comply with a simple pattern: Only letters a-z and numbers are allowed - no special characters, no space.

If the name already exists, the script asks the user if he wishes to overwrite the data.

The script asks for the password that shall be used for the entry in the table.
The script stores a <code>bcrypt</code> hash in the column <code>password</code>.

=== Script-based setup of the Balling dosing configuration ===
Optionally, the user can setup the Balling mineral dosing configuration in the table <code>balling_set_vals</code>.

The script offers the user the possibility to erase all existing Balling dosing configuration.

The user can modify any pump configuration identified by the pump id which ranges from one to four.

Alternatively, the user can leave the configuration of a specific pump empty.

If there is an existing entry in the balling dosing configuration, the script asks the user if he wishes to overwrite this entry.

=== Script-based setup of the heating set values ===
Optionally, the user can setup the heating control in the table <code>heating_set_vals</code>.

If there is existing data in the table, the script asks the user if the data shall be erased.

The script asks the user for the temperature value to switch off the heating stored in the column <code>heating_switch_off_temp</code> and the temperature value to switch on the heating stored in the column <code>heating_switch_on_temp</code>.

The script checks if the value provided by the user for <code>heating_switch_off_temp</code> is higher than the value provided by the user for <code>heating_switch_on_temp</code>. If this is not the case, the script repeats the sequence for entering the data.

=== Script-based setup of the ventilation set values ===
Optionally, the user can setup the ventilation control in the table <code>ventilation_set_vals</code>.

If there is existing data in the table, the script asks the user if the data shall be erased.

The script asks the user for the temperature value to switch off the ventilation stored in the column <code>ventilation_switch_off_temp</code> and the temperature value to switch on the ventilation stored in the column <code>ventilation_switch_on_temp</code>.

The script checks if the value provided by the user for <code>ventilation_switch_off_temp</code> is lower than the value provided by the user for <code>ventilation_switch_on_temp</code>. If this is not the case, the script repeats the sequence for entering the data.

=== Script-based setup of the actuator schedule ===
Optionally, the user can request to setup a default actuator schedule in the table <code>schedule</code>.

If there is existing data in the table, the script asks the user if the data shall be erased.

The script creates the following entries:

{| class="wikitable" style="margin:auto"
|+ Default actuator schedule
|-
! schedule_type !! start_time !! stop_time !! is_active
|-
| balling || 0:00 || 23:59 || 0
|-
| refill || 0:00 || 23:59 || 0
|-
| ventilation || 0:00 || 23:59 || 0
|-
| heating || 0:00 || 23:59 || 0
|}

=== Configuration of connection timeout ===
Edit the file <code>/etc/mysql/mariadb.conf.d/50-server.cnf</code> and add <code>wait_timeout = 10000</code>.
This avoids connection timeouts. The application checks this configuration during startup.

Use of an asynchronous runtime for the main application

2026-07-12T09:16:03Z

Uwe: /* Overview */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the Tokio asynchronous runtime for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated native operating system threads for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
# <code>worker_threads(1)</code>: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
# <code>max_blocking_threads(4)</code>: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via <code>tokio::task::spawn_blocking</code> or <code>block_in_place</code>).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with Tokio Console integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
# Use the <code>debug_tokio</code> feature flag, which initializes the <code>console-subscriber</code> in <code>run.rs</code>: <code>RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"</code>
# The <code>tokio_unstable</code> compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
<code>cargo install --locked tokio-console</code>

==== Running and Reading ====
# Launch the compiled application:
# Open a separate terminal window and run <code>tokio-console</code>.
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.

[[File:tokio-console.png | center | 800px | Screenshot of tokio-console during execution of the main application.]]

=== Interpreting Task Size Warnings ===
When checking with <code>tokio-console</code>, you see warnings that tasks like <code>signal_handler</code>, <code>relay_manager</code>, <code>data_logger</code>, or <code>heating</code> are 1024 bytes or larger.
* These warnings can be safely ignored.
* The size refers to the stack footprint of the compiler-generated <code>Future</code> state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:48:26Z

Uwe: /* Running and Reading */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
# <code>worker_threads(1)</code>: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
# <code>max_blocking_threads(4)</code>: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via <code>tokio::task::spawn_blocking</code> or <code>block_in_place</code>).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with Tokio Console integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
# Use the <code>debug_tokio</code> feature flag, which initializes the <code>console-subscriber</code> in <code>run.rs</code>: <code>RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"</code>
# The <code>tokio_unstable</code> compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
<code>cargo install --locked tokio-console</code>

==== Running and Reading ====
# Launch the compiled application:
# Open a separate terminal window and run <code>tokio-console</code>.
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.

[[File:tokio-console.png | center | 800px | Screenshot of tokio-console during execution of the main application.]]

=== Interpreting Task Size Warnings ===
When checking with <code>tokio-console</code>, you see warnings that tasks like <code>signal_handler</code>, <code>relay_manager</code>, <code>data_logger</code>, or <code>heating</code> are 1024 bytes or larger.
* These warnings can be safely ignored.
* The size refers to the stack footprint of the compiler-generated <code>Future</code> state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:48:16Z

Uwe: /* Running and Reading */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
# <code>worker_threads(1)</code>: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
# <code>max_blocking_threads(4)</code>: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via <code>tokio::task::spawn_blocking</code> or <code>block_in_place</code>).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with Tokio Console integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
# Use the <code>debug_tokio</code> feature flag, which initializes the <code>console-subscriber</code> in <code>run.rs</code>: <code>RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"</code>
# The <code>tokio_unstable</code> compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
<code>cargo install --locked tokio-console</code>

==== Running and Reading ====
# Launch the compiled application:
# Open a separate terminal window and run <code>tokio-console</code>.
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.

[[File:tokio-console.png | center | 300px | Screenshot of tokio-console during execution of the main application.]]

=== Interpreting Task Size Warnings ===
When checking with <code>tokio-console</code>, you see warnings that tasks like <code>signal_handler</code>, <code>relay_manager</code>, <code>data_logger</code>, or <code>heating</code> are 1024 bytes or larger.
* These warnings can be safely ignored.
* The size refers to the stack footprint of the compiler-generated <code>Future</code> state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:47:57Z

Uwe: /* Running and Reading */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
# <code>worker_threads(1)</code>: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
# <code>max_blocking_threads(4)</code>: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via <code>tokio::task::spawn_blocking</code> or <code>block_in_place</code>).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with Tokio Console integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
# Use the <code>debug_tokio</code> feature flag, which initializes the <code>console-subscriber</code> in <code>run.rs</code>: <code>RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"</code>
# The <code>tokio_unstable</code> compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
<code>cargo install --locked tokio-console</code>

==== Running and Reading ====
# Launch the compiled application:
# Open a separate terminal window and run <code>tokio-console</code>.
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.
[[File:tokio-console.png | 300px | Screenshot of tokio-console during execution of the main application.]]

=== Interpreting Task Size Warnings ===
When checking with <code>tokio-console</code>, you see warnings that tasks like <code>signal_handler</code>, <code>relay_manager</code>, <code>data_logger</code>, or <code>heating</code> are 1024 bytes or larger.
* These warnings can be safely ignored.
* The size refers to the stack footprint of the compiler-generated <code>Future</code> state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:47:20Z

Uwe: /* Running and Reading */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
# <code>worker_threads(1)</code>: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
# <code>max_blocking_threads(4)</code>: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via <code>tokio::task::spawn_blocking</code> or <code>block_in_place</code>).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with Tokio Console integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
# Use the <code>debug_tokio</code> feature flag, which initializes the <code>console-subscriber</code> in <code>run.rs</code>: <code>RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"</code>
# The <code>tokio_unstable</code> compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
<code>cargo install --locked tokio-console</code>

==== Running and Reading ====
# Launch the compiled application:
# Open a separate terminal window and run <code>tokio-console</code>.
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.
[[File:tokio-console.png | Screenshot of tokio-console during execution of the main application.]]

=== Interpreting Task Size Warnings ===
When checking with <code>tokio-console</code>, you see warnings that tasks like <code>signal_handler</code>, <code>relay_manager</code>, <code>data_logger</code>, or <code>heating</code> are 1024 bytes or larger.
* These warnings can be safely ignored.
* The size refers to the stack footprint of the compiler-generated <code>Future</code> state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:46:53Z

Uwe: /* Running and Reading */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
# <code>worker_threads(1)</code>: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
# <code>max_blocking_threads(4)</code>: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via <code>tokio::task::spawn_blocking</code> or <code>block_in_place</code>).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with Tokio Console integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
# Use the <code>debug_tokio</code> feature flag, which initializes the <code>console-subscriber</code> in <code>run.rs</code>: <code>RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"</code>
# The <code>tokio_unstable</code> compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
<code>cargo install --locked tokio-console</code>

==== Running and Reading ====
# Launch the compiled application:
# Open a separate terminal window and run <code>tokio-console</code>.
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.
[[File:tokio-console.png | thumb | Screenshot of tokio-console during execution of the main application.]]

=== Interpreting Task Size Warnings ===
When checking with <code>tokio-console</code>, you see warnings that tasks like <code>signal_handler</code>, <code>relay_manager</code>, <code>data_logger</code>, or <code>heating</code> are 1024 bytes or larger.
* These warnings can be safely ignored.
* The size refers to the stack footprint of the compiler-generated <code>Future</code> state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:45:49Z

Uwe: /* Running and Reading */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
# <code>worker_threads(1)</code>: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
# <code>max_blocking_threads(4)</code>: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via <code>tokio::task::spawn_blocking</code> or <code>block_in_place</code>).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with Tokio Console integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
# Use the <code>debug_tokio</code> feature flag, which initializes the <code>console-subscriber</code> in <code>run.rs</code>: <code>RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"</code>
# The <code>tokio_unstable</code> compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
<code>cargo install --locked tokio-console</code>

==== Running and Reading ====
1. Launch the compiled application:
2. Open a separate terminal window and run <code>tokio-console</code>.
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.
[[File:tokio-terminal.png | thumb | Screenshot of tokio-terminal during execution of the main application.]]

=== Interpreting Task Size Warnings ===
When checking with <code>tokio-console</code>, you see warnings that tasks like <code>signal_handler</code>, <code>relay_manager</code>, <code>data_logger</code>, or <code>heating</code> are 1024 bytes or larger.
* These warnings can be safely ignored.
* The size refers to the stack footprint of the compiler-generated <code>Future</code> state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:44:33Z

Uwe: /* Developer Diagnostics with Tokio Console */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
# <code>worker_threads(1)</code>: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
# <code>max_blocking_threads(4)</code>: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via <code>tokio::task::spawn_blocking</code> or <code>block_in_place</code>).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with Tokio Console integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
# Use the <code>debug_tokio</code> feature flag, which initializes the <code>console-subscriber</code> in <code>run.rs</code>: <code>RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"</code>
# The <code>tokio_unstable</code> compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
<code>cargo install --locked tokio-console</code>

==== Running and Reading ====
1. Launch the compiled application:
2. Open a separate terminal window and run <code>tokio-console</code>.
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.
[[File:File.jpg]]

=== Interpreting Task Size Warnings ===
When checking with <code>tokio-console</code>, you see warnings that tasks like <code>signal_handler</code>, <code>relay_manager</code>, <code>data_logger</code>, or <code>heating</code> are 1024 bytes or larger.
* These warnings can be safely ignored.
* The size refers to the stack footprint of the compiler-generated <code>Future</code> state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

File:Tokio-console.png

2026-07-11T11:43:37Z

Uwe: Screenshot of tokio-console during execution of main application

== Summary ==
Screenshot of tokio-console during execution of main application

Use of an asynchronous runtime for the main application

2026-07-11T11:42:15Z

Uwe: /* Overview */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
# <code>worker_threads(1)</code>: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
# <code>max_blocking_threads(4)</code>: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via <code>tokio::task::spawn_blocking</code> or <code>block_in_place</code>).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with **Tokio Console** integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
# Use the <code>debug_tokio</code> feature flag, which initializes the <code>console-subscriber</code> in <code>run.rs</code>: <code>RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"</code>
# The <code>tokio_unstable</code> compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
<code>cargo install --locked tokio-console</code>

==== Running and Reading ====
1. Launch the compiled application:
2. Open a separate terminal window and run <code>tokio-console</code>.
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.

=== Interpreting Task Size Warnings ===
When checking with <code>tokio-console</code>, you see warnings that tasks like <code>signal_handler</code>, <code>relay_manager</code>, <code>data_logger</code>, or <code>heating</code> are 1024 bytes or larger.
* These warnings can be safely ignored.
* The size refers to the stack footprint of the compiler-generated <code>Future</code> state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:42:00Z

Uwe: /* Interpreting Task Size Warnings */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

---

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
# <code>worker_threads(1)</code>: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
# <code>max_blocking_threads(4)</code>: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via <code>tokio::task::spawn_blocking</code> or <code>block_in_place</code>).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with **Tokio Console** integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
# Use the <code>debug_tokio</code> feature flag, which initializes the <code>console-subscriber</code> in <code>run.rs</code>: <code>RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"</code>
# The <code>tokio_unstable</code> compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
<code>cargo install --locked tokio-console</code>

==== Running and Reading ====
1. Launch the compiled application:
2. Open a separate terminal window and run <code>tokio-console</code>.
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.

=== Interpreting Task Size Warnings ===
When checking with <code>tokio-console</code>, you see warnings that tasks like <code>signal_handler</code>, <code>relay_manager</code>, <code>data_logger</code>, or <code>heating</code> are 1024 bytes or larger.
* These warnings can be safely ignored.
* The size refers to the stack footprint of the compiler-generated <code>Future</code> state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:41:46Z

Uwe: /* Interpreting Task Size Warnings */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

---

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
# <code>worker_threads(1)</code>: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
# <code>max_blocking_threads(4)</code>: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via <code>tokio::task::spawn_blocking</code> or <code>block_in_place</code>).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with **Tokio Console** integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
# Use the <code>debug_tokio</code> feature flag, which initializes the <code>console-subscriber</code> in <code>run.rs</code>: <code>RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"</code>
# The <code>tokio_unstable</code> compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
<code>cargo install --locked tokio-console</code>

==== Running and Reading ====
1. Launch the compiled application:
2. Open a separate terminal window and run <code>tokio-console</code>.
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.

=== Interpreting Task Size Warnings ===
When checking with <code>tokio-console</code>, you see warnings that tasks like <code>signal_handler</code>, <code>relay_manager</code>, <code>data_logger</code>, or <code>heating</code> are **1024 bytes or larger**.
* These warnings can be safely ignored.
* The size refers to the stack footprint of the compiler-generated <code>Future</code> state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:41:28Z

Uwe: /* Prerequisites & Compilation */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

---

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
# <code>worker_threads(1)</code>: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
# <code>max_blocking_threads(4)</code>: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via <code>tokio::task::spawn_blocking</code> or <code>block_in_place</code>).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with **Tokio Console** integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
# Use the <code>debug_tokio</code> feature flag, which initializes the <code>console-subscriber</code> in <code>run.rs</code>: <code>RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"</code>
# The <code>tokio_unstable</code> compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
<code>cargo install --locked tokio-console</code>

==== Running and Reading ====
1. Launch the compiled application:
2. Open a separate terminal window and run <code>tokio-console</code>.
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.

=== Interpreting Task Size Warnings ===
When checking with <code>tokio-console</code>, you see warnings that tasks like <code>signal_handler</code>, <code>relay_manager</code>, <code>data_logger</code>, or <code>heating</code> are **1024 bytes or larger**.
* **These warnings can be safely ignored.**
* The size refers to the stack footprint of the compiler-generated <code>Future</code> state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:41:08Z

Uwe: /* Prerequisites & Compilation */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

---

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
# <code>worker_threads(1)</code>: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
# <code>max_blocking_threads(4)</code>: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via <code>tokio::task::spawn_blocking</code> or <code>block_in_place</code>).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with **Tokio Console** integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
# Use the <code>debug_tokio</code> feature flag, which initializes the <code>console-subscriber</code> in <code>run.rs</code>:
<code>RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"</code>
# The <code>tokio_unstable</code> compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
<code>cargo install --locked tokio-console</code>

==== Running and Reading ====
1. Launch the compiled application:
2. Open a separate terminal window and run <code>tokio-console</code>.
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.

=== Interpreting Task Size Warnings ===
When checking with <code>tokio-console</code>, you see warnings that tasks like <code>signal_handler</code>, <code>relay_manager</code>, <code>data_logger</code>, or <code>heating</code> are **1024 bytes or larger**.
* **These warnings can be safely ignored.**
* The size refers to the stack footprint of the compiler-generated <code>Future</code> state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:40:50Z

Uwe: /* Why this configuration is chosen */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

---

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
# <code>worker_threads(1)</code>: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
# <code>max_blocking_threads(4)</code>: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via <code>tokio::task::spawn_blocking</code> or <code>block_in_place</code>).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with **Tokio Console** integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
1. Use the <code>debug_tokio</code> feature flag, which initializes the <code>console-subscriber</code> in <code>run.rs</code>:
<code>RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"</code>
2. The <code>tokio_unstable</code> compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
<code>cargo install --locked tokio-console</code>

==== Running and Reading ====
1. Launch the compiled application:
2. Open a separate terminal window and run <code>tokio-console</code>.
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.

=== Interpreting Task Size Warnings ===
When checking with <code>tokio-console</code>, you see warnings that tasks like <code>signal_handler</code>, <code>relay_manager</code>, <code>data_logger</code>, or <code>heating</code> are **1024 bytes or larger**.
* **These warnings can be safely ignored.**
* The size refers to the stack footprint of the compiler-generated <code>Future</code> state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:40:04Z

Uwe: /* Tokio Runtime Configuration */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

---

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
1. <code>worker_threads(1)</code>: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
2. <code>max_blocking_threads(4)</code>: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via <code>tokio::task::spawn_blocking</code> or <code>block_in_place</code>).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with **Tokio Console** integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
1. Use the <code>debug_tokio</code> feature flag, which initializes the <code>console-subscriber</code> in <code>run.rs</code>:
<code>RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"</code>
2. The <code>tokio_unstable</code> compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
<code>cargo install --locked tokio-console</code>

==== Running and Reading ====
1. Launch the compiled application:
2. Open a separate terminal window and run <code>tokio-console</code>.
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.

=== Interpreting Task Size Warnings ===
When checking with <code>tokio-console</code>, you see warnings that tasks like <code>signal_handler</code>, <code>relay_manager</code>, <code>data_logger</code>, or <code>heating</code> are **1024 bytes or larger**.
* **These warnings can be safely ignored.**
* The size refers to the stack footprint of the compiler-generated <code>Future</code> state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:36:31Z

Uwe: /* Tokio Runtime Configuration */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

---

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<syntaxhighlight lang="rust">
let rt = tokio::runtime::Builder::new_multi_thread()
.worker_threads(1)
.max_blocking_threads(4)
.enable_all()
.build()
</syntaxhighlight>
<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
1. **`worker_threads(1)`**: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
2. **`max_blocking_threads(4)`**: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via `tokio::task::spawn_blocking` or `block_in_place`).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with **Tokio Console** integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
1. Use the `debug_tokio` feature flag, which initializes the `console-subscriber` in `run.rs`:
```bash
RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"
```
2. The `tokio_unstable` compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
```bash
cargo install --locked tokio-console
```

==== Running and Reading ====
1. Launch the compiled application:
2. Open a separate terminal window and run:
```bash
tokio-console
```
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.

=== Interpreting Task Size Warnings ===
When checking with `tokio-console`, you see warnings that tasks like `signal_handler`, `relay_manager`, `data_logger`, or `heating` are **1024 bytes or larger**.
* **These warnings can be safely ignored.**
* The size refers to the stack footprint of the compiler-generated `Future` state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:36:20Z

Uwe: /* Tokio Runtime Configuration */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

---

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<syntaxhighlight lang="rust" line>
let rt = tokio::runtime::Builder::new_multi_thread()
.worker_threads(1)
.max_blocking_threads(4)
.enable_all()
.build()
</syntaxhighlight>
<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
1. **`worker_threads(1)`**: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
2. **`max_blocking_threads(4)`**: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via `tokio::task::spawn_blocking` or `block_in_place`).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with **Tokio Console** integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
1. Use the `debug_tokio` feature flag, which initializes the `console-subscriber` in `run.rs`:
```bash
RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"
```
2. The `tokio_unstable` compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
```bash
cargo install --locked tokio-console
```

==== Running and Reading ====
1. Launch the compiled application:
2. Open a separate terminal window and run:
```bash
tokio-console
```
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.

=== Interpreting Task Size Warnings ===
When checking with `tokio-console`, you see warnings that tasks like `signal_handler`, `relay_manager`, `data_logger`, or `heating` are **1024 bytes or larger**.
* **These warnings can be safely ignored.**
* The size refers to the stack footprint of the compiler-generated `Future` state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:36:04Z

Uwe: /* Tokio Runtime Configuration */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

---

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<syntaxhighlight lang="rust" line>
let rt = tokio::runtime::Builder::new_multi_thread()
.worker_threads(1)
.max_blocking_threads(4)
.enable_all()
.build()
<syntaxhighlight>
<code>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
</code>
=== Why this configuration is chosen ===
1. **`worker_threads(1)`**: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
2. **`max_blocking_threads(4)`**: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via `tokio::task::spawn_blocking` or `block_in_place`).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with **Tokio Console** integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
1. Use the `debug_tokio` feature flag, which initializes the `console-subscriber` in `run.rs`:
```bash
RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"
```
2. The `tokio_unstable` compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
```bash
cargo install --locked tokio-console
```

==== Running and Reading ====
1. Launch the compiled application:
2. Open a separate terminal window and run:
```bash
tokio-console
```
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.

=== Interpreting Task Size Warnings ===
When checking with `tokio-console`, you see warnings that tasks like `signal_handler`, `relay_manager`, `data_logger`, or `heating` are **1024 bytes or larger**.
* **These warnings can be safely ignored.**
* The size refers to the stack footprint of the compiler-generated `Future` state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.

Use of an asynchronous runtime for the main application

2026-07-11T11:35:48Z

Uwe: /* Tokio Runtime Configuration */

= Overview =
The Aquarium Control application uses a hybrid execution model to balance responsiveness, low latency, and hardware constraints. It uses the **Tokio asynchronous runtime** for coordinating sensor logging, network communication, safety interlocks, and scheduling. Concurrently, it spawns dedicated **native operating system threads** for operations requiring strict timing or blocking I/O (such as direct GPIO sensor reading).

---

== Task and Thread Inventory ==

The table below lists all tasks and threads running in the application:

{| class="wikitable sortable"
|-
! Name
! Description
! Type (OS Thread / Async Task)
! Usage of <code>block_on</code>
|-
| '''Main Thread'''
| Bootstraps the application, reads configuration, establishes database pools, builds the Tokio runtime, and blocks on the execution of all tasks.
| OS Thread
| Yes (<code>rt.block_on</code>)
|-
| '''<code>TcpCommunication</code>'''
| Mock simulator thread that handles TCP connections and commands from the GUI simulator. Runs only when <code>use_simulator</code> is active.
| OS Thread
| No
|-
| '''<code>Dht</code>'''
| Direct driver reader thread for the DHT22 ambient temperature and humidity sensor. Handled as an OS thread to prevent blocking the async runtime.
| OS Thread
| No
|-
| '''<code>i2c_interface</code>'''
| Manages serial I2C bus communications for sensor expansion units.
| Async Task
| No
|-
| '''<code>signal_handler</code>'''
| Captures shutdown signals (SIGINT, SIGTERM) and coordinates the graceful, phase-based shutdown of all sub-components.
| Async Task
| No
|-
| '''<code>schedule_check</code>'''
| Performs regular database checks against the active rules database to ensure operations are authorized based on the current time.
| Async Task
| No
|-
| '''<code>sensor_manager</code>'''
| Coordinates, aggregates, and caches values read from individual sensor tasks (DS18B20, DHT22, Atlas Scientific).
| Async Task
| No
|-
| '''<code>atlas_scientific</code>'''
| Manages data acquisition and calibration for the Atlas Scientific EZO pH and conductivity probes.
| Async Task
| No
|-
| '''<code>relay_manager</code>'''
| Acts as the central actuator gateway, processing on/off/pulse commands and sending them directly to the hardware relays.
| Async Task
| No
|-
| '''<code>data_logger</code>'''
| Periodically logs sensor values and thermal controller statuses into the MySQL database.
| Async Task
| No
|-
| '''<code>temperature_gradient</code>'''
| Monitors the rate of temperature changes to detect heater or ventilation inefficiencies/failures.
| Async Task
| No
|-
| '''<code>heating</code>'''
| Orchestrates the heating loop, using hysteresis or safety controls to actuate the aquarium heater.
| Async Task
| No
|-
| '''<code>ventilation</code>'''
| Controls the surface cooling fan loop, maintaining temperature thresholds.
| Async Task
| No
|-
| '''<code>monitors</code>'''
| Runs regular diagnostic checks and outputs warning/critical logs when states drift outside target thresholds.
| Async Task
| No
|-
| '''<code>refill</code>'''
| Drives the fresh water top-off system, managing level switch states and pump runs with safety timers.
| Async Task
| No
|-
| '''<code>feed</code>'''
| Monitors the feeding schedule and actuates the automatic feeder.
| Async Task
| No
|-
| '''<code>balling</code>'''
| Oversees peristaltic mineral pumps to dose minerals into the aquarium according to schedule.
| Async Task
| No
|-
| '''<code>tank_level_switch</code>'''
| Periodically reads the state of physical water level floats or simulator ports.
| Async Task
| No
|-
| '''<code>watchdog</code>'''
| Performs periodic heartbeats to ensure system safety loops are executing.
| Async Task
| No
|-
| '''<code>ds18b20</code>'''
| Periodically queries 1-Wire DS18B20 digital thermometers for water temperature.
| Async Task
| No
|-
| '''<code>messaging</code>'''
| Stub mock receiver that routes command queues when running on non-Linux platforms (like macOS).
| Async Task
| No
|}

== Tokio Runtime Configuration ==

The Tokio runtime is explicitly built at startup with a constrained configuration:

<syntaxhighlight lang="rust" line>
let rt = tokio::runtime::Builder::new_multi_thread()
.worker_threads(1)
.max_blocking_threads(4)
.enable_all()
.build()
<syntaxhighlight>
<syntaxhighlight lang="rust" line>
let rt = tokio::runtime::Builder::new_multi_thread().worker_threads(1).max_blocking_threads(4).enable_all().build()
<syntaxhighlight>
=== Why this configuration is chosen ===
1. **`worker_threads(1)`**: The application runs on Raspberry Pi. Limiting the event loop scheduler to one worker thread minimizes CPU context-switching overhead and prevents resource exhaustion.
2. **`max_blocking_threads(4)`**: Restricting the blocking thread pool prevents the runtime from spawning too many concurrent threads when database pings, file operations, or synchronous calculations are invoked (such as via `tokio::task::spawn_blocking` or `block_in_place`).

=== Developer Diagnostics with Tokio Console ===

For runtime inspection, task profiling, and detecting deadlocks or starvation, you can run the application with **Tokio Console** integration.

==== Prerequisites & Compilation ====
Tokio Console requires unstable instrumentation.
1. Use the `debug_tokio` feature flag, which initializes the `console-subscriber` in `run.rs`:
```bash
RUSTFLAGS="--cfg tokio_unstable" cargo build --features "debug_tokio"
```
2. The `tokio_unstable` compiler flag ensures that Tokio exposes internal tracing endpoints (like the task builder names).

==== Installing the Terminal Console ====
Install the client CLI on your development machine (macOS/Linux) via Cargo:
```bash
cargo install --locked tokio-console
```

==== Running and Reading ====
1. Launch the compiled application:
2. Open a separate terminal window and run:
```bash
tokio-console
```
This presents a live dashboard of running tasks, showing busy poll times, total lifetime, and idle periods.

=== Interpreting Task Size Warnings ===
When checking with `tokio-console`, you see warnings that tasks like `signal_handler`, `relay_manager`, `data_logger`, or `heating` are **1024 bytes or larger**.
* **These warnings can be safely ignored.**
* The size refers to the stack footprint of the compiler-generated `Future` state machine. In debug builds, these are larger due to lack of optimization.
* Because these tasks are long-lived workers spawned once at startup and run until shutdown, they are allocated on the heap only once. A 1–2 KiB heap footprint has zero impact on application performance, fragmentation, or memory leaks.