Bluetooth Subsystem
Relevant source files
The following files were used as context for generating this wiki page:
The Bluetooth subsystem in Zephyr is a highly configurable, feature-rich protocol stack with a primary focus on Bluetooth Low Energy (LE). It is designed to be portable across all architectures supported by the project, supporting various build combinations including Controller-only, Host-only, and combined Host + Controller configurations. The subsystem is Bluetooth v5.3 compliant and supports both LE and basic Bluetooth BR/EDR (Classic) functionality.
Sources: doc/connectivity/bluetooth/features.rst:11-25, doc/introduction/index.rst:118-124
Subsystem Architecture
The architecture is divided into two primary layers: the Bluetooth Host and the Bluetooth Controller. These layers communicate via a clean Host Controller Interface (HCI) driver abstraction. This modularity allows Zephyr to act as a full stack, or as a standalone Controller for another Host via physical transports like UART, SPI, USB, or IPC.
Bluetooth Host
The Host layer manages high-level profiles and protocols. It includes support for the Generic Access Profile (GAP), Generic Attribute Profile (GATT), and Pairing support (including Secure Connections from Bluetooth 4.2). It also incorporates a Bluetooth Mesh stack and LE Audio capabilities.
Bluetooth Controller (LE Link Layer)
The Controller manages the physical radio hardware. It supports unlimited role and connection counts, concurrent multi-protocol operation, and intelligent scheduling to minimize role overlap. It is portable to various radios, including Nordic Semiconductor nRF52x/nRF53x series and proprietary hardware.
Sources: doc/connectivity/bluetooth/features.rst:31-65, doc/introduction/index.rst:125-132
System Data Flow
The following diagram illustrates the relationship between the Application, the Bluetooth Host, and the Bluetooth Controller across the HCI interface.
The HCI driver abstraction supports multiple physical transports, including 3-Wire (H:5) and 5-Wire (H:4) UART, SPI, and virtual HCI drivers for local controllers.
Sources: doc/connectivity/bluetooth/features.rst:79-84
Key Features and Capabilities
The subsystem provides extensive support for both standard Bluetooth operations and advanced mesh networking.
| Category | Supported Features |
|---|---|
| LE Host | Peripheral, Central, Observer, Broadcaster roles; 2Mbps/Coded PHY; Extended & Periodic Advertising |
| GATT | Client & Server roles; Enhanced ATT (EATT); Database Hash; Multiple Notifications |
| Mesh | Relay, Friend, Low-Power (LPN), and GATT Proxy nodes; PB-ADV & PB-GATT bearers |
| Classic | GAP, L2CAP, RFCOMM (Serial Port Emulation), SDP |
| Security | Pairing with Secure Connections; Non-volatile storage for settings/keys |
Sources: doc/connectivity/bluetooth/features.rst:43-77, doc/introduction/index.rst:133-140
Development and Debugging Tools
Zephyr provides several methods for testing Bluetooth applications without dedicated hardware, as well as binary logging for embedded targets.
Emulation and Simulation
Bluetooth applications can be executed in the QEMU emulator or as native Linux applications using native_sim. In these environments, the host system's Bluetooth controller can be exported to the emulator via a UNIX socket or BlueZ user channel.
HCI Tracing
HCI traffic can be monitored using the btmon tool from the BlueZ suite. For embedded targets where physical UART access is limited, Zephyr supports a binary protocol that interleaves system logs with HCI traffic over UART or Segger RTT.
Configuration Options for Debugging
| Option | Description |
|---|---|
CONFIG_BT_DEBUG_MONITOR_UART | Activates binary protocol formatting on UART for btmon compatibility. |
CONFIG_UART_CONSOLE | Must be disabled (n) when using BT_DEBUG_MONITOR_UART to free the UART. |
CONFIG_BT_DEBUG_MONITOR_RTT | Uses Segger RTT for HCI tracing instead of UART. |
Sources: doc/connectivity/bluetooth/bluetooth-tools.rst:157-178
Security and Safety
The Bluetooth subsystem is integrated into Zephyr's broader security and safety frameworks.
Security Architecture
The subsystem leverages PSA Crypto (typically via mbedTLS) for cryptographic operations, ensuring standardized approaches to encryption and key management. The monolithic design of Zephyr, where the Host and application are linked into a single binary, reduces the attack surface by eliminating dynamic loading of malicious code.
Functional Safety
For safety-critical applications, the Bluetooth subsystem's interactions with the kernel must align with IEC 61508 standards. This involves rigorous requirements tracing and structural test coverage (100% statement/branch coverage) for the safety-relevant scope of the codebase.
Sources: doc/security/security-overview.rst:54-70, doc/safety/safety_overview.rst:116-130
Conclusion
The Zephyr Bluetooth subsystem provides a professional-grade, SIG-qualifiable protocol stack suitable for resource-constrained IoT devices. Its modular architecture allows for flexible hardware setups, while its extensive feature set—ranging from LE Audio to Mesh networking—ensures compatibility with modern Bluetooth standards. The subsystem's integration with Linux-based debugging tools and its adherence to Zephyr's security and quality standards make it a robust choice for embedded wireless development.