109 lines
3.4 KiB
Markdown
109 lines
3.4 KiB
Markdown
---
|
|
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 |