112 lines
3.1 KiB
Markdown
112 lines
3.1 KiB
Markdown
---
|
|
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}
|