---
title: "Relay Component Documentation"
description: "Documentation for the Relay component which provides control of digital relays with Modbus integration"
keywords: [relay, modbus, component, switch, control, esp32]
---

## Relay

**Path**: [`src/Relay.h`](../../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`](../../src/Component.h) - Base class for all system components
- [`ArduinoLog`](https://github.com/thijse/Arduino-Log) - Logging utility
- [`App`](../../src/App.h) - Application framework
- [`enums.h`](../../src/enums.h) - System-wide enumeration definitions
- [`config.h`](../../src/config.h) - System configuration 
- [`Modbus`](../../src/modbus/Modbus.h) - Modbus protocol implementation
- [`ModbusTCP`](../../src/modbus/ModbusTCP.h) - Modbus TCP implementation
- [`config-modbus.h`](../../src/config-modbus.h) - Modbus configuration

```mermaid
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.

```mermaid
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:

```cpp
#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