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

# Relay

**Path**: [`src/components/Relay.h`](../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](./Component.md) - Base class for all components
- [ArduinoLog](https://github.com/thijse/Arduino-Log) - Logging facility
- [Modbus](./Modbus.md) - Modbus protocol support
- [ModbusTCP](./ModbusTCP.md) - Modbus TCP implementation
- [Bridge](./Bridge.md) - Serial command interface

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

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

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