Struct ActuateControllino

pub struct ActuateControllino {
    config: ActuateControllinoConfig,
    pub spin_sleeper: SpinSleeper,
    pub controllino_processing_duration: Duration,
    pub serial_port_opt: Option<Box<dyn SerialPort>>,
}

Contains relay configuration and trait implementation for actuation using Controllino hardware

Fields

config: ActuateControllinoConfig

Configuration for setup of Controllino device

spin_sleeper: SpinSleeper

Object is used frequently to wait for a determined period of time, so storing it instead of recreating when needed. Attribute is public because access from within test cases.

controllino_processing_duration: Duration

Object is used frequently to wait for a determined period of time, so storing it instead of recreating when needed. Attribute is public because access from within test cases.

serial_port_opt: Option<Box<dyn SerialPort>>

Interface to serial port for communication via USB Attribute is public because access from within test cases.

Implementations

impl ActuateControllino

pub fn check_valid_relay_id_config( config: &ActuateControllinoConfig, ) -> Result<(), ActuateControllinoError>

Validates the provided relay ID configuration for the Controllino.

This function performs two critical checks:

1. Ensures that all configured relay IDs fall within the permissible range defined by CONTROLLINO_MIN_RELAY_ID and CONTROLLINO_MAX_RELAY_ID.
2. It confirms that all assigned relay IDs are unique, preventing conflicts where multiple devices might be configured to the same physical relay.

Arguments

• config - A reference to the ActuateControllinoConfig containing the relay ID mappings for various aquarium devices.

Returns

An empty Result (Ok(())) if the configuration is valid.

Errors

Returns an ActuateControllinoError if an invalid configuration is found:

• RelayIdOutsideRange: If a relay ID is less than the minimum or greater than the maximum allowed value.
• RelayIdDuplicate: If the same relay ID is assigned to more than one device.

pub fn new( config: ActuateControllinoConfig, ) -> Result<ActuateControllino, ActuateControllinoError>

Creates a new ActuateControllino instance, establishing communication with the Controllino hardware.

This constructor performs essential setup for hardware actuation. It validates the provided relay ID configuration for correctness and uniqueness, ensures a serial port name is provided, and then opens and initializes the serial port connection to the Controllino device if active is true.

Arguments

• config - Configuration data for the Controllino relays, which is moved into the new instance.

Returns

A Result containing a new ActuateControllino struct, ready for sending commands to the hardware.

Errors

Returns an ActuateControllinoError if any part of the setup fails:

• If check_valid_relay_id_config finds an error in the relay IDs.
• EmptyPortName: If the port_name in the configuration is an empty string.
• If controllino_open_serial_port fails to open and configure the serial port.

Trait Implementations

impl RelayActuationTrait for ActuateControllino

fn actuate( &mut self, internal_command: &InternalCommand, ) -> Result<(), RelayError>

Actuates a specific relay on the Controllino hardware via serial port communication.

This function translates high-level InternalCommands (SwitchOn, SwitchOff, Pulse) into low-level serial messages for the Controllino. It sends the command, waits for the Controllino to process it (including any pulse durations), and then reads and validates the response, including checksum verification.

Arguments

• internal_command - The InternalCommand specifying the device and desired action (e.g., SwitchOn(Heater), Pulse(PeristalticPump1, 500)).

Returns

An empty Result (Ok(())) if the command was sent successfully and a valid acknowledgment was received from the Controllino.

Errors

This function will return a RelayError if any step in the communication process fails:

• FailureCommandMessageCreation: If there’s an issue preparing the Controllino message.
• WriteError: If the command cannot be written to the serial port.
• ReadError: If a response cannot be read from the serial port within the timeout.
• IncorrectChecksum: If the received response has an invalid checksum, indicating data corruption.
• SerialPortNotConfigured: If the serial port was not initialized (e.g., active is false in config).
• IrrelevantCommand: If an inapplicable command (e.g., ResetAllErrors) is provided.

fn get_heartbeat_interval_seconds(&self) -> Option<u64>

Gets the configured heartbeat interval in seconds.

This function returns the interval at which the heartbeat method should be called to keep the hardware connection alive.

Returns

An Option<u64> containing the heartbeat interval in seconds. It returns Some for this implementation as the interval is always configured.

fn heartbeat(&mut self) -> Result<(), RelayError>

Sends a heartbeat signal to the Controllino to indicate the software is active.

Returns

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

Errors

This function will return a RelayError if:

• The serial port is not configured (SerialPortNotConfigured).
• Sending the heartbeat message over the serial port fails (SendToSerialPortFailed).

fn flush_buffer(&mut self) -> Result<(), RelayError>

Flushes the serial communication buffer to recover from framing or synchronization errors.

The root cause is usually a desynchronization between the sender (Controllino) and receiver (Raspberry Pi). This can happen due to:

• Noise on the line: A stray bit flip could make the Pi misinterpret the start of a message.
• Timing issues: The Pi’s read might start too early or too late relative to when the Controllino actually begins sending data.
• Buffer state: Leftover bytes from a previous, incomplete, or corrupted transmission can throw off further reads.

Returns

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

Errors

This function will return a RelayError if:

• The serial port is not configured (SerialPortNotConfigured).
• Clearing the serial port buffer fails (SerialPortFlushFailed).