# bronkhorst-developer/bronkhorst-propar architecture

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

- Interactive diagram: https://gitdiagram.com/bronkhorst-developer/bronkhorst-propar
- Repository: https://github.com/bronkhorst-developer/bronkhorst-propar

## Overview

##### Project Type and Purpose
- This is an open-source Python library (“bron­khorst-propar”) that provides a Propar master implementation for communicating with Bronkhorst flow and pressure instruments over RS232/RS485 and FLOW-BUS.
- It is not a full-stack web app but a hardware-communication SDK/library intended for embedding in user scripts or applications.

##### File Structure Overview
- Top-level:
- setup.py, setup.cfg, MANIFEST.in, LICENSE, README.md – packaging and metadata
- .readthedocs.yml – ReadTheDocs configuration
- docs/ – Sphinx documentation source (RST files, Makefiles, images)
- propar/ – library code (package init + parameters module)
- test/ – automated test suite (unit and integration tests)
- build.bat, upload.bat – Windows scripts for build/upload tasks
- Key patterns:
- Small, single package “propar”
- Sphinx-driven docs, pytest/unittest tests
- Serial communication dependency (pyserial)

##### README Insights
- Core functionality: open serial port, send/receive Propar protocol frames, support single or multi-instrument FLOW-BUS.
- External dependency: pyserial.
- Cross-platform: Windows & Linux.
- Documentation hosted on ReadTheDocs.

a. Main components
1. User Application (any Python script or service using bronkhorst-propar)
2. bronkhorst-propar Library
– propar package (classes for connection, framing, parameter handling)
3. pyserial (external dependency providing SerialPort abstraction)
4. OS Serial Driver / RS232/RS485 Interface
5. FLOW-BUS Network (optional multi-drop bus)
6. Physical Instruments (flow meters, controllers, pressure devices)
7. Build/CI Components
– setup.py, pytest, build scripts, ReadTheDocs
b. Interactions
– pyserial invokes OS serial driver → physical wires (RS232/485)
– If FLOW-BUS mode: messages are broadcast to multiple instruments on the bus
– Instruments respond back through same path, data flows upstream into library
– Library decodes frames into parameter objects and returns to User App
– Build/CI flows: source → setup.py → package on PyPI; tests run via pytest; docs built via Sphinx → ReadTheDocs
c. Architectural Patterns and Design Principles
– Layered design: Application layer → Protocol library → Transport layer → Hardware
– Single Responsibility: propar.parameters handles parameter definitions, separate from serial framing
– Dependency Injection: library expects any SerialPort-compatible object (for mocking in tests)
– Test isolation: serial port injection in tests, use of mock ILogger for broadcast_logger
d. Key Technologies and Frameworks
– Python 3.x
– pyserial for serial I/O
– pytest/unittest for testing
– Sphinx for documentation
– ReadTheDocs for hosted docs
– setuptools for packaging

##### Capturing Essential Details
- Both single-device mode and FLOW-BUS multi-drop mode branching from pyserial.
- Packaging flow: source → setup.py → PyPI → pip install.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    subgraph "Application Layer" 
        direction TB
        UserApp["User Application\n(calls connect(), read(), write())"]:::user
    end

    %% Library Layer
    subgraph "bronkhorst-propar Library" 
        direction TB
        ProparInit["propar package"]:::library
        Params["propar.parameters module\n(handles parameter definitions)"]:::library
    end

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        PySerial["pyserial\n(SerialPort abstraction)"]:::external
        OSDriver["OS Serial Driver\n(COM/tty interface)"]:::external
    end

    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        RSBus["RS232/RS485 Bus"]:::hardware
        FlowBus["FLOW-BUS Network\n(optional multi-drop)"]:::hardware
        Instruments["Physical Instruments\n(flow meters, controllers)"]:::hardware
    end

    %% Build & CI Layer
    subgraph "Build & CI Pipeline"
        direction TB
        SetupPy["setup.py"]:::build
        SetupCfg["setup.cfg"]:::build
        Manifest["MANIFEST.in"]:::build
        Readme["README.md"]:::build
        License["LICENSE"]:::build
        Tests["Test Suite"]:::build
        DocsConfig[".readthedocs.yml"]:::build
        Docs["docs/"]:::build
        BuildScript["build.bat\nupload.bat"]:::build
    end

    %% Connections
    UserApp -->|"uses API"| ProparInit
    ProparInit -->|"imports definitions"| Params
    ProparInit -->|"uses serial"| PySerial
    Params -->|"framing & parsing"| ProparInit
    PySerial -->|"opens port"| OSDriver
    OSDriver -->|"sends/receives frames"| RSBus
    RSBus -->|"optional broadcast"| FlowBus
    FlowBus -->|"drives"| Instruments
    Instruments -->|"data frames"| OSDriver
    OSDriver -->|"frame bytes"| PySerial
    PySerial -->|"raw frames"| ProparInit
    ProparInit -->|"decoded parameters"| UserApp

    %% Build & CI connections
    SetupPy -->|"packages source"| SetupCfg
    SetupCfg --> Manifest
    SetupPy -->|"publishes to PyPI"| Readme
    Tests -->|"executes tests"| ProparInit
    Tests -->|"mocks SerialPort/logger"| Params
    DocsConfig --> Docs
    Docs -->|"built by Sphinx"| Readme
    Docs -->|"hosted on ReadTheDocs"| Readme
    BuildScript --> SetupPy

    %% Click Events
    click ProparInit "https://github.com/bronkhorst-developer/bronkhorst-propar/blob/master/propar/__init__.py"
    click Params "https://github.com/bronkhorst-developer/bronkhorst-propar/blob/master/propar/parameters.py"
    click SetupPy "https://github.com/bronkhorst-developer/bronkhorst-propar/blob/master/setup.py"
    click SetupCfg "https://github.com/bronkhorst-developer/bronkhorst-propar/blob/master/setup.cfg"
    click Manifest "https://github.com/bronkhorst-developer/bronkhorst-propar/blob/master/MANIFEST.in"
    click Readme "https://github.com/bronkhorst-developer/bronkhorst-propar/blob/master/README.md"
    click License "https://github.com/bronkhorst-developer/bronkhorst-propar/tree/master/LICENSE"
    click DocsConfig "https://github.com/bronkhorst-developer/bronkhorst-propar/blob/master/.readthedocs.yml"
    click Docs "https://github.com/bronkhorst-developer/bronkhorst-propar/tree/master/docs/"
    click Tests "https://github.com/bronkhorst-developer/bronkhorst-propar/tree/master/test/"
    click BuildScript "https://github.com/bronkhorst-developer/bronkhorst-propar/blob/master/build.bat"
    click BuildScript "https://github.com/bronkhorst-developer/bronkhorst-propar/blob/master/upload.bat"

    %% Styles
    classDef user fill:#cfe2f3,stroke:#2f5597,color:#0b5394;
    classDef library fill:#d9ead3,stroke:#6aa84f,color:#38761d;
    classDef external fill:#fff2cc,stroke:#b45f06,color:#bf9000;
    classDef hardware fill:#f4cccc,stroke:#cc0000,color:#a61c00;
    classDef build fill:#d9d2e9,stroke:#674ea7,color:#351c75;
```
