Crate trouble_host

trouble

TrouBLE is a Bluetooth Low Energy (BLE) Host implementation for embedded devices written in Rust, with a future goal of qualification. The initial implementation was based on bleps but has been adapted to work with types and traits from bt-hci and adding support for more of the BLE specification such as L2CAP connection oriented channels. The current implementation also takes strong inspiration from the nrf-softdevice project.

What is a Host?

A BLE Host is one side of the Host Controller Interface (HCI). The BLE specification defines the software of a BLE implementation in terms of a controller (lower layer) and a host (upper layer).

These communicate via a standardized protocol, that may run over different transports such as as UART, USB or a custom in-memory IPC implementation.

The advantage of this split is that the Host can generally be reused for different controller implementations.

Hardware support

TrouBLE can use any controller that implements the traits from bt-hci. At present, that includes:

• nRF Softdevice Controller.
• UART HCI.
• Raspberry Pi Pico W.
• Apache NimBLE Controller.
• ESP32.

Current status

The implementation has the following functionality working:

• Peripheral role - advertise as a peripheral and accept connections.
• Central role - scan for devices and establish connections.
• Basic GATT server supporting write, read, notifications
• Basic GATT client supporting service and characteristic lookup and read + write
• L2CAP CoC (Connection oriented Channels) with credit management (for both central and peripheral)

See the issues for a list of TODOs.

Documentation

See the documentation and the rustdoc.

Minimum supported Rust version (MSRV)

Trouble is guaranteed to compile on stable Rust 1.80 and up. It might compile with older versions but that may change in any new patch release.

Examples

See examples for example applications for different BLE controllers.

• nrf-sdc for the nRF52 based using the nrf-sdc crate.
• serial-hci which runs on std using a controller attached via a serial port (Such as this Zephyr sample).
• apache-nimble which uses the controller from the NimBLE stack through high-level bindings from the apache-nimble crate.
• esp32 which uses the BLE controller in the esp-hal.
• rp-pico-w which uses the BLE controller in the Raspberry Pi Pico W.
• rp-pico-2-w which uses the BLE controller in the Raspberry Pi Pico 2 W.

Since a lot of the examples demo the same BLE functionality, they only contain basic wiring specific to the BLE controller, and share the ‘business logic’ within the examples/apps folder.

More information on these examples can be found is the examples/README.md.

License

Trouble is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Modules

advertise

Advertisement config.

att

Attribute Protocol (ATT) PDU definitions

attribute

Attribute protocol implementation.

central

Functionality for the BLE central role.

config

Compile-time configuration.

connection

BLE connection.

gap

Generic Access Profile

gatt

GATT server and client implementation.

l2cap

L2CAP channels.

packet_pool

A packet pool for allocating and freeing packet buffers with quality of service policy.

peripheral

Functionality for the BLE peripheral role.

prelude

Convenience include of most commonly used types.

scan

Scan config.

types

Common types.

Structs

Address

A BLE address. Every BLE device is identified by a unique Bluetooth Device Address, which is a 48-bit identifier similar to a MAC address. BLE addresses are categorized into two main types: Public and Random.

Host

Host components.

HostResources

HostResources holds the resources used by the host.

Stack

Contains the host stack

Enums

BleHostError

Errors returned by the host.

Error

Errors related to Host.

Traits

Controller

Trait that defines the controller implementation required by the host.

Functions

new

Create a new instance of the BLE host using the provided controller implementation and the resource configuration