Skip to main content

Crate bluetooth_host

Crate bluetooth_host 

Source
Expand description

§bluetooth-host

crates.io docs.rs

A Bluetooth host stack over raw HCI.

cargo add bluetooth-host

It talks to a controller directly, over the Linux HCI user channel, H4 on a serial port, or H4 over TCP, so the same features work on every board with no BlueZ or D-Bus. HCI commands and events are encoded and decoded by the bt_hci crate; everything above HCI is here:

  • controller capability discovery, so features degrade cleanly on old chips;
  • the observer: passive and active scanning, legacy and extended reports, the coded PHY, periodic advertising sync, duplicate filtering, and private addresses resolved to identities;
  • the broadcaster: legacy, extended and periodic advertising sets;
  • central and peripheral connections, parameter, PHY and data length updates;
  • L2CAP signaling and LE credit-based channels;
  • ATT, a GATT client, and a GATT server built at run time;
  • SMP: legacy and Secure Connections pairing, every association model, bonding with a persistent key store, and privacy.
use bluetooth_host::{Host, HostConfig, HostEvent, ScanConfig};
let host = Host::open(&"hci0".parse().unwrap(), HostConfig::default()).await?;
let mut events = host.events();
host.start_scan(ScanConfig::default()).await?;
while let Ok(HostEvent::Advertisement(r)) = events.recv().await {
    println!("{} {} dBm {:?}", r.device(), r.rssi, r.advertisement().local_name);
}

Part of bluetooth-bridge, maintained by Pulzar. See the user guide, the library guide and the API documentation.

License: MIT.

Re-exports§

pub use address::Address;
pub use address::AddressType;
pub use advertise::AdvertisingParams;
pub use advertise::PeriodicParams;
pub use connection::ConnEvent;
pub use connection::ConnParams;
pub use connection::Connection;
pub use connection::ParamsRequest;
pub use connection::Phy;
pub use connection::Role;
pub use connection::Security;
pub use controller::Capabilities;
pub use error::Error;
pub use error::Result;
pub use scan::Dedup;
pub use scan::PeriodicReport;
pub use scan::Report;
pub use scan::ScanConfig;
pub use smp::Agent;
pub use smp::AutoAgent;
pub use smp::FixedAgent;
pub use smp::IoCapability;
pub use smp::Method;
pub use smp::OobData;
pub use transport::TransportSpec;
pub use bluetooth_adv as adv;

Modules§

address
Device addresses (Core Vol 6, Part B, 1.3).
advertise
The broadcaster: advertising sets (legacy, extended, periodic), so the gateway can send packets as well as hear them.
att
The Attribute Protocol bearer (Core Vol 3, Part F).
connection
LE connections: state, parameters, PHY and data length, and the handle applications hold.
controller
What the controller can do, read once at start, so every feature can check before it asks and degrade cleanly on an old chip (a Pi 3’s Bluetooth 4.1 controller has no extended advertising, no 2M or coded PHY and no data length extension).
crypto
The Security Manager’s cryptographic toolbox (Core Vol 3, Part H, 2.2), on RustCrypto’s AES, CMAC and P-256.
error
Errors.
gatt
GATT (Core Vol 3, Part G): a client for peers’ servers, and our own server.
keys
Bonds (the keys pairing leaves behind), our own identity, and resolving private addresses to the identities they hide.
l2cap
L2CAP on LE (Core Vol 3, Part A): the fixed channels (ATT, signaling, SMP), the LE signaling channel, and credit-based connection-oriented channels, both the LE Credit Based (0x14) and the enhanced Credit Based (0x17) forms.
probe
Naming a controller without starting a host: reset it and read who made it and what it can do. Bounded and harmless: it sends only Reset and read commands, and closes the transport when done.
scan
The observer: scanning (passive and active, legacy and extended, 1M and coded PHY), duplicate filtering, reassembly of fragmented extended reports, resolution of private addresses, and periodic advertising sync.
smp
The Security Manager (Core Vol 3, Part H): LE legacy pairing and LE Secure Connections, every association model (Just Works, Numeric Comparison, Passkey Entry, Out of Band), key distribution and bonding, and re-encryption with stored keys.
transport
Moving HCI packets to and from a controller.

Structs§

ConnectParams
How to connect.
Host
A running Bluetooth host on one controller. Cloning it is cheap; every clone drives the same controller.
HostConfig
How the host presents itself and pairs.

Enums§

HostEvent
Something that happened, for the application.