# virantha/bricknil architecture

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

- Interactive diagram: https://gitdiagram.com/virantha/bricknil
- Repository: https://github.com/virantha/bricknil

## Overview

##### Main Components
- External Communication Layer – the Bluetooth radio interface provided by external libraries (Adafruit BluefruitLE for OS X, Bleak for Linux/Win10). Indicate that these libraries run their own event loop/thread.
- Asynchronous Event Loop – the Curio-based async environment that drives the user code and manages concurrent operations.
- Bluetooth Interface Modules – components like “ble_queue” and “bleak_interface” which bridge the external Bluetooth communication and the asynchronous code.
- Core Library: BrickNil’s own modules such as “bricknil”, “hub”, and “process” which provide core abstractions. For example:
– Hub classes (e.g., PoweredUpHub, BoostHub, DuploTrainHub) that encapsulate connected devices.
– Sensor modules (located in bricknil/sensor, e.g. motor, light, peripheral, sound) that define how to interact with different types of sensors/actuators.
– Message dispatch, constants, and versioning modules that standardize communication and maintain the library’s state.
- User Application Layer – the code written by the user (using decorators like @attach and calling start(system)) which instantiates hub objects and contains the control logic.
- Logging/Process Monitoring – the “process” module sub-classing that provides logging and status messages during the run loop.

##### Relationships and Interactions
- That the external BLE libraries (via their separate run loops/threads) pass Bluetooth events to BrickNil’s Bluetooth interface modules.
- Core Hub classes to their attached sensors (highlighted with the @attach decorator), indicating that sensor change events (e.g. vision sensor updates, button presses) trigger callbacks in the Hub’s logic.
- Messaging flow – e.g., how messages are dispatched from the sensor handlers to process methods, then relayed to the user’s callback code.
- A feedback loop where the Hub class calls sensor commands (like set_speed or ramp_speed) that eventually result in a command being sent back out through the BLE interface to the physical LEGO device.

##### Architectural Patterns and Design Principles
- Asynchronous concurrent programming – the use of async/await in every sensor and motor operation.
- Separation of concerns by isolating:
– BLE communication in its dedicated modules and run loops.
– The core logic of controlling hubs and sensors in distinct classes.
– The user code, which builds on top of these abstractions to form a complete control system.
- Dual run-loop design: one for BLE radio events and one for the async event processing (Curio).

##### Relevant Technologies and Frameworks
- Python 3.7+ (as required by the project)
- Curio for asynchronous programming
- Adafruit BluefruitLE and Bleak as BLE communication libraries
- Standard Python logging for process messaging

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External BLE Libraries"
        extBLE("External BLE Libraries (AdafruitBluefruitLE,Bleak)"):::infrastructure
    end

    subgraph "Bluetooth Interface Modules"
        bleQueue("BLE Queue"):::interface
        bleInterface("Bleak Interface"):::interface
    end

    subgraph "Asynchronous Event Loop"
        asyncLoop("Curio Async Loop"):::infrastructure
    end

    subgraph "Core Library"
        hubClasses("Hub Classes"):::core
        sensorModules("Sensor Modules"):::core
        msgDispatch("Message&Dispatch"):::core
    end

    subgraph "Process Logging/Monitoring"
        processLog("Process Logging"):::process
    end

    subgraph "User Application Layer"
        userApp("User App Logic"):::user
    end

    %% Connections between layers
    extBLE -->|"sends_BLE_events"| bleQueue
    extBLE -->|"sends_BLE_events"| bleInterface

    bleQueue -->|"injects_events"| asyncLoop
    bleInterface -->|"injects_events"| asyncLoop

    asyncLoop -->|"triggers_callbacks"| hubClasses

    hubClasses -->|"attaches_sensors"| sensorModules
    sensorModules -->|"dispatches_messages"| msgDispatch

    hubClasses -->|"sends_commands"| bleQueue
    hubClasses -->|"sends_commands"| bleInterface

    asyncLoop -->|"logs_events"| processLog

    userApp -->|"starts_event_loop"| asyncLoop
    userApp -->|"instantiates_hubs"| hubClasses

    %% Click Events
    click bleQueue "https://github.com/virantha/bricknil/blob/master/bricknil/ble_queue.py"
    click bleInterface "https://github.com/virantha/bricknil/blob/master/bricknil/bleak_interface.py"
    click asyncLoop "https://github.com/virantha/bricknil/blob/master/bricknil/bricknil.py"
    click hubClasses "https://github.com/virantha/bricknil/blob/master/bricknil/hub.py"
    click sensorModules "https://github.com/virantha/bricknil/tree/master/bricknil/sensor/"
    click msgDispatch "https://github.com/virantha/bricknil/blob/master/bricknil/message_dispatch.py"
    click processLog "https://github.com/virantha/bricknil/blob/master/bricknil/process.py"
    click userApp "https://github.com/virantha/bricknil/tree/master/examples/"

    %% Class Definitions
    classDef infrastructure fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef interface fill:#D4EFDF,stroke:#27AE60,stroke-width:2px;
    classDef core fill:#FEF9E7,stroke:#B7950B,stroke-width:2px;
    classDef process fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef user fill:#FBEEC1,stroke:#F39C12,stroke-width:2px;
```
