Universal BLE 3.0 is a breaking release for the Flutter Bluetooth package we use in BT Cam and Cinema Slate. It makes command queuing safer by default, gives device IDs one format across platforms, and reports connection errors in a single object.
Install it from pub.dev, or read the full changelog before upgrading.
Queues follow each platform’s behaviour
QueueType.auto is now the default for both central and peripheral APIs. Android, Web, and Linux use a queue per device, because their Bluetooth stacks reject or misbehave on overlapping operations. Other platforms run commands in parallel. If you switch over every QueueType value, add the new auto case.
Device IDs use one case
Scan results, connection and value callbacks, pairing events, and peripheral streams now emit device IDs in lower case on every platform. Android previously reported upper-case MAC addresses while Windows used lower case, so an ID stored on one platform did not match the same device on another. Web keeps its opaque browser tokens verbatim.
UniversalBle.canonicalDeviceId() returns the comparable form for the current platform, for maps and comparisons in your own code.
Errors travel with events
onConnectionChange now receives a BleConnectionChange with the device ID, connection state, a unified errorCode, and the raw nativeErrorCode from CoreBluetooth or Android’s GATT stack. connectionChangeStream and BleDevice.connectionChangeStream deliver the same updates. onValueChange likewise receives one BleCharacteristicValue, including the timestamp.
requestMtu now discovers services on demand on iOS, macOS, and Linux. Apple no longer reports the default ATT MTU as though it had been negotiated, and BleCapabilities.mtuRequiresServiceDiscovery tells you when discovery is needed first.
Pickers, scans, and data helpers
requestDevice opens the platform’s own device chooser: the browser’s Bluetooth picker on Web and the AccessorySetupKit picker on iOS 18 and later, where one call can offer several accessories. On iOS 18 and later, unpair now removes those accessories instead of failing.
Scanning gains skipDuplicates to report each device once per session, connectableOnly on ScanFilter, and a connectable property on BleDevice. Windows now reports non-connectable devices, enables extended advertisements, and delivers scan responses, so a peripheral that publishes its service UUID only in the scan response is no longer invisible.
Byte handling gets fuller conversions on Uint8List and Future<Uint8List>: signed and unsigned integers, floats, UTF-8, hex strings, byte offsets, and a byteData view. In peripheral mode, subscribedCentrals and subscribedCentralsStream show which centrals are subscribed to a characteristic.
Fixes behind the API
Several platforms had latent faults worth the upgrade on their own. The GATT client cache is now kept per Flutter engine rather than process-wide, so a connection made from a new engine cannot reuse a client from a destroyed one and report connected with no services. Android reuses an MTU already negotiated on the connection and reports every failed bond rather than only the first. iOS and macOS handle write-without-response backpressure. Windows disposes disconnected GATT objects off the UI thread and retries transient discovery failures.
Migrating from 2.x
The package now ships agent skills, installed with dart run skills@ get: universal-ble-setup for adding Bluetooth to an app, universal-ble-migrate-2-to-3 for the upgrade, and universal-ble-migrate-from-flutter-blue-plus for projects moving from flutter_blue_plus.
The changelog documents each breaking change with its replacement. Point releases since 3.0 add service-data scan filters and align ATT error reporting across platforms, so upgrade to the latest 3.x. Building a product that talks to hardware? Explore our connected-device expertise or discuss your project.