---
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)