rblue_flutter
Early experimental preview. The API, wire contract, native binaries, and supported targets may change before a stable release.
rblue_flutter packages the experimental Flutter binding maintained in
rblue-rs/rblue. It wraps rblue's
message-passing C ABI with a typed Dart client for Bluetooth Low Energy. This
Pub.dev release preserves the upstream project links and license; publication
under a Pub.dev account does not imply a separate stability guarantee.
Current support
| Platform | Packaged target | Minimum | Status |
|---|---|---|---|
| Android | arm64-v8a, armeabi-v7a, x86_64 | API 24 | Experimental; physical-device smoke testing still required |
| iOS device | arm64 | iOS 15 | Experimental; unsigned build/link validation only |
| iOS simulator | arm64 (Apple Silicon) | iOS 15 | Packaging/UI only; simulators have no BLE radio coverage |
macOS, Windows, Linux, web, Intel iOS simulators, and HarmonyOS are not declared by this Flutter package. This is not yet a production-stability claim.
Implemented operations include adapter initialization, scan/start/stop, peripheral lookup, connect/disconnect, service discovery, characteristic read/write, subscribe/unsubscribe, RSSI, MTU query, maximum write length, capabilities, connection state, and iOS system-connected peripheral lookup.
Installation
dependencies:
rblue_flutter: ^0.0.1-dev.1
The Pub package contains the native libraries. Consumers do not need the rblue monorepo, Rust, Cargo, or local path dependencies to install and build it.
App setup
Android
The plugin manifest contributes the BLE permissions. Request runtime permission before creating the client:
final granted = await RbluePluginChannel.instance.requestBlePermissions();
if (!granted) {
throw StateError('Bluetooth permission was not granted');
}
final client = await RblueClient.create();
await client.initialize();
The consuming app must use minSdk >= 24. On Android 12+ the plugin requests
BLUETOOTH_SCAN and BLUETOOTH_CONNECT; on older Android it requests fine
location. The bundled manifest uses Android's neverForLocation assertion by
default, which can filter some BLE beacons. Apps deriving physical location or
scanning those beacons must override that manifest policy and manage the
additional location permission themselves. The plugin initializes the JNI
backend on the engine thread before Dart enters the Rust C ABI.
iOS
Set an honest Bluetooth explanation in the consuming app's Info.plist:
<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to communicate with nearby devices.</string>
The CoreBluetooth prompt appears on first use. The package currently contains only arm64 device and arm64 simulator libraries, so Intel simulator builds are unsupported.
Minimal scan
final client = await RblueClient.create();
final subscription = client.events.listen((event) {
// Inspect AdapterEvent values here.
});
await client.initialize();
await client.startScan();
// Later:
await client.stopScan();
await subscription.cancel();
client.dispose();
Always call dispose(). Subscribe to event/notification streams before starting
operations if the first event must not be missed.
A complete Android/iOS app is under example/. It demonstrates
scan, GATT read/write/notify, and host-managed reconnect behavior.
Native packaging and provenance
This release packages prebuilt rblue-c binaries so an installed Pub package
works without reaching outside itself:
- Android:
android/src/main/jniLibs/<abi>/librblue_c.so; - iOS:
ios/Libs/ios{,-sim}/librblue_c.a; - Android btleplug Java/JNI helpers:
android/src/main/java/.
The corresponding mobile Rust source snapshot, pinned lockfile, exact build
instructions, checksums, and exported-symbol checks are included under
native/. This is for reproducibility and license compliance; normal
Flutter builds consume the packaged binaries rather than compiling Rust.
See THIRD_PARTY_NOTICES.md for dependency attribution
and license texts. The package itself is dual-licensed under MIT or Apache-2.0.
Known limitations
- There is no automated real-radio acceptance claim; use physical Android and iOS devices before relying on behavior with your peripherals.
- Reconnect policy lives in Dart. Rust
ConnectionSupervisorand GATT queue behavior are not exported by the current C ABI. - Notification streams are broadcast streams without built-in bounded backpressure. Production consumers must define an aggregation/drop policy.
- GATT characteristic instance IDs are connection-scoped and must be rediscovered after reconnecting.
- Pairing, descriptor read/write, and explicit Android MTU requests are not exposed yet.
- Some Android failures are collapsed by the pinned btleplug fork to
NotConnected; raw GATT status is preserved only when the backend supplies it. - Android BLE behavior depends on the pinned btleplug fork revision
1af8299c291f24fca68dfb6b7ef1b5c0475892e1.
Please report reproducible issues at github.com/rblue-rs/rblue/issues.
Libraries
- rblue_flutter
- Early experimental Flutter binding for the rblue BLE project.