firmware-base/docs/mb-lang.md

Modbus Logic Language (mb-lang)

This document describes the design and usage of the simple logic engine configurable via Modbus TCP.

Purpose

The Modbus Logic Engine allows users to define simple conditional automation rules directly by writing to specific Modbus holding registers. This enables basic automation sequences like "if sensor value X exceeds Y, then turn on relay Z" without modifying the core firmware code.

Architecture

A dedicated component, ModbusLogicEngine, runs within the firmware.

• It exposes a block of Modbus Holding Registers for configuration and status.
• It periodically evaluates the enabled rules.
• It can read the state of other Modbus registers/coils.
• It can perform actions like writing to Modbus registers/coils or calling pre-defined methods on other firmware components.
• It updates status registers after each rule evaluation/action attempt.

Configuration and Status

The engine supports a fixed number of logic rules, defined by MAX_LOGIC_RULES (e.g., 8). Each rule is configured and monitored using a block of REGISTERS_PER_RULE (now 13) consecutive Holding Registers.

• Base Address: MODBUS_LOGIC_RULES_START (Defined in config-modbus.h)
• Rule N Address: MODBUS_LOGIC_RULES_START + (N * REGISTERS_PER_RULE) where N is the rule index (0 to MAX_LOGIC_RULES - 1).

Register Map per Rule (N)

Offset	Register Name	Address Offset	R/W	Description	Notes
+0	Rule_N_Enabled	Base + (N*13) + 0	R/W	Enable/Disable Rule: 0 = Disabled, 1 = Enabled	Rules are ignored if disabled.
+1	Rule_N_Cond_Src_Type	Base + (N*13) + 1	R/W	Condition Source Type: 0 = Holding Register, 1 = Coil	Specifies what type of Modbus item the condition reads.
+2	Rule_N_Cond_Src_Addr	Base + (N*13) + 2	R/W	Condition Source Address: Modbus address of the register/coil to read for the condition.	The address of the data point to check.
+3	Rule_N_Cond_Operator	Base + (N*13) + 3	R/W	Condition Operator: 0===, 1=!=, 2=<, 3=<=, 4=>, 5=>=	The comparison to perform.
+4	Rule_N_Cond_Value	Base + (N*13) + 4	R/W	Condition Value: The value to compare the source against.	For Coils, use 0 for OFF and 1 for ON.
+5	Rule_N_Action_Type	Base + (N*13) + 5	R/W	Action Type: 0=None, 1=Write Holding Reg, 2=Write Coil, 3=Call Component Method	Specifies what to do if the condition is true.
+6	Rule_N_Action_Target	Base + (N*13) + 6	R/W	Action Target: Modbus Address (for Write Reg/Coil) or Component ID (for Call Method)	Specifies what to act upon (Register Address, Coil Address, Component ID).
+7	Rule_N_Action_Param1	Base + (N*13) + 7	R/W	Action Parameter 1: Value (for Write Reg), ON/OFF (for Write Coil, 0=OFF, 1=ON), Method ID (for Call)	Specifies how to act upon the target.
+8	Rule_N_Action_Param2	Base + (N*13) + 8	R/W	Action Parameter 2: Argument 1 for Call Component Method	First argument for the component method. Ignored for Write actions.
+9	Rule_N_Action_Param3	Base + (N*13) + 9	R/W	Action Parameter 3: Argument 2 for Call Component Method	Second argument for the component method. Ignored for Write actions.
+10	Rule_N_Last_Status	Base + (N*13) + 10	R	Last Action Status: 0=Idle/OK, 1=Err Cond Read, 2=Err Action Write/Call, 3=Invalid Action Params	Reports the outcome of the last trigger attempt. (See Status Codes below)
+11	Rule_N_Last_Trigger_Timestamp	Base + (N*13) + 11	R	Last Trigger Timestamp: System time (e.g., seconds since boot) when rule last triggered.	0 if never triggered. Wraps eventually.
+12	Rule_N_Trigger_Count	Base + (N*13) + 12	R	Trigger Count: Number of times this rule's action has been successfully triggered.	Wraps eventually. Can be reset by writing 0 via Modbus.

Note: Base refers to MODBUS_LOGIC_RULES_START. R=Read-Only, W=Writeable (from Modbus perspective). Status registers (+10 to +12) are updated internally but the count (+12) can potentially be reset via write.

Status Codes (Rule_N_Last_Status)

Code	Meaning
0	Idle / Action OK
1	Error Reading Condition Src
2	Error Performing Action
3	Invalid Action Parameters
4	Component Method Call Failed
...	(Other specific errors TBD)

Actions

1. Write Holding Register

• Action Type: 1
• Action Target: Modbus address of the Holding Register.
• Action Parameter 1: Value to write.
• Action Parameters 2 & 3: Ignored.

2. Write Coil

• Action Type: 2
• Action Target: Modbus address of the Coil.
• Action Parameter 1: Value to write (0 for OFF, 1 for ON). Other non-zero values may also be interpreted as ON.
• Action Parameters 2 & 3: Ignored.

3. Call Component Method

• Action Type: 3
• Action Target: The numeric Component ID.
• Action Parameter 1: The numeric Method ID.
• Action Parameter 2: The first integer argument (arg1).
• Action Parameter 3: The second integer argument (arg2).

Important: Only specific, pre-registered methods can be called. Available Component/Method IDs need separate documentation.

Execution Flow

1. The ModbusLogicEngine loops periodically.
2. For each rule N from 0 to MAX_LOGIC_RULES - 1: a. Read Rule_N_Enabled. If 0, skip. b. Read condition parameters. c. Attempt to read the current value from Cond_Src_Addr. d. If read fails, update Rule_N_Last_Status (e.g., to 1) and skip to the next rule. e. Evaluate the condition. f. If the condition is TRUE: i. Read action parameters. ii. Attempt to perform the specified action. iii. Update Rule_N_Last_Status based on action success (0) or failure (e.g., 2, 3, 4). iv. If action was successful, increment Rule_N_Trigger_Count and update Rule_N_Last_Trigger_Timestamp. g. If the condition is FALSE, potentially reset Rule_N_Last_Status to 0 (Idle), unless it holds an error state.

Example Scenarios

(Addresses updated for REGISTERS_PER_RULE = 13)

Example 1: Turn on Relay 5 if Register 200 >= 100

Assume:

• MODBUS_LOGIC_RULES_START = 1000
• Rule Index N = 0 (Base = 1000)
• Relay 5 is mapped to Coil address 5
• Register 200

Write:

Register Address	Value	Meaning
1000	1	Rule 0: Enabled
1001	0	Cond Src Type: Reg
1002	200	Cond Src Addr: 200
1003	5	Cond Operator: >= (5)
1004	100	Cond Value: 100
1005	2	Action Type: Write Coil
1006	5	Action Target: Coil Addr 5
1007	1	Action Param 1: Value ON
1008	0	Action Param 2: (Ignored)
1009	0	Action Param 3: (Ignored)

Read Status (after trigger):

Register Address	Value	Meaning
1010	0	Last Status: OK
1011	e.g., 12345	Last Trigger: Timestamp
1012	e.g., 1	Trigger Count: 1

Example 2: Call resetCounter() Method on Component StatsTracker if Coil 10 is ON

Assume:

• Rule Index N = 1 (Base = 1000 + 13 = 1013)
• Coil 10
• Component StatsTracker ID = 5
• Method resetCounter ID = 1 (takes no args)

Write:

Register Address	Value	Meaning
1013	1	Rule 1: Enabled
1014	1	Cond Src Type: Coil
1015	10	Cond Src Addr: Coil 10
1016	0	Cond Operator: == (0)
1017	1	Cond Value: ON (1)
1018	3	Action Type: Call Method
1019	5	Action Target: Component ID 5
1020	1	Action Param 1: Method ID 1
1021	0	Action Param 2: Arg1 = 0
1022	0	Action Param 3: Arg2 = 0

Read Status (after trigger):

Register Address	Value	Meaning
1023	0	Last Status: OK
1024	e.g., 12360	Last Trigger: Timestamp
1025	e.g., 1	Trigger Count: 1

Limitations & Considerations

• Complexity: Only simple, single conditions per rule. No AND/OR/ELSE.
• Execution Order: Rules evaluated sequentially.
• Performance: Rule evaluation takes time. Consider impact and execution frequency.
• Timestamp: The Last_Trigger_Timestamp resolution and potential for wrapping depend on the firmware implementation (e.g., millis() overflow, using seconds since boot).
• Error Handling: Status codes provide basic feedback. More detailed logging might be needed for complex debugging.
• Method Availability: Callable methods are fixed in firmware.
• Concurrency: Actions (especially method calls) might take time. The engine design needs to consider if rule evaluation should block or if actions run asynchronously (current design implies synchronous execution within the loop).

Limitations & Considerations

• Complexity: Only simple, single conditions per rule are supported. No AND/OR or ELSE logic.
• Execution Order: Rules are evaluated sequentially. Be mindful of potential interactions if multiple rules modify the same target.
• Performance: Reading Modbus values and executing actions takes time. Complex rules or a large number of rules might impact overall system performance. Rule execution frequency should be considered.
• Error Handling: The current design doesn't explicitly define Modbus registers for rule execution status or errors. This could be added later.
• Method Availability: The list of callable methods (Component ID, Method ID) is fixed in the firmware and needs to be documented for users.