149 lines
4.9 KiB
Markdown
149 lines
4.9 KiB
Markdown
---
|
|
title: ModbusLogicEngine Component
|
|
description: A programmable logic rule engine that operates on Modbus registers to execute conditional commands
|
|
keywords: modbus, automation, rules engine, logic, conditional execution, industrial automation
|
|
---
|
|
|
|
# ModbusLogicEngine
|
|
|
|
**Path**: [`src/components/ModbusLogicEngine.h`](../src/components/ModbusLogicEngine.h)
|
|
|
|
**Revision History**: Initial documentation
|
|
|
|
The ModbusLogicEngine component provides a programmable logic rule engine that executes conditional actions based on Modbus register values. It functions similar to a basic PLC (Programmable Logic Controller), allowing the system to be configured with a set of if-then rules via Modbus registers without requiring firmware modifications.
|
|
|
|
## REQUIREMENTS
|
|
|
|
### Hardware
|
|
- No specific hardware pins required
|
|
- Operates entirely on Modbus data
|
|
|
|
### Software
|
|
- Requires `ENABLE_MB_SCRIPT` to be defined in the configuration
|
|
- Access to Modbus register data (holding registers, coils, etc.)
|
|
- PHApp instance to interact with other components
|
|
|
|
## FEATURES
|
|
|
|
- Supports up to 8 configurable logic rules (adjustable via `MAX_LOGIC_RULES`)
|
|
- Each rule includes:
|
|
- A condition based on Modbus register or coil values
|
|
- An action to execute when the condition is met
|
|
- Status tracking (trigger count, last execution time, etc.)
|
|
- Condition types: equal, not equal, less than, less or equal, greater than, greater or equal
|
|
- Action types:
|
|
- Write to a Modbus holding register
|
|
- Write to a Modbus coil
|
|
- Call a registered component method
|
|
- Rule debugging capabilities via flags
|
|
- Rules are fully configurable via Modbus registers
|
|
|
|
## DEPENDENCIES
|
|
|
|
- [Component](../src/Component.h)
|
|
- [ArduinoLog](https://github.com/thijse/Arduino-Log)
|
|
- [config.h](../src/config.h)
|
|
- [ModbusTypes.h](../src/modbus/ModbusTypes.h)
|
|
|
|
```mermaid
|
|
graph TD
|
|
ModbusLogicEngine --> Component
|
|
ModbusLogicEngine --> PHApp
|
|
ModbusLogicEngine --> ArduinoLog
|
|
ModbusLogicEngine --> ModbusTypes
|
|
```
|
|
|
|
## BEHAVIOUR
|
|
|
|
The ModbusLogicEngine evaluates rules at regular intervals (default 100ms). For each enabled rule:
|
|
|
|
```mermaid
|
|
graph TD
|
|
A[Check if rule enabled] -->|Yes| B[Read condition source value]
|
|
B --> C[Evaluate condition]
|
|
C -->|Condition true| D[Execute action]
|
|
D --> E[Update status registers]
|
|
C -->|Condition false| E
|
|
A -->|No| F[Skip rule]
|
|
F --> E
|
|
```
|
|
|
|
Each rule occupies a block of 13 consecutive Modbus registers with the following structure:
|
|
|
|
1. Enabled (0/1)
|
|
2. Condition Source Type (register type)
|
|
3. Condition Source Address (Modbus address)
|
|
4. Condition Operator (0=Equal, 1=Not Equal, 2=Less Than, etc.)
|
|
5. Condition Value (to compare against)
|
|
6. Command Type (2=Write Coil, 3=Write Register, 100=Call Method)
|
|
7. Command Target (address or component ID)
|
|
8. Command Parameter 1 (value or method ID)
|
|
9. Command Parameter 2 (additional argument)
|
|
10. Flags (debug settings)
|
|
11. Last Status (execution result code)
|
|
12. Last Trigger Timestamp
|
|
13. Trigger Count
|
|
|
|
## TODOS
|
|
|
|
### PERFORMANCE
|
|
|
|
- Consider optimizing the rule evaluation frequency based on application needs
|
|
- Implement priority levels for rules to ensure critical rules execute first
|
|
- Add rate limiting options for high-frequency triggers
|
|
|
|
### SECURITY
|
|
|
|
- Implement range checking on Modbus addresses to prevent unauthorized memory access
|
|
- Add authorization mechanism for registering and modifying component methods
|
|
- Consider adding CRC or checksum validation for rule configurations
|
|
|
|
### COMPLIANCE
|
|
|
|
- Document compatibility with IEC 61131-3 (PLC programming standard) concepts
|
|
- Add options for meeting real-time response requirements for industrial control systems
|
|
|
|
### RECOMMENDATIONS
|
|
|
|
- Use debug flags during initial rule setup and disable for production
|
|
- Organize rule addresses logically to group related functionality
|
|
- Implement a backup/restore mechanism for rule configurations
|
|
- Consider adding a web interface for easier rule configuration
|
|
|
|
## EXAMPLE
|
|
|
|
This section would typically show how the component is constructed and mounted, but the CPP file couldn't be located. However, based on the header file, a typical initialization would look like:
|
|
|
|
```cpp
|
|
#ifdef ENABLE_MB_SCRIPT
|
|
// Create the ModbusLogicEngine component
|
|
modbusLogicEngine = new ModbusLogicEngine(this); // 'this' is PHApp instance
|
|
|
|
if (modbusLogicEngine)
|
|
{
|
|
components.push_back(modbusLogicEngine);
|
|
|
|
// Register methods that can be called by logic rules
|
|
modbusLogicEngine->registerMethod(
|
|
COMPONENT_KEY_RELAY_0, // component ID
|
|
1, // method ID for toggle
|
|
[this](short arg1, short arg2) -> short {
|
|
// Method implementation
|
|
return 0; // Success
|
|
}
|
|
);
|
|
|
|
Log.infoln(F("ModbusLogicEngine initialized"));
|
|
}
|
|
else
|
|
{
|
|
Log.errorln(F("ModbusLogicEngine initialization failed"));
|
|
}
|
|
#endif
|
|
```
|
|
|
|
### References
|
|
|
|
- [Modbus Specification](https://modbus.org/specs.php)
|
|
- [PLC Programming Concepts](https://en.wikipedia.org/wiki/Programmable_logic_controller)
|