Arduino-based relay actuation

Using an additional device, the aquarium control can actuate a set of relays.

One such device is the Controllino from Boot & Work Corp, S.L..

According to their website, the Controllino is an industry-grade PLC based on open source software. It is not affiliated to Arduino and is a derivative product. Tech support for Controllino needs to be directed to the above mentioned manufacturer.

Note: This project is NOT affiliated with neither Controllino nor Arduino.

The SW provided as part of this project enables the device to act as fail-safe relay actuator. It operates as a "slave" device, receiving commands from a central controller (likely a Raspberry Pi via USB/Serial) and managing high-voltage physical devices like pumps, lights, and feeders.

1. Communication Protocol

The device communicates via a serial USB connection using a custom, fixed-length message protocol.

Message Structure: Every command consists of a fixed packet size (8 bytes).

Data Integrity: The firmware implements a checksum validation process. It calculates a logical "signature" for incoming data to ensure the message wasn't corrupted during transmission. If a message is corrupt, the device rejects it and returns an error code; otherwise, it executes the command.

Feedback: The device sends confirmation messages back to the controller, including current status data or error flags if a command is unrecognized.

2. Core Control Capabilities

The firmware allows the external controller to manipulate the hardware in several ways:

Relay Switching: Direct commands to turn specific relays ON (Set) or OFF (Unset).

Digital I/O Control: Similar control for digital input/output pins.

Pulse Actuation: A specialized command to turn a relay ON for a specific, precise duration (defined in the message) and then automatically turn it OFF. This is useful for dosing pumps or precise feeding.

Status Reporting: The device can query the internal state of all 16 relays and return a bitmap indicating exactly which devices are currently running.

3. Safety Mechanisms

A major focus of this code is strictly enforcing safety to prevent hardware failure or aquarium disasters (like overflowing or overfeeding).

A. "Dead Man's Switch" (Silence Watchdog)

The firmware monitors the connection with the master controller.

Heartbeat Monitoring: It expects regular valid messages (heartbeats or commands).

Fail-safe Trigger: If the device detects "silence" (no valid messages received) for a specific threshold (set to 3 minutes), it assumes the master controller has crashed or disconnected.

Safe State: Upon triggering, the device immediately resets all relays to a default "OFF" state to prevent equipment from running indefinitely without supervision.

B. Run-Time Limiters (Runaway Prevention)

To prevent specific critical equipment from getting stuck in the "ON" state, the code tracks how long relays have been active.

Targeted Monitoring: Two specific relays (designated for the Refill Pump and the Feeder) are monitored.

Automatic Cut-off: If either of these devices remains ON for longer than a hard-coded safety limit (1 minute), the firmware overrides the command and forces them OFF. This prevents a stuck command from emptying a reservoir or dumping too much food.

C. Soft-Start Initialization

When the device powers up or resets:

It ensures all relays start in the OFF state.

It initializes the pins sequentially with a slight delay between each. This prevents a sudden power surge (inrush current) that might occur if all electrical devices were turned on simultaneously.