# deviceplug/btleplug architecture

> Architecture diagram of the GitHub repository deviceplug/btleplug, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deviceplug/btleplug
- Repository: https://github.com/deviceplug/btleplug

## Overview

btleplug is an async Rust Bluetooth LE central library. Its main workflow obtains platform adapters, scans for peripherals, connects, discovers GATT services and characteristics, then reads, writes, or subscribes to values. The graph separates the shared API from the Linux, Apple, Android, and Windows backends. README capabilities include descriptor access, notifications, adapter state, and platform-specific address/connection features; backend details beyond the excerpts are represented at subsystem level where needed. Some internal links rely on the SOURCE INDEX rather than inspected implementation excerpts.

Main entry points: [`src/platform.rs`](https://github.com/deviceplug/btleplug/blob/master/src/platform.rs) (Platform exports), [`src/droidplug/jni/objects.rs`](https://github.com/deviceplug/btleplug/blob/master/src/droidplug/jni/objects.rs) (JNI object bridge), [`src/api/mod.rs`](https://github.com/deviceplug/btleplug/blob/master/src/api/mod.rs) (Peripheral API), [`src/bluez/adapter.rs`](https://github.com/deviceplug/btleplug/blob/master/src/bluez/adapter.rs) (BlueZ adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared API"]
  node_manager_api["Manager API<br/>[mod.rs]"]
  node_central_api["Central API<br/>[mod.rs]"]
  node_peripheral_api["Peripheral API<br/>[mod.rs]"]
  node_ble_types["BLE types<br/>[bdaddr.rs]"]
  node_advertisement["Advertisement parser<br/>[advertisement.rs]"]
  node_platform["Platform exports<br/>[platform.rs]"]
  node_adapter_state[("Adapter manager state<br/>[adapter_manager.rs]")]
end

subgraph group_linux["Linux BlueZ"]
  node_bluez_manager["BlueZ manager<br/>[manager.rs]"]
  node_bluez_adapter["BlueZ adapter<br/>[adapter.rs]"]
  node_bluez_peripheral["BlueZ peripheral<br/>[peripheral.rs]"]
end

subgraph group_apple["Apple CoreBluetooth"]
  node_core_manager["CoreBluetooth manager<br/>[manager.rs]"]
  node_core_adapter["CoreBluetooth adapter<br/>[adapter.rs]"]
  node_core_peripheral["CoreBluetooth peripheral<br/>[peripheral.rs]"]
end

subgraph group_android["Android JNI"]
  node_android_manager["Android manager<br/>[manager.rs]"]
  node_android_adapter["Android adapter<br/>[adapter.rs]"]
  node_android_peripheral["Android peripheral<br/>[peripheral.rs]"]
  node_jni_objects["JNI object bridge<br/>[objects.rs]"]
  node_jni_utils["JNI async utilities<br/>[future.rs]"]
  node_java_bridge["Android Java BLE<br/>[Peripheral.java]"]
end

subgraph group_windows["Windows WinRT"]
  node_win_manager["WinRT manager<br/>[manager.rs]"]
  node_win_adapter["WinRT adapter<br/>[adapter.rs]"]
  node_win_peripheral["WinRT peripheral<br/>[peripheral.rs]"]
  node_win_gatt["WinRT GATT objects<br/>[characteristic.rs]"]
end

node_application(("Rust application"))

node_application -->|"creates"| node_manager_api
node_application -->|"scans"| node_central_api
node_application -->|"connects and uses"| node_peripheral_api
node_manager_api -->|"resolves implementation"| node_platform
node_platform -->|"exports on Linux"| node_bluez_manager
node_platform -->|"exports on Apple"| node_core_manager
node_platform -->|"exports on Android"| node_android_manager
node_platform -->|"exports on Windows"| node_win_manager
node_bluez_manager -->|"creates adapters"| node_bluez_adapter
node_bluez_adapter -->|"uses peripherals"| node_bluez_peripheral
node_core_manager -->|"creates adapter"| node_core_adapter
node_android_manager -->|"returns adapter"| node_android_adapter
node_android_adapter -->|"uses JNI objects"| node_jni_objects
node_android_peripheral -->|"uses JNI objects"| node_jni_objects
node_jni_objects -->|"uses futures and streams"| node_jni_utils
node_jni_objects -.->|"calls Java BLE methods"| node_java_bridge
node_win_manager -->|"creates adapters"| node_win_adapter
node_win_adapter -->|"uses peripherals"| node_win_peripheral
node_win_peripheral -->|"uses GATT objects"| node_win_gatt
node_bluez_peripheral -->|"implements"| node_peripheral_api
node_win_peripheral -->|"implements"| node_peripheral_api
node_ble_types -->|"defines shared types"| node_peripheral_api
node_advertisement -.->|"parses advertising data"| node_ble_types
node_bluez_adapter -.->|"uses shared state"| node_adapter_state

click node_manager_api "https://github.com/deviceplug/btleplug/blob/master/src/api/mod.rs"
click node_central_api "https://github.com/deviceplug/btleplug/blob/master/src/api/mod.rs"
click node_peripheral_api "https://github.com/deviceplug/btleplug/blob/master/src/api/mod.rs"
click node_ble_types "https://github.com/deviceplug/btleplug/blob/master/src/api/bdaddr.rs"
click node_advertisement "https://github.com/deviceplug/btleplug/blob/master/src/advertisement.rs"
click node_platform "https://github.com/deviceplug/btleplug/blob/master/src/platform.rs"
click node_bluez_manager "https://github.com/deviceplug/btleplug/blob/master/src/bluez/manager.rs"
click node_bluez_adapter "https://github.com/deviceplug/btleplug/blob/master/src/bluez/adapter.rs"
click node_bluez_peripheral "https://github.com/deviceplug/btleplug/blob/master/src/bluez/peripheral.rs"
click node_core_manager "https://github.com/deviceplug/btleplug/blob/master/src/corebluetooth/manager.rs"
click node_core_adapter "https://github.com/deviceplug/btleplug/blob/master/src/corebluetooth/adapter.rs"
click node_core_peripheral "https://github.com/deviceplug/btleplug/blob/master/src/corebluetooth/peripheral.rs"
click node_android_manager "https://github.com/deviceplug/btleplug/blob/master/src/droidplug/manager.rs"
click node_android_adapter "https://github.com/deviceplug/btleplug/blob/master/src/droidplug/adapter.rs"
click node_android_peripheral "https://github.com/deviceplug/btleplug/blob/master/src/droidplug/peripheral.rs"
click node_jni_objects "https://github.com/deviceplug/btleplug/blob/master/src/droidplug/jni/objects.rs"
click node_jni_utils "https://github.com/deviceplug/btleplug/blob/master/src/droidplug/jni_utils/future.rs"
click node_java_bridge "https://github.com/deviceplug/btleplug/blob/master/src/droidplug/java/src/main/java/com/nonpolynomial/btleplug/android/impl/Peripheral.java"
click node_win_manager "https://github.com/deviceplug/btleplug/blob/master/src/winrtble/manager.rs"
click node_win_adapter "https://github.com/deviceplug/btleplug/blob/master/src/winrtble/adapter.rs"
click node_win_peripheral "https://github.com/deviceplug/btleplug/blob/master/src/winrtble/peripheral.rs"
click node_win_gatt "https://github.com/deviceplug/btleplug/blob/master/src/winrtble/ble/characteristic.rs"
click node_adapter_state "https://github.com/deviceplug/btleplug/blob/master/src/common/adapter_manager.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manager_api,node_central_api,node_peripheral_api,node_ble_types,node_advertisement,node_platform,node_adapter_state toneBlue
class node_bluez_manager,node_bluez_adapter,node_bluez_peripheral toneAmber
class node_core_manager,node_core_adapter,node_core_peripheral toneMint
class node_android_manager,node_android_adapter,node_android_peripheral,node_jni_objects,node_jni_utils,node_java_bridge toneRose
class node_win_manager,node_win_adapter,node_win_peripheral,node_win_gatt,node_application toneIndigo
```

## Components

### Shared API

- [Manager API](https://github.com/deviceplug/btleplug/blob/master/src/api/mod.rs): `src/api/mod.rs`
- [Central API](https://github.com/deviceplug/btleplug/blob/master/src/api/mod.rs): `src/api/mod.rs`
- [Peripheral API](https://github.com/deviceplug/btleplug/blob/master/src/api/mod.rs): `src/api/mod.rs`
- [BLE types](https://github.com/deviceplug/btleplug/blob/master/src/api/bdaddr.rs): `src/api/bdaddr.rs`
- [Advertisement parser](https://github.com/deviceplug/btleplug/blob/master/src/advertisement.rs): `src/advertisement.rs`
- [Platform exports](https://github.com/deviceplug/btleplug/blob/master/src/platform.rs): `src/platform.rs`
- [Adapter manager state](https://github.com/deviceplug/btleplug/blob/master/src/common/adapter_manager.rs): `src/common/adapter_manager.rs`

### Linux BlueZ

- [BlueZ manager](https://github.com/deviceplug/btleplug/blob/master/src/bluez/manager.rs): `src/bluez/manager.rs`
- [BlueZ adapter](https://github.com/deviceplug/btleplug/blob/master/src/bluez/adapter.rs): `src/bluez/adapter.rs`
- [BlueZ peripheral](https://github.com/deviceplug/btleplug/blob/master/src/bluez/peripheral.rs): `src/bluez/peripheral.rs`

### Apple CoreBluetooth

- [CoreBluetooth manager](https://github.com/deviceplug/btleplug/blob/master/src/corebluetooth/manager.rs): `src/corebluetooth/manager.rs`
- [CoreBluetooth adapter](https://github.com/deviceplug/btleplug/blob/master/src/corebluetooth/adapter.rs): `src/corebluetooth/adapter.rs`
- [CoreBluetooth peripheral](https://github.com/deviceplug/btleplug/blob/master/src/corebluetooth/peripheral.rs): `src/corebluetooth/peripheral.rs`

### Android JNI

- [Android manager](https://github.com/deviceplug/btleplug/blob/master/src/droidplug/manager.rs): `src/droidplug/manager.rs`
- [Android adapter](https://github.com/deviceplug/btleplug/blob/master/src/droidplug/adapter.rs): `src/droidplug/adapter.rs`
- [Android peripheral](https://github.com/deviceplug/btleplug/blob/master/src/droidplug/peripheral.rs): `src/droidplug/peripheral.rs`
- [JNI object bridge](https://github.com/deviceplug/btleplug/blob/master/src/droidplug/jni/objects.rs): `src/droidplug/jni/objects.rs`
- [JNI async utilities](https://github.com/deviceplug/btleplug/blob/master/src/droidplug/jni_utils/future.rs): `src/droidplug/jni_utils/future.rs`
- [Android Java BLE](https://github.com/deviceplug/btleplug/blob/master/src/droidplug/java/src/main/java/com/nonpolynomial/btleplug/android/impl/Peripheral.java): `src/droidplug/java/src/main/java/com/nonpolynomial/btleplug/android/impl/Peripheral.java`

### Windows WinRT

- [WinRT manager](https://github.com/deviceplug/btleplug/blob/master/src/winrtble/manager.rs): `src/winrtble/manager.rs`
- [WinRT adapter](https://github.com/deviceplug/btleplug/blob/master/src/winrtble/adapter.rs): `src/winrtble/adapter.rs`
- [WinRT peripheral](https://github.com/deviceplug/btleplug/blob/master/src/winrtble/peripheral.rs): `src/winrtble/peripheral.rs`
- [WinRT GATT objects](https://github.com/deviceplug/btleplug/blob/master/src/winrtble/ble/characteristic.rs): `src/winrtble/ble/characteristic.rs`

### Other components

- **Rust application**

## Connections

- Rust application → Manager API: creates
- Rust application → Central API: scans
- Rust application → Peripheral API: connects and uses
- Manager API → Platform exports: resolves implementation (evidence: `src/platform.rs`)
- Platform exports → BlueZ manager: exports on Linux (evidence: `src/platform.rs`)
- Platform exports → CoreBluetooth manager: exports on Apple (evidence: `src/platform.rs`)
- Platform exports → Android manager: exports on Android (evidence: `src/platform.rs`)
- Platform exports → WinRT manager: exports on Windows (evidence: `src/platform.rs`)
- BlueZ manager → BlueZ adapter: creates adapters (evidence: `src/bluez/manager.rs`)
- BlueZ adapter → BlueZ peripheral: uses peripherals (evidence: `src/bluez/adapter.rs`)
- CoreBluetooth manager → CoreBluetooth adapter: creates adapter (evidence: `src/corebluetooth/manager.rs`)
- Android manager → Android adapter: returns adapter (evidence: `src/droidplug/manager.rs`)
- Android adapter → JNI object bridge: uses JNI objects (evidence: `src/droidplug/adapter.rs`)
- Android peripheral → JNI object bridge: uses JNI objects (evidence: `src/droidplug/peripheral.rs`)
- JNI object bridge → JNI async utilities: uses futures and streams (evidence: `src/droidplug/jni/objects.rs`)
- JNI object bridge → Android Java BLE: calls Java BLE methods
- WinRT manager → WinRT adapter: creates adapters (evidence: `src/winrtble/manager.rs`)
- WinRT adapter → WinRT peripheral: uses peripherals (evidence: `src/winrtble/adapter.rs`)
- WinRT peripheral → WinRT GATT objects: uses GATT objects (evidence: `src/winrtble/peripheral.rs`)
- BlueZ peripheral → Peripheral API: implements (evidence: `src/bluez/peripheral.rs`)
- WinRT peripheral → Peripheral API: implements (evidence: `src/winrtble/peripheral.rs`)
- BLE types → Peripheral API: defines shared types (evidence: `src/api/mod.rs`)
- Advertisement parser → BLE types: parses advertising data
- BlueZ adapter → Adapter manager state: uses shared state
