Crate bluest

Expand description

Bluest is a cross-platform Bluetooth Low Energy (BLE) library for Rust. It currently supports Windows (version 10 and later), MacOS/iOS, and Linux. Android support is planned.

The goal of Bluest is to create a thin abstraction on top of the platform-specific Bluetooth APIs in order to provide safe, cross-platform access to Bluetooth LE devices. The crate currently supports the GAP Central and GATT Client roles. Peripheral and Server roles are not supported.

§Usage

let adapter = Adapter::default().await.ok_or("Bluetooth adapter not found")?;
adapter.wait_available().await?;

println!("starting scan");
let mut scan = adapter.scan(&[]).await?;
println!("scan started");
while let Some(discovered_device) = scan.next().await {
   println!(
       "{}{}: {:?}",
       discovered_device.device.name().as_deref().unwrap_or("(unknown)"),
       discovered_device
           .rssi
           .map(|x| format!(" ({}dBm)", x))
           .unwrap_or_default(),
       discovered_device.adv_data.services
   );
}

§Overview

The primary functions provided by Bluest are:

Device discovery:
- Scanning for devices and receiving advertisements
- Finding connected devices
- Opening previously found devices
- Connecting to discovered devices
- Pairing with devices
Accessing remote GATT services:
- Discovering device services
- Discovering service characteristics
- Discovering characteristic descriptors
- Read, write (including write without response), and notify/indicate operations on remote characteristics
- Read and write operations on characteristic descriptors

§Asynchronous runtimes

On non-linux platforms, Bluest should work with any asynchronous runtime. On linux the underlying bluer crate requires the Tokio runtime and Bluest makes use of Tokio’s block_in_place API (which requires Tokio’s multi-threaded runtime) to make a few methods synchronous. Linux-only asynchronous versions of those methods are also provided, which should be preferred in platform-specific code.

§Platform specifics

Because Bluest aims to provide a thin abstraction over the platform-specific APIs, the available APIs represent the lowest common denominator of APIs among the supported platforms. For example, CoreBluetooth never exposes the Bluetooth address of devices to applications, therefore there is no method on Device for retrieving an address or even any Bluetooth address struct in the crate.

Most Bluest APIs should behave consistently across all supported platforms. Those APIs with significant differences in behavior are summarized in the table below.

Method	MacOS/iOS	Windows	Linux
`Adapter::connect_device`	✅	✨	✅
`Adapter::disconnect_device`	✅	✨	✅
`Device::name`	✅	✅	⌛️
`Device::is_paired`	❌	✅	✅
`Device::pair`	✨	✅	✅
`Device::pair_with_agent`	✨	✅	✅
`Device::unpair`	❌	✅	✅
`Device::rssi`	✅	❌	❌
`Service::uuid`	✅	✅	⌛️
`Service::is_primary`	✅	❌	✅
`Characteristic::uuid`	✅	✅	⌛️
`Characteristic::max_write_len`	✅	✅	⌛️
`Descriptor::uuid`	✅	✅	⌛️

✅ = supported
✨ = managed automatically by the OS, this method is a no-op
⌛️ = the underlying API is async so this method uses Tokio’s block_in_place API internally
❌ = returns a NotSupported error

Also, the errors returned by APIs in a given situation may not be consistent from platform to platform. For example, Linux’s bluez API does not return the underlying Bluetooth protocol error in a useful way, whereas the other platforms do. Where it is possible to return a meaningful error, Bluest will attempt to do so. In other cases, Bluest may return an error with a kind of Other and you would need to look at the platform-specific source of the error for more information.

§Feature flags

The serde feature is available to enable serializing/deserializing device identifiers.

§Examples

Examples demonstrating basic usage are available in the examples folder.

Re-exports§

pub use btuuid::BluetoothUuidExt;
pub use error::Error;

Modules§

btuuid: Uuid extensions for Bluetooth UUIDs
error: Bluest errors
pairing: Custom Bluetooth pairing agent.

Structs§

Adapter: The system’s Bluetooth adapter interface.
AdvertisementData: Data included in a Bluetooth advertisement or scan reponse.
AdvertisingDevice: Represents a device discovered during a scan operation
Characteristic: A Bluetooth GATT characteristic
CharacteristicProperties: GATT characteristic properties as defined in the Bluetooth Core Specification, Vol 3, Part G, §3.3.1.1. Extended properties are also included as defined in §3.3.3.1.
Descriptor: A Bluetooth GATT descriptor
Device: A Bluetooth LE device
DeviceId: A platform-specific device identifier.
L2capChannel: A Bluetooth LE L2CAP Connection-oriented Channel (CoC)
L2capChannelReader: Reader half of a L2CAP Connection-oriented Channel (CoC)
L2capChannelWriter: Writerhalf of a L2CAP Connection-oriented Channel (CoC)
ManufacturerData: Manufacturer specific data included in Bluetooth advertisements. See the Bluetooth Core Specification Supplement §A.1.4 for details.
Service: A Bluetooth GATT service
ServicesChanged: A services changed notification
Uuid: A Universally Unique Identifier (UUID).

Enums§

AdapterEvent: Events generated by Adapter::events
ConnectionEvent: Events generated by Adapter::device_connection_events

Type Aliases§

Result: Convenience alias for a result with Error

Crate bluestCopy item path