Rust Cross-Platform Host-Side Bluetooth LE Access Library
btleplug
btleplug is an async Rust BLE library, supporting Windows 10, macOS, Linux, iOS, and Android (including Flutter, see below for more info).
It grew out of several earlier abandoned libraries for various platforms (rumble, blurmac, etc...), with the goal of building a fully cross platform library. If you're curious about how the library grew, you can read more on that in this blog post.
btleplug is meant to be host/central mode only. If you are interested in peripheral BTLE (i.e. acting like a Bluetooth LE device instead of connecting to one), check out bluster or ble-peripheral-rust.
This library DOES NOT SUPPORT BLUETOOTH 2/CLASSIC. There are no plans to add BT2/Classic support.
Platform Status
- Linux / Windows / macOS (>= 10.15) / iOS / Android
- WASM/WebBluetooth
Platform Feature Table
- X: Completed and released
- O: In development
- Blank: Not started
Platform Caveats
Scan Filtering on Linux (BlueZ)
The ScanFilter passed to start_scan() behaves differently on Linux than other platforms. btleplug forwards service UUID filters to BlueZ, but BlueZ merges discovery filters across all D-Bus clients. Your application will receive advertisements matching the union of all applications' filters, not just your own. Additionally, BlueZ's UUID filter can drop some advertisement types (such as service data) that it shouldn't. Applications targeting Linux should perform their own post-filtering on scan results rather than relying solely on ScanFilter.
Library Features
Serialization/Deserialization
To enable implementation of serde's Serialize and Deserialize across some common types in the api module, use the serde feature.
[dependencies]
btleplug = { version = "0.12", features = ["serde"] }Build/Installation Notes for Specific Platforms
macOS
To use Bluetooth on macOS Big Sur (11) or later, you need to either package your binary into an application bundle with an Info.plist including NSBluetoothAlwaysUsageDescription, or (for a command-line application such as the examples included with btleplug) enable the Bluetooth permission for your terminal. You can do the latter by going to System Preferences → _Security & Privacy → Privacy → Bluetooth_, clicking the '+' button, and selecting 'Terminal' (or iTerm or whichever terminal application you use).
Android
Due to requiring a hybrid Rust/Java build, btleplug for Android requires a somewhat complicated setup.
There is now a build script at ./scripts/build-java.sh for building the java portion of the library on linux or macOS. This can also be used as a guide for manual building if need be.
If your app uses Proguard/R8 with minifyEnabled true, you must add keep rules for btleplug's Java classes. All of btleplug's Java code (including vendored jni-utils classes) is only accessed via JNI from native code, so R8 will treat it as dead code and strip it without these rules.
In your build.gradle, ensure Proguard is configured for release builds:
buildTypes { release { shrinkResources true minifyEnabled true proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro' } }proguard-rules.pro:
# btleplug Java classes (accessed only via JNI) -keep class com.nonpolynomial.* { ; } -keep class io.github.gedgygedgy.* { ; }iOS
As the Corebluetooth implementation is shared between macOS and iOS, btleplug on iOS should "just work", and seems to be stable. How this is built can vary based on your app setup and what language you're binding to, but sample instructions are as follows (taken from here):
- Write a rust library (static) that uses btleplug and exposes an FFI API to C
- Use cbindgen to generate a C header file for that API
- Use cargo-lipo to build a universal static lib
- Drag the header file and the library into your Xcode project
- Add NSBluetoothAlwaysUsageDescription to your Info.plist file
Flutter
While we don't specifically support Flutter, there's a template repo available at https://github.com/trobanga/flutter_btleplug. This template has builds for both Android and iOS using btleplug.
As flutter compilation tends to be complex across platforms, we cannot help with flutter build issues.
Tauri
While we don't specifically support Tauri, there's a plugin available at https://github.com/MnlPhlp/tauri-plugin-blec. Please note that all Tauri questions should go to the plugin repo before coming here, we cannot help with Tauri issues as none of this project's developers use Tauri.
Alternative Libraries
Everyone has different bluetooth needs, so if btleplug doesn't fit yours, try these other libraries by the rust community!
- Bluest - Cross Platform BLE library (Windows/macOS/iOS/Linux)
- Bluey - Cross Platform BLE library (Windows/Android)
- Bluer - Official Rust interface for Bluez on Linux, with more
Integration Tests
btleplug includes integration tests that exercise real BLE operations against a test peripheral.
Quick start with hardware:
# Flash the nRF52840 DK (one-time setup)
cd test-peripheral/zephyr
west build -b nrf52840dk/nrf52840 && west flash
Run integration tests
cargo test --test '*' -- --ignoredQuick start with a virtual peripheral (requires USB BLE dongle):
# Start the Bumble virtual peripheral
cd test-peripheral/bumble
pip install -r requirements.txt
./run.sh usb:0 # transport argument may vary; see Bumble docs
In another terminal, run integration tests
cargo test --test '*' -- --ignoredSee test-peripheral/README.md for full setup instructions.
License
BTLEPlug is covered under a BSD 3-Clause License, with some parts from Rumble/Blurmac covered under MIT/Apache dual license, and BSD 3-Clause licenses, respectively. See LICENSE.md for more info and copyright information.
