flutter_blue_plus 1.7.7

flutter_blue_plus: ^1.7.7 copied to clipboard

Note: this plugin is continuous work from FlutterBlue since maintenance stopped.

Foreward #

For simple BLE apps, I highly recommend QuickBlue (https://pub.flutter-io.cn/packages/quick_blue) in favor of FlutterBlue. It has a simpler API, a much smaller codebase, is less buggy, and supports iOS, MacOS, Android, Windows, and partial Linux support.

Introduction #

FlutterBluePlus is a bluetooth plugin for Flutter, a new app SDK to help developers build modern multi-platform apps.

Cross-Platform Bluetooth LE #

FlutterBluePlus aims to offer the most from both platforms (iOS and Android).

Using the FlutterBluePlus instance, you can scan for and connect to nearby devices (BluetoothDevice). Once connected to a device, the BluetoothDevice object can discover services (BluetoothService), characteristics (BluetoothCharacteristic), and descriptors (BluetoothDescriptor). The BluetoothDevice object is then used to directly interact with characteristics and descriptors.

Usage #

Obtain an instance #

FlutterBluePlus flutterBlue = FlutterBluePlus.instance;

Scan for devices #

// Start scanning
flutterBlue.startScan(timeout: Duration(seconds: 4));

// Listen to scan results
var subscription = flutterBlue.scanResults.listen((results) {
    // do something with scan results
    for (ScanResult r in results) {
        print('${r.device.name} found! rssi: ${r.rssi}');
    }
});

// Stop scanning
flutterBlue.stopScan();

Connect to a device #

// Connect to the device
await device.connect();

// Disconnect from device
device.disconnect();

Discover services #

List<BluetoothService> services = await device.discoverServices();
services.forEach((service) {
    // do something with service
});

Read and write characteristics #

// Reads all characteristics
var characteristics = service.characteristics;
for(BluetoothCharacteristic c in characteristics) {
    List<int> value = await c.read();
    print(value);
}

// Writes to a characteristic
await c.write([0x12, 0x34])

Read and write descriptors #

// Reads all descriptors
var descriptors = characteristic.descriptors;
for(BluetoothDescriptor d in descriptors) {
    List<int> value = await d.read();
    print(value);
}

// Writes to a descriptor
await d.write([0x12, 0x34])

Set notifications and listen to changes #

await characteristic.setNotifyValue(true);
characteristic.value.listen((value) {
    // do something with new value
});

Read the MTU and request larger size #

final mtu = await device.mtu.first;
await device.requestMtu(512);

Note that iOS will not allow requests of MTU size, and will always try to negotiate the highest possible MTU (iOS supports up to MTU size 185)

Getting Started #

Change the minSdkVersion for Android #

flutter_blue_plus is compatible only from version 19 of Android SDK so you should change this in android/app/build.gradle:

Android {
  defaultConfig {
     minSdkVersion: 19

Add permissions for Bluetooth #

We need to add the permission to use Bluetooth and access location:

Android

In the android/app/src/main/AndroidManifest.xml let’s add:

	  <uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />
	  <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
 <application

By default the package does not request the ACCESS_FINE_LOCATION permission on Android 12+. In case you need to get the physical location of the device via Bluetooth, you need to add the permission to the android/app/src/main/AndroidManifest.xml:

	  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
 <application

and set the androidUsesFineLocation flag to true when scanning:

// Start scanning
flutterBlue.startScan(timeout: Duration(seconds: 4), androidUsesFineLocation: true);

// Stop scanning
flutterBlue.stopScan();

IOS

In the ios/Runner/Info.plist let’s add:

	<dict>
	    <key>NSBluetoothAlwaysUsageDescription</key>
	    <string>Need BLE permission</string>
	    <key>NSBluetoothPeripheralUsageDescription</key>
	    <string>Need BLE permission</string>
	    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
	    <string>Need Location permission</string>
	    <key>NSLocationAlwaysUsageDescription</key>
	    <string>Need Location permission</string>
	    <key>NSLocationWhenInUseUsageDescription</key>
	    <string>Need Location permission</string>

For location permissions on iOS see more at: https://developer.apple.com/documentation/corelocation/requesting_authorization_for_location_services

Reference #

FlutterBlue API #

BluetoothDevice API #

BluetoothCharacteristic API #

BluetoothDescriptor API #

Troubleshooting #

When I scan using a service UUID filter, it doesn't find any devices. #

Make sure the device is advertising which service UUID's it supports. This is found in the advertisement packet as UUID 16 bit complete list or UUID 128 bit complete list.