# ait-rdp/rdp-modbus-crawler architecture

> Architecture diagram of the GitHub repository ait-rdp/rdp-modbus-crawler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ait-rdp/rdp-modbus-crawler
- Repository: https://github.com/ait-rdp/rdp-modbus-crawler

## Overview

##### Project type and purpose
- This is an open-source Python library (“Modbus Crawler”) that automates reading and writing Modbus registers.
- It provides generic, pluggable support for specifying registers via CSV or pandas DataFrame, and for connecting over TCP or RTU, sync or async.

##### File structure
Top level:
- setup.py, README.md, LICENSE, CI config
- modbus_crawler/ (core package)
– input_data_validation.py
– modbus_register_list_parser.py
– modbus_register_list_parser_csv.py
– modbus_register_list_parser_pandas.py
– register_block.py
– modbus_device.py
– modbus_device_tcp.py / modbus_device_tcp_async.py
– modbus_device_rtu.py  / modbus_device_rtu_async.py
- test/ (unit tests and example CSVs)

Patterns & layers:
- “Parser” layer: reading & validating spec (CSV or pandas)
- “Model” layer: RegisterBlock abstraction
- “Device” layer: common API + four transport implementations (TCP/RTU × sync/async)
- “External I/O” layer: network socket or serial port to Modbus slave device

##### Insights from the README
- Purpose: group registers into blocks, decode to Python types, minimize Modbus calls
- Supported data types, case-insensitive headers, string handling
- Example API use (connect, read_registers_as_dict, disconnect)
- Extensibility: alias maps in input_data_validation, multiple parser backends

##### Main components
A. Register Spec Input
- CSV Parser (modbus_register_list_parser_csv.py)
- Pandas Parser (modbus_register_list_parser_pandas.py)
- Validation module (input_data_validation.py)
B. RegisterBlock assembly (register_block.py)
C. Device API layer (modbus_device.py)
– defines connect(), disconnect(), read_register(s), write_register()
D. Transport implementations
- ModbusTcpDevice (modbus_device_tcp.py)
- ModbusTcpDeviceAsync (modbus_device_tcp_async.py)
- ModbusRtuDevice (modbus_device_rtu.py)
- ModbusRtuDeviceAsync (modbus_device_rtu_async.py)
E. External Modbus Slave
F. Test suite (test/)

##### Relationships & data flows
1. User application → invokes library API (ModbusTcpDevice or RTU)
2. Device constructor loads a register spec via Parser layer → Validation
3. Parser outputs list of register definitions → RegisterBlock groups registers into blocks
4. read_registers() calls the transport implementation → issues Modbus read on TCP/Serial
5. Raw bytes ← network/serial → transport → decode in RegisterBlock → Map to Python types
6. write_register() mirrors above for writes
7. Test suite exercises parsers, blocks, devices using sample CSV & config

##### Architectural patterns & principles
- Layered architecture: Separation between parsing, business logic, transport
- Strategy/Plugin pattern: interchangeable parsers (CSV vs pandas), transport classes (sync vs async)
- Single Responsibility: each module handles one concern (validation, parsing, register grouping, transport)
- Abstraction: common Device API hiding sync/async and TCP/RTU differences

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User and Spec Input
    UA["User Application"]:::external
    SpecCSV["Register Spec (CSV)"]:::external
    SpecDF["Register Spec (DataFrame)"]:::external

    %% Parser Layer
    subgraph "Parser Layer"
        direction TB
        GPI["Generic Parser Interface"]:::core
        CSVP["CSV Parser"]:::parser
        PDSP["Pandas Parser"]:::parser
    end

    %% Validation and Core Logic
    subgraph "Core Business Logic"
        direction TB
        VAL["Validation Module"]:::core
        RB["RegisterBlock Assembly"]:::core
    end

    %% Device API
    subgraph "Device API Layer"
        direction TB
        DEV["Device API Base"]:::core
        ASYNCDEV["Async Device API Base"]:::core
    end

    %% Transport Implementations
    subgraph "Transport Implementations"
        direction TB
        MTCP["Modbus TCP Sync"]:::transport
        MTCPA["Modbus TCP Async"]:::transport
        MRTU["Modbus RTU Sync"]:::transport
        MRTUA["Modbus RTU Async"]:::transport
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        Slave["Modbus Slave Device"]:::external
        PandasLib["pandas Library"]:::external
        SerialLib["serial / pymodbus"]:::external
    end

    %% Test Suite
    subgraph "Test Suite" 
        direction TB
        style TestSuite stroke-dasharray: 5 5,stroke:gray
        TS["Unit Tests & CSV Examples"]:::test
    end

    %% Data Flows
    UA -->|"provides spec"| SpecCSV
    UA -->|"provides DataFrame"| SpecDF

    SpecCSV -->|"CSV content"| CSVP
    SpecDF -->|"DataFrame"| PDSP
    CSVP -->|"implements"| GPI
    PDSP -->|"implements"| GPI

    GPI -->|"parsed data"| VAL
    VAL -->|"validated register list"| RB

    RB -->|"blocks & decode"| DEV
    DEV -->|"sync calls"| MTCP
    DEV -->|"sync calls"| MRTU
    ASYNCDEV -->|"async calls"| MTCPA
    ASYNCDEV -->|"async calls"| MRTUA

    MTCP -->|"Modbus read/write"| Slave
    MRTU -->|"Modbus read/write"| Slave
    MTCPA -->|"Modbus read/write"| Slave
    MRTUA -->|"Modbus read/write"| Slave

    MTCPA -->|"uses async base"| ASYNCDEV
    MRTUA -->|"uses async base"| ASYNCDEV

    DEV -->|"optional async base decision"| ASYNCDEV

    %% Library Dependencies
    PDSP -->|"relies on"| PandasLib
    MRTU -->|"uses"| SerialLib
    MRTUA -->|"uses"| SerialLib
    MTCP -->|"uses"| SerialLib
    MTCPA -->|"uses"| SerialLib

    %% Test Suite Connections
    TS --> GPI
    TS --> VAL
    TS --> RB
    TS --> MTCP
    TS --> MRTU

    %% Click Events
    click VAL "https://github.com/ait-rdp/rdp-modbus-crawler/blob/main/modbus_crawler/input_data_validation.py"
    click GPI "https://github.com/ait-rdp/rdp-modbus-crawler/blob/main/modbus_crawler/modbus_register_list_parser.py"
    click CSVP "https://github.com/ait-rdp/rdp-modbus-crawler/blob/main/modbus_crawler/modbus_register_list_parser_csv.py"
    click PDSP "https://github.com/ait-rdp/rdp-modbus-crawler/blob/main/modbus_crawler/modbus_register_list_parser_pandas.py"
    click RB "https://github.com/ait-rdp/rdp-modbus-crawler/blob/main/modbus_crawler/register_block.py"
    click DEV "https://github.com/ait-rdp/rdp-modbus-crawler/blob/main/modbus_crawler/modbus_device.py"
    click ASYNCDEV "https://github.com/ait-rdp/rdp-modbus-crawler/blob/main/modbus_crawler/modbus_device_async.py"
    click MTCP "https://github.com/ait-rdp/rdp-modbus-crawler/blob/main/modbus_crawler/modbus_device_tcp.py"
    click MTCPA "https://github.com/ait-rdp/rdp-modbus-crawler/blob/main/modbus_crawler/modbus_device_tcp_async.py"
    click MRTU "https://github.com/ait-rdp/rdp-modbus-crawler/blob/main/modbus_crawler/modbus_device_rtu.py"
    click MRTUA "https://github.com/ait-rdp/rdp-modbus-crawler/blob/main/modbus_crawler/modbus_device_rtu_async.py"
    click TS "https://github.com/ait-rdp/rdp-modbus-crawler/tree/main/test/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#00509e,color:#000;
    classDef parser fill:#d4edda,stroke:#1e7e34,color:#000;
    classDef transport fill:#fff3cd,stroke:#856404,color:#000;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000;
    classDef test fill:none,stroke:#6c757d,color:#6c757d;
    class GPI,VAL,RB,DEV,ASYNCDEV core
    class CSVP,PDSP parser
    class MTCP,MTCPA,MRTU,MRTUA transport
    class UA,SpecCSV,SpecDF,Slave,PandasLib,SerialLib external
    class TS test
```
