# bluekitchen/btstack architecture

> Architecture diagram of the GitHub repository bluekitchen/btstack, 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/bluekitchen/btstack
- Repository: https://github.com/bluekitchen/btstack

## Overview

BTstack is an embedded-capable Bluetooth protocol stack, with platform ports that bind a controller transport and run loop to the stack; larger-system deployments also expose a server and language bindings. The principal workflow is an application using Bluetooth services and profiles, through protocol handling and HCI, to a Bluetooth controller. The README documents broad protocol and profile coverage; available source references give more concrete evidence for the POSIX port’s HCI, transport, run-loop, and persistence setup. Unsampled subsystems are represented at their documented level rather than with inferred call chains.

Main entry points: [`port/linux/main.c`](https://github.com/bluekitchen/btstack/blob/master/port/linux/main.c) (POSIX port), [`src/hci.h`](https://github.com/bluekitchen/btstack/blob/master/src/hci.h) (HCI management), [`port/msp432p401lp-cc256x/main.c`](https://github.com/bluekitchen/btstack/blob/master/port/msp432p401lp-cc256x/main.c) (Embedded ports), [`src/hci_transport.h`](https://github.com/bluekitchen/btstack/blob/master/src/hci_transport.h) (HCI transport API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Platform Integration"]
  node_posixport["POSIX port<br/>[main.c]"]
  node_embeddedport["Embedded ports<br/>[main.c]"]
  node_server["BTstack server"]
  node_javabinding["Java binding<br/>[GATTService.java]"]
end

subgraph group_core["Stack Core"]
  node_hci["HCI management<br/>[hci.h]"]
  node_transportapi["HCI transport API<br/>[hci_transport.h]"]
  node_h4transport["H4 transport<br/>[hci_transport_h4.h]"]
  node_runloop["Run loop<br/>[btstack_run_loop.h]"]
  node_memory["Memory pools<br/>[btstack_memory.h]"]
end

subgraph group_protocols["Protocols and Profiles"]
  node_l2cap["L2CAP and ATT<br/>[hci.h]"]
  node_classicprofiles["Classic profiles<br/>[avrcp_controller.c]"]
  node_gattclient["GATT client<br/>[gatt_client.c]"]
  node_mesh["Mesh services"]
end

subgraph group_services["GATT Services"]
  node_gattservices["GATT services"]
end

subgraph group_persistence["State and Diagnostics"]
  node_tlv["TLV storage<br/>[le_device_db_tlv.h]"]
  node_linkkeys["Link-key storage"]
  node_logging["HCI diagnostics<br/>[hci_dump.h]"]
end

node_application(("Bluetooth application"))
node_controller{{"Bluetooth controller"}}

node_application -.->|"uses port"| node_posixport
node_application -.->|"uses port"| node_embeddedport
node_posixport -->|"configures"| node_hci
node_posixport -->|"selects transport"| node_transportapi
node_posixport -->|"initializes"| node_runloop
node_embeddedport -->|"configures"| node_hci
node_embeddedport -->|"selects transport"| node_transportapi
node_hci -.->|"exchanges HCI packets"| node_controller
node_transportapi -->|"specializes"| node_h4transport
node_hci -.->|"coordinates protocols"| node_l2cap
node_application -.->|"uses profiles"| node_classicprofiles
node_application -.->|"uses client"| node_gattclient
node_application -.->|"uses services"| node_gattservices
node_application -.->|"uses mesh"| node_mesh
node_posixport -->|"configures storage"| node_tlv
node_posixport -->|"configures storage"| node_linkkeys
node_posixport -->|"configures dump"| node_logging
node_server -.->|"serves clients"| node_application
node_application -.->|"accesses via binding"| node_javabinding

click node_posixport "https://github.com/bluekitchen/btstack/blob/master/port/linux/main.c"
click node_embeddedport "https://github.com/bluekitchen/btstack/blob/master/port/msp432p401lp-cc256x/main.c"
click node_server "https://github.com/bluekitchen/btstack/blob/master/platform/daemon/src/rfcomm_service_db_memory.c"
click node_javabinding "https://github.com/bluekitchen/btstack/blob/master/platform/daemon/binding/java/src/com/bluekitchen/btstack/GATTService.java"
click node_hci "https://github.com/bluekitchen/btstack/blob/master/src/hci.h"
click node_transportapi "https://github.com/bluekitchen/btstack/blob/master/src/hci_transport.h"
click node_h4transport "https://github.com/bluekitchen/btstack/blob/master/src/hci_transport_h4.h"
click node_runloop "https://github.com/bluekitchen/btstack/blob/master/src/btstack_run_loop.h"
click node_memory "https://github.com/bluekitchen/btstack/blob/master/src/btstack_memory.h"
click node_l2cap "https://github.com/bluekitchen/btstack/blob/master/src/hci.h"
click node_classicprofiles "https://github.com/bluekitchen/btstack/blob/master/src/classic/avrcp_controller.c"
click node_gattclient "https://github.com/bluekitchen/btstack/blob/master/src/ble/gatt_client.c"
click node_mesh "https://github.com/bluekitchen/btstack/blob/master/src/mesh/gatt-service/mesh_provisioning_service_server.c"
click node_gattservices "https://github.com/bluekitchen/btstack/blob/master/src/ble/gatt-service/object_transfer_service_server.c"
click node_tlv "https://github.com/bluekitchen/btstack/blob/master/src/ble/le_device_db_tlv.h"
click node_linkkeys "https://github.com/bluekitchen/btstack/blob/master/src/classic/btstack_link_key_db_tlv.h"
click node_logging "https://github.com/bluekitchen/btstack/blob/master/src/hci_dump.h"

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_posixport,node_embeddedport,node_server,node_javabinding toneBlue
class node_hci,node_transportapi,node_h4transport,node_runloop,node_memory toneAmber
class node_l2cap,node_classicprofiles,node_gattclient,node_mesh toneMint
class node_gattservices toneRose
class node_tlv,node_linkkeys,node_logging,node_application,node_controller toneIndigo
```

## Components

### Platform Integration

- [POSIX port](https://github.com/bluekitchen/btstack/blob/master/port/linux/main.c): `port/linux/main.c`
- [Embedded ports](https://github.com/bluekitchen/btstack/blob/master/port/msp432p401lp-cc256x/main.c): `port/msp432p401lp-cc256x/main.c`
- [BTstack server](https://github.com/bluekitchen/btstack/blob/master/platform/daemon/src/rfcomm_service_db_memory.c): `platform/daemon/src/rfcomm_service_db_memory.c`
- [Java binding](https://github.com/bluekitchen/btstack/blob/master/platform/daemon/binding/java/src/com/bluekitchen/btstack/GATTService.java): `platform/daemon/binding/java/src/com/bluekitchen/btstack/GATTService.java`

### Stack Core

- [HCI management](https://github.com/bluekitchen/btstack/blob/master/src/hci.h): `src/hci.h`
- [HCI transport API](https://github.com/bluekitchen/btstack/blob/master/src/hci_transport.h): `src/hci_transport.h`
- [H4 transport](https://github.com/bluekitchen/btstack/blob/master/src/hci_transport_h4.h): `src/hci_transport_h4.h`
- [Run loop](https://github.com/bluekitchen/btstack/blob/master/src/btstack_run_loop.h): `src/btstack_run_loop.h`
- [Memory pools](https://github.com/bluekitchen/btstack/blob/master/src/btstack_memory.h): `src/btstack_memory.h`

### Protocols and Profiles

- [L2CAP and ATT](https://github.com/bluekitchen/btstack/blob/master/src/hci.h): `src/hci.h`
- [Classic profiles](https://github.com/bluekitchen/btstack/blob/master/src/classic/avrcp_controller.c): `src/classic/avrcp_controller.c`
- [GATT client](https://github.com/bluekitchen/btstack/blob/master/src/ble/gatt_client.c): `src/ble/gatt_client.c`
- [Mesh services](https://github.com/bluekitchen/btstack/blob/master/src/mesh/gatt-service/mesh_provisioning_service_server.c): `src/mesh/gatt-service/mesh_provisioning_service_server.c`

### GATT Services

- [GATT services](https://github.com/bluekitchen/btstack/blob/master/src/ble/gatt-service/object_transfer_service_server.c): `src/ble/gatt-service/object_transfer_service_server.c`

### State and Diagnostics

- [TLV storage](https://github.com/bluekitchen/btstack/blob/master/src/ble/le_device_db_tlv.h): `src/ble/le_device_db_tlv.h`
- [Link-key storage](https://github.com/bluekitchen/btstack/blob/master/src/classic/btstack_link_key_db_tlv.h): `src/classic/btstack_link_key_db_tlv.h`
- [HCI diagnostics](https://github.com/bluekitchen/btstack/blob/master/src/hci_dump.h): `src/hci_dump.h`

### Other components

- **Bluetooth application**
- **Bluetooth controller**

## Connections

- Bluetooth application → POSIX port: uses port
- Bluetooth application → Embedded ports: uses port
- POSIX port → HCI management: configures (evidence: `port/linux/main.c`)
- POSIX port → HCI transport API: selects transport (evidence: `port/linux/main.c`)
- POSIX port → Run loop: initializes (evidence: `port/linux/main.c`)
- Embedded ports → HCI management: configures (evidence: `port/msp432p401lp-cc256x/main.c`)
- Embedded ports → HCI transport API: selects transport (evidence: `port/msp432p401lp-cc256x/main.c`)
- HCI management → Bluetooth controller: exchanges HCI packets
- HCI transport API → H4 transport: specializes (evidence: `src/hci_transport_h4.h`)
- HCI management → L2CAP and ATT: coordinates protocols (evidence: `src/hci.h`)
- Bluetooth application → Classic profiles: uses profiles
- Bluetooth application → GATT client: uses client
- Bluetooth application → GATT services: uses services
- Bluetooth application → Mesh services: uses mesh
- POSIX port → TLV storage: configures storage (evidence: `port/linux/main.c`)
- POSIX port → Link-key storage: configures storage (evidence: `port/linux/main.c`)
- POSIX port → HCI diagnostics: configures dump (evidence: `port/linux/main.c`)
- BTstack server → Bluetooth application: serves clients
- Bluetooth application → Java binding: accesses via binding
