Usage

SimpleFltBLE brings SimpleBLE to Flutter apps on Android, iOS, macOS, Windows, and Linux. Its API is SimpleDartBLE's, with futures, streams, and one object per Bluetooth object, and it adds the setup Flutter apps need on Android.

Requirements

• Flutter 3.38 or newer.
• Android 12 (API 31) or newer, iOS 15.8 or newer, macOS 15.0 or newer, Windows 10 or newer, or Linux with glibc 2.28 or newer.
• On Linux, BlueZ and the D-Bus library (libdbus-1-3 on Debian and Ubuntu).

Install from pub.dev

flutter pub add simplefltble

The package carries the native SimpleBLE library for every supported platform, so nothing is compiled or downloaded during your build. Import it where you use Bluetooth:

import 'package:simplefltble/simplefltble.dart';

App setup

Raise your app's platform minimums to SimpleBLE's: minSdk = 31 in android/app/build.gradle.kts, and the deployment target to iOS 15.8 and macOS 15.0 in Xcode.

On Android, SimpleFltBLE's manifest declares BLUETOOTH_SCAN, BLUETOOTH_CONNECT, and BLUETOOTH_ADVERTISE, and your app asks for them at runtime before using Bluetooth, for example with permission_handler:

import 'dart:io';

import 'package:permission_handler/permission_handler.dart';

Future<bool> requestBluetooth() async {
  if (!Platform.isAndroid) return true;
  final statuses = await [Permission.bluetoothScan, Permission.bluetoothConnect].request();
  return statuses.values.every((status) => status.isGranted);
}

Add Permission.bluetoothAdvertise to the list to host a local peripheral.

BLUETOOTH_SCAN is declared with neverForLocation, so scanning needs no location permission, and Android leaves some beacons out of the results. To scan for beacons, remove the flag in your app's AndroidManifest.xml, under a <manifest> element that declares xmlns:tools="http://schemas.android.com/tools", and request ACCESS_FINE_LOCATION at runtime as well:

<uses-permission android:name="android.permission.BLUETOOTH_SCAN" tools:remove="android:usesPermissionFlags" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

On iOS and macOS, add NSBluetoothAlwaysUsageDescription to your app's Info.plist, and on macOS the com.apple.security.device.bluetooth entitlement to DebugProfile.entitlements and Release.entitlements. The system asks the user the first time the app uses Bluetooth.

First scan

import 'package:simplefltble/simplefltble.dart';

Future<void> scan() async {
  final adapter = (await Adapter.getAdapters()).first;

  adapter.onScanFound.listen((peripheral) {
    print('${peripheral.identifier} ${peripheral.address} ${peripheral.rssi}');
  });
  await adapter.scanFor(const Duration(seconds: 5));
}

Calls that reach the Bluetooth stack run on helper isolates, so they never hold up your app's UI. After a hot restart, the new isolate takes over SimpleBLE's events.

The API

SimpleFltBLE re-exports SimpleDartBLE, so its classes, events, and exceptions are SimpleDartBLE's. SimpleDartBLE Usage covers them: calls, events, and lifetime, GATT, hosting a local peripheral, handlers, backend configuration, the Dongl on Windows, macOS, and Linux, logging, and platform-specific features.

For more, see Quickstart, Read, Write, Notify, and the SimpleFltBLE Examples.

Platform notes

• Android: SimpleFltBLE loads SimpleBLE's native library and gives it the application context when the app starts, so hosting a local peripheral needs no setup beyond the permissions.
• macOS: Bluetooth permission belongs to the app, with the Info.plist entry and entitlement from App setup.
• Linux: SimpleBLE talks to BlueZ over the D-Bus system bus, so the user needs access to it, as described in Bluetooth Permissions.
• Web: Flutter's web platform can't load native libraries, so SimpleFltBLE doesn't support it.