Bluest: Cross-platform BLE library for Rust

Bluest provides a thin abstraction for the following BLE operations:

Device Discovery

• Scanning: Use Adapter::scan to find devices and receive advertisements.
• Connected Devices: Use Adapter::connected_devices to find currently connected devices.
• Opening Devices: Use Adapter::open_device to access previously found devices.
• Connecting: Use Adapter::connect_device to establish a connection.
• Pairing: Use Device::pair to pair with a device.

GATT Operations

• Service Discovery: Use Device::discover_services to find services on a device.
• Characteristic Discovery: Use Service::discover_characteristics to find characteristics within a service.
• Descriptor Discovery: Use Characteristic::discover_descriptors to find descriptors for a characteristic.
• Data Operations:
  • Read: Characteristic::read or Descriptor::read.
  • Write: Characteristic::write (with response) or Characteristic::write_without_response.
  • Notify/Indicate: Characteristic::notify.
  • Descriptor Write: Descriptor::write.

Bluest provides a thin abstraction, meaning it only exposes the lowest common denominator of APIs across supported platforms.

Important Note on Addresses: Because Apple's CoreBluetooth does not expose Bluetooth addresses to applications, Bluest does not provide a method to retrieve a device's Bluetooth address, nor does it include a Bluetooth address struct.

Supported Platforms

• Windows (version 10 and later)
• MacOS/iOS
• Linux
• Android support is planned.

API Availability Matrix

Legend:

• ✅ = supported
• ✨ = managed automatically by the OS (method is a no-op)
• ⌛️ = underlying API is async; uses Tokio's block_in_place internally
• ❌ = returns ErrorKind::NotSupported error

Bluest provides a thin abstraction for the GAP Central and GATT Client roles. The workflow typically follows these steps:

1. Discovery: Use Adapter::scan to find devices or Adapter::connected_devices to find existing connections.
2. Connection: Use Adapter::open_device to access a known device or Adapter::connect_device to establish a new connection.
3. Pairing: Use Device::pair or Device::pair_with_agent to pair with a device.
4. GATT Exploration: Once connected, use Device::discover_services to find services, Service::discover_characteristics to find characteristics within a service, and Characteristic::discover_descriptors to find descriptors.
5. Data Operations: Perform Characteristic::read, Characteristic::write, Characteristic::write_without_response, or Characteristic::notify on characteristics, and Descriptor::read/write on descriptors.

To start using Bluest, initialize an Adapter, wait for it to become available, and then call scan. You can iterate over the discovered devices using a stream. Each AdvertisingDevice provides access to the Device object, advertisement data, and RSSI (signal strength).

Note: On Linux, Bluest requires the tokio multi-threaded runtime because it uses block_in_place for certain synchronous operations.

use bluest::Adapter;
use futures_lite::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let adapter = Adapter::default().await?;
    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
        );
    }

    Ok(())
}