Struct TankLevelSwitch

pub struct TankLevelSwitch {

    config: TankLevelSwitchConfig,
    tank_level_switch_position: bool,
    tank_level_switch_position_stabilized: bool,
    tank_level_switch_invalid: bool,
    tank_level_switch_position_low_stabilization_counter: u32,
    pub lock_warn_inapplicable_command_signal_handler: bool,
    pub lock_error_channel_receive_termination: bool,
    pub lock_warn_max_mutex_access_duration: bool,
    lock_error_mutex_poisoned: bool,
    lock_error_input_pin_none: bool,
    lock_error_simulator_communication: bool,
    lock_error_channel_not_provided: bool,
    pub max_mutex_access_duration: Duration,
}

Contains the measurement of tank level position and calculation of stabilized tank level position signal. Tank level position is measured by accessing the state of a dedicated GPIO pin. Alternatively, TCP communication is used when configured to run with the simulator. The struct holds attributes for the results and for error flags indicating unsuccessful communication. Thread communication of this component is as follows:

graph LR signal_handler[SignalHandler] --> tank_level_switch tank_level_switch --> signal_handler tank_level_switch --> tcp_communication[TcpCommunication] tcp_communication --> tank_level_switch

Communication with the simulator (TcpCommunication) and signal handler uses channels. Refill control, Heating control and the data logger read from a mutex to which TankLevelSwitch writes to.

Fields

config: TankLevelSwitchConfig

configuration of tank level switch calculation

tank_level_switch_position: bool

flag indicating if the last measurement of tank level switch indicates high (true) or low (false)

tank_level_switch_position_stabilized: bool

flag indicating if the stabilized tank level switch indicates high (true) or low (false)

tank_level_switch_invalid: bool

flag indicating that the tank level switch position may be inaccurate

tank_level_switch_position_low_stabilization_counter: u32

time counter to determine if the position is stabilized

lock_warn_inapplicable_command_signal_handler: bool

inhibition flag to avoid flooding the log file with repeated messages about having received inapplicable command from the signal handler

lock_error_channel_receive_termination: bool

inhibition flag to avoid flooding the log file with repeated messages about failure to receive termination signal via the channel

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_mutex_poisoned: bool

inhibition flag to avoid flooding the log file with repeated messages about mutex not being accessible.

lock_error_input_pin_none: bool

inhibition flag to avoid flooding the log file with repeated messages about not having received an input pin

lock_error_simulator_communication: bool

inhibition flag to avoid flooding the log file with repeated messages about simulator communication error

lock_error_channel_not_provided: bool

inhibition flag to avoid flooding the log file with repeated messages about channel(s) not being provided

max_mutex_access_duration: Duration

Maximum permissible access duration for Mutex

Implementations

impl TankLevelSwitch

pub fn new( config: TankLevelSwitchConfig, initial_position_stabilized: bool, ) -> Result<TankLevelSwitch, TankLevelSwitchError>

Creates a new TankLevelSwitch instance for development or unsupported platforms.

This constructor is activated when the application is compiled for a non-Linux operating system or when the target_hw feature is not enabled. In this mode, it acts as a mock or placeholder, allowing basic testing and compilation without requiring actual GPIO hardware. It initializes the sensor position to true (high water) and the invalid flag to false by default, but sets the stabilized position based on the provided initial_position_stabilized argument.

Arguments

• config - Configuration data for the tank level switch, primarily dictating the use_simulator flag and stabilization logic.
• initial_position_stabilized - The assumed initially stabilized position of the tank level (true for high water, false for low) before any actual measurements.

Returns

A new TankLevelSwitch struct, configured for simulated or non-hardware operation, wrapped in Ok().

Errors

This specific implementation for non-hardware platforms does not produce any errors and always returns Ok. The Result type is used to maintain signature compatibility with the hardware-specific version of this function.

pub fn update_tank_level_switch_signals( &mut self, tx_tank_level_switch_to_tcp_opt: &mut Option<AquaSender<InternalCommand>>, rx_tank_level_switch_from_tcp_opt: &mut Option<AquaReceiver<Result<f32, TcpCommunicationError>>>, ) -> Result<(), TankLevelSwitchError>

Updates the measured tank level switch signals from either a GPIO pin or a simulator.

This function determines the source of the tank level switch position and invalid status based on the use_simulator configuration.

Arguments

• tx_tank_level_switch_to_tcp_opt - An Option containing the sender channel to the TCP simulator.
• rx_tank_level_switch_from_tcp_opt - An Option containing the receiver channel from the TCP simulator.

Returns

An empty Result (Ok(())) on success.

Errors

Returns a TankLevelSwitchError if:

• TankLevelSwitchError::SimulatorChannelNotProvided: If in simulator mode, and the required channels are missing.
• TankLevelSwitchError::SimulatorCommunicationError: If communication with the simulator fails for either signal.
• TankLevelSwitchError::InputPinNotProvided: If in hardware mode but the GPIO input pin is not available.

fn calc_tank_level_switch_position_stabilized(&mut self)

Calculates a stabilized tank level position, applying asymmetric delay and handling invalid inputs.

This private helper updates the tank_level_switch_position_stabilized flag. It implements the following logic:

• Invalid Signal: If tank_level_switch_invalid is true, the stabilized position is immediately forced to true (a safe, high-water state).
• High Water Level: If the raw position is true, the stabilized signal is set to true immediately, and the low-level stabilization counter is reset.
• Low Water Level (with Delay): If the raw position is false, a counter increments. The stabilized signal only changes to false after this counter exceeds the configured threshold, preventing flickering from momentary low readings.

pub fn execute( &mut self, tank_level_switch_channels: &mut TankLevelSwitchChannels, mutex_tank_level_switch_signals: Arc<Mutex<TankLevelSwitchSignals>>, ) -> Result<(), TankLevelSwitchError>

Executes the main control loop for the tank level switch module.

This function runs continuously, managing the measurement, stabilization, and provision of the tank water level. It periodically updates its state by reading from a physical GPIO pin or a simulator and writes the result to a shared mutex for access by other threads.

The loop maintains a fixed cycle time and responds to Quit commands from the signal handler for graceful shutdown.

Arguments

• tank_level_switch_signals - A mutable reference to the struct containing the channels.
• mutex_tank_level_switch_signals - The shared Mutex where the latest sensor signals are written for other modules to consume.

Returns

An empty Result (Ok(())) on successful shutdown.

Errors

Returns a TankLevelSwitchError::SimulatorChannelNotProvided if the module is configured to use the simulator, but the required TCP communication channels are not provided at startup.

Trait Implementations

impl CheckMutexAccessDurationTrait for TankLevelSwitch

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 GetResponseFromSimulatorTrait for TankLevelSwitch

fn get_response_from_simulator( requester: String, tx_to_tcp: &mut AquaSender<InternalCommand>, rx_from_tcp: &mut AquaReceiver<Result<f32, TcpCommunicationError>>, internal_command: InternalCommand, ) -> Result<f32, TcpCommunicationError>

Sends a request to a simulator via a channel and blocks until a response is received.

impl ProcessExternalRequestTrait for TankLevelSwitch

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 TankLevelSwitch

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