flutter_blue_plus 1.10.1

flutter_blue_plus: ^1.10.1 copied to clipboard

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

Foreward #

For simple BLE apps, you should also consider QuickBlue (https://pub.flutter-io.cn/packages/quick_blue). Fewer features, smaller codebase.

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 all supported platforms: iOS, macOS, Android. (Feel free to contribute Windows support!)

Usage #

Error Handling #

Flutter Blue Plus uses exceptions for error handling. Most functions can throw and must be handled.

See the Reference section below for a complete list of throwing function.

Scan for devices #

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

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

// Stop scanning
FlutterBluePlus.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.onValueReceived.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 #

Throwing functions #

All functions in FlutterBluePlus will throw exceptions when they encounter errors.

You MUST handle exceptions for bluetooth communication:

• BluetoothDevice.connect()
• BluetoothDevice.disconnect()
• BluetoothDevice.discoverServices()
• BluetoothDevice.requestMtu()
• BluetoothDevice.readRssi()
• BluetoothDevice.pair()
• BluetoothCharacteristic.read()
• BluetoothCharacteristic.write()
• BluetoothCharacteristic.setNotifyValue()
• BluetoothDescriptor.read()
• BluetoothDescriptor.read()

These functions also THROW:

• FlutterBluePlus.turnOn()
• FlutterBluePlus.turnOff()
• FlutterBluePlus.startScan()
• FlutterBluePlus.stopScan()
• FlutterBluePlus.scan()
• `BluetoothDevice.requestConnectionPriority
• BluetoothDevice.mtu
• BluetoothDevice.removeBond()
• BluetoothDevice.clearGattCache()
• BluetoothDevice.services
• BluetoothDevices.mtu

At the time of writing, these function DO NOT throw exceptions

• FlutterBluePlus.isAvailable
• FlutterBluePlus.isOn
• FlutterBluePlus.adapterState
• FlutterBluePlus.isScanning
• FlutterBluePlus.isScanningNow
• FlutterBluePlus.scanResults
• FlutterBluePlus.setLogLevel()
• BluetoothDevice.localName
• BluetoothDevice.connectionState
• BluetoothDevice.setPreferredPhy()
• BluetoothCharacteristic.isNotifying
• BluetoothCharacteristic.lastValue, uuid, & other simple accessors
• BluetoothDescriptor.lastValue, uuid, & other simple accessors

Streams #

All of the Bluetooth receive streams NEVER emit errors and NEVER close. They only emit on success. These include:

• BluetoothCharacteristic.onValueReceived
• BluetoothCharacteristic.lastValueStream
• BluetoothDescriptor.onValueReceived
• BluetoothDescriptor.lastValueStream

You can listen to BluetoothDevice.connectionState to know when to stop listening.

These streams also NEVER emit any errors of any kind.

• FlutterBluePlus.isScanning
• FlutterBluePlus.scanResults
• FlutterBluePlus.adapterState
• BluetoothDevice.connectionState
• BluetoothDevice.isDiscoveringServices
• BluetoothDevice.services (only throws on first call if remoteId is invalid)
• BluetoothDevices.mtu (only throws on first call if remoteId is invalid)

Troubleshooting #

The easiest way to debug issues in FlutterBluePlus is to first make local copy.

cd /user/downloads
git clone https://github.com/boskokg/flutter_blue_plus.git

then in pubspec.yaml add the repo by path:

  flutter_blue_plus:
    path: /user/downloads/flutter_blue_plus

Now you can edit FlutterBluePlus code and debug issues yourself.

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.