# weliem/blessed-android architecture

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

- Interactive diagram: https://gitdiagram.com/weliem/blessed-android
- Repository: https://github.com/weliem/blessed-android

## Overview

- The core library source under the “blessed” directory, which contains all the BLE logic (classes such as BluetoothCentralManager, BluetoothPeripheral, BluetoothPeripheralManager, BluetoothCentral, and BluetoothBytesParser) and associated callbacks.
- An example app (“app” directory) that demonstrates typical use cases (scanning, connecting, reading/writing characteristics, notifications, bonding, etc.) by utilizing the core library.
There are also additional supporting directories (like “docs” for documentation, Gradle configuration files, CI configurations in .github/workflows, etc.).

##### Main Components
a. Android BLE Subsystem – representing the native Android Bluetooth stack.
b. Core Blessed Library Components – individual classes/abstractions:
– BluetoothCentralManager (for scanning and managing connections)
– BluetoothPeripheral (as a wrapper for managing GATT operations)
– BluetoothPeripheralManager (to create and manage a peripheral)
– BluetoothCentral (for uses in peripheral creation via callbacks)
– BluetoothBytesParser (a utility for parsing/building BLE byte arrays)
c. Application Layer – the example app that uses the blessed library to demonstrate functionalities (UI activities, example tests, etc.).
d. External Dependencies and Configuration – Gradle, CI/CD (GitHub workflows), and accompanying documentation.

##### Relationships and Interactions
- The application layer calls the Blessed library’s API. For example, the MainActivity in the “app” package will instantiate a BluetoothCentralManager and register a callback to listen for scan results.
- The BluetoothCentralManager interacts with the underlying Android BLE system to perform scanning and connection efforts.
- Once devices are discovered, the BluetoothPeripheral objects (wrapped versions of Android BluetoothDevice/Gatt) are managed, and service discovery and characteristic read/write operations occur.
- Callbacks such as onConnectedPeripheral, onServicesDiscovered, onCharacteristicUpdate, etc., illustrate the asynchronous communication between the library and the application.
- The library itself abstracts many low-level details like queuing operations, managing threading, handling bonding, and negotiating MTU or Phy settings.

##### Architectural Patterns and Design Principles
– Abstraction Layer: The library abstracts Android BLE’s low-level APIs so that developers have a simpler interface (similar to iOS’s CoreBluetooth).
– Asynchronous Communication: The use of callbacks for asynchronous operations (e.g., scanning, connecting, bonding) is central to the design.
– Separation of Concerns: There is a clear separation between the core BLE functionality (in the “blessed” package) and the user/developer facing example application (in the “app” package).
– Modular Design: Distinct classes and callback interfaces are defined for each BLE-related operation (scanning, connection handling, characteristic read/write, notifications, and Bluetooth 5 features).

##### Relevant Technologies, Frameworks, and Libraries
- Android SDK – underlying BLE APIs.
- Gradle – for build and dependency management.
- GitHub Actions (gradle.yml) – for continuous integration.
- Timber – used for logging.
- Java (and optimizations/compatibility for Kotlin) – primary language of the library.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Example Application"
        Main("Application UI/Example App (MainActivity)"):::app
    end

    subgraph "Core Blessed Library"
        BCM("BluetoothCentralManager"):::library
        BP("BluetoothPeripheral"):::library
        BPM("BluetoothPeripheralManager"):::library
        BC("BluetoothCentral"):::library
        BBytes("BluetoothBytesParser"):::library
    end

    subgraph "Android BLE Subsystem"
        ABLE("Android BLE Subsystem"):::system
    end

    subgraph "External & Configurations"
        ED("External Dependencies (Gradle)"):::external
        CI("CI Configuration"):::external
        DOC("Documentation"):::external
    end

    Main -->|"InitiateScan"| BCM
    BCM -->|"PerformScan/Connect"| ABLE
    ABLE -->|"ScanResults/Callbacks"| BCM
    BCM -->|"WrapDevice"| BP
    BP -->|"Callback:onConnectedPeripheral,onServicesDiscovered,onCharacteristicUpdate"| Main
    BCM -->|"UsesCallback"| BC
    BPM -->|"AdvertisePeripheral"| ABLE
    BCM -->|"Utilizes"| BBytes
    BP -->|"Utilizes"| BBytes

    ED -.->|"BuildEnvironment"| BCM
    ED -.->|"BuildEnvironment"| Main
    CI -.-> ED
    DOC -.-> ED

    click BCM "https://github.com/weliem/blessed-android/blob/master/blessed/src/main/java/com/welie/blessed/BluetoothCentralManager.java"
    click BP "https://github.com/weliem/blessed-android/blob/master/blessed/src/main/java/com/welie/blessed/BluetoothPeripheral.java"
    click BPM "https://github.com/weliem/blessed-android/blob/master/blessed/src/main/java/com/welie/blessed/BluetoothPeripheralManager.java"
    click BC "https://github.com/weliem/blessed-android/blob/master/blessed/src/main/java/com/welie/blessed/BluetoothCentral.java"
    click BBytes "https://github.com/weliem/blessed-android/blob/master/blessed/src/main/java/com/welie/blessed/BluetoothBytesParser.java"
    click Main "https://github.com/weliem/blessed-android/blob/master/app/src/main/java/com/welie/blessedexample/MainActivity.java"
    click ED "https://github.com/weliem/blessed-android/blob/master/blessed/build.gradle"
    click CI "https://github.com/weliem/blessed-android/blob/master/.github/workflows/gradle.yml"
    click DOC "https://github.com/weliem/blessed-android/tree/master/docs"

    classDef system fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef library fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef app fill:#f94144,stroke:#333,stroke-width:2px;
    classDef external fill:#577590,stroke:#333,stroke-width:2px;
```
