repository·main·Indexed 19 days ago
https://github.com/embassy-rs/troubleA Rust-based Bluetooth Low Energy (BLE) Host implementation for embedded devices. Designed to be hardware-agnostic via bt-hci traits, it supports various controllers including Linux HCI sockets (via bt-hci-linux), USB adapters (via bt-hci-usb), and specific hardware targets such as ESP32, nRF52, and nRF54.
The current implementation supports the following BLE features:
bt-hci-linux crate provides a Transport implementation for the bt-hci ecosystem. It allows you to communicate with Bluetooth hardware via the Linux HCI socket interface (BlueZ). This is useful for running Bluetooth protocol tests or applications on Linux systems that have access to Bluetooth controllers via standard HCI sockets.L2CAP (Logical Link Control and Adaptation Protocol) is the data transport layer for BLE. GATT and other protocols run on top of it.
While GATT uses fixed channels, BLE also supports Connection-Oriented Channels (CoC) for transferring arbitrary data with credit-based flow control.
Use CoC when:
Each CoC is identified by a SPSM (Simplified Protocol/Service Multiplexer) value, similar to a port number.
TrouBLE is a Bluetooth Low Energy (BLE) Host implementation written in Rust.
In the BLE specification, the software is split into two layers:
These layers communicate via the Host Controller Interface (HCI) protocol. Because TrouBLE implements the Host side, it can be reused across different hardware controllers as long as they communicate via a standardized HCI transport (such as UART, USB, or in-memory IPC).
TrouBLE relies on the bt-hci crate. Any controller that implements the bt-hci traits is compatible with TrouBLE.
Every BLE device is identified by a 48-bit Bluetooth Device Address. These are categorized into two types:
Globally unique and assigned by the IEEE. These remain constant and are used for stable identification.
Used to enhance privacy by preventing device tracking. They are subdivided into:
BLE security manages data encryption and device authentication.
Trouble uses procedural macros to define GATT structures. A service is a struct annotated with #[gatt_service], and each field within that struct represents a characteristic.
uuid (required): The Service UUID. Supports 16-bit short strings ("180f"), 128-bit strings, or predefined constants.uuid (required): The Characteristic UUID.read: Allows clients to read the value.write: Allows clients to write a value (with response).write_without_response: Allows clients to write without waiting for a response.notify: Enables server-initiated notifications (no confirmation).indicate: Enables server-initiated indications (requires client confirmation).value = <expr>: Sets the initial value. Supports literals, byte arrays, and const expressions.permissions(encrypted): Requires an encrypted connection.permissions(authenticated): Requires an authenticated (MITM-protected) connection.u8, u16, u32, u64, f32, f64, bool, [u8; N], and heapless::Vec<u8, N>.
Descriptors are defined as additional attributes on the field using #[descriptor(...)]:
uuid (required)readvaluenametypeuse trouble_host::prelude::*;
#[gatt_service(uuid = "180f")]
struct BatteryService {
#[characteristic(uuid = "2a19", read, notify, value = 10)]
level: u8,
#[descriptor(uuid = descriptors::VALID_RANGE, read, value = [0, 100])]
#[descriptor(uuid = descriptors::MEASUREMENT_DESCRIPTION, name = "hello", read, value = "Battery Level", type = &'static str)]
#[characteristic(uuid = characteristic::BATTERY_LEVEL, read, notify, value = 10)]
level: u8,
}The HostResources type manages the memory for packets, connections, and channels. You must specify the following generic parameters when instantiating it:
PacketPool: The allocator used for payloads (size should match your attribute size or L2CAP MTU).CONNS: Maximum number of BLE connections.CHANNELS: Maximum number of L2CAP channels (excluding GATT).ADV_SETS: Maximum number of advertising sets (default of 1 is usually sufficient).BONDS: Maximum number of stored bond records (requires security feature; default is 10).// Example: 4 connections, 2 L2CAP channels, 1 advertising set, 10 bonds
let mut resources: HostResources<DefaultPacketPool, 4, 2, 1, 10> = HostResources::new();TrouBLE can interface with any controller that implements the bt-hci traits. Currently supported controllers include:
The L2CAP_CHANNELS_MAX parameter on HostResources must account for all internal and user-defined channels. The total count is calculated as follows:
Examples:
2 (signaling + ATT).3.In BLE communication, devices operate in one of two primary roles:
Communication Flow: