Struct Ds18b20

pub struct Ds18b20 {
    config: Ds18b20Config,
    pub lock_warn_max_mutex_access_duration: bool,
    pub max_mutex_access_duration: Duration,
}

Represents a Ds18b20 sensor module responsible for reading temperature signals.

This struct encapsulates the configuration, interface details, and internal state required to communicate with the sensor. It handles communication with the operating system. Retries, and perform post-processing (checksum validation, signal calculation) before providing the final temperature and humidity values.

Thread Communication: This module is designed to run in its own dedicated thread, periodically reading sensor data and making the latest measurements available via a shared Arc<Mutex<Ds18b20Result>>. Other modules (like SensorManager or DataLogger) can then read from this mutex to get the current temperature and humidity. It also responds to Quit commands for graceful shutdown.

Platform-Specific Behavior: The sensor reading logic (read function) will only work on Linux systems but compile for any other system as well.

Thread communication of this component is as follows:

graph LR
    ds18b20[Ds18b20] -.-> sensor_manager[SensorManager]
    ds18b20[Ds18b20] -.-> data_logger[DataLogger]
    signal_handler[SignalHandler] --> ds18b20

Fields

config: Ds18b20Config

configuration for communication with Ds18b20 sensor

lock_warn_max_mutex_access_duration: bool

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

max_mutex_access_duration: Duration

maximum allowed duration of access to mutex

Implementations

impl Ds18b20

pub fn new(config: Ds18b20Config) -> Result<Ds18b20, Ds18b20Error>

Creates a new Ds18b20 instance, validating the provided configuration.

This constructor initializes the DS18B20 sensor module, preparing it to read temperatures from 1-Wire devices via the Linux sysfs interface. It performs several critical checks on the configuration to ensure that the module can operate correctly.

Arguments

• config - Configuration data for the DS18B20 sensor, including driver paths, sensor IDs, and retry settings.

Returns

A Result containing a new Ds18b20 struct on success.

Errors

Returns a Ds18b20Error variant if the configuration is invalid, preventing the module from being created. This allows the application to handle setup failures gracefully. Specific errors include:

• Ds18b20Error::SystemDriverBasePathEmpty: If the base path for the 1-Wire driver in the configuration is empty.
• Ds18b20Error::SystemDriverSensorPathEmpty: If the sensor path prefix is not specified.
• Ds18b20Error::SystemDriverFileNameEmpty: If the filename for the sensor data (e.g., w1_slave) is not provided.
• Ds18b20Error::NoSensorIdProvided: If the module is configured to be active but both the water and ambient temperature sensor IDs are empty.
• Ds18b20Error::SensorIdsIdentical: If the module is active and the same ID is assigned to both the water and ambient temperature sensors.

pub fn read(&self, sensor_id: &str) -> Result<Ds18b20ResultData, Ds18b20Error>

Reads temperature from a DS18B20 1-Wire sensor via the Linux sysfs interface.

This function attempts to read temperature data from a specific DS18B20 sensor, identified by its sensor_id. It constructs the file path based on the configured system driver paths. The function includes a retry mechanism for robust reading, as 1-Wire communication can sometimes be flaky.

Arguments

• sensor_id - A string slice containing the unique 64-bit ID of the DS18B20 sensor to read (e.g., “28-00000abcde12”).

Returns

A Ds18b20Result containing Ds18b20ResultData on success, which includes the temperature in degrees Celsius.

Errors

Returns a Ds18b20Error variant if the reading fails, even after retries. Specific errors include:

• Ds18b20Error::SensorIdNotFound: If the directory for the given sensor_id does not exist.
• Ds18b20Error::ReadToStringFailure: If the underlying file read from the sysfs fails.
• Ds18b20Error::InsufficientLinesInFile: If the sensor file does not contain at least two lines.
• Ds18b20Error::Line0NotEndingWithYes: If the first line of the sensor file does not end with “YES”, indicating a CRC error or invalid reading.
• Ds18b20Error::TemperatureEntryNotFound: If the second line does not contain the “t=” marker.
• Ds18b20Error::TemperatureParseError: If the temperature value after “t=” cannot be parsed into a number.
• Ds18b20Error::TemperatureOutOfRange: If the parsed temperature is outside the plausible range defined by MIN_TEMPERATURE and MAX_TEMPERATURE.

fn parse_contents(&self, contents: &str) -> Result<f32, Ds18b20Error>

Parses the string contents of a DS18B20 sysfs file. This private helper contains the core parsing logic.

pub fn execute( &mut self, ds18b20_channels: &mut Ds18b20Channels, mutex_water_temperature: Arc<Mutex<Result<Ds18b20ResultData, Ds18b20Error>>>, mutex_ambient_temperature: Arc<Mutex<Result<Ds18b20ResultData, Ds18b20Error>>>, )

Executes the main control loop for the DS18B20 sensor module.

This function runs continuously, managing the periodic measurement of water and ambient temperatures from DS18B20 sensors via the Linux sysfs 1-Wire interface. It updates shared mutexes with the latest sensor readings, making them available to other application threads. The loop remains responsive to Quit commands from the signal handler for graceful shutdown.

Arguments

• rx_from_signal_handler - The receiver channel for commands (e.g., Quit) from the main signal handler.
• mutex_water_temperature - An Arc<Mutex<Ds18b20Result>> into which the latest water temperature reading will be written, ensuring thread-safe access for other modules.
• mutex_ambient_temperature - An Arc<Mutex<Ds18b20Result>> into which the latest ambient temperature reading will be written, ensuring thread-safe access for other modules.

Trait Implementations

impl CheckMutexAccessDurationTrait for Ds18b20

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: &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 ProcessExternalRequestTrait for Ds18b20

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.