babayaga b630d72caa polymech - fw - base 0.9 - its got to go somewhere :)

2026-01-23 16:14:47 +01:00

15 KiB

Raw Permalink Blame History

Modbus RTU Client Subsystem Documentation

Overview

This document describes the classes, structures, and enums involved in the Modbus RTU Client functionality within the firmware. This subsystem is primarily managed by the ModbusRTU class and is responsible for communicating with downstream Modbus RTU slave devices over a serial (RS485) connection. It often works in conjunction with the Modbus TCP server (ModbusManager) to act as a TCP-to-RTU gateway.

The core tasks include queuing read/write operations, managing communication timing, handling retries and errors, caching slave data, and providing an interface to interact with the RTU devices.

Key Classes

`ModbusRTU`

Header: src/ModbusRTU.h
Source: src/ModbusRTU.cpp
Purpose: The central class managing Modbus RTU client communication. It uses the eModbus library's ModbusClientRTU internally.
Responsibilities:
- Initializes the RTU client and serial port.
- Manages a queue (operationQueue) of pending ModbusOperation requests.
- Handles the execution of operations, respecting timing intervals (minOperationInterval).
- Processes responses and errors from the eModbus library via callbacks (onDataReceived, onErrorReceived).
- Maintains a cache (slaveData) of the last known values for registers and coils on each slave device using SlaveData and ModbusValueEntry.
- Provides public methods (readCoil, writeRegister, etc.) to queue operations.
- Manages an optional filter chain (ModbusOperationFilter) to preprocess outgoing operations (e.g., prevent duplicates, rate limit).
- Provides status information (error counts, success rates).
- Handles adaptive timing adjustments if ENABLE_ADAPTIVE_TIMEOUT is defined.

`BaseModbusDevice`

Header: src/ModbusTypes.h
Source: src/ModbusTypes.cpp
Purpose: Represents the state and basic interaction logic for a single external Modbus RTU slave device being managed by ModbusRTU.
Responsibilities:
- Stores the slave ID (deviceId).
- Tracks the device's communication state (E_DeviceState: IDLE, RUNNING, ERROR).
- Manages communication timing (timeout, sync interval) and error counts for the specific device.
- Holds collections (inputRegisters, outputRegisters) of RegisterState objects representing the data points on the slave.
- Provides methods to add/manage RegisterState objects (addInputRegister, addOutputRegister).
- Provides methods to interact with the device's registers via the ModbusRTU manager (initialize, syncFromDevice, writeOutputs).
- Provides local accessors for register values (getInputRegisterValue, getOutputRegisterValue, setOutputRegisterValue).
- Includes helper methods for state management (printState, reset, runTestSequence).

`ModbusDeviceState`

Header: src/ModbusDeviceState.h
Source: src/ModbusDeviceState.cpp
Purpose: A derived class of BaseModbusDevice. Intended for application-specific implementations or specializations of Modbus RTU slave devices.
Responsibilities:
- Currently, mainly overrides setState to add specific logging.
- Its constructor can be used to add specific default registers required by the application logic using the addInputRegister/addOutputRegister methods inherited from BaseModbusDevice.

`RegisterState`

Header: src/ModbusTypes.h
Source: src/ModbusTypes.cpp
Purpose: Represents a single data point (Input Register, Holding Register, Coil, or Discrete Input) on an external Modbus RTU slave device.
Responsibilities:
- Stores the register type (RegType), Modbus address, current value, min/max values (for validation), and priority.
- Provides methods (readFromDevice, writeToDevice) to queue corresponding read/write operations via the ModbusRTU manager.
- Includes helper methods for boolean conversion (getBoolValue, setBoolValue) and printing state (printState).

Supporting Structures

`ModbusOperation`

Header: src/ModbusTypes.h
Purpose: Represents a single Modbus read or write request waiting to be executed or currently in progress. Stored in the ModbusRTU's operationQueue.
Key Members:
- timestamp: When the operation was created.
- token: Unique identifier used by eModbus library for asynchronous handling.
- address, value, quantity: Modbus request parameters.
- slaveId: Target slave device.
- type: The type of operation (E_MB_OpType).
- status: Current status (E_MB_OpStatus: PENDING, SUCCESS, FAILED, RETRYING).
- retries: Number of times execution has been attempted.
- flags: Bit flags indicating state (USED, HIGH_PRIORITY, IN_PROGRESS, BROADCAST, SYNCHRONIZED).

`ModbusValueEntry`

Header: src/ModbusTypes.h
Purpose: Represents a cached value for a single register or coil address on a specific slave. Used within the SlaveData structure.
Key Members:
- address: The Modbus address.
- value: The last known value.
- lastUpdate: Timestamp of the last update.
- synchronized: Flag indicating if the cached value is believed to be in sync with the device.
- used: Flag indicating if this entry is actively used.

`SlaveData`

Header: src/ModbusTypes.h
Purpose: Holds the cached data for a single Modbus RTU slave device managed by ModbusRTU. An array of SlaveData is stored in ModbusRTU.
Key Members:
- coils: Fixed-size array of ModbusValueEntry for coils.
- registers: Fixed-size array of ModbusValueEntry for registers.
- coilCount, registerCount: Number of used entries in the arrays.

Operation Filtering

`ModbusOperationFilter` (Base Class)

Header: src/ModbusTypes.h
Purpose: Abstract base class for filters that can be chained together to process ModbusOperation requests before they are queued for execution by ModbusRTU.
Key Methods:
- filter(op): Pure virtual method; derived classes implement logic here. Returns true to allow the operation, false to drop it.
- process(op): Processes the operation through the current filter and the rest of the chain.
- setNext(filter*), getNext(): Manage the filter chain links.
- notifyOperationExecuted(op), notifyOperationCompleted(op): Optional methods for stateful filters.
- getType(): Returns the filter type (E_FilterType).

Derived Filter Classes

Header: src/ModbusTypes.h
Source: src/ModbusTypes.cpp
Classes:
- DuplicateOperationFilter: Prevents queuing an operation if an identical one (same slave, type, address) is already pending in the ModbusRTU queue. Requires a pointer to the ModbusRTU instance.
- RateLimitFilter: Enforces a minimum time interval between consecutive operations passing through it.
- PriorityFilter: Currently a placeholder; intended to potentially adjust operation priority flags (though filtering itself always returns true).
- OperationLifecycleFilter: Drops operations that have exceeded MAX_RETRIES or have timed out (OPERATION_TIMEOUT).

Key Enums

E_MB_OpType: (src/ModbusTypes.h) Defines the type of Modbus operation (READ_COIL, WRITE_REGISTER, etc.).
E_MB_OpStatus: (src/ModbusTypes.h) Defines the status of a queued ModbusOperation (PENDING, SUCCESS, FAILED, RETRYING).
MB_Error: (src/ModbusTypes.h) Comprehensive error codes, combining standard Modbus exceptions, internal queue/operation errors, and eModbus communication errors.
E_FilterType: (src/ModbusTypes.h) Identifies the type of a ModbusOperationFilter.
E_DeviceState: (src/ModbusTypes.h) State of a BaseModbusDevice (IDLE, RUNNING, ERROR).
RegType: (src/ModbusTypes.h) Type of a RegisterState (INPUT, HOLDING, COIL, DISCRETE_INPUT).
E_InitState: (src/ModbusRTU.h) Internal state for the ModbusRTU class initialization process.

Key Constants

MAX_MODBUS_SLAVES: (src/ModbusTypes.h) Max number of RTU slaves the client can manage.
MAX_ADDRESSES_PER_SLAVE: (src/ModbusTypes.h) Size of the ModbusValueEntry arrays within SlaveData.
MAX_PENDING_OPERATIONS: (src/ModbusTypes.h) Size of the ModbusRTU operation queue.
MAX_RETRIES: (src/ModbusTypes.h) Default max retries for a failing operation.
OPERATION_TIMEOUT: (src/ModbusTypes.h) Default timeout for an operation before being considered failed/expired by OperationLifecycleFilter.
BAUDRATE: (src/ModbusTypes.h) Default serial baud rate for RS485.
PRIORITY_* Defines: (src/ModbusTypes.h) Constants used for setting RegisterState priorities.
OP_FLAG_* Defines: (src/ModbusTypes.h) Bit flags used within ModbusOperation.flags.

Callback Functions

ResponseCallback: (src/ModbusTypes.h) typedef void (*ResponseCallback)(uint8_t slaveId). Can be set on ModbusRTU to trigger custom logic when any response (success or error) is received for a slave.
OnRegisterChangeCallback: (src/ModbusTypes.h) typedef void (*OnRegisterChangeCallback)(const ModbusOperation& op, uint16_t oldValue, uint16_t newValue). Set on ModbusRTU to be notified when a successful read operation results in a changed value in the cache.
OnWriteCallback: (src/ModbusTypes.h) typedef void (*OnWriteCallback)(const ModbusOperation& op). Set on ModbusRTU to be notified when a write operation completes successfully.
OnErrorCallback: (src/ModbusTypes.h) typedef void (*OnErrorCallback)(const ModbusOperation& op, int errorCode, const char* errorMessage). Set on ModbusRTU to be notified when an operation fails (either timeout, Modbus exception, or internal error).

Mermaid Diagrams

Core Class Relationships

classDiagram
    class ModbusRTU {
        +MB_Error begin(HardwareSerial&, uint32_t)
        +MB_Error process()
        +MB_Error readCoil(uint8_t, uint16_t)
        +MB_Error writeRegister(uint8_t, uint16_t, uint16_t)
        +bool getCoilValue(uint8_t, uint16_t, bool&)
        +bool getRegisterValue(uint8_t, uint16_t, uint16_t&)
        +bool isCoilSynchronized(uint8_t, uint16_t)
        +bool isRegisterSynchronized(uint8_t, uint16_t)
        +bool hasPendingOperations(uint8_t)
        +void addFilter(ModbusOperationFilter*)
        -SlaveData slaveData[MAX_MODBUS_SLAVES]
        -ModbusOperation operationQueue[MAX_PENDING_OPERATIONS]
        -ModbusOperationFilter* firstFilter
        -MB_Error queueOperation(ModbusOperation, bool)
        -void onDataReceived(ModbusMessage, uint32_t)
        -void onErrorReceived(Error, uint32_t)
        -ModbusValueEntry* findCoilEntry(...)
        -ModbusValueEntry* createCoilEntry(...)
        -ModbusValueEntry* findRegisterEntry(...)
        -ModbusValueEntry* createRegisterEntry(...)
    }

    class BaseModbusDevice {
        +uint8_t deviceId
        +E_DeviceState state
        +unsigned long syncInterval
        +bool addInputRegister(uint16_t, uint8_t)
        +bool addOutputRegister(uint16_t, uint16_t, uint8_t)
        +void updateState(ModbusRTU&)
        +bool initialize(ModbusRTU&)
        +void syncFromDevice(ModbusRTU&)
        +void writeOutputs(ModbusRTU&)
        +void printState(ModbusRTU&)
        +void reset()
        +uint16_t getInputRegisterValue(uint16_t)
        +uint16_t getOutputRegisterValue(uint16_t)
        +void setOutputRegisterValue(uint16_t, uint16_t)
        #RegisterState* inputRegisters[]
        #RegisterState* outputRegisters[]
        #int inputRegCount
        #int outputRegCount
    }

    class ModbusDeviceState {
      +ModbusDeviceState(uint8_t)
      +void setState(E_DeviceState) override
    }

    class RegisterState {
        +RegType type
        +uint16_t address
        +uint16_t value
        +uint8_t priority
        +MB_Error readFromDevice(ModbusRTU&, uint8_t)
        +MB_Error writeToDevice(ModbusRTU&, uint8_t)
        +void printState(ModbusRTU&, uint8_t)
        +bool getBoolValue()
    }

    class ModbusOperation {
        +unsigned long timestamp
        +uint32_t token
        +uint16_t address
        +uint16_t value
        +uint16_t quantity
        +uint8_t slaveId
        +E_MB_OpType type
        +E_MB_OpStatus status
        +uint8_t flags
    }

    class SlaveData {
        #ModbusValueEntry coils[]
        #ModbusValueEntry registers[]
        #uint8_t coilCount
        #uint8_t registerCount
    }

    class ModbusValueEntry {
        +unsigned long lastUpdate
        +uint16_t address
        +uint16_t value
        +bool synchronized
        +bool used
    }

    ModbusRTU o-- "0..MAX_MODBUS_SLAVES" SlaveData : contains cache
    ModbusRTU o-- "0..MAX_PENDING_OPERATIONS" ModbusOperation : queues
    ModbusRTU ..> ModbusOperationFilter : uses chain
    BaseModbusDevice o-- "0..MAX_INPUT_REGISTERS" RegisterState : manages inputs
    BaseModbusDevice o-- "0..MAX_OUTPUT_REGISTERS" RegisterState : manages outputs
    BaseModbusDevice ..> ModbusRTU : interacts via
    ModbusDeviceState --|> BaseModbusDevice : inherits from
    SlaveData o-- "0..MAX_ADDRESSES_PER_SLAVE" ModbusValueEntry : caches coil values
    SlaveData o-- "0..MAX_ADDRESSES_PER_SLAVE" ModbusValueEntry : caches register values
    RegisterState ..> ModbusRTU : interacts via

Filter Chain Relationships

classDiagram
    class ModbusOperationFilter {
        <<Abstract>>
        +process(ModbusOperation) bool
        +setNext(ModbusOperationFilter*)
        +getType() E_FilterType
        #ModbusOperationFilter* nextFilter
        +$ filter(ModbusOperation) bool
        +$ notifyOperationExecuted(ModbusOperation) void
        +$ notifyOperationCompleted(ModbusOperation) void
    }

    class DuplicateOperationFilter {
        +DuplicateOperationFilter(ModbusRTU*)
        +filter(ModbusOperation) bool
        -ModbusRTU* modbusRTU
    }

    class RateLimitFilter {
        +RateLimitFilter(ulong)
        +filter(ModbusOperation) bool
        -ulong minInterval
        -ulong lastOperationTime
    }

    class PriorityFilter {
        +filter(ModbusOperation) bool
        +adjustPriority(ModbusOperation&) bool
    }

    class OperationLifecycleFilter {
        +OperationLifecycleFilter(ulong, uint8_t)
        +filter(ModbusOperation) bool
        -ulong timeout
        -uint8_t maxRetries
    }

    DuplicateOperationFilter --|> ModbusOperationFilter
    RateLimitFilter --|> ModbusOperationFilter
    PriorityFilter --|> ModbusOperationFilter
    OperationLifecycleFilter --|> ModbusOperationFilter

15 KiB Raw Permalink Blame History