How renjy886/ble-stack works
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: stack BLE host · platform PAL · profiles Profiles · ll Link layer
Components 22
Firmware images
Composed sample-device deliverables and their app wiring
- BLE builds · Sample BLE firmware images composed from app, profile, host, controller, and platform layers
ble-apps/build - BLE apps · Application logic and device-specific GATT/profile behavior for BLE samples
ble-apps/sources - Mesh builds · Sample Bluetooth Mesh firmware images for light, switch, and provisioner devices
ble-mesh-apps/build - Mesh 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 · Build fragments selecting mesh stack, provisioning, bearer, and profile components
ble-mesh-profile/build - Mesh stack · Mesh bearer, provisioning, access, transport, network, proxy, friend, security, and configuration APIs
ble-mesh-profile/sources/stack - Mesh models · Generic, Light, Scene, Scheduler, Time, Health, and vendor model implementations
ble-mesh-model/sources - Profiles build · Build fragments selecting profile, service, and application-framework modules
ble-profiles/build/common/gcc - App framework · Application framework glue for UI, database, hardware, and terminal integration
ble-profiles/sources/af - Services · Reusable GATT service implementations used by BLE profile and app deliverables
ble-profiles/sources/services - Profiles · Standard BLE profile implementations such as BAS, DIS, HRS, HTS, GLS, CPS, CSC, HID, and WDX
ble-profiles/sources/profiles - BLE host · ATT, L2CAP, SMP, device management, and host-side HCI handling
ble-host/sources/stack - Host HCI · Host-side command/event translation and transport glue to the controller
ble-host/sources/hci - Controller builds · Controller firmware compositions for BLE4 and BLE5 targets
controller/build - Link layer · Link-layer control, state machines, initialization, privacy, PHY, ISO, and role behavior
controller/sources/ble/ll - Baseband · Packet handling, advertising, connection scheduling, filters, periodic lists, sniffer, and DTM
controller/sources/ble/bb - Ctrl HCI · Controller-side HCI command and event plumbing
controller/sources/ble/lhci - Scheduler · Radio and link-event scheduling coordination
controller/sources/ble/sch
Runtime
Shared embedded services and stack-wide support
- WSF · Shared embedded framework for buffers, queues, timers, heap, NVM, and tracing
wsf
Platform
Hardware abstraction and vendor dependencies
- PAL · Nordic hardware abstraction for radio, timers, GPIO, UART, SPI, flash, crypto, and peripherals
platform - Nordic BSP · Nordic board support, nrfx integration, startup code, and MCU-specific build support
thirdparty/nordic-bsp - Crypto libs · Vendor cryptography backends and accelerators including CC310, Oberon, and uecc
thirdparty
Connections 27
- 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