NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
pub.dev
pub.dev, #1166 most downloaded on pub.dev
A cross-platform (Android/iOS/macOS/Windows/Linux/Web) Bluetooth Low Energy (BLE) plugin for Flutter
Latest stable
3.3.0
Last release 11 days ago
10 Nov 2026
Ships fairly regularly
a new release about every 3 weeks
Nearly every release is documented
notes for 53 of 54 stable releases
Nothing withdrawn
no release was ever pulled
3 years old
54 releases · first in 2024
Drag across the ruler to compare, or tap a release to open it.
Apple: complete service discovery when a peripheral's GATT database holds multiple services with the same UUID (#369).
UniversalBleCentralStateRestoration (Boolean NO in Info.plist) while keeping the bluetooth-central background execution mode. When disabled, CBCentralManager is created without a restoration identifier and deferred lazily until first use (#370).feat: add autoConnect option to PeripheralAndroidOptions for configur…
feat: add autoConnect option to PeripheralAndroidOptions for configur…
UniversalBlePeripheral.setAutoConnect(bool) (defaulting to true) to configure whether BluetoothGattServer.connect(device, autoConnect) enables background auto-reconnection when a central connects (#368).readCharacteristic() is called, as writes already did, so a response that arrives before that call returns cannot be lost, and unregisters it again when the stack refuses the request (#364).updateCharacteristicValue returns after submitting notifications instead of blocking the platform thread until every subscribed client has been notified, so a slow or wedged link no longer freezes the UI. Failures while starting the operation are still returned; transport failures and truncated values are logged when error logging is enabled. Repeated failures for a characteristic are suppressed until a successful update, with recovery logged at info level. Failures observed while logging is disabled do not consume the first visible failure. Dart queues (including QueueType.perDevice and QueueType.global) and awaiting the returned future serialize submission only: Windows notification operations can overlap, and delivery order is not guaranteed (#363).BluetoothLEDevice and GATT services were closed on Flutter's UI thread, where Close can deadlock as disconnect teardown did before #333; they are now closed on a background thread. The next connect to the same address waits for that close, at most 10 seconds, then fails with a connection error instead of waiting for the Dart-side timeout (#358).instanceId. GATT allows several characteristics with the same UUID (HID exposes one Report characteristic per report), but the plugin addressed them by UUID and could only reach the first. Set BlePeripheralCharacteristic.instanceId to address each instance in updateCharacteristicValue and getSubscribedClients; read/write/descriptor callbacks and subscription events echo it back. UUID-only callers keep the first-match behaviour. OnPeripheralReadRequestWithInstance (and the write/descriptor variants, plus setReadRequestHandlersWithInstance etc.) receive the identity; the existing callbacks and setters are unchanged.GATT_FAILURE.onNotificationSent; Apple retries from peripheralManagerIsReady(toUpdateSubscribers). A release report can no longer be dropped or overtake its press when the transmit queue is full.value instead of failing.clearPendingNotifications for discarding unsent native updates. Android retains already submitted packets until their completion callback; Windows has no plugin-owned pending queue.Your coding agent can read these notes before it upgrades. Set up the MCP server →
Windows: Service Data advertised under a 128-bit UUID is reported under that UUID, and ScanFilter.withServiceData matches it. The 16 UUID bytes are li
ScanFilter.withServiceData matches it. The 16 UUID bytes are little-endian on air but were read in the order they arrive, so BleDevice.serviceData used a byte-reversed key and a filter with the real UUID found nothing (#356).Apple, Linux: discoverServices honours its timeout. Both gave up after a fixed 10 seconds, so a longer timeout could not help a peripheral that is slo
discoverServices honours its timeout. Both gave up after a fixed 10 seconds, so a longer timeout could not help a peripheral that is slow to answer. On Apple, timeout (or, without one, the global UniversalBle.timeout) is now passed on as the native limit, which AppleDiscoverServicesOptions(timeoutMillis:) in DiscoverServicesPlatformConfig.apple also sets directly, and then bounds the whole call when no timeout is given; without either, it stays 10 seconds. On Linux the discovery no longer has a limit of its own and is bounded by timeout alone, as on Android, Windows and Web, so one that runs out of time now fails with a TimeoutException rather than Failed to resolve services (#349).UniversalBleErrorCode (insufficientEncryption, insufficientAuthentication, readNotPermitted, ...), as Android does, instead of unknownError. The error code is still in details. Codes in CBErrorDomain are unchanged: its numbers overlap ATT's with other meanings (#348).UniversalBleErrorCode (insufficientEncryption, insufficientAuthentication, readNotPermitted, ...) instead of the generic failed, as Android already does. Characteristic/descriptor reads and writes and SetNotifiable are covered; service/characteristic discovery at connect time is unchanged. Application-defined codes 0x80-0xFF now report unknownError. The raw ATT error code is still in details.ATT error:, so an unrelated hex value in the message is no longer mistaken for the code.bluez to ^0.9.0.pigeon dev dependency to ^29.0.0.@asyncCallback, so the existing callback-based native implementations (Swift completion handlers, Kotlin callbacks) are kept as-is rather than migrated to native async/suspend. No public API change./utf-8. The Pigeon-generated sources contain UTF-8 doc comments, and MSVC decoded them using the system ANSI code page, so a clean build failed with C4819/C2220 on machines configured with a code page such as 936, 932, 949 or 950 (#354).BleDevice.services is now normalised to full 128-bit lower-case UUIDs on every platform, matching the keys of BleDevice.serviceData. Apple was the out
BleDevice.services is now normalised to full 128-bit lower-case UUIDs on every platform, matching the keys of BleDevice.serviceData. Apple was the outlier: it reported 16-bit advertised service UUIDs in their short form (180D), so the same field had a different shape per platform and stored keys or comparisons did not transfer between them. Compare against, or store, the 128-bit form; short (180D) and 0x-prefixed forms are still accepted as input. Entries that are not valid UUIDs are kept verbatim rather than dropped.ScanFilter.withServiceData to discover devices that carry a service UUID inside their advertising Service Data (the 0x16/0x20/0x21 advertising data types) — beacons such as Eddystone (0xFEAA) or the ATC_MiThermometer (0x181A) — which withServices cannot match, because it only looks at the advertised service UUID list (#57). The matching payloads are reported in BleDevice.serviceData. On Android and Apple this switches the scan to the software filter path (the platform cannot filter on Service Data), so more advertisements reach the app process; on Web it throws notSupported.withNamePrefix/withManufacturerData), instead of relying on CBUUID equality, which does not match a 16-bit advertised service UUID against the full 128-bit form the API sends. ScanFilter.withServices can now filter 16-bit services on that path.BleDevice.serviceData documentation to the README (the API existed but was undocumented).Fix the broken "Try it online" demo URL in the README.
Bump flutter_web_bluetooth to ^1.2.0.
flutter_web_bluetooth to ^1.2.0.startupTimeout instead of the hand-rolled abort/timeout workaround. unwatchAdvertisements now also aborts a pending advertisement startup.Breaking: Add QueueType.auto which auto-selects the best queueing strategy per platform: Android, Web, and Linux use a per-device queue (their BLE sta
QueueType.auto which auto-selects the best queueing strategy per platform: Android, Web, and Linux use a per-device queue (their BLE stacks reject or misbehave on overlapping operations), while all other platforms run commands in parallel. It is now the default for both UniversalBle and UniversalBlePeripheral, replacing the previous QueueType.global default. Any exhaustive switch over QueueType must handle the new auto value.getRemoteDevice needs upper-case). Callers that stored or compared an emitted ID by exact case (e.g. an Android upper-case MAC) must now lower-case it, or compare case-insensitively. Web is exempt: Web Bluetooth IDs are opaque, case-sensitive browser tokens rather than addresses, so they are emitted and matched verbatim. Follow-up to the case-insensitive matching in 2.1.1. Custom UniversalBlePlatform implementations must report the canonical form too: the event-stream filters now match the canonical id directly, so a platform that pushes a non-canonical id straight onto the exported stream controllers (instead of calling the update* handlers, which canonicalise) will no longer match a query made with a different casing. The same applies to peripheral mode: central device IDs in UniversalBlePeripheral streams, read/write request handlers, and getSubscribedClients results are emitted in lower-case, and IDs passed to updateCharacteristicValue / getMaximumNotifyLength are accepted in any case.onConnectionChange now receives a single BleConnectionChange (deviceId, isConnected, error) instead of three positional arguments. It also carries a unified errorCode (UniversalBleErrorCode.deviceDisconnected, connectionTimeout, connectionFailed, ...) and the raw nativeErrorCode (CBError.Code on Apple, GATT status on Android); a connection attempt that never succeeds is connectionFailed on both. Add connectionChangeStream and BleDevice.connectionChangeStream emitting the same updates per device; connectionStream is unchanged. UniversalBlePlatform.bleConnectionChangeStreamController (internal) now carries BleConnectionChange instead of a record.onValueChange now receives a single BleCharacteristicValue (deviceId, characteristicId, value, timestamp) instead of four positional arguments.BleConnectionParametersUpdated to BleConnectionParametersChange, aligning the payload with the …Change event naming. The onConnectionParametersChange callback and the model's fields are unchanged.unpair now removes an accessory authorized through AccessorySetupKit (it previously threw notSupported on iOS). Devices not managed by AccessorySetupKit fail with deviceNotFound.onPairingStateChange / pairingStateStream now fire. These platforms have no native bond API, so pair() drives them from its encrypted-characteristic probe: true when the probe succeeds, a failure event (false) when it throws. Without a pairingCommand the probe reads every readable characteristic and now fails if none can be read, rather than resolving successfully. The 0.12.0 changelog claimed this support, but the callback was never actually wired on those platforms until now.requestMtu now discovers the device's services on demand on iOS/macOS and Linux, instead of returning a misleading MTU (Apple reported the default ATT MTU, 23, as if it were the negotiated value) or failing with an unclear operationNotSupported (Linux). It is a no-op when the services were already discovered, so calling discoverServices first still works and is not required, and concurrent calls (including one racing a discoverServices) share a single discovery. timeout bounds each step, so a call that must discover first can take up to roughly twice timeout. Android and Windows read the MTU off the connection itself and are unchanged. Add BleCapabilities.mtuRequiresServiceDiscovery.requestDevice, a single entry point for the platform's native device picker: the browser's Bluetooth chooser on Web and the iOS 18+ AccessorySetupKit picker on Apple (configured via PickerPlatformConfig.apple), returning the selected BleDevice. Connect it with the existing connect(device.deviceId). AppleAccessorySetupOptions holds a list of AppleAccessoryPickerItems, so the picker can offer several accessories. Platforms without a native picker throw notSupported.AllowExtendedAdvertisements), with graceful fallback on unsupported OS versions or adapters.skipDuplicates to startScan to report each device only once per scan session — later sightings, including ones whose advertisement payload changed, are suppressed until the scan is restarted. Native filtering is applied where available (iOS/macOS, Android ScanSettings, Linux BlueZ DuplicateData) and the Dart layer de-duplicates on every platform so the behavior is consistent everywhere. Defaults to false (unchanged).connectable property to BleDevice.connectableOnly to ScanFilter to filter for connectable devices during scanning.startScan: Windows reports that packet with IsConnectable == false and it was dropped before reaching the caller.Uint8List and Future<Uint8List> extensions with comprehensive BLE data type conversions (int8, uint8, int16, uint16, int32, uint32, float32, float64, toUtf8, toHexString), byte offset support, and direct byteData view accessor.UniversalBle.canonicalDeviceId(deviceId), which returns a device ID in the comparable form for the current platform (lower-case on native platforms, verbatim on Web) — for keying a map or comparing IDs yourself.subscribedCentralsStream and subscribedCentrals getter to UniversalBlePeripheral to track and expose active central devices (BleCentral) subscribed to characteristics in peripheral mode.platformConfig to discoverServices(); AndroidDiscoverServicesOptions(clearGattCache: true) clears Android's GATT cache (BluetoothGatt.refresh()) before discovery. Ignored on other platforms.universal_ble package skills installable with dart run skills@ get: universal-ble-setup (add BLE to an app from scratch), universal-ble-migrate-2-to-3 (upgrade from 2.x), and universal-ble-migrate-from-flutter-blue-plus (migrate from flutter_blue_plus).connect() from one engine could short-circuit on a client created by a destroyed engine — returning a connection that reported as connected but whose service discovery came back empty. Each engine now sees only its own clients, and closeGattOnDetach releases only the clients the detaching engine created instead of every client in the process.BOND_NONE — not only the first per process. A failed pairing attempt is an event rather than a state, so onPairingStateChange no longer de-duplicates it against the cached pairing state (#325).Add isSubscribed and getSubscribedCharacteristics to check characteristic notification/indication subscription status in Central mode.
isSubscribed and getSubscribedCharacteristics to check characteristic notification/indication subscription status in Central mode.closeGattOnDetach connection option to release GATT clients when the app is killeddisconnect(), and report the real disconnect statusgetReadinessState() to check permissions and adapter power before advertising support, and throttle startAdvertising Bluetooth enable prompts to at most one dialog.Expose microsecond scan timestamps captured before Flutter event dispatch
BleCommandQueue support to UniversalBlePeripheral (queueType, timeout, clearQueue, and onQueueUpdate)updateCharacteristicValuediscoverServices callsHandle device IDs case-insensitively
BleCharacteristic equality and hashCode to compare properties by valueBleCharacteristic equality and hashCode to compare properties by valueRe-generate pigeon files
Re-generate pigeon files
queueId parameter to all APIsAppleConnectionOptions to connect (via ConnectionPlatformConfig) — map to CBConnectPeripheralOptionNotifyOnConnectionKey, NotifyOnDisconnectionKey and NotifyOnNotificationKey, so a suspended app is relaunched into the background to handle connection events (e.g. auto-reconnect while the phone is locked)legacy to AndroidOptions — set legacy: true to scan legacy BLE 4.x advertisements (e.g. ESP32) on API 26+; default (null/false) keeps extended-advertisement scanning unchanged from prior releasesaddServicesInScanResponse to PeripheralAndroidOptions - set addServicesInScanResponse: true to Put advertised service UUIDs in the scan response instead of the primary advertisementiOS: make Bluetooth state restoration optional by enabling it only when the bluetooth-central background mode is declared
bluetooth-central background mode is declaredCBCentralManager at launch only if Bluetooth permission is grantediOS/macOS: defer CBPeripheralManager creation until peripheral APIs are used, fixing Bluetooth permission prompt on app launch
CBPeripheralManager creation until peripheral APIs are used, fixing Bluetooth permission prompt on app launchbluetooth-central background mode in Info.plist (see README → Permissions → iOS / macOS).iOS/macOS: retain peripheral from retrievePeripherals to fix API MISUSE on connect
Add onConnectionParametersChange to notify when Android link-layer connection parameters change (API 26+)
onConnectionParametersChange to notify when Android link-layer connection parameters change (API 26+)pair() or when encryption requires itcallbackType, matchMode, and numOfMatches on AndroidOptions so callers can configure ScanSettings to defeat aggressive chip-side advert de-duplication on Pixel devices. callbackType accepts a List<AndroidScanCallbackType> (OR-folded on the native side) and includes a new allMatchesAutoBatch value (API 34+).Add peripheral mode on Android, iOS, macOS, and Windows
requestConnectionPriority to allow tuning BLE connection intervals on AndroidAdd autoConnect parameter to connect() method for automatic reconnection support on Android and iOS/macOS
autoConnect parameter to connect() method for automatic reconnection support on Android and iOS/macOSserviceData in BleDeviceAndroidScanMode and reportDelayMillis to AndroidOptions for scanningPermissionHandler is now activity-aware and succeeds silently if permissions are already granted when no activity is available* Add readRssi method
Nothing published for this version
BREAKING CHANGE: OnValueChange callback also includes timestamp
OnValueChange callback also includes timestampisScanning apihasPermissions apirequestPermissions api and auto ask permission on startScanwithDescriptors parameter in discoverServices APItimestamp in BleDevicesetLogLevel api for configuring logsdisconnect now waits for disconnection confirmation before returningFix device name resolution on Windows
exclusionFilters to filter out devices from scan resultsBREAKING CHANGE: connectionTimeout argument from connect, isPaired and pair API renamed to timeout
connectionTimeout argument from connect, isPaired and pair API renamed to timeouttimeout argument to all APIsclearQueue() APIFix BleCharacteristic.onValueReceived
BleCharacteristic.onValueReceivedFix writeWithoutResponse() which was not properly waiting for completion on Android and Apple
writeWithoutResponse() which was not properly waiting for completion on Android and AppleBREAKING CHANGE: bleDevice.isPaired is now bleDevice.paired
bleDevice.isPaired is now bleDevice.pairedreadValue in favor of readwriteValue in favor of writesetNotifiable in favor of subscribeNotifications, subscribeIndications, unsubscribegetBluetoothAvailabilityState reporting wrong Bluetooth status on browsers where Web Bluetooth can globally be disabledstartScan on web now throws a WebBluetoothGloballyDisabled exception if scanning cannot proceed due to Web Bluetooth being globally disabledGet and prefer advertised name of scanned devices on Apple
Add Streams: scanStream, availabilityStream, connectionStream, characteristicValueStream, pairingStateStream
scanStream, availabilityStream, connectionStream, characteristicValueStream, pairingStateStreamconnect api bug to detect proper connection stategetSystemDevices() on LinuxFix Windows crash when calling pair APIs with an unknown deviceId
Unable to establish connection on channel when hot restartingBREAKING CHANGE: payload is now payloadPrefix
payload is now payloadPrefixmask is now payloadMaskgetSystemDevices(withServices:) now sets several generic services by default as filter
getSystemDevices(withServices:) now sets several generic services by default as filtergetConnectionState on Android will now return BleConnectionState.disconnected if device is connected to the system but not to the appBREAKING CHANGE: bleDevice.name now filters out non-printable characters
bleDevice.name now filters out non-printable charactersbleDevice.rawNamedisableBluetooth APIstartScanscan too frequently and auto retry scan once sufficient time has passedonValueChanged events on Android 11 or earlierwithServices filterstartScanCharacteristic already notifying error. Subscribing to characteristic notifications multiple times is now handled safelyBREAKING CHANGE: scanFilter filters are now in OR relation
scanFilter filters are now in OR relationmanufacturerDataHead is removed from BleDeviceWebConfig is now WebOptionsManufacturerDataFilter.data is now ManufacturerDataFilter.payloadconnect() does not return a boolean anymore. It will throw error on connection failurepair() does not return a boolean anymore. It will throw error on connection failureonConnectionChange returns error as wellmanufacturerData is deprecated in BleDevice and will be removed in the futuremanufacturerDataList as List<ManufacturerData> in BleDeviceManufacturerData object instead of Uint8List for manufacturerDataconnectionStream API to get connection updates as streamgetSystemDevices()scanFilter handlingBREAKING CHANGE: unPair is now unpair
unPair is now unpaironPairingStateChange does not return error anymorepair(), isPaired and onPairingStateChange support for Apple and webconnect() and pair() now return a bool resultPlatformConfig property in StartScanWebConfig property in PlatformConfigReceive advertisement events on web
Unify UUID format across all platforms, 128-bit lowercase
BREAKING CHANGE: ScanResult is now BleDevice
ScanResult is now BleDevicegetConnectedDevices is now getSystemDevicesisPaired is now nullableonValueChanged is now onValueChangeonConnectionChanged is now onConnectionChangeconnectionState property to BleDeviceisSystemDevice property to BleDevice.perDevice queueAdd device name prefix filtering
Remove scan result caching on Windows
convertcollectionImprove service discovery on Apple
Improve manufacturer data discovery on Windows
Fix characteristic keying on linux allowing receiving data from multiple BLE devices at the same time
Fix a Windows issue where characteristics of certain services would not be discovered
Windows support has graduated from beta to stable
Fix Windows crash when no Bluetooth adapter is present
Add scan filter (withServices:) in startScan()
startScan()BleScanResultImprove error handling on Android, iOS, macOS, Windows, Linux and web
* Improve logging
Improve windows device name discovery
Add WebRequestOptionsBuilder.defaultServices for convenience when setting optionalServices when scanning on web
WebRequestOptionsBuilder.defaultServices for convenience when setting optionalServices when scanning on webRename onPairStateChange *> onPairingStateChange
* Improve readme
* Update supported platforms
* Initial release
One column per month.