universal_ble 0.9.3

A cross-platform (Android/iOS/macOS/Windows/Linux/Web) Bluetooth Low Energy (BLE) plugin for Flutter

Universal BLE

A cross-platform (Android/iOS/macOS/Windows/Linux/Web) Bluetooth Low Energy (BLE) plugin for Flutter.

Try it online, provided your browser supports Web Bluetooth.

Features

• Scanning
• Connecting
• Discovering Services
• Reading & Writing data
• Pairing
• Bluetooth Availability
• Command Queue
• Timeout

API Support Matrix

API	Android	iOS	macOS	Windows (beta)	Linux (beta)	Web
startScan/stopScan	✔️	✔️	✔️	✔️	✔️	✔️
connect/disconnect	✔️	✔️	✔️	✔️	✔️	✔️
getConnectedDevices	✔️	✔️	✔️	✔️	✔️	❌
discoverServices	✔️	✔️	✔️	✔️	✔️	✔️
readValue	✔️	✔️	✔️	✔️	✔️	✔️
writeValue	✔️	✔️	✔️	✔️	✔️	✔️
setNotifiable	✔️	✔️	✔️	✔️	✔️	✔️
pair/unPair	✔️	❌	❌	✔️	✔️	❌
onPairingStateChange	✔️	❌	❌	✔️	✔️	❌
enableBluetooth	✔️	❌	❌	✔️	✔️	❌
onAvailabilityChange	✔️	✔️	✔️	✔️	✔️	✔️
requestMtu	✔️	✔️	✔️	✔️	🚧	❌

Getting Started

Add universal_ble in your pubspec.yaml:

dependencies:
  universal_ble:

and import it wherever you want to use it:

import 'package:universal_ble/universal_ble.dart';

Scanning

// Set a scan result handler
UniversalBle.onScanResult = (scanResult) {
  // e.g. Use scan result to connect
}

// Perform a scan
UniversalBle.startScan();

// Or optionally add a scan filter
UniversalBle.startScan(
  scanFilter: ScanFilter(
      withServices: ["SERVICE_UUID"],
  )
);

// Stop scanning
UniversalBle.stopScan();

Already connected devices, either through previous sessions or connected through system settings, won't show up as scan results. You can list those devices using getConnectedDevices(). You still need to explicitly connect before using them.

// You can set `withServices` to narrow down the results
await UniversalBle.getConnectedDevices(withServices: []);

Connecting

// Connect to a device using the `deviceId` of the scanResult received from `UniversalBle.onScanResult`
String deviceId = scanResult.deviceId;
UniversalBle.connect(deviceId);

// Disconnect from a device
UniversalBle.disconnect(deviceId);

// Get notified for connection state changes
UniversalBle.onConnectionChanged = (String deviceId, BleConnectionState state) {
  print('OnConnectionChanged $deviceId, $state');
}

Discovering Services

// Discover services of a specific device
UniversalBle.discoverServices(deviceId);

Reading & Writing data

// Read data from a characteristic
UniversalBle.readValue(deviceId, serviceId, characteristicId);

// Write data to a characteristic
UniversalBle.writeValue(deviceId, serviceId, characteristicId, value);

// Subscribe to a characteristic
UniversalBle.setNotifiable(deviceId, serviceId, characteristicId, BleInputProperty.notification);

// Get characteristic updates in `onValueChanged`
UniversalBle.onValueChanged = (String deviceId, String characteristicId, Uint8List value) {
  print('onValueChanged $deviceId, $characteristicId, ${hex.encode(value)}');
}

// Unsubscribe from a characteristic
UniversalBle.setNotifiable(deviceId, serviceId, characteristicId, BleInputProperty.disabled);

Pairing

// Pair
UniversalBle.pair(deviceId);

// Get the pairing result
UniversalBle.onPairingStateChange = (String deviceId, bool isPaired, String? error) {
  // Handle Pairing state change
}

// Unpair
UniversalBle.unPair(deviceId);

// Check current pairing state
bool isPaired = UniversalBle.isPaired(deviceId);

Bluetooth Availability

// Get current Bluetooth availability state
AvailabilityState availabilityState = UniversalBle.getBluetoothAvailabilityState(); // e.g. poweredOff or poweredOn,

// Receive Bluetooth availability changes
UniversalBle.onAvailabilityChange = (state) {
  // Handle the new Bluetooth availability state
};

// Enable Bluetooth programmatically
UniversalBle.enableBluetooth();

Command Queue

By default, all commands will be executed in a queue. Each command will wait for the previous one to finish. Some platforms (e.g. Android) will fail to send consecutive commands without any delay between them so it is a good idea to leave to queue enabled.

// Disable queue
UniversalBle.queuesCommands = false;

Timeout

By default, all commands have a timeout of 10 seconds.

// Change timeout
UniversalBle.timeout = const Duration(seconds: 10);

// Disable timeout
UniversalBle.timeout = null;

Platform-Specific Setup

Android

Add the following permissions to your AndroidManifest.xml file:

<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="30" />

If you use BLUETOOTH_SCAN to determine location, modify your AndroidManifest.xml file to include the following entry:

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

If your app uses location services, remove android:maxSdkVersion="30" from the location permission tags.

iOS / macOS

Add NSBluetoothPeripheralUsageDescription and NSBluetoothAlwaysUsageDescription to Info.plist of your iOS and macOS app.

Add the Bluetooth capability to the macOS app from Xcode.

Web

On web, you have to add filters and specify optional services when scanning for devices. The parameter is ignored on other platforms.

UniversalBle.startScan(
  webRequestOptions: WebRequestOptionsBuilder.acceptAllDevices(
    optionalServices: ["SERVICE_UUID"],
  ),
);

Customizing Platform Implementation of UniversalBle

// Create a class that extends UniversalBlePlatform
class UniversalBleMock extends UniversalBlePlatform {
  // Implement all commands
}

UniversalBle.setInstance(UniversalBleMock());