webbluetooth 0.0.5

The Web Bluetooth API in Rust — Apple platforms, Linux, Android, Windows and the browser
Documentation

webbluetooth

The Web Bluetooth API in Rust — on Apple platforms, Linux, Android, Windows and the browser.

requestDevice, gatt.connect(), getPrimaryService, readValue, startNotifications — the same names, the same security model. Promises become async fns and events become Streams; everything else reads like the JavaScript original.

use webbluetooth::prelude::*;
use webbluetooth::uuid::{characteristics, services};

let bluetooth = Bluetooth::new();

let device = bluetooth.request_device(
    RequestDeviceOptions::new()
        .filter(DeviceFilter::new().service(services::HEART_RATE)?)
        .optional_service(services::BATTERY_SERVICE)?,
).await?;

let gatt = device.gatt();
gatt.connect().await?;

let service = gatt.get_primary_service(services::HEART_RATE).await?;
let characteristic = service
    .get_characteristic(characteristics::HEART_RATE_MEASUREMENT).await?;

let mut beats = characteristic.start_notifications().await?;
while let Some(value) = beats.next().await {
    println!("{} bpm", value[1]);
}
[dependencies]
webbluetooth = "0.0.5"

That is the whole dependency list for the example above. webbluetooth::prelude re-exports StreamExt, because notifications, advertisements and disconnects are all streams and a stream has no .next() without it — so the example used to need a futures-util dependency nobody had mentioned.

You do need an executor to run any of it. This crate brings none, so that it works with whichever you already have; the examples use futures_executor, which is the smallest thing that will do.

No Swift, no Objective-C, no Java, no libdbus, no code generation, no shim. Each platform is reached through its own C ABI directly, and where one demands a type that does not exist — a CoreBluetooth delegate, an Android callback subclass — it is built at run time rather than shipped.

Start here

cargo run --example doctor    # why Bluetooth is or isn't usable
cargo run --example scan      # list everything in range
cargo run --example battery   # read the nearest battery level

Run doctor first. Almost every "it finds nothing" report is an authorization problem rather than anything to do with the radio — on Apple platforms a process with no NSBluetoothAlwaysUsageDescription is reported Unauthorized and is never prompted. The repository's README explains what to do about that; it is the single most common way to lose an afternoon here.

Platforms

Platform Central Peripheral L2CAP
macOS, iOS, Mac Catalyst ✅ ✅ ✅
tvOS, watchOS, visionOS ✅ ❌ ✅
Linux (BlueZ, or a raw socket with linux-hci) ✅ ✅ ✅
Android (API 26+) ✅ ✅ ✅ (29+)
Windows 10 1709+ ✅ ✅ ❌
Browser (WebAssembly) ✅ ❌ ❌
Node.js / Deno ✅ ❌ ❌

PERIPHERAL_ROLE and L2CAP are const bools to branch on, and the modules they describe do not exist where they are false.

Native extensions

The standard-shaped API is available from the root crate. Native extensions are opt-in through Cargo features:

Feature Provides
public The Web Bluetooth-compatible imports under webbluetooth::public.
classic Enables Bluetooth Classic capability reporting.
rfcomm Enables RFCOMM byte streams on Linux, Android, Windows and macOS; it implies classic, and on macOS apple-classic.
apple-classic macOS: Bluetooth Classic through IOBluetooth — paired-device listing; rfcomm turns it on.
classic-l2cap Enables Bluetooth Classic L2CAP channels; it implies classic and is currently implemented on Linux.
linux-hci Uses the Linux controller directly instead of BlueZ.
uuid Converts to and from the uuid crate's Uuid.

For example:

[dependencies]
webbluetooth = { version = "0.0.5", features = ["public", "rfcomm"] }

BluetoothDevice::mtu() reports the negotiated ATT MTU. On Android, BluetoothDevice::request_mtu() asks the platform to negotiate a requested value; platforms that hide or automatically manage the exchange return Error::NotSupported.

Descriptors support read_value() and write_value() as well as read_value_at_offset() and write_value_at_offset(). The offset helpers use portable whole-value reads and writes, validate offsets, and enforce the 512-byte ATT attribute limit.

On Linux, BluetoothDevice::open_rfcomm_channel(channel) opens a Bluetooth Classic RFCOMM byte stream and open_classic_l2cap_channel(psm) opens a Classic L2CAP channel. On Android, open_rfcomm_service(service_uuid) opens an RFCOMM service-record connection. On Windows, open_rfcomm_channel(channel) goes through WinSock. On macOS, RFCOMM is IOBluetooth's rather than CoreBluetooth's, and the two share no identifier: Bluetooth::open_rfcomm_channel(address, channel) opens by address (Bluetooth::paired_classic_devices() lists them), and BluetoothDevice::open_rfcomm_channel(channel) finds a dual-mode device's Classic side by name. IOBluetooth delivers RFCOMM events on the main thread's run loop, so a command-line program has to keep it turning — see the rfcomm_macos example. These transports are separate from BLE L2CAP and from the Web Bluetooth surface; iOS and browser targets do not expose them.

What is different from a browser

The chooser is yours. requestDevice() is defined around a user gesture and a picker dialog. A library has no chrome to draw, so it is a trait: FirstMatch (the default, and a deliberate removal of the consent step), StrongestSignal, TerminalChooser, a predicate, or your own.

Everything else about the security model is kept — the GATT blocklist, the manufacturer-data blocklist, and the rule that a device grants access only to the services that were asked for.

Features

public Re-export the Web Bluetooth-compatible API under webbluetooth::public.
classic Enable Bluetooth Classic capability reporting and native extensions.
rfcomm Enable RFCOMM byte streams on Linux, Android, Windows and macOS; implies classic.
linux-hci Talk to the controller directly instead of going through BlueZ.
terminal-chooser A device chooser that prints numbered candidates and reads a line.
uuid Convert to and from the uuid crate's Uuid.

More

The repository has the full guide: authorization, the peripheral role, L2CAP channels, state restoration, how each backend works, and what is tested where. PLATFORMS.md is the per-platform reference.

License

MIT. See LICENSE.