Struct Heating

pub struct Heating {
    config: HeatingConfig,
    lock_error_channel_receive_schedule_check: bool,
    lock_error_channel_send_schedule_check: bool,
    pub last_ping_instant: Instant,
    pub database_ping_interval: Duration,
    pub lock_warn_max_mutex_access_duration: bool,
    lock_error_heating_set_value_read_failure: bool,
    pub lock_warn_inapplicable_command_signal_handler: bool,
    pub lock_error_channel_receive_termination: bool,
    pub max_mutex_access_duration: Duration,
}

Contains the configuration and the implementation for the heating control. Thread communication is as follows:

graph LR ambient[Ambient] -.-> heating tank_level_switch[Tank Level Switch] -.-> heating heating --> relay_manager[Relay Manager] relay_manager --> heating heating --> signal_handler[Signal Handler] signal_handler --> heating heating --> data_logger[Data Logger] data_logger --> heating heating --> schedule_check[Schedule Check] schedule_check --> heating messaging[Messaging] --> heating

Fields

config: HeatingConfig

configuration data for heating control

lock_error_channel_receive_schedule_check: bool

inhibition flag to avoid flooding the log file with repeated messages about failure to receive information from schedule check

lock_error_channel_send_schedule_check: bool

inhibition flag to avoid flooding the log file with repeated messages about failure to send information to schedule check

last_ping_instant: Instant

recording when the last database ping happened

database_ping_interval: Duration

database ping interval

lock_warn_max_mutex_access_duration: bool

inhibition flag to avoid flooding the log file with repeated messages about excessive access time to mutex

lock_error_heating_set_value_read_failure: bool

Flag to avoid flooding the log with warnings when the heating set values could not be read from the database

lock_warn_inapplicable_command_signal_handler: bool

Inhibition flag to avoid flooding the log with warning about having received inapplicable command from the signal handler

lock_error_channel_receive_termination: bool

Inhibition flag to avoid flooding the log with errors about the channel communication not working

max_mutex_access_duration: Duration

Maximum permissible access duration for Mutex

Implementations

impl Heating

pub fn new(config: HeatingConfig, database_ping_interval: Duration) -> Heating

Creates a new Heating control instance.

This constructor initializes the heating control module with its specific configuration and a dedicated SQL interface. It also sets up all internal “lock” flags to false by default; these flags are crucial during operation to prevent log files from being flooded with repeated error or warning messages stemming from channel communication or invalid requests.

Arguments

• config - Configuration data for the heating control, loaded from a TOML file. This includes parameters such as target temperatures, safety features, and behavioral strategies.
• sql_interface_heating - The specific SQL interface for heating-related database operations. This instance is moved into the Heating struct.
• database_ping_interval - A Duration instance, providing the interval to ping the database.

Returns

A new Heating struct, ready to manage the aquarium’s heating system.

fn calc_normalized_control_deviation(&self, measured_value: f32) -> f32

Calculates a normalized control deviation based on the measured temperature and configured heating thresholds.

This private helper function determines how far the measured_value deviates from the switch_on_temperature relative to the total temperature control range (switch_on_temperature to switch_off_temperature). The result is a float between 0.0 and 1.0. A value of 0.0 means the temperature is at or below switch_on_temperature (full heating needed), and 1.0 means it’s at or above switch_off_temperature (no heating needed).

Arguments

• measured_value - The current measured temperature (f32).

Returns

An f32 representing the normalized control deviation, ranging from 0.0 to 1.0. Returns 0.0 if switch_off_temperature is not greater than switch_on_temperature (i.e., target_value_delta is not positive), indicating an invalid configuration.

fn get_duration_until_midnight( &mut self, sql_interface_heating: &mut SqlInterfaceHeatingStats, ) -> i64

Retrieves the duration in seconds until the next midnight from the database.

This private helper function acts as a robust wrapper around the SQL interface’s get_duration_until_midnight method.

Returns

An i64 representing the number of seconds remaining until the next midnight.

Errors

This function handles errors internally. If the database call fails, it logs the error and returns a default fallback value of 24 hours (86.400 seconds). This prevents a crash and suspends statistics recording until the next day.

pub fn execute( &mut self, mutex_device_scheduler_heating: Arc<Mutex<i32>>, heating_channels: &mut HeatingChannels, heating_stats_transfer: &mut impl HeatingStatsDataTransferTrait, heating_set_val_updater: &mut impl ThermalSetValueUpdaterTrait, heating_mutexes: HeatingMutexes, sql_interface_heating: SqlInterfaceHeatingStats, )

Executes the main control loop for the heating module.

This function runs continuously, managing the aquarium’s heating system until a termination signal is received. It adjusts heater operation based on water temperature and tank level switch signals adhering to the limitations imposed by a schedule. The ambient temperature signal is considered for logging daily statistical data. It also processes external Start/Stop commands, applies a sawtooth profile for proportional control, and logs daily heating statistics.

Key Operations:

• Sensor Data Acquisition: Reads current water temperature, ambient temperature, and tank level switch states from shared mutexes.
• Safety Interlocks: Implements a critical safety feature to turn off the heater if the water level is too low for a configured duration, preventing damage.
• Schedule & External Control: Checks with the ScheduleCheck module and responds to Start/Stop commands to inhibit or enable heating.
• Proportional Control: When within the active temperature range, uses a SawToothProfile to achieve a “PWM-like” heating effect.
• Energy Logging: Periodically updates and transfers daily heating statistics (energy consumption, average temperatures) to the SQL database.
• Cycle Management: Maintains a fixed cycle time, sleeping as necessary, and warning if execution duration exceeds the cycle limit.
• Graceful Shutdown: Responds to Quit and Terminate commands from the signal handler, ensuring a safe shutdown of the heater and final data logging.

Arguments

• mutex_device_scheduler_heating - A clone of the Arc<Mutex<i32>> used to coordinate device actuation across the application, preventing conflicts and tracking activity counts.
• heating_channels - A struct containing all sender and receiver channels for communication with modules like RelayManager, SignalHandler, DataLogger, ScheduleCheck, and Messaging.
• heating_stats_transfer - A mutable reference to an object implementing HeatingStatsDataTransferTrait, responsible for persisting daily heating statistics to the database.
• heating_stats_transfer - A mutable reference to an object implementing HeatingSetValueUpdaterTrait, responsible for updating the set values dynamically by communicating with SQL database.
• heating_mutexes - Struct containing the mutexes to access data from different threads.

Returns

This function does not return a value in the traditional sense, as it is designed to loop indefinitely. It will only break out of its loop and terminate when a Quit command is received from the signal handler, after which it performs final cleanup (switching off the heater, logging final stats) and confirms shutdown.

Trait Implementations

impl CheckMutexAccessDurationTrait for Heating

fn get_warn_lock(&self, _key_opt: &Option<&AquariumSignal>) -> bool

Method connects the default trait implementation with the specific implementation reading the warn-lock.

fn set_warn_lock(&mut self, _key_opt: &Option<&AquariumSignal>, value: bool)

Method connects the default trait implementation with the specific implementation setting the warn-lock.

fn get_max_mutex_access_duration(&self) -> Duration

Method connects the default trait implementation with the specific implementation for getting maximum permissible access duration

fn get_location(&self) -> &str

inform the location of the warning for logging purposes

fn check_mutex_access_duration( &mut self, key_opt: Option<&AquariumSignal>, instant_after_locking_mutex: Instant, instant_before_locking_mutex: Instant, )

impl DatabasePingTrait for Heating

fn get_ping_interval(&self) -> Duration

Gets the interval at which the resource should be pinged.

fn get_last_ping_instant(&self) -> Instant

Gets the timestamp of the last successful ping.

fn update_last_ping_instant(&mut self)

Updates the timestamp of the last successful ping.

fn check_timing_and_ping_database( &mut self, database_interface: &mut (impl Pingable + ?Sized), )

Pings the database.

impl ProcessExternalRequestTrait for Heating

fn process_external_request( &mut self, rx_from_signal_handler: &mut AquaReceiver<InternalCommand>, rx_from_messaging_opt: Option<&mut AquaReceiver<InternalCommand>>, ) -> (bool, bool, bool)

Checks for and processes new commands received from the signal handler and an optional messaging channel.

impl WaitForTerminationTrait for Heating

fn get_warn_lock_mut(&mut self) -> &mut bool

Method connects the default trait implementation with the specific implementation accessing the warn-lock.

fn get_error_lock_mut(&mut self) -> &mut bool

Method connects the default trait implementation with the specific implementation for accessing the error-lock.

fn wait_for_termination( &mut self, rx_waiting_thread_from_signal_handler: &mut AquaReceiver<InternalCommand>, sleep_duration: Duration, origin: &str, )

Implements the graceful shutdown wait loop for several threads (default implementation).