firmware-base/docs-c/components/Relay.md

title	description	keywords
Relay Component Documentation	Documentation for the Relay component which provides control of digital relays with Modbus integration	relay modbus component switch control esp32

Relay

Path: src/Relay.h

Revision History: Initial documentation

The Relay component provides a simple interface for controlling digital relay outputs with Modbus integration. It enables turning physical relays on and off both programmatically and via Modbus commands, making it suitable for industrial control applications with remote management capabilities.

REQUIREMENTS

• A digital output pin for controlling the relay
• ESP-32 microcontroller
• Modbus-485 infrastructure for remote control

FEATURES

• Control of digital relay outputs (ON/OFF)
• Modbus integration for remote control
• State persistence and notification
• Digital output pin management
• Clean API for both direct and Modbus control

DEPENDENCIES

• Component - Base class for all system components
• ArduinoLog - Logging utility
• App - Application framework
• enums.h - System-wide enumeration definitions
• config.h - System configuration
• Modbus - Modbus protocol implementation
• ModbusTCP - Modbus TCP implementation
• config-modbus.h - Modbus configuration

graph TD
    Relay --> Component
    Relay --> ArduinoLog
    Relay --> App
    Relay --> enums
    Relay --> config
    Relay --> Modbus
    Relay --> ModbusTCP
    Relay --> configmodbus[config-modbus.h]

BEHAVIOUR

The Relay component maintains a simple state machine transitioning between ON and OFF states, controllable both via direct commands and Modbus.

stateDiagram-v2
    OFF --> ON: setValue(true) / Modbus Write(1)
    ON --> OFF: setValue(false) / Modbus Write(0)

TODOS

PERFORMANCE

• Consider implementing batch operations for applications requiring multiple relay controls
• Evaluate if digital write operations should be debounced or rate-limited in high-frequency scenarios

SECURITY

• Add optional authorization for relay state changes
• Implement validation logic for Modbus commands based on system state or conditions

COMPLIANCE

• Ensure relay state changes are properly logged for audit in systems requiring operation traceability
• Consider adding timing constraints for safety-critical applications

RECOMMENDATIONS

• For critical applications, implement a watchdog mechanism to set relays to a safe state if communication is lost
• When controlling high-power relays, consider implementing safety checks before switching states

EXAMPLE

This example shows how to instantiate and register a Relay component within the main application:

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

References