navideck/universal_ble/universal-ble-migrate-from-flutter-blue-plus

Migrating from flutter_blue_plus to universal_ble

This skill guides a mechanical, central-role migration from flutter_blue_plus (FlutterBluePlus, "FBP") to universal_ble (UniversalBle, "UB"). Both are Flutter BLE central-role plugins; most concepts map 1:1, but the object model and a handful of APIs differ.

Migration workflow

Work top to bottom, keeping the project compiling after each step:

1. Swap the dependency and imports.
2. Port adapter/availability state handling.
3. Port scanning.
4. Port connecting and service discovery.
5. Port read/write and descriptor access.
6. Port notifications/indications.
7. Replace FBP error handling with UB's typed exceptions.
8. Update platform setup (Windows especially).
9. Run flutter analyze and fix remaining references to flutter_blue_plus.

Search the codebase for FlutterBluePlus, BluetoothDevice, BluetoothCharacteristic, BluetoothDescriptor, ScanResult, Guid, and import 'package:flutter_blue_plus.

1. Dependency and imports

Remove flutter_blue_plus (and flutter_blue_plus_winrt if present) and add universal_ble:

dependencies:
  universal_ble: ^3.0.0

Replace imports:

// Before
import 'package:flutter_blue_plus/flutter_blue_plus.dart';
 
// After
import 'package:universal_ble/universal_ble.dart';

Windows previously required the separate flutter_blue_plus_winrt package; UB supports Android, iOS, macOS, Windows, Linux, and Web from the single package.

2. Mental model

Key differences to internalize:

• UUIDs are plain strings. No Guid wrapper. Pass "180D", "180d", or the

full 128-bit form interchangeably; UB normalizes everything to lowercase 128-bit (e.g. 0000180d-0000-1000-8000-00805f9b34fb). Use BleUuidParser.string(), BleUuidParser.number(), or BleUuidParser.compare() if you need explicit conversion.

• Two styles. Prefer the high-level BleDevice / extension API (closest to FBP).

The low-level UniversalBle.read(deviceId, service, characteristic, ...) statics are for deviceId-only workflows. Do not mix object methods with a device you never obtained as a BleDevice.

• Streams never close and never emit errors. Cancel subscriptions yourself.

3. Symbol mapping

Adapter / availability

FBP's initial adapter state is often unknown on iOS; UB reports unknown too, so keep any "wait for poweredOn" logic.

Scanning

Notable differences:

• No `timeout:` parameter. Implement the FBP timeout yourself:

``dart UniversalBle.startScan(scanFilter: ScanFilter(withServices: ['180D'])); Timer(const Duration(seconds: 15), () => UniversalBle.stopScan()); ``

• No list batching. scanStream emits one BleDevice per result, not a list.

There is no "clears between scans" distinction; maintain your own list if needed.

• No `withRemoteIds`. Filter scan results in Dart, or use ScanFilter.exclusionFilters.
• Android fine location: pass platformConfig: PlatformConfig(android: AndroidOptions(requestLocationPermission: true)) instead of androidUsesFineLocation:.

Devices

getSystemDevices on Apple requires withServices; without it UB defaults to generic 18XX services. You must still connect() to system devices before use.

Characteristics and descriptors

Boolean inversion: FBP uses withoutResponse:; UB uses withResponse:.

FBP's write(data) (no flag) means with response; UB's write(data) also

defaults to withResponse: true, so a direct call ports unchanged.

For indications, use characteristic.indications.subscribe() instead of notifications.subscribe().

Events API

FBP's global FlutterBluePlus.events.* streams map to UB streams/handlers:

Prefer the per-device/stream form (scanStream, connectionStream, characteristicValueStream, stream.listen) over the global onX handlers when you already hold the relevant object.

4. Before / after examples

Adapter state

// Before (flutter_blue_plus)
FlutterBluePlus.adapterState.listen((state) {
  if (state == BluetoothAdapterState.on) startScanning();
});
 
// After (universal_ble)
UniversalBle.availabilityStream.listen((state) {
  if (state == AvailabilityState.poweredOn) startScanning();
});

Filtered scan

// Before
FlutterBluePlus.onScanResults.listen((results) {
  for (final r in results) {
    print('${r.device.remoteId} ${r.advertisementData.advName}');
  }
});
await FlutterBluePlus.startScan(
  withServices: [Guid('180D')],
  withNames: ['Bluno'],
  timeout: const Duration(seconds: 15),
);
 
// After
UniversalBle.scanStream.listen((BleDevice d) {
  print('${d.deviceId} ${d.name}');
});
await UniversalBle.startScan(
  scanFilter: ScanFilter(withServices: ['180D'], withNamePrefix: ['Bluno']),
);
Timer(const Duration(seconds: 15), () => UniversalBle.stopScan());

Connect and discover services