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 *;
use ;
let bluetooth = new;
let device = bluetooth.request_device.await?;
let gatt = device.gatt;
gatt.connect.await?;
let service = gatt.get_primary_service.await?;
let characteristic = service
.get_characteristic.await?;
let mut beats = characteristic.start_notifications.await?;
while let Some = beats.next.await
[]
= "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
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:
[]
= { = "0.0.5", = ["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.