firmware-base/docs-c/components/ModbusLogicEngine.md

title	description	keywords
Modbus Logic Engine	A scriptable rule engine for industrial ESP-32 applications using Modbus	ESP-32 Modbus Logic Engine Rule Engine Automation

Modbus Logic Engine

Path: src/ModbusLogicEngine.cpp

Revision History: Initial documentation

The Modbus Logic Engine is a programmable rule engine that allows defining conditional logic rules through Modbus registers. It evaluates conditions on register values and executes actions when conditions are met, providing automation capabilities without requiring firmware modifications.

REQUIREMENTS

• ESP-32 microcontroller
• Platform.io development environment
• Modbus TCP/RTU implementation
• Feature flag ENABLE_MB_SCRIPT must be defined in configuration

FEATURES

• Rules-based automation through Modbus registers
• Configurable conditions with multiple comparison operators
• Multiple action types including:
  • Writing to Modbus registers
  • Setting coils
  • Calling component methods
• Debug flags for troubleshooting
• Rule status monitoring and counters
• Configurable evaluation interval

DEPENDENCIES

• Component.h - Base component class
• ArduinoLog.h - Logging functionality
• ModbusTypes.h - Modbus type definitions
• PHApp.h - Application context

graph TD
    ModbusLogicEngine --> Component
    ModbusLogicEngine --> ModbusTypes
    ModbusLogicEngine --> PHApp
    ModbusLogicEngine --> ArduinoLog

BEHAVIOUR

The Modbus Logic Engine continuously evaluates rules at a configurable interval, checking conditions against Modbus register values and executing actions when conditions are met.

stateDiagram-v2
    [*] --> Initialization
    Initialization --> Idle
    Idle --> EvaluateRules: Interval elapsed
    EvaluateRules --> CheckCondition
    CheckCondition --> PerformAction: Condition met
    CheckCondition --> Idle: Condition not met
    PerformAction --> Idle
    EvaluateRules --> Idle: All rules processed

TODOS

PERFORMANCE

• Consider adding a priority system for rules that need faster evaluation
• Optimize condition evaluation by caching register values when multiple rules reference the same address
• Implement batch processing for rules that write to sequential registers

SECURITY

• Consider adding authentication for modifying rule configurations
• Implement range checking for target addresses to prevent unauthorized access
• Add validation for rule parameters to prevent malformed rules

COMPLIANCE

• Ensure rule execution timing meets industrial control requirements
• Document rule format for compliance with automation standards
• Implement logging capabilities for audit trails in regulated environments

RECOMMENDATIONS

• Use separate register blocks for different rule sets to improve organization
• Implement a backup/restore mechanism for rule configurations
• Consider a graphical rule editor for easier configuration
• Add rule dependencies to allow chaining of rules

EXAMPLE

The Modbus Logic Engine is typically constructed early in the application startup:

#ifdef ENABLE_MB_SCRIPT
  modbusLogicEngine = new ModbusLogicEngine(
      this  // Owner (PHApp instance)
  );
  if (modbusLogicEngine) {
    components.push_back(modbusLogicEngine);
    Log.infoln(F("ModbusLogicEngine initialized."));
    
    // Register component methods that can be called from rules
    modbusLogicEngine->registerMethod(
        COMPONENT_ID_LED, // Component ID
        1,                // Method ID
        [this](short arg1, short arg2) -> short {
            // Example method implementation
            if (ledComponent) {
                return ledComponent->setPattern(arg1);
            }
            return E_COMPONENT_ERROR;
        }
    );
  } else {
    Log.errorln(F("ModbusLogicEngine initialization failed."));
  }
#endif

References