firmware-base/docs/Relay.md

title	description	keywords
Relay Component	A digital output component for controlling relays via GPIO pins with Modbus integration	relay, GPIO, digital output, modbus, coil

Relay

Path: src/components/Relay.h

Revision History: Initial documentation

The Relay component provides a simple interface for controlling digital outputs typically connected to relays. It supports toggling the state of a GPIO pin between HIGH and LOW and exposes this functionality through both a programmatic API and Modbus integration.

Requirements

• A GPIO pin capable of digital output
• Properly configured hardware relay circuitry
• Modbus TCP server (if using Modbus control)

Features

• Simple ON/OFF control of a digital output pin
• State change notifications
• Full Modbus integration via coil operations
• Serial bridge command interface
• Thread-safe operation

Dependencies

• Component - Base class for all components
• ArduinoLog - Logging facility
• Modbus - Modbus protocol support
• ModbusTCP - Modbus TCP implementation
• Bridge - Serial command interface

graph TD
    Relay --> Component
    Relay --> ArduinoLog
    Relay --> Modbus
    Relay --> ModbusTCP
    Relay --> Bridge

Behaviour

The Relay component maintains a simple state machine that toggles between ON and OFF states. State changes can be triggered by direct method calls, Modbus commands, or serial bridge commands.

stateDiagram-v2
    [*] --> OFF: Initialize
    OFF --> ON: setValue(true) / Modbus Write Coil(1)
    ON --> OFF: setValue(false) / Modbus Write Coil(0)
    ON --> ON: setValue(true) / No Change
    OFF --> OFF: setValue(false) / No Change

TODOs

Performance

• Consider adding pulse mode functionality for timed relay activation
• Implement debounce or rate limiting for rapidly changing states

Security

• Add authentication for critical relay operations
• Implement secure state persistence across power cycles

Compliance

• Ensure proper handling of inductive loads to prevent electrical hazards
• Add electrical certification compliance documentation if used in industrial applications

Recommendations

• Use external protection circuitry for high-current or inductive loads
• Implement a heartbeat mechanism to ensure relay states are as expected
• Consider adding fault detection for relay feedback

Example

Below is an example of how to initialize and use a Relay component:

#ifdef GPIO_PIN_CH1
  relay_0 = new Relay(
      this,                // owner
      GPIO_PIN_CH1,        // pin
      COMPONENT_KEY_RELAY_0, // id
      MB_RELAY_0_ADDR      // modbusAddress
  );
  if (relay_0)
  {
    components.push_back(relay_0);
    Log.infoln(F("Relay_0 initialized. Pin:%d, ID:%d, MB:%d"),
               GPIO_PIN_CH1, COMPONENT_KEY_RELAY_0, MB_RELAY_0_ADDR);
  }
  else
  {
    Log.errorln(F("Relay_0 initialization failed."));
  }
#endif

References

${DOXYGEN_PLACEHOLDER}

${VENDOR_PLACEHOLDER}