# arduino-libraries/arduinoble architecture

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

- Interactive diagram: https://gitdiagram.com/arduino-libraries/arduinoble
- Repository: https://github.com/arduino-libraries/arduinoble

## Overview

##### Project type and purpose
- ArduinoBLE is an open-source Arduino library that enables Bluetooth Low Energy (BLE) connectivity on various Arduino boards (e.g., MKR WiFi, Nano 33 BLE, UNO R4 WiFi).
- It provides both Peripheral (local) and Central (remote) BLE roles, exposing a high-level API to users’ Arduino sketches.

##### File structure
- Top-level:
- src/ — core library code, subdivided into:
– src/ArduinoBLE.h — main API header.
– src/*.cpp & .h — high-level classes: BLEDevice, BLEService, BLECharacteristic, BLEDescriptor, typed/string characteristics.
– src/local/ — classes for Peripheral mode (BLELocalDevice, BLELocalService/Characteristic/Descriptor).
– src/remote/ — classes for Central mode (BLERemoteDevice, BLERemoteService/Characteristic/Descriptor).
– src/utility/ — BLE protocol stack and transport layers (GAP, GATT, ATT, L2CAP, HCI, UUID, transports, bit utilities, security).
- examples/ — sample sketches demonstrating Peripheral and Central use cases.
- docs/ — markdown documentation and API reference.
- extras/test/ — unit-test harness with fake devices and transport stubs.
- CI configs (.github/workflows) and project metadata (library.properties, README.md, LICENSE).

##### README for additional insights
- Core functionality: creating/applying BLE services, characteristics, advertising, scanning.
- Supported hardware dependencies: NINA or ESP32-S3 firmware on specific Arduino boards.

a. Main components
- Application Layer: Arduino sketches (examples) invoking the library.
- API Layer: ArduinoBLE.h + user-facing classes.
- Role Modules:
– Peripheral (src/local/*)
– Central (src/remote/*)
- Protocol Stack (src/utility/*):
– GAP, GATT, ATT, L2CAP, Security (keyDistribution, btct), UUID, linked lists.
- Transport Layer: HCI transports (UART, Cordio, Silabs, Virtual)
- Hardware/Firmware: NINA-W102 or ESP32-S3 module running required firmware.
- Test Harness (extras/test): fake devices and transports for unit testing.

b. Relationships and interactions
- Application → API Layer: calls into BLEDevice, BLEService, etc.
- API Layer → Role Modules: instantiates local or remote objects depending on mode.
- Role Modules ↔ Protocol Stack: use GAP/GATT to build and parse BLE PDUs.
- Protocol Stack → Transport Layer: sends/receives raw HCI commands/events.
- Transport Layer → Hardware/Firmware: physical serial or USB interface to radio module.
- CI workflows and Test Harness → Library Code: compile and run unit tests against fake transports.

c. Architectural patterns and design principles
- Layered architecture: clear separation of API, role logic, protocol, transport, hardware.
- Strategy pattern for transports: interchangeable HCI transport implementations.
- Adapter/facade: ArduinoBLE.h exposes a simplified interface over complex stack.
- Dependency inversion in tests: fake transports/ devices in extras/test to isolate logic.

d. Key technologies, frameworks, libraries
- C++ classes and templates for characteristics (typed vs string).
- HCI transport drivers (UART, Cordio, Silabs, Virtual).
- Arduino build system and CMake for examples/tests.

##### Detail
- Every src/utility submodule (GAP, GATT, ATT, L2CAP, security) is represented or collapsed under “Protocol Stack.”
- Both Peripheral and Central paths distinctly.
- Conditional dependency on external firmware modules.
- Examples/docs/CI as external consumers/maintainers of the library.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    subgraph "Application Layer"
        Examples["Arduino Sketches"]:::app
    end

    %% API Layer
    subgraph "API Layer"
        ArduinoBLE["ArduinoBLE.h"]:::api
        BLEDevice["BLEDevice"]:::api
        BLEService["BLEService"]:::api
        BLECharacteristic["BLECharacteristic"]:::api
        BLEDescriptor["BLEDescriptor"]:::api
        BLEStringCharacteristic["BLEStringCharacteristic"]:::api
        BLETypedCharacteristics["BLETypedCharacteristics"]:::api
    end

    %% Role Modules
    subgraph "Role Modules"
        subgraph "Peripheral (Local)"
            BLELocalDevice["BLELocalDevice"]:::role
            BLELocalService["BLELocalService"]:::role
            BLELocalCharacteristic["BLELocalCharacteristic"]:::role
            BLELocalDescriptor["BLELocalDescriptor"]:::role
            BLELocalAttribute["BLELocalAttribute"]:::role
        end
        subgraph "Central (Remote)"
            BLERemoteDevice["BLERemoteDevice"]:::role
            BLERemoteService["BLERemoteService"]:::role
            BLERemoteCharacteristic["BLERemoteCharacteristic"]:::role
            BLERemoteDescriptor["BLERemoteDescriptor"]:::role
            BLERemoteAttribute["BLERemoteAttribute"]:::role
        end
    end

    %% Protocol Stack
    subgraph "Protocol Stack"
        GAP["GAP"]:::protocol
        GATT["GATT"]:::protocol
        ATT["ATT"]:::protocol
        L2CAPSignaling["L2CAPSignaling"]:::protocol
        btct["btct"]:::protocol
        keyDistribution["keyDistribution"]:::protocol
        BLEUuid["BLEUuid"]:::protocol
        BLELinkedList["BLELinkedList"]:::protocol
        bitDescriptions["bitDescriptions"]:::protocol
    end

    %% Transport Layer
    subgraph "Transport Layer"
        HCITransport["HCITransport"]:::transport
        HCI["HCI"]:::transport
        HCIUartTransport["HCIUartTransport"]:::transport
        HCICordioTransport["HCICordioTransport"]:::transport
        HCISilabsTransport["HCISilabsTransport"]:::transport
        HCIVirtualTransport["HCIVirtualTransport"]:::transport
        HCIVirtualTransportAT["HCIVirtualTransportAT"]:::transport
        CordioHCICustomDriver["CordioHCICustomDriver"]:::transport
    end

    %% Hardware/Firmware
    subgraph "Hardware / Firmware"
        HardwareModule["Radio Module Firmware"]:::hardware
    end

    %% Test Harness
    subgraph "Test Harness & CI"
        TestHarness["Test Harness"]:::test
    end

    %% Connections
    Examples -->|"includes API"| ArduinoBLE
    ArduinoBLE -->|"uses"| BLEDevice
    BLEDevice -->|"instantiates"| BLELocalDevice
    BLEDevice -->|"instantiates"| BLERemoteDevice
    BLELocalDevice -->|"calls GAP/GATT"| GAP
    BLERemoteDevice -->|"calls GAP/GATT"| GATT
    GAP -->|"requests"| HCITransport
    GATT -->|"requests"| HCITransport
    ATT -->|"requests"| HCITransport
    L2CAPSignaling -->|"requests"| HCITransport
    btct -->|"security ops"| HCITransport
    keyDistribution -->|"key exchange"| HCITransport
    BLEUuid -->|"UUID ops"| HCITransport
    BLELinkedList -->|"list ops"| HCITransport
    bitDescriptions -->|"bit ops"| HCITransport
    HCITransport -->|"serializes packets"| HardwareModule
    HCI -->|"manages HCI"| HardwareModule
    HCIUartTransport -->|"UART link"| HardwareModule
    HCICordioTransport -->|"Cordio link"| HardwareModule
    HCISilabsTransport -->|"Silabs link"| HardwareModule
    HCIVirtualTransport -->|"Virtual link"| HardwareModule
    HCIVirtualTransportAT -->|"Virtual AT link"| HardwareModule
    CordioHCICustomDriver -->|"Driver"| HardwareModule

    TestHarness -.-> ArduinoBLE
    TestHarness -.-> BLELocalDevice
    TestHarness -.-> BLERemoteDevice
    TestHarness -.-> GAP
    TestHarness -.-> HCITransport

    %% Click Events
    click Examples "https://github.com/arduino-libraries/arduinoble/tree/master/examples/"
    click ArduinoBLE "https://github.com/arduino-libraries/arduinoble/blob/master/src/ArduinoBLE.h"
    click BLEDevice "https://github.com/arduino-libraries/arduinoble/blob/master/src/BLEDevice.h"
    click BLEService "https://github.com/arduino-libraries/arduinoble/blob/master/src/BLEService.h"
    click BLECharacteristic "https://github.com/arduino-libraries/arduinoble/blob/master/src/BLECharacteristic.h"
    click BLEDescriptor "https://github.com/arduino-libraries/arduinoble/blob/master/src/BLEDescriptor.h"
    click BLEStringCharacteristic "https://github.com/arduino-libraries/arduinoble/blob/master/src/BLEStringCharacteristic.h"
    click BLETypedCharacteristics "https://github.com/arduino-libraries/arduinoble/blob/master/src/BLETypedCharacteristics.h"
    click BLELocalDevice "https://github.com/arduino-libraries/arduinoble/blob/master/src/local/BLELocalDevice.h"
    click BLELocalService "https://github.com/arduino-libraries/arduinoble/blob/master/src/local/BLELocalService.h"
    click BLELocalCharacteristic "https://github.com/arduino-libraries/arduinoble/blob/master/src/local/BLELocalCharacteristic.h"
    click BLELocalDescriptor "https://github.com/arduino-libraries/arduinoble/blob/master/src/local/BLELocalDescriptor.h"
    click BLELocalAttribute "https://github.com/arduino-libraries/arduinoble/blob/master/src/local/BLELocalAttribute.h"
    click BLERemoteDevice "https://github.com/arduino-libraries/arduinoble/blob/master/src/remote/BLERemoteDevice.h"
    click BLERemoteService "https://github.com/arduino-libraries/arduinoble/blob/master/src/remote/BLERemoteService.h"
    click BLERemoteCharacteristic "https://github.com/arduino-libraries/arduinoble/blob/master/src/remote/BLERemoteCharacteristic.h"
    click BLERemoteDescriptor "https://github.com/arduino-libraries/arduinoble/blob/master/src/remote/BLERemoteDescriptor.h"
    click BLERemoteAttribute "https://github.com/arduino-libraries/arduinoble/blob/master/src/remote/BLERemoteAttribute.h"
    click GAP "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/GAP.h"
    click GATT "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/GATT.h"
    click ATT "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/ATT.h"
    click L2CAPSignaling "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/L2CAPSignaling.h"
    click btct "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/btct.h"
    click keyDistribution "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/keyDistribution.h"
    click BLEUuid "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/BLEUuid.h"
    click BLELinkedList "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/BLELinkedList.h"
    click bitDescriptions "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/bitDescriptions.h"
    click HCITransport "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/HCITransport.h"
    click HCI "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/HCI.h"
    click HCIUartTransport "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/HCIUartTransport.h"
    click HCICordioTransport "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/HCICordioTransport.h"
    click HCISilabsTransport "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/HCISilabsTransport.h"
    click HCIVirtualTransport "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/HCIVirtualTransport.h"
    click HCIVirtualTransportAT "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/HCIVirtualTransportAT.h"
    click CordioHCICustomDriver "https://github.com/arduino-libraries/arduinoble/blob/master/src/utility/CordioHCICustomDriver.h"
    click TestHarness "https://github.com/arduino-libraries/arduinoble/tree/master/extras/test/"

    %% Styles
    classDef app fill:#FFF0B3,stroke:#333
    classDef api fill:#D0E8FF,stroke:#333
    classDef role fill:#B0D4FF,stroke:#333
    classDef protocol fill:#DFFFD0,stroke:#333
    classDef transport fill:#FFE8B0,stroke:#333
    classDef hardware fill:#D3D3D3,stroke:#333
    classDef test fill:#FFF8B0,stroke:#333
```
