flutter_ble_connection_manager library

A production-grade BLE connection lifecycle manager.

This package manages the complete lifecycle of a single BLE connection — from initial connection through readiness, including retry, recovery, and graceful teardown — built on top of flutter_blue_plus.

Core Responsibility

Move a BLE device from Disconnected to Application Ready in a predictable, observable and recoverable way.

Everything else belongs to the application or flutter_blue_plus.

Quick Start

import 'package:flutter_ble_connection_manager/flutter_ble_connection_manager.dart';

final manager = BleConnectionManager(
  device: myDevice,
  config: ConnectionConfig(
    onSetup: (device, token) async {
      await device.setNotifyValue(characteristic, true);
    },
  ),
);

await manager.connect(); // Completes when ready
// Use device directly: manager.device.readCharacteristic(...)
await manager.disconnect();
await manager.dispose();

Classes

BleConnectionManager: Manages the complete lifecycle of a single BLE connection.
BleLifecycleEvent: Base class for all lifecycle events emitted by BleConnectionManager.
CancellationToken: A cooperative cancellation mechanism for async operations.
ConnectionAttemptStarted: A connection attempt has started.
ConnectionConfig: Configuration for BleConnectionManager.
ConnectionEstablished: BLE transport connection established (GATT connected).
ConnectionFailed: A connection attempt failed.
ConnectionReady: The device is fully ready for application use.
Disconnected: The device is now disconnected.
DisconnectionInitiated: Disconnection process has been initiated.
ReconnectionStarted: Automatic reconnection has started after unexpected disconnection.
RecoveryPolicy: Defines the retry/reconnect behavior for connection failures.
RetryScheduled: A retry has been scheduled after a failed attempt.
ServiceDiscoveryCompleted: Service discovery completed successfully.
ServiceDiscoveryStarted: Service discovery has started.
SetupCompleted: The setup callback completed successfully.
SetupStarted: The setup callback has started executing.

Enums

BleConnectionState: The public lifecycle state of a BLE connection.
BleDisconnectReason: The reason a BLE connection ended.
ConnectionPhase: The phase of the connection lifecycle where a failure occurred.

Typedefs

SetupCallback = Future<void> Function(BluetoothDevice device, CancellationToken token): Signature for the setup callback executed after BLE connection and service discovery.

Exceptions / Errors

BleConnectionException: Base exception for all connection manager errors.
CancellationFailure: The operation was cancelled by a user-initiated disconnect.
CancelledException: Thrown when an operation is cancelled via CancellationToken.
ConfigurationError: Invalid configuration parameters.
ManagerDisposedError: Method called after BleConnectionManager.dispose.
SetupFailure: The app's setup callback threw an exception.
TimeoutFailure: A lifecycle phase exceeded its timeout duration.
TransportFailure: Platform-level BLE transport error (e.g., Android GATT error 133).

flutter_ble_connection_manager library

Core Responsibility

Quick Start

Classes

Enums

Typedefs

Exceptions / Errors

flutter_ble_connection_manager package

flutter_ble_connection_manager library