# renjy886/ble-stack architecture

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

- Interactive diagram: https://gitdiagram.com/renjy886/ble-stack
- Repository: https://github.com/renjy886/ble-stack

## Overview

1. Repository shape  
This is a multi-image embedded Bluetooth stack distribution, not a single application. The code is organized into separate deliverables for:
- `controller` — Bluetooth LE Link Layer / controller
- `ble-host` — GATT/ATT, SMP, HCI, L2CAP, device/security manager
- `ble-profiles` — Classic BLE application profiles and services
- `ble-mesh` / `ble-mesh-profile` / `ble-mesh-apps` — Bluetooth Mesh stack, models, and sample apps
- `ble-apps` — BLE sample applications built on host + profiles
- `platform` + `thirdparty` — board support, HALs, crypto, toolchain support, vendor SDKs
- `wsf` — common runtime/services used across the stack

2. Main architectural split: app layer, stack layer, platform layer  
The repository is layered so that sample applications sit above protocol stacks, and the stacks sit above platform abstraction code. Application code calls profile/mesh APIs; those APIs call into the host/mesh stack; the host/mesh stack exchanges HCI/transport events with the controller; the controller talks to the radio via the platform abstraction layer (`PAL`) on Nordic hardware.

3. BLE application deliverables (`ble-apps`)  
`ble-apps/build/*` contains complete firmware images for sample devices such as `tag`, `watch`, `hidapp`, `medc`, `meds`, `locator`, `uribeacon`, `fit`, `cycling`, `gluc`, `datc/dats`, `assettag`. Each sample has a small `main.c` and a corresponding `stack_*.c` that wires the app into the stack. The `ble-apps/sources/*` directories hold the application logic and device-specific GATT/profile behavior.

4. BLE host stack (`ble-host`)  
This subtree implements the host-side protocol machinery: ATT/EATT, L2CAP, SMP/security, device management, HCI handling, and command/event handlers. It is organized by protocol boundary:
- `stack/att` for ATT server/client and EATT
- `stack/l2c` for L2CAP and CoC
- `stack/smp` for pairing/security
- `stack/dm` for device management, scanning/connection, PHY, advertising, ISO/BIS/CIS logic
- `sources/hci` for host-side HCI command/event translation and vendor-specific handling
This layer is the primary boundary between application/profile code and the controller.

5. BLE controller (`controller`)  
This subtree contains the low-level link-layer implementation. It is split into:
- `bb` (baseband) for packet handling, advertising, connection scheduling, PDU filtering, periodic list, whitelist, sniffer, DTM
- `lctr` for link-layer control procedures, state machines, ISR/main loops, and role-specific behavior
- `ll` for LL initialization and runtime behavior across advertising, scanning, connection, privacy, encryption, ISO, PHY, PAST, PAwR/PC features
- `lhci` for controller-side HCI command/event plumbing
- `lmgr` for link-layer manager coordination
- `sch` for BLE scheduling
This is the layer that directly interfaces with radio timing and link events.

6. BLE profiles (`ble-profiles`)  
This module packages standard BLE GATT services and client/server profiles used by the sample apps. It is split into:
- `profiles/*` for profile implementations such as BAS, DIS, HRS, HTS, GLS, CPS, CSC, RSC, PLX, HID, WSS, WDX, URICFG, etc.
- `services/*` for the underlying GATT services
- `af/*` for application framework glue, including app state, UI, terminal, and database abstractions  
These profiles are the functional layer used by the sample apps on top of the host stack.

7. Mesh stack and mesh apps (`ble-mesh-profile`, `ble-mesh-model`, `ble-mesh-apps`)  
Mesh is split into three concerns:
- `ble-mesh-profile` provides the Mesh Protocol stack: bearer, provisioning, access, friend/LPN, proxy, security, network, transports, configuration API, and local config
- `ble-mesh-model` provides model implementations and APIs: Generic, Light, Scene, Scheduler, Time, Health, and vendor test models, with client/server separation
- `ble-mesh-apps` contains sample devices such as `light`, `switch`, and `provisioner`, plus shared bearer/proxy/app coordination code  
This separation mirrors Mesh architecture: transport/network/access layers below, models above, and provisioning/proxy as distinct control paths.

8. Common runtime (`wsf`)  
`wsf` is the shared embedded framework used by the protocol stack. It supplies OS abstractions, buffers, queues, timers, heap/NVM, trace/logging, and utility code. It has target-specific implementations for bare metal and Win32, which indicates the stack can be built both for embedded targets and host-side test/verification environments.

9. Platform abstraction (`platform`)  
The `platform/include` and `platform/targets/nordic` directories provide the hardware abstraction layer for buttons, LEDs, UART, SPI, timers, RTC, flash, radio, crypto, I2S, etc. This is where the protocol software is adapted to Nordic SoCs and boards. The build files and linker scripts under `platform/targets/nordic/build` define the actual board/MCU image layout.

10. External/vendor dependencies (`thirdparty`)  
The repo vendors Nordic BSP and nrfx, plus cryptographic and utility libraries such as `nrf_cc310`, `nrf_cc310_bl`, `nrf_oberon`, `uecc`, and `nano-pb`. These are not just build-time extras; they materially affect the architecture because they provide hardware drivers, crypto backends, startup code, linker support, USB support, and protocol-related helper libraries.

11. How data flows through the system  
The runtime path is typically:
application or profile event → host or mesh API → protocol stack state machine → HCI/transport/bearer interface → controller link-layer processing → radio/PAL driver → air interface, then back as interrupts/events in the reverse direction.  
For Mesh, the path is application/model → access layer → transport/network → bearer (adv/GATT) → controller/radio.  
For BLE profiles, the path is app → GATT service/profile → ATT/L2CAP/SMP → HCI → controller.

12. Important architectural boundaries  
The most important boundary in this repo is between the protocol logic and the hardware adaptation:
- protocol-side code lives in `ble-host`, `controller`, `ble-profiles`, `ble-mesh-*`
- hardware/timing/board code lives in `platform` and `thirdparty`
A second major boundary is the HCI split between host and controller. A third is the profile/model split: profiles implement standardized behavior, while the sample apps only bind profile instances, UI/terminal hooks, and board-specific configuration.

13. Build products and composition  
Each sample app under `ble-apps/build`, `ble-mesh-apps/build`, and `controller/build` is a composed firmware image. The top-level `main.c` in each build folder selects the app, stack configuration, and target board. The `sources.mk`/`makefile` fragments determine which subsets of the shared stacks are linked into a given image.

14. What to draw in an architecture diagram  
A correct diagram should show:
- multiple standalone firmware families, not one monolith
- a shared embedded runtime (`wsf`)
- a protocol split between host and controller connected by HCI
- Mesh as a parallel stack with provisioning/bearer/access/model layers
- sample applications on top of profile/model APIs
- Nordic-specific platform/driver code and third-party libraries at the bottom
- board/build configuration selecting which layers are assembled into each final image

Main entry points: [`ble-host/sources/stack`](https://github.com/renjy886/ble-stack/tree/master/ble-host/sources/stack) (BLE host), [`platform`](https://github.com/renjy886/ble-stack/tree/master/platform) (PAL), [`ble-profiles/sources/profiles`](https://github.com/renjy886/ble-stack/tree/master/ble-profiles/sources/profiles) (Profiles), [`controller/sources/ble/ll`](https://github.com/renjy886/ble-stack/tree/master/controller/sources/ble/ll) (Link layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Firmware images"]
  node_ble_apps_build["BLE builds<br/>firmware family"]
  node_ble_apps_sources["BLE apps<br/>sample apps"]
  node_ble_mesh_apps_build["Mesh builds<br/>firmware family"]
  node_ble_mesh_apps_sources["Mesh apps<br/>sample apps"]
end

subgraph group_stacks["Protocol stacks"]
  node_ble_mesh_profile_build["Mesh build<br/>stack config"]
  node_ble_mesh_profile_stack["Mesh stack<br/>mesh protocol"]
  node_ble_mesh_models["Mesh models<br/>model library"]
  node_ble_profiles_build["Profiles build<br/>stack config"]
  node_ble_profiles_af["App framework<br/>af layer"]
  node_ble_profiles_services["Services"]
  node_ble_profiles_profiles["Profiles<br/>profile library"]
  node_ble_host_stack["BLE host<br/>host stack"]
  node_ble_host_hci["Host HCI<br/>hci bridge"]
  node_controller_build["Controller builds<br/>firmware family"]
  node_controller_ll["Link layer<br/>ll control"]
  node_controller_bb["Baseband<br/>radio scheduling"]
  node_controller_lhci["Ctrl HCI<br/>hci bridge"]
  node_controller_sched["Scheduler<br/>timing core"]
end

subgraph group_runtime["Runtime"]
  node_wsf_runtime["WSF<br/>runtime"]
end

subgraph group_platform["Platform"]
  node_platform_pal["PAL<br/>hardware abstraction"]
  node_nordic_bsp["Nordic BSP<br/>vendor sdk"]
  node_crypto_libs["Crypto libs<br/>vendor crypto"]
end

node_ble_apps_build -->|"composes"| node_ble_apps_sources
node_ble_apps_sources -->|"uses"| node_ble_profiles_profiles
node_ble_apps_sources -->|"calls"| node_ble_host_stack
node_ble_apps_build -->|"links"| node_ble_profiles_build
node_ble_mesh_apps_build -->|"composes"| node_ble_mesh_apps_sources
node_ble_mesh_apps_sources -->|"uses"| node_ble_mesh_models
node_ble_mesh_apps_sources -->|"calls"| node_ble_mesh_profile_stack
node_ble_mesh_apps_build -->|"links"| node_ble_mesh_profile_build
node_ble_mesh_profile_stack -->|"exposes"| node_ble_mesh_models
node_ble_mesh_profile_stack -->|"depends on"| node_wsf_runtime
node_ble_profiles_profiles -->|"wraps"| node_ble_profiles_services
node_ble_profiles_profiles -->|"binds"| node_ble_profiles_af
node_ble_profiles_profiles -->|"uses"| node_ble_host_stack
node_ble_profiles_af -->|"depends on"| node_wsf_runtime
node_ble_host_stack -->|"bridges"| node_ble_host_hci
node_ble_host_stack -->|"depends on"| node_wsf_runtime
node_ble_host_hci -->|"connects"| node_controller_lhci
node_controller_build -->|"composes"| node_controller_ll
node_controller_ll -->|"uses"| node_controller_bb
node_controller_ll -->|"scheduled by"| node_controller_sched
node_controller_ll -->|"exports"| node_controller_lhci
node_controller_bb -->|"drives"| node_platform_pal
node_controller_sched -->|"times"| node_platform_pal
node_platform_pal -->|"implemented by"| node_nordic_bsp
node_platform_pal -->|"uses"| node_crypto_libs
node_wsf_runtime -->|"ported through"| node_platform_pal
node_ble_host_stack -->|"syncs"| node_controller_lhci

click node_ble_apps_build "https://github.com/renjy886/ble-stack/tree/master/ble-apps/build"
click node_ble_apps_sources "https://github.com/renjy886/ble-stack/tree/master/ble-apps/sources"
click node_ble_mesh_apps_build "https://github.com/renjy886/ble-stack/tree/master/ble-mesh-apps/build"
click node_ble_mesh_apps_sources "https://github.com/renjy886/ble-stack/tree/master/ble-mesh-apps/sources"
click node_ble_mesh_profile_build "https://github.com/renjy886/ble-stack/tree/master/ble-mesh-profile/build"
click node_ble_mesh_profile_stack "https://github.com/renjy886/ble-stack/tree/master/ble-mesh-profile/sources/stack"
click node_ble_mesh_models "https://github.com/renjy886/ble-stack/tree/master/ble-mesh-model/sources"
click node_ble_profiles_build "https://github.com/renjy886/ble-stack/tree/master/ble-profiles/build/common/gcc"
click node_ble_profiles_af "https://github.com/renjy886/ble-stack/tree/master/ble-profiles/sources/af"
click node_ble_profiles_services "https://github.com/renjy886/ble-stack/tree/master/ble-profiles/sources/services"
click node_ble_profiles_profiles "https://github.com/renjy886/ble-stack/tree/master/ble-profiles/sources/profiles"
click node_ble_host_stack "https://github.com/renjy886/ble-stack/tree/master/ble-host/sources/stack"
click node_ble_host_hci "https://github.com/renjy886/ble-stack/tree/master/ble-host/sources/hci"
click node_controller_build "https://github.com/renjy886/ble-stack/tree/master/controller/build"
click node_controller_ll "https://github.com/renjy886/ble-stack/tree/master/controller/sources/ble/ll"
click node_controller_bb "https://github.com/renjy886/ble-stack/tree/master/controller/sources/ble/bb"
click node_controller_lhci "https://github.com/renjy886/ble-stack/tree/master/controller/sources/ble/lhci"
click node_controller_sched "https://github.com/renjy886/ble-stack/tree/master/controller/sources/ble/sch"
click node_wsf_runtime "https://github.com/renjy886/ble-stack/tree/master/wsf"
click node_platform_pal "https://github.com/renjy886/ble-stack/tree/master/platform"
click node_nordic_bsp "https://github.com/renjy886/ble-stack/tree/master/thirdparty/nordic-bsp"
click node_crypto_libs "https://github.com/renjy886/ble-stack/tree/master/thirdparty"

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_ble_apps_build,node_ble_apps_sources,node_ble_mesh_apps_build,node_ble_mesh_apps_sources toneBlue
class node_ble_mesh_profile_build,node_ble_mesh_profile_stack,node_ble_mesh_models,node_ble_profiles_build,node_ble_profiles_af,node_ble_profiles_services,node_ble_profiles_profiles,node_ble_host_stack,node_ble_host_hci,node_controller_build,node_controller_ll,node_controller_bb,node_controller_lhci,node_controller_sched toneAmber
class node_wsf_runtime toneMint
class node_platform_pal,node_nordic_bsp,node_crypto_libs toneRose
```

## Components

### Firmware images

Composed sample-device deliverables and their app wiring

- [BLE builds](https://github.com/renjy886/ble-stack/tree/master/ble-apps/build): firmware family · Sample BLE firmware images composed from app, profile, host, controller, and platform layers · `ble-apps/build`
- [BLE apps](https://github.com/renjy886/ble-stack/tree/master/ble-apps/sources): sample apps · Application logic and device-specific GATT/profile behavior for BLE samples · `ble-apps/sources`
- [Mesh builds](https://github.com/renjy886/ble-stack/tree/master/ble-mesh-apps/build): firmware family · Sample Bluetooth Mesh firmware images for light, switch, and provisioner devices · `ble-mesh-apps/build`
- [Mesh apps](https://github.com/renjy886/ble-stack/tree/master/ble-mesh-apps/sources): sample apps · Mesh sample devices and shared bearer/proxy coordination code · `ble-mesh-apps/sources`

### Protocol stacks

BLE host, controller, profiles, and mesh protocol layers

- [Mesh build](https://github.com/renjy886/ble-stack/tree/master/ble-mesh-profile/build): stack config · Build fragments selecting mesh stack, provisioning, bearer, and profile components · `ble-mesh-profile/build`
- [Mesh stack](https://github.com/renjy886/ble-stack/tree/master/ble-mesh-profile/sources/stack): mesh protocol · Mesh bearer, provisioning, access, transport, network, proxy, friend, security, and configuration APIs · `ble-mesh-profile/sources/stack`
- [Mesh models](https://github.com/renjy886/ble-stack/tree/master/ble-mesh-model/sources): model library · Generic, Light, Scene, Scheduler, Time, Health, and vendor model implementations · `ble-mesh-model/sources`
- [Profiles build](https://github.com/renjy886/ble-stack/tree/master/ble-profiles/build/common/gcc): stack config · Build fragments selecting profile, service, and application-framework modules · `ble-profiles/build/common/gcc`
- [App framework](https://github.com/renjy886/ble-stack/tree/master/ble-profiles/sources/af): af layer · Application framework glue for UI, database, hardware, and terminal integration · `ble-profiles/sources/af`
- [Services](https://github.com/renjy886/ble-stack/tree/master/ble-profiles/sources/services): gatt services · Reusable GATT service implementations used by BLE profile and app deliverables · `ble-profiles/sources/services`
- [Profiles](https://github.com/renjy886/ble-stack/tree/master/ble-profiles/sources/profiles): profile library · Standard BLE profile implementations such as BAS, DIS, HRS, HTS, GLS, CPS, CSC, HID, and WDX · `ble-profiles/sources/profiles`
- [BLE host](https://github.com/renjy886/ble-stack/tree/master/ble-host/sources/stack): host stack · ATT, L2CAP, SMP, device management, and host-side HCI handling · `ble-host/sources/stack`
- [Host HCI](https://github.com/renjy886/ble-stack/tree/master/ble-host/sources/hci): hci bridge · Host-side command/event translation and transport glue to the controller · `ble-host/sources/hci`
- [Controller builds](https://github.com/renjy886/ble-stack/tree/master/controller/build): firmware family · Controller firmware compositions for BLE4 and BLE5 targets · `controller/build`
- [Link layer](https://github.com/renjy886/ble-stack/tree/master/controller/sources/ble/ll): ll control · Link-layer control, state machines, initialization, privacy, PHY, ISO, and role behavior · `controller/sources/ble/ll`
- [Baseband](https://github.com/renjy886/ble-stack/tree/master/controller/sources/ble/bb): radio scheduling · Packet handling, advertising, connection scheduling, filters, periodic lists, sniffer, and DTM · `controller/sources/ble/bb`
- [Ctrl HCI](https://github.com/renjy886/ble-stack/tree/master/controller/sources/ble/lhci): hci bridge · Controller-side HCI command and event plumbing · `controller/sources/ble/lhci`
- [Scheduler](https://github.com/renjy886/ble-stack/tree/master/controller/sources/ble/sch): timing core · Radio and link-event scheduling coordination · `controller/sources/ble/sch`

### Runtime

Shared embedded services and stack-wide support

- [WSF](https://github.com/renjy886/ble-stack/tree/master/wsf): runtime · Shared embedded framework for buffers, queues, timers, heap, NVM, and tracing · `wsf`

### Platform

Hardware abstraction and vendor dependencies

- [PAL](https://github.com/renjy886/ble-stack/tree/master/platform): hardware abstraction · Nordic hardware abstraction for radio, timers, GPIO, UART, SPI, flash, crypto, and peripherals · `platform`
- [Nordic BSP](https://github.com/renjy886/ble-stack/tree/master/thirdparty/nordic-bsp): vendor sdk · Nordic board support, nrfx integration, startup code, and MCU-specific build support · `thirdparty/nordic-bsp`
- [Crypto libs](https://github.com/renjy886/ble-stack/tree/master/thirdparty): vendor crypto · Vendor cryptography backends and accelerators including CC310, Oberon, and uecc · `thirdparty`

## Connections

- BLE builds → BLE apps: composes · Sample application firmware images pull in app logic and stack wiring
- BLE apps → Profiles: uses · BLE apps bind to standard profile APIs and device services
- BLE apps → BLE host: calls · Profiles and app logic drive host-side GATT/ATT/SMP/L2CAP behavior
- BLE builds → Profiles build: links · BLE app images include profile and service subsets selected at build time
- Mesh builds → Mesh apps: composes · Mesh firmware images pull in the selected mesh sample application
- Mesh apps → Mesh models: uses · Mesh apps instantiate and bind models to device behavior
- Mesh apps → Mesh stack: calls · Mesh sample apps use provisioning, bearer, proxy, and stack APIs
- Mesh builds → Mesh build: links · Mesh apps assemble with mesh stack and bearer/provisioning build fragments
- Mesh stack → Mesh models: exposes · Mesh stack provides access and transport plumbing to model logic
- Mesh stack → WSF: depends on · Mesh stack uses shared buffers, timers, queues, and NVM services
- Profiles → Services: wraps · Profiles sit on top of reusable GATT services
- Profiles → App framework: binds · Profiles connect into app framework state, UI, and terminal glue
- Profiles → BLE host: uses · Profile behavior is transported through host ATT/L2CAP/SMP layers
- App framework → WSF: depends on · Application framework uses the shared embedded runtime
- BLE host → Host HCI: bridges · Host stack exchanges HCI commands and events with the controller path
- BLE host → WSF: depends on · Host protocols rely on shared runtime primitives
- Host HCI → Ctrl HCI: connects · Host-side HCI maps into controller-side HCI plumbing
- Controller builds → Link layer: composes · Controller images include the link-layer runtime and role-specific modules
- Link layer → Baseband: uses · Link-layer control relies on baseband packet and radio timing services
- Link layer → Scheduler: scheduled by · Link-layer activity is coordinated by BLE scheduling
- Link layer → Ctrl HCI: exports · Controller link layer exposes HCI-facing commands and events
- Baseband → PAL: drives · Baseband code depends on radio and peripheral abstraction
- Scheduler → PAL: times · Scheduling depends on timers, RTC, and radio-control primitives
- PAL → Nordic BSP: implemented by · PAL is backed by Nordic BSP and nrfx support
- PAL → Crypto libs: uses · Platform crypto hooks rely on vendor cryptographic libraries
- WSF → PAL: ported through · WSF target implementations adapt the runtime to bare-metal and Nordic targets
- BLE host → Ctrl HCI: syncs · Host protocols synchronize with controller HCI via the transport split
