firmware-base/docs/ModbusLogicEngine.md

title	description	keywords
ModbusLogicEngine Component	A programmable logic rule engine that operates on Modbus registers to execute conditional commands	modbus, automation, rules engine, logic, conditional execution, industrial automation

ModbusLogicEngine

Path: 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
• ArduinoLog
• config.h
• ModbusTypes.h

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

BEHAVIOUR

The ModbusLogicEngine evaluates rules at regular intervals (default 100ms). For each enabled rule:

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:

#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
• PLC Programming Concepts