Flutter reactive BLE library

Flutter library that handles BLE operations for multiple devices.

Usage

The reactive BLE lib supports the following:

BLE device discovery
Observe host device BLE status
Establishing a BLE connection
Maintaining connection status of multiple BLE devices
Discover services(will be implicit)
Read / write a characteristic
Subscribe to a characteristic
Clear GATT cache
Negotiate MTU size

Device discovery

Discovering BLE devices should be done like this:

reactivebleclient.scanForDevices(withServices: [serviceId], scanMode: ScanMode.lowLatency).listen((device) {
      //code for handling results
    }, onError: () {
      //code for handling error
    });

The withServices parameter specifies the advertised service IDs to look for. If an empty list is passed, all the advertising devices will be reported. The parameter scanMode is only used on Android and follows the conventions described on ScanSettings Android reference page. If scanMode is omitted the balanced scan mode will be used.

Observe host device BLE status

Use statusStream to retrieve updates about the BLE status of the host device (the device running the app) . This stream can be used in order to determine if the BLE is turned on, on the device or if the required permissions are granted. Example usage:

_ble.statusStream.listen((status) {
  //code for handling status update
});

Use _ble.status to get the current status of the host device.

Establishing connection

To interact with a device you first need to establish a connection:

reactiveBleClient.connectToDevice(
      id: foundDeviceId,
      servicesWithCharacteristicsToDiscover: {serviceId: [char1, char2]},
      connectionTimeout: const Duration(seconds: 2),
    ).listen((connectionState) {
      // Handle connection state updates
    }, onError: (Object error) {
      // Handle a possible error
    });

For the required id parameter use a device ID retrieved through device discovery. On iOS the device ID is a UUID and on Android it is a MAC address (which may also be randomized, depending on the Android version). Supplying a map with service and characteristic IDs you want to discover may speed up the connection on iOS (otherwise all services and characteristics will be discovered). You can specify a connectionTimeout when the client will provide an error in case the connection cannot be established within the specified time.

There are numerous issues on the Android BLE stack that leave it hanging when you try to connect to a device that is not in range. To work around this issue use the method connectToAdvertisingDevice to first scan for the device and only if it is found connect to it.

reactiveBleClient.connectToAdvertisingDevice(
    id: foundDeviceId,
    withServices: [serviceUuid],
    prescanDuration: const Duration(seconds: 5),
    servicesWithCharacteristicsToDiscover: {serviceId: [char1, char2]},
    connectionTimeout: const Duration(seconds:  2),
  ).listen((connectionState) {
    // Handle connection state updates
  }, onError: (dynamic error) {
    // Handle a possible error
  });

Besides the normal connection parameters that are described above this function also has 2 additional required parameters: withServices and prescanDuration. PreScanDuration is the amount of time the ble stack will scan for the device before it attempts to connect (if the device is found)

Read / write characteristics

Read characteristic

final characteristic = QualifiedCharacteristic(serviceId: serviceUuid, characteristicId: characteristicUuid, deviceId: foundDeviceId);
final response = await reactiveBleClient.readCharacteristic(characteristic);

Write with response

Write a value to characteristic and await the response. The return value is a list of bytes (List<int>).

final characteristic = QualifiedCharacteristic(serviceId: serviceUuid, characteristicId: characteristicUuid, deviceId: foundDeviceId);
final response = await reactiveBleClient.writeCharacteristicWithResponse(characteristic, value: [0x00]);

Write without response

Use this operation if you want to execute multiple consecutive write operations in a small timeframe (e.g uploading firmware to device) or if the device does not provide a response. This is performance wise the fastest way of writing a value but there’s a chance that the BLE device cannot handle that many consecutive writes in a row, so do a writeWithResponse once in a while.

final characteristic = QualifiedCharacteristic(serviceId: serviceUuid, characteristicId: characteristicUuid, deviceId: foundDeviceId);
reactiveBleClient.writeCharacteristicWithoutResponse(characteristic, value: [0x00]);

Subscribe to characteristic

Instead of periodically reading the characteristic you can also listen to the notifications (in case the specific service supports it) in case the value changes.

final characteristic = QualifiedCharacteristic(serviceId: serviceUuid, characteristicId: characteristicUuid, deviceId: foundDeviceId);
   reactiveBleClient.subscribeToCharacteristic(characteristic).listen((data) {
      // code to handle incoming data
    }, onError: (dynamic error) {
      // code to handle errors
    });

Negotiate MTU size

You can increase or decrease the MTU size to reach a higher throughput. This operation will return the actual negotiated MTU size, but it is no guarantee that the requested size will be successfully negotiated. iOS has a default MTU size which cannot be negotiated, however you can still use this operation to get the current MTU.

final mtu = await reactiveBleClient.requestMtu(deviceId: foundDeviceId, mtu: 250);

Android specific operations

The following operations will only have effect for Android and are not supported by iOS. When using these operations on iOS the library will throw an UnSupportedOperationException.

Request connection priority

On Android you can send a connection priority update to the BLE device. The parameter priority is an enum that uses the same spec as the BluetoothGatt Android spec. Using highPerformance will increase battery usage but will speed up GATT operations. Be cautious when setting the priority when communicating with multiple devices because if you set highperformance for all devices the effect of increasing the priority will be lower.

await reactiveBleClient.requestConnectionPriority(deviceId: foundDeviceId, priority:  ConnectionPriority.highPerformance);

Clear GATT cache

The Android OS maintains a table per device of the discovered service in cache. Sometimes it happens that after a firmware update a new service is introduced but the cache is not updated. To invalidate the cache you can use the cleargattCache operation.

This is a hidden BLE operation and should be used with extreme caution since this operation is on the greylist.

await reactiveBleClient.clearGattCache(foundDeviceId);

FAQ

How to handle the BLE undeliverable exception

On Android side we use the RxAndroidBle library of Polidea. After migration towards RxJava 2 some of the errors are not routed properly to their listeners and thus this will result in a BLE Undeliverable Exception. The root cause lies in the threading of the Android OS. As workaround RxJava has a hook where you can set the global errorhandler. For more info see RxJava docs .

A default workaround implementation in the Flutter app (needs to be in the Java / Kotlin part e.g. mainactivity) is shown below. For an example (in Java) see Polidea RxAndroidBle sample.

BleException is coming from Polidea RxAndroidBle, so make sure your application declares the following depedency: implementation "com.polidea.rxandroidble2:rxandroidble:1.11.1"

RxJavaPlugins.setErrorHandler { throwable ->
  if (throwable is UndeliverableException && throwable.cause is BleException) {
    return@setErrorHandler // ignore BleExceptions since we do not have subscriber
  }
  else {
    throw throwable
  }
}

Which permissions are needed?

Android

For android the library uses the following permissions:

ACCESS_FINE_LOCATION : this permission is needed because old Nexus devices need location services in order to provide reliable scan results
BLUETOOTH : allows apps to connect to a paired bluetooth device
BLUETOOTH_ADMIN: allows apps to discover and pair bluetooth devices

These permissions are already added in the manifest of the this library and thus should automatically merge into the manifest of your app. It is not needed to add the permissions in your manifest.

iOS

For iOS it is required you add the following entries to the Info.plist file of your app. It is not allowed to access Core BLuetooth without this. See our example app on how to implement this. For more indepth details: Blog post on iOS bluetooth permissions

iOS13 and higher

NSBluetoothAlwaysUsageDescription

iOS12 and lower

NSBluetoothPeripheralUsageDescription

Download Details:

Author: PhilipsHue

Demo: https://developers.meethue.com/

Source Code: https://github.com/PhilipsHue/flutter_reactive_ble

#flutter #dart #mobile-apps