From 012b621624974dbedd0efd5e0d6da8ec4a041df1 Mon Sep 17 00:00:00 2001 From: Ulf Lilleengen Date: Thu, 2 May 2024 19:05:58 +0200 Subject: [PATCH] Update README and rust doc --- README.md | 29 +++++++++++++++++++---------- host/src/adapter.rs | 15 +++++++++++++++ host/src/advertise.rs | 1 + host/src/connection.rs | 8 +++++++- host/src/l2cap.rs | 1 + host/src/lib.rs | 3 +++ host/src/scan.rs | 1 + host/src/types/mod.rs | 1 + 8 files changed, 48 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index ceab236..17fe87f 100644 --- a/README.md +++ b/README.md @@ -2,33 +2,42 @@ [![CI](https://github.com/embassy-rs/trouble/actions/workflows/ci.yaml/badge.svg)](https://github.com/embassy-rs/trouble/actions/workflows/ci.yaml) -*WIP* Basic functionality works, however API is likely to change a bit. Use [`nrf-softdevice`](https://github.com/embassy-rs/nrf-softdevice) for the time being if you want a production ready BLE Rust stack for nRF. +TrouBLE is a Bluetooth Low Energy (BLE) Host implementation written in Rust, with a future goal of qualification. The initial implementation was based on [`bleps`](https://github.com/bjoernQ/bleps) but has been adopted to work with types and traits from [`bt-hci`](https://github.com/alexmoon/bt-hci). -TrouBLE is a Bluetooth Low Energy (BLE) Host implementation written in Rust, with a future goal of qualification. +### What is a Host? -The initial implementation was based on [`bleps`](https://github.com/bjoernQ/bleps) but has been adopted to work with [`bt-hci`](https://github.com/alexmoon/bt-hci), which implements Rust types for the HCI specification as well as an interface -for a BLE Controller. +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). -### HCI what? +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](https://github.com/alexmoon/nrf-sdc). Use [`nrf-softdevice`](https://github.com/embassy-rs/nrf-softdevice) for the time being if you want a production ready BLE Rust stack for nRF. +* [Zephyr UART HCI](https://docs.zephyrproject.org/latest/samples/bluetooth/hci_uart/README.html). +* [Raspberry Pi Pico W](https://github.com/embassy-rs/embassy/pull/2865) - This is still WIP and largely untested. -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 called the Host-Controller Interface (HCI), which can operate over different transports such as UART, USB or a custom IPC implementation. ## Current status -The implementation has some basic functionality working: +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 * L2CAP CoC (Connection oriented Channels) with credit management (for both central and peripheral) -* Runs on any transport supporting the `Controller` and `ControllerCmd` traits from `bt-hci`. The `SerialTransport` and `ExternalController` helper types can be used to create additional implementations. -## Example +See the [issues](https://github.com/embassy-rs/trouble/issues) for a list of TODOs. + +## Examples See `examples` for example applications. Currently there are two examples: * `nrf-sdc` for the nRF52 based using the [`nrf-sdc`](https://github.com/alexmoon/nrf-sdc) crate. -* `serial-hci` which runs on a PC using a HCI controller attached via a serial port (Such as [this Zephyr sample](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/zephyr/samples/bluetooth/hci_uart/README.html)). +* `serial-hci` which runs on std using a controller attached via a serial port (Such as [this Zephyr sample](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/zephyr/samples/bluetooth/hci_uart/README.html)). ## License diff --git a/host/src/adapter.rs b/host/src/adapter.rs index 0f2b384..a12a3b0 100644 --- a/host/src/adapter.rs +++ b/host/src/adapter.rs @@ -1,3 +1,6 @@ +//! Adapter +//! +//! The adapter module contains the main entry point for the TrouBLE host. use core::future::pending; use core::task::Poll; @@ -42,6 +45,10 @@ use crate::types::l2cap::{ use crate::{attribute::AttributeTable, gatt::GattServer}; use crate::{AdapterError, Address, Error}; +/// HostResources holds the resources used by the host. +/// +/// The packet pool is used by the adapter to multiplex data streams, by allocating space for +/// incoming packets and dispatching to the appropriate connection and channel. pub struct HostResources { pool: PacketPool, } @@ -49,6 +56,7 @@ pub struct HostResources HostResources { + /// Create a new instance of host resources with the provided QoS requirements for packets. pub fn new(qos: Qos) -> Self { Self { pool: PacketPool::new(qos), @@ -61,6 +69,13 @@ pub trait VendorEventHandler { fn on_event(&self, event: &Vendor<'_>); } +/// A BLE Host adapter. +/// +/// The adapter holds the runtime state of the host, and is the entry point +/// for all interactions with the controller. +/// +/// The adapter performs connection management, l2cap channel management, and +/// multiplexes events and data across connections and l2cap channels. pub struct Adapter< 'd, M, diff --git a/host/src/advertise.rs b/host/src/advertise.rs index b26f4fb..a879662 100644 --- a/host/src/advertise.rs +++ b/host/src/advertise.rs @@ -1,3 +1,4 @@ +//! Advertisement config. pub use bt_hci::param::{AdvChannelMap, AdvFilterPolicy, PhyKind}; use bt_hci::param::{AdvEventProps, AdvHandle, AdvSet}; use embassy_time::Duration; diff --git a/host/src/connection.rs b/host/src/connection.rs index 1b21c19..8f95da6 100644 --- a/host/src/connection.rs +++ b/host/src/connection.rs @@ -1,3 +1,4 @@ +//! BLE connection. use bt_hci::cmd::le::LeConnUpdate; use bt_hci::cmd::link_control::Disconnect; use bt_hci::cmd::status::ReadRssi; @@ -45,10 +46,11 @@ impl Connection { Self { handle } } - pub fn handle(&self) -> ConnHandle { + pub(crate) fn handle(&self) -> ConnHandle { self.handle } + /// Request disconnection of this connection handle. pub fn disconnect< M: RawMutex, T: Controller + ControllerCmdSync, @@ -65,6 +67,7 @@ impl Connection { Ok(()) } + /// The connection role for this connection. pub fn role< M: RawMutex, T: Controller, @@ -81,6 +84,7 @@ impl Connection { Ok(role) } + /// The peer address for this connection. pub fn peer_address< M: RawMutex, T: Controller, @@ -97,6 +101,7 @@ impl Connection { Ok(addr) } + /// The RSSI value for this connection. pub async fn rssi< M: RawMutex, T, @@ -115,6 +120,7 @@ impl Connection { Ok(ret.rssi) } + /// Update connection parameters for this connection. pub async fn set_connection_params< M: RawMutex, T, diff --git a/host/src/l2cap.rs b/host/src/l2cap.rs index 4bceb3e..a21f04e 100644 --- a/host/src/l2cap.rs +++ b/host/src/l2cap.rs @@ -1,3 +1,4 @@ +//! L2CAP channels. use bt_hci::cmd::link_control::Disconnect; use bt_hci::controller::{Controller, ControllerCmdSync}; use bt_hci::param::DisconnectReason; diff --git a/host/src/lib.rs b/host/src/lib.rs index ca7ca17..fe86e77 100644 --- a/host/src/lib.rs +++ b/host/src/lib.rs @@ -39,6 +39,7 @@ mod attribute_server; #[cfg(feature = "gatt")] pub mod gatt; +/// A BLE address. #[derive(Debug, Clone, Copy)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub struct Address { @@ -55,6 +56,7 @@ impl Address { } } +/// Errors returned by the adapter. #[derive(Debug)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum AdapterError { @@ -62,6 +64,7 @@ pub enum AdapterError { Adapter(Error), } +/// Errors related to Host. #[derive(Debug)] #[cfg_attr(feature = "defmt", derive(defmt::Format))] pub enum Error { diff --git a/host/src/scan.rs b/host/src/scan.rs index 38ff755..1e4ece9 100644 --- a/host/src/scan.rs +++ b/host/src/scan.rs @@ -1,3 +1,4 @@ +//! Scan config. use core::iter::FusedIterator; use bt_hci::param::{AddrKind, BdAddr, LeAdvReport, LeExtAdvReport}; diff --git a/host/src/types/mod.rs b/host/src/types/mod.rs index 5169f9c..ceef5e5 100644 --- a/host/src/types/mod.rs +++ b/host/src/types/mod.rs @@ -1,3 +1,4 @@ +//! Common types. pub(crate) mod l2cap; pub(crate) mod primitives; pub mod uuid;