Flutter Blue Plus

https://pub.dev/packages/flutter_blue_plus
Admin
Flutter Blue Plus is a Flutter plugin that provides Bluetooth Low Energy functionality for...
Tokens:14,636
Snippets:233
Trust Score:9.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Run the Example App

Source: https://pub.dev/packages/flutter_blue_plus

Commands to navigate to the example directory and launch the application.

```bash
cd ./example
flutter run
```

--------------------------------

### Example Proguard error output

Source: https://pub.dev/packages/flutter_blue_plus

This error indicates missing Proguard rules in release builds.

```text
PlatformException(startScan, Field androidScanMode_ for m0.e0 not found. Known fields are
 [private int m0.e0.q, private b3.b0$i m0.e0.r, private boolean m0.e0.s, private static final m0.e0 m0.e0.t,
 private static volatile b3.a1 m0.e0.u], java.lang.RuntimeException: Field androidScanMode_ for m0.e0 not found
```

--------------------------------

### startScan

Source: https://pub.dev/packages/flutter_blue_plus

Starts a scan for Ble devices.

```APIDOC
## startScan

### Description
Starts a scan for available Bluetooth Low Energy devices. This operation can fail.
```

--------------------------------

### Get System Devices

Source: https://pub.dev/packages/flutter_blue_plus

Retrieve devices connected to the system by any app, requiring a manual connection and service discovery for communication.

```dart
// `withServices` required on iOS, ignored on android
List<Guid> withServices = [Guid("180F")]; // e.g. Battery Service
List<BluetoothDevice> devs = await FlutterBluePlus.systemDevices(withServices);
for (var d in devs) {
    await d.connect(); // Must connect *our* app to the device
    await d.discoverServices();
}
```

--------------------------------

### Get Connected Devices

Source: https://pub.dev/packages/flutter_blue_plus

Retrieve a list of devices currently connected to the application.

```dart
List<BluetoothDevice> devs = FlutterBluePlus.connectedDevices;
for (var d in devs) {
    print(d);
}
```

--------------------------------

### Initialize Bluetooth Application State

Source: https://pub.dev/packages/flutter_blue_plus/example

Sets up the main application entry point and a stateful widget to monitor Bluetooth adapter status, switching between scan and off screens accordingly.

```dart
// Copyright 2017-2023, Charles Weinberger
// All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

import 'dart:async';

import 'package:flutter/material.dart';
import 'package:flutter_blue_plus/flutter_blue_plus.dart';

import 'screens/bluetooth_off_screen.dart';
import 'screens/scan_screen.dart';

void main() {
  FlutterBluePlus.setLogLevel(LogLevel.verbose, color: true);
  runApp(const FlutterBlueApp());
}

//
// This widget shows BluetoothOffScreen or
// ScanScreen depending on the adapter state
//
class FlutterBlueApp extends StatefulWidget {
  const FlutterBlueApp({super.key});

  @override
  State<FlutterBlueApp> createState() => _FlutterBlueAppState();
}

class _FlutterBlueAppState extends State<FlutterBlueApp> {
  BluetoothAdapterState _adapterState = BluetoothAdapterState.unknown;

  late StreamSubscription<BluetoothAdapterState> _adapterStateStateSubscription;

  @override
  void initState() {
    super.initState();
    _adapterStateStateSubscription = FlutterBluePlus.adapterState.listen((state) {
      _adapterState = state;
      if (mounted) {
        setState(() {});
      }
    });
  }

  @override
  void dispose() {
    _adapterStateStateSubscription.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    Widget screen = _adapterState == BluetoothAdapterState.on
        ? const ScanScreen()
        : BluetoothOffScreen(adapterState: _adapterState);

    return MaterialApp(
      color: Colors.lightBlue,
      debugShowCheckedModeBanner: false,
      home: screen,
      navigatorObservers: [BluetoothAdapterStateObserver()],
    );
  }
}

//
// This observer listens for Bluetooth Off and dismisses the DeviceScreen
//
class BluetoothAdapterStateObserver extends NavigatorObserver {
  StreamSubscription<BluetoothAdapterState>? _adapterStateSubscription;

  @override
  void didPush(Route route, Route? previousRoute) {
    super.didPush(route, previousRoute);
    if (route.settings.name == '/DeviceScreen') {
      // Start listening to Bluetooth state changes when a new route is pushed
      _adapterStateSubscription ??= FlutterBluePlus.adapterState.listen((state) {
        if (state != BluetoothAdapterState.on) {
          // Pop the current route if Bluetooth is off
          navigator?.pop();
        }
      });
    }
  }

  @override
  void didPop(Route route, Route? previousRoute) {
    super.didPop(route, previousRoute);
    // Cancel the subscription when the route is popped
    _adapterStateSubscription?.cancel();
    _adapterStateSubscription = null;
  }
}
```

--------------------------------

### Add flutter_blue_plus dependency

Source: https://pub.dev/packages/flutter_blue_plus

Use the command line to add the plugin to your project.

```bash
flutter pub add flutter_blue_plus:x.y.z
```

--------------------------------

### device.connect()

Source: https://pub.dev/packages/flutter_blue_plus

Establishes a connection to the Bluetooth device. Supports auto-connect functionality.

```APIDOC
## connect(autoConnect: bool, mtu: int?)

### Description
Connects to the Bluetooth device. When autoConnect is true, the connection will be attempted whenever the device is found.

### Parameters
- **autoConnect** (bool) - Optional - If true, automatically connects when the device is discovered.
- **mtu** (int) - Optional - The MTU size to request upon connection.
```

--------------------------------

### turnOn

Source: https://pub.dev/packages/flutter_blue_plus

Turns on the bluetooth adapter.

```APIDOC
## turnOn

### Description
Attempts to turn on the bluetooth adapter. This operation can fail.
```

--------------------------------

### setOptions

Source: https://pub.dev/packages/flutter_blue_plus

Sets configurable bluetooth options for the plugin.

```APIDOC
## setOptions

### Description
Sets configurable bluetooth options for the plugin. Used for advanced configurations like enabling background state restoration.

### Parameters
- **restoreState** (bool) - Optional - If set to true, enables background state restoration.
```

--------------------------------

### device.discoverServices()

Source: https://pub.dev/packages/flutter_blue_plus

Retrieves the list of services available on the connected device.

```APIDOC
## discoverServices()

### Description
Discovers all services provided by the device. This must be called after every re-connection.
```

--------------------------------

### Initialize and Monitor Bluetooth State in Flutter

Source: https://pub.dev/packages/flutter_blue_plus_windows/example

Sets up the Bluetooth adapter state listener and manages navigation based on the adapter's availability.

```dart
// Copyright 2017-2023, Charles Weinberger & Paul DeMarco.
// All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

import 'dart:async';

import 'package:flutter/material.dart';
import 'package:flutter_blue_plus_windows/flutter_blue_plus_windows.dart';

import 'screens/bluetooth_off_screen.dart';
import 'screens/scan_screen.dart';

void main() {
  FlutterBluePlus.setLogLevel(LogLevel.verbose, color: true);
  runApp(const FlutterBlueApp());
}

//
// This widget shows BluetoothOffScreen or
// ScanScreen depending on the adapter state
//
class FlutterBlueApp extends StatefulWidget {
  const FlutterBlueApp({Key? key}) : super(key: key);

  @override
  State<FlutterBlueApp> createState() => _FlutterBlueAppState();
}

class _FlutterBlueAppState extends State<FlutterBlueApp> {
  BluetoothAdapterState _adapterState = BluetoothAdapterState.unknown;

  late StreamSubscription<BluetoothAdapterState> _adapterStateStateSubscription;

  @override
  void initState() {
    super.initState();
    _adapterStateStateSubscription = FlutterBluePlus.adapterState.listen((state) {
      _adapterState = state;
      if (mounted) {
        setState(() {});
      }
    });
  }

  @override
  void dispose() {
    _adapterStateStateSubscription.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    Widget screen = _adapterState == BluetoothAdapterState.on
        ? const ScanScreen()
        : BluetoothOffScreen(adapterState: _adapterState);

    return MaterialApp(
      color: Colors.lightBlue,
      home: screen,
      navigatorObservers: [BluetoothAdapterStateObserver()],
    );
  }
}

//
// This observer listens for Bluetooth Off and dismisses the DeviceScreen
//
class BluetoothAdapterStateObserver extends NavigatorObserver {
  StreamSubscription<BluetoothAdapterState>? _adapterStateSubscription;

  @override
  void didPush(Route route, Route? previousRoute) {
    super.didPush(route, previousRoute);
    if (route.settings.name == '/DeviceScreen') {
      // Start listening to Bluetooth state changes when a new route is pushed
      _adapterStateSubscription ??= FlutterBluePlus.adapterState.listen((state) {
        if (state != BluetoothAdapterState.on) {
          // Pop the current route if Bluetooth is off
          navigator?.pop();
        }
      });
    }
  }

  @override
  void didPop(Route route, Route? previousRoute) {
    super.didPop(route, previousRoute);
    // Cancel the subscription when the route is popped
    _adapterStateSubscription?.cancel();
    _adapterStateSubscription = null;
  }
}
```

--------------------------------

### Import the package

Source: https://pub.dev/packages/flutter_blue_plus_darwin/install

Include the package in your Dart files to access its functionality.

```dart
import 'package:flutter_blue_plus_darwin/flutter_blue_plus_darwin.dart';
```

--------------------------------

### Add dependency via command line

Source: https://pub.dev/packages/flutter_blue_plus_winrt/install

Use the flutter pub add command to automatically add the package to your project.

```bash
 $ flutter pub add flutter_blue_plus_winrt
```

--------------------------------

### Add package dependency

Source: https://pub.dev/packages/flutter_blue_plus/changelog

Command to add the flutter_blue_plus package to a project.

```text
flutter_blue_plus: ^2.3.11
```

--------------------------------

### Handle iOS Adapter State Initialization

Source: https://pub.dev/packages/flutter_blue_plus

Wait for the adapter state to transition from unknown on iOS.

```dart
if (await FlutterBluePlus.adapterState.first == BluetoothAdapterState.unknown) {
    await Future.delayed(const Duration(seconds: 1));
}

```

--------------------------------

### Add dependency via command line

Source: https://pub.dev/packages/flutter_blue_plus_android/install

Use this command in your terminal to automatically add the package to your project.

```bash
 $ flutter pub add flutter_blue_plus_android
```

--------------------------------

### Configure iOS Info.plist permissions

Source: https://pub.dev/packages/flutter_blue_plus

Add the Bluetooth usage description to your Info.plist file.

```xml
<dict>
...
    <key>NSBluetoothAlwaysUsageDescription</key>
    <string>This app needs Bluetooth to function</string>
...
</dict>
```

--------------------------------

### Configure Android Proguard rules

Source: https://pub.dev/packages/flutter_blue_plus

Add this rule to your proguard-rules.pro file to prevent release build errors.

```text
-keep class com.lib.flutter_blue_plus.* { *; }
```

--------------------------------

### Configure Android minSdkVersion

Source: https://pub.dev/packages/flutter_blue_plus

Set the minimum SDK version to 21 in your build.gradle file.

```gradle
android {
  defaultConfig {
     minSdkVersion: 21
```

--------------------------------

### Configure Windows dependencies

Source: https://pub.dev/packages/flutter_blue_plus/changelog

Required dependency configuration for Windows users when winrt is not an explicit dependency.

```yaml
dependencies:
  flutter_blue_plus: ^2.3.1
  flutter_blue_plus_winrt: ^0.19
```

--------------------------------

### Configure Android Manifest permissions (With Fine Location)

Source: https://pub.dev/packages/flutter_blue_plus

Add these permissions to AndroidManifest.xml when location services or iBeacons are required.

```xml
<!-- Tell Google Play Store that your app uses Bluetooth LE
     Set android:required="true" if bluetooth is necessary -->
<uses-feature android:name="android.hardware.bluetooth_le" android:required="false" />

<!-- New Bluetooth permissions in Android 12
https://developer.android.com/about/versions/12/features/bluetooth-permissions -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"/>
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!-- legacy for Android 11 or lower -->
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />

<!-- legacy for Android 9 or lower -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="28" />
```

--------------------------------

### Wait for Bluetooth Adapter State

Source: https://pub.dev/packages/flutter_blue_plus

Ensure the Bluetooth adapter is fully initialized before proceeding.

```dart
await FlutterBluePlus.adapterState.where((state) => state == BluetoothAdapterState.on).first;
```

--------------------------------

### Search System Devices

Source: https://pub.dev/packages/flutter_blue_plus

Retrieve and iterate through devices already connected to the system.

```dart
// search system devices. i.e. any device connected to by *any* app
List<BluetoothDevice> system = await FlutterBluePlus.systemDevices;
for (var d in system) {
    print('${r.device.platformName} already connected to! ${r.device.remoteId}');
    if (d.platformName == "myBleDevice") {
         await r.connect(); // must connect our app
    }
}
```

--------------------------------

### Clone FlutterBluePlus Repository

Source: https://pub.dev/packages/flutter_blue_plus

Commands to clone the repository for local debugging.

```bash
cd /user/downloads
git clone https://github.com/chipweinberger/flutter_blue_plus.git

```

--------------------------------

### Configure Local Path in pubspec.yaml

Source: https://pub.dev/packages/flutter_blue_plus

Add the local path dependency to your project configuration.

```yaml
  flutter_blue_plus:
    path: /user/downloads/flutter_blue_plus

```

--------------------------------

### Configure iOS Background Modes

Source: https://pub.dev/packages/flutter_blue_plus

Add this key-value pair to your Info.plist to allow the system to wake your app for BLE events.

```xml
<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
</array>
```

--------------------------------

### Configure Log Levels

Source: https://pub.dev/packages/flutter_blue_plus

Adjust logging verbosity and listen to log streams for debugging purposes.

```dart
// if your terminal doesn't support color you'll see annoying logs like `\x1B[1;35m`
FlutterBluePlus.setLogLevel(LogLevel.verbose, color:false);

// optional
FlutterBluePlus.logs.listen((String s){
    // send logs anywhere you want
});
```

--------------------------------

### Manage Device Connection and Disconnection

Source: https://pub.dev/packages/flutter_blue_plus

Handles connection state monitoring, automatic cleanup of subscriptions upon disconnection, and manual connection/disconnection.

```dart
// listen for disconnection
var subscription = device.connectionState.listen((BluetoothConnectionState state) async {
    if (state == BluetoothConnectionState.disconnected) {
        // 1. typically, start a periodic timer that tries to 
        //    reconnect, or just call connect() again right now
        // 2. you must always re-discover services after disconnection!
        print("${device.disconnectReason?.code} ${device.disconnectReason?.description}");
    }
});

// cleanup: cancel subscription when disconnected
//   - [delayed] This option is only meant for `connectionState` subscriptions.  
//     When `true`, we cancel after a small delay. This ensures the `connectionState` 
//     listener receives the `disconnected` event.
//   - [next] if true, the the stream will be canceled only on the *next* disconnection,
//     not the current disconnection. This is useful if you setup your subscriptions
//     before you connect.
device.cancelWhenDisconnected(subscription, delayed:true, next:true);

// Connect to the device
await device.connect();

// Disconnect from device
await device.disconnect();

// cancel to prevent duplicate listeners
subscription.cancel();
```

--------------------------------

### Importing Flutter Blue Plus for Windows

Source: https://pub.dev/packages/flutter_blue_plus_windows

Replace the standard Flutter Blue Plus import with the Windows-specific version, or use a hide clause to avoid conflicts.

```dart
// instead of import 'package:flutter_blue_plus/flutter_blue_plus.dart';
import 'package:flutter_blue_plus_windows/flutter_blue_plus_windows.dart';

// Alternatively, you can hide FlutterBluePlus when importing the FBP statement
import 'package:flutter_blue_plus/flutter_blue_plus.dart' hide FlutterBluePlus;
import 'package:flutter_blue_plus_windows/flutter_blue_plus_windows.dart';
```

--------------------------------

### isSupported

Source: https://pub.dev/packages/flutter_blue_plus

Checks whether the device supports Bluetooth.

```APIDOC
## isSupported

### Description
Checks whether the current device supports Bluetooth functionality.
```

--------------------------------

### Create and Remove Bond (Android Only)

Source: https://pub.dev/packages/flutter_blue_plus

Manage device bonding states manually, though platform-level automatic bonding is standard.

```dart
final bsSubscription = device.bondState.listen((value) {
    print("$value prev:{$device.prevBondState}");
});

// cleanup: cancel subscription when disconnected
device.cancelWhenDisconnected(bsSubscription);

// Force the bonding popup to show now (Android Only) 
await device.createBond();

// remove bond
await device.removeBond();
```

--------------------------------

### device.requestMtu()

Source: https://pub.dev/packages/flutter_blue_plus

Manually requests a change to the MTU size.

```APIDOC
## requestMtu(mtu: int)

### Description
Requests a specific MTU size from the device. Primarily used on Android.
```

--------------------------------

### Configure Multi-Device Performance

Source: https://pub.dev/packages/flutter_blue_plus

Set the operation queue mode to per-device to allow concurrent BLE operations across multiple devices.

```dart
// note: call this function before starting any other FBP work
FlutterBluePlus.setOperationQueueMode(OperationQueueMode.perDevice);
```

--------------------------------

### Add dependency via terminal

Source: https://pub.dev/packages/flutter_blue_plus_darwin/install

Use the Flutter CLI to add the package to your project dependencies.

```bash
$ flutter pub add flutter_blue_plus_darwin
```

--------------------------------

### Add dependency via CLI

Source: https://pub.dev/packages/flutter_blue_plus/install

Use this command in your terminal to automatically add the package to your pubspec.yaml file.

```bash
$ flutter pub add flutter_blue_plus
```

--------------------------------

### Connecting to a device

Source: https://pub.dev/packages/flutter_blue_plus_windows

Filter scanned results by device name and initiate a connection to the target device.

```dart
final scannedDevice = scannedDevices
    .where((scanResult) => scanResult.device.platformName == DEVICE_NAME)
    .firstOrNull;
final device = scannedDevice?.device;
device?.connect();
```

--------------------------------

### Configure Android Manifest permissions (No Location)

Source: https://pub.dev/packages/flutter_blue_plus

Add these permissions to AndroidManifest.xml when location services are not required.

```xml
<!-- Tell Google Play Store that your app uses Bluetooth LE
     Set android:required="true" if bluetooth is necessary -->
<uses-feature android:name="android.hardware.bluetooth_le" android:required="false" />

<!-- New Bluetooth permissions in Android 12
https://developer.android.com/about/versions/12/features/bluetooth-permissions -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

<!-- legacy for Android 11 or lower -->
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30"/>

<!-- legacy for Android 9 or lower -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="28" />
```

--------------------------------

### Discover Services

Source: https://pub.dev/packages/flutter_blue_plus

Retrieves available services from a connected device. Must be called after every reconnection.

```dart
// Note: You must call discoverServices after every re-connection!
List<BluetoothService> services = await device.discoverServices();
services.forEach((service) {
    // do something with service
});
```

--------------------------------

### BluetoothDevice API

Source: https://pub.dev/packages/flutter_blue_plus

Methods and properties for managing Bluetooth device connections, services, and state.

```APIDOC
## BluetoothDevice API

### Methods
- **connect()** - Establishes a connection to the device.
- **disconnect()** - Cancels an active or pending connection.
- **discoverServices()** - Discover services on the device.
- **readRssi()** - Read RSSI from a connected device.
- **requestMtu(int mtu)** - Request to change the MTU for the device (Android only).
- **requestConnectionPriority()** - Request high priority, low latency connection (Android only).
- **createBond()** - Force a system pairing dialogue.
- **removeBond()** - Remove Bluetooth Bond of device.
- **setPreferredPhy()** - Set preferred RX and TX phy.
- **clearGattCache()** - Clear android cache of service discovery results.

### Properties
- **platformName** - The platform preferred name of the device.
- **advName** - The advertised name of the device.
- **isConnected** - Boolean, is this device currently connected to your app?
- **isDisconnected** - Boolean, is this device currently disconnected from your app?
- **connectionState** - Stream of connection changes.
- **servicesList** - The current list of available services.
- **onServicesReset** - Stream, services changed and must be rediscovered.
- **mtu** - Stream of current mtu value.
- **mtuNow** - The current mtu value.
- **bondState** - Stream of device bond state.
```

--------------------------------

### BluetoothDescriptor API

Source: https://pub.dev/packages/flutter_blue_plus

Methods and properties for interacting with Bluetooth descriptors.

```APIDOC
## BluetoothDescriptor API

### Methods
- **read()** - Retrieves the value of the descriptor.
- **write(List<int> value)** - Writes the value of the descriptor.

### Properties
- **uuid** - The uuid of descriptor.
- **onValueReceived** - Stream of descriptor value reads & writes.
- **lastValue** - The most recent value of the descriptor.
- **lastValueStream** - Stream of onValueReceived + writes.
```

--------------------------------

### Check MTU Size

Source: https://pub.dev/packages/flutter_blue_plus

Verify the current MTU size to ensure it is large enough to accommodate the message being received.

```dart
device.mtu
```

--------------------------------

### Enable Auto Connect

Source: https://pub.dev/packages/flutter_blue_plus

Configures a device to automatically reconnect when found, requiring manual monitoring of the connection state.

```dart
// enable auto connect
//  - note: autoConnect is incompatible with mtu argument, so you must call requestMtu yourself
await device.connect(autoConnect:true, mtu:null)

// wait until connection
//  - when using autoConnect, connect() always returns immediately, so we must
//    explicity listen to `device.connectionState` to know when connection occurs 
await device.connectionState.where((val) => val == BluetoothConnectionState.connected).first;

// disable auto connect
await device.disconnect()
```

--------------------------------

### Manage Bluetooth State

Source: https://pub.dev/packages/flutter_blue_plus

Check hardware support, monitor adapter state changes, and programmatically enable Bluetooth on Android.

```dart
// first, check if bluetooth is supported by your hardware
// Note: The platform is initialized on the first call to any FlutterBluePlus method.
if (await FlutterBluePlus.isSupported == false) {
    print("Bluetooth not supported by this device");
    return;
}

// handle bluetooth on & off
// note: for iOS the initial state is typically BluetoothAdapterState.unknown
// note: if you have permissions issues you will get stuck at BluetoothAdapterState.unauthorized
var subscription = FlutterBluePlus.adapterState.listen((BluetoothAdapterState state) {
    print(state);
    if (state == BluetoothAdapterState.on) {
        // usually start scanning, connecting, etc
    } else {
        // show an error to the user, etc
    }
});

// turn on bluetooth ourself if we can
// for iOS, the user controls bluetooth enable/disable
if (!kIsWeb && Platform.isAndroid) {
    await FlutterBluePlus.turnOn();
}

// cancel to prevent duplicate listeners
subscription.cancel();
```

--------------------------------

### Manage MTU Settings

Source: https://pub.dev/packages/flutter_blue_plus

Monitors MTU changes and manually requests a specific MTU size on Android devices.

```dart
final subscription = device.mtu.listen((int mtu) {
    // iOS: initial value is always 23, but iOS will quickly negotiate a higher value
    print("mtu $mtu");
});

// cleanup: cancel subscription when disconnected
device.cancelWhenDisconnected(subscription);

// You can also manually change the mtu yourself.
if (!kIsWeb && Platform.isAndroid) {
    await device.requestMtu(512);
}
```

--------------------------------

### BluetoothCharacteristic API

Source: https://pub.dev/packages/flutter_blue_plus

Methods and properties for interacting with Bluetooth characteristics.

```APIDOC
## BluetoothCharacteristic API

### Methods
- **read()** - Retrieves the value of the characteristic.
- **write(List<int> value)** - Writes the value of the characteristic.
- **setNotifyValue(bool notify)** - Sets notifications or indications on the characteristic.

### Properties
- **uuid** - The uuid of characteristic.
- **isNotifying** - Are notifications or indications currently enabled.
- **onValueReceived** - Stream of characteristic value updates.
- **lastValue** - The most recent value of the characteristic.
- **lastValueStream** - Stream of onValueReceived + writes.
```

--------------------------------

### characteristic.write()

Source: https://pub.dev/packages/flutter_blue_plus

Writes data to a Bluetooth characteristic.

```APIDOC
## write(data: List<int>, allowLongWrite: bool)

### Description
Writes a list of bytes to the characteristic.

### Parameters
- **data** (List<int>) - Required - The byte array to write.
- **allowLongWrite** (bool) - Optional - Enables long write protocol for data up to 512 bytes.
```

--------------------------------

### FlutterBluePlus.systemDevices

Source: https://pub.dev/packages/flutter_blue_plus

Retrieves a list of devices currently connected to the system by any application.

```APIDOC
## systemDevices(List<Guid> withServices)

### Description
Gets devices connected to the system by any app. Note that the app must still call connect() and discoverServices() to communicate with these devices.

### Method
Async Method

### Parameters
- **withServices** (List<Guid>) - Required - List of service GUIDs to filter by (required on iOS, ignored on Android).
```

--------------------------------

### Perform Split Write

Source: https://pub.dev/packages/flutter_blue_plus

Splits large data payloads into chunks based on the current MTU size for reliable transmission.

```dart
import 'dart:math';
// split write should be used with caution.
//    1. due to splitting, `characteristic.read()` will return partial data.
//    2. it can only be used *with* response to avoid data loss
//    3. The characteristic must be designed to support split data
extension splitWrite on BluetoothCharacteristic {
  Future<void> splitWrite(List<int> value, {int timeout = 15}) async {
    int chunk = min(device.mtuNow - 3, 512); // 3 bytes BLE overhead, 512 bytes max
    for (int i = 0; i < value.length; i += chunk) {
      List<int> subvalue = value.sublist(i, min(i + chunk, value.length));
      await write(subvalue, withoutResponse:false, timeout: timeout);
    }
  }
}
```

--------------------------------

### Unreferenced _hexEncode function warning

Source: https://pub.dev/packages/flutter_blue_plus_windows/score

Static analysis warning indicating that the _hexEncode function in lib/src/windows/util.dart is not referenced.

```dart
  ╷
3 │ String _hexEncode(List<int> numbers) {
  │        ^^^^^^^^^^
  ╵
```

--------------------------------

### Unreferenced _hexDecode function warning

Source: https://pub.dev/packages/flutter_blue_plus_windows/score

Static analysis warning indicating that the _hexDecode function in lib/src/windows/util.dart is not referenced.

```dart
  ╷
9 │ List<int> _hexDecode(String hex) {
  │           ^^^^^^^^^^
  ╵
```

--------------------------------

### Manage Adapter State Listeners

Source: https://pub.dev/packages/flutter_blue_plus

Prevent multiple listeners by properly managing and canceling subscriptions.

```dart
// tip: using ??= makes it easy to only make new listener when currently null
final subscription ??= FlutterBluePlus.adapterState.listen((value) {
    // ...
});

// also, make sure you cancel the subscription when done!
subscription.cancel()
```

--------------------------------

### Subscribe to a characteristic

Source: https://pub.dev/packages/flutter_blue_plus

Listen to characteristic updates via onValueReceived and manage subscription lifecycle with cancelWhenDisconnected.

```dart
final subscription = characteristic.onValueReceived.listen((value) {
    // onValueReceived is updated:
    //   - anytime read() is called
    //   - anytime a notification arrives (if subscribed)
});

// cleanup: cancel subscription when disconnected
device.cancelWhenDisconnected(subscription);

// subscribe
// Note: If a characteristic supports both **notifications** and **indications**,
// it will default to **notifications**. This matches how CoreBluetooth works on iOS.
await characteristic.setNotifyValue(true);
```

--------------------------------

### Scanning for Bluetooth devices

Source: https://pub.dev/packages/flutter_blue_plus_windows

Initiate a scan for a specified duration and collect results from the scanResults stream.

```dart
final scannedDevices = <ScanResult>{};

const timeout = Duration(seconds: 3);
FlutterBluePlus.startScan(timeout: timeout);

final sub = FlutterBluePlus.scanResults.expand((e)=>e).listen(scannedDevices.add);

await Future.delayed(timeout);
sub.cancel();
scannedDevices.forEach(print);
```

--------------------------------

### characteristic.read()

Source: https://pub.dev/packages/flutter_blue_plus

Reads the current value of a Bluetooth characteristic.

```APIDOC
## read()

### Description
Reads the data from the characteristic. Ensure the characteristic has the 'read' property enabled.
```

--------------------------------

### Listen to Global Events API

Source: https://pub.dev/packages/flutter_blue_plus

Monitor events across all devices simultaneously using the global events stream.

```dart
// listen to *any device* connection state changes 
FlutterBluePlus.events.onConnectionStateChanged.listen((event)) {
    print('${event.device} ${event.connectionState}');
}
```

--------------------------------

### Configure Android Bluetooth Scan Permissions

Source: https://pub.dev/packages/flutter_blue_plus/changelog

Add this entry to the Android Manifest to opt back into the neverForLocation behavior for Bluetooth scanning.

```xml
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"
  android:usesPermissionFlags="neverForLocation" />
```

--------------------------------

### Handle Services Changed Characteristic

Source: https://pub.dev/packages/flutter_blue_plus

Listen for services reset events to trigger re-discovery of device services.

```dart
// - uses the GAP Services Changed characteristic (0x2A05)
// - you must call discoverServices() again
device.onServicesReset.listen(() async {
    print("Services Reset");
    await device.discoverServices();
});
```

--------------------------------

### turnOff

Source: https://pub.dev/packages/flutter_blue_plus

Turns off the bluetooth adapter.

```APIDOC
## turnOff

### Description
Attempts to turn off the bluetooth adapter. This operation can fail.
```

--------------------------------

### Enable Background State Restoration

Source: https://pub.dev/packages/flutter_blue_plus

Call this before any other FlutterBluePlus operations to ensure the app can be woken up by the OS after being killed.

```dart
FlutterBluePlus.setOptions(restoreState: true);
```

--------------------------------

### Scan for BLE Devices

Source: https://pub.dev/packages/flutter_blue_plus

Listen for scan results, manage subscriptions, and initiate a filtered scan with a timeout.

```dart
// listen to scan results
// Note: `onScanResults` clears the results between scans. You should use
//  `scanResults` if you want the current scan results *or* the results from the previous scan.
var subscription = FlutterBluePlus.onScanResults.listen((results) {
        if (results.isNotEmpty) {
            ScanResult r = results.last; // the most recently found device
            print('${r.device.remoteId}: "${r.advertisementData.advName}" found!');
        }
    },
    onError: (e) => print(e),
);

// cleanup: cancel subscription when scanning stops
FlutterBluePlus.cancelWhenScanComplete(subscription);

// Wait for Bluetooth enabled & permission granted
// In your real app you should use `FlutterBluePlus.adapterState.listen` to handle all states
await FlutterBluePlus.adapterState.where((val) => val == BluetoothAdapterState.on).first;

// Start scanning w/ timeout
// Optional: use `stopScan()` as an alternative to timeout
await FlutterBluePlus.startScan(
  withServices:[Guid("180D")], // match any of the specified services
  withNames:["Bluno"], // *or* any of the specified names
  timeout: Duration(seconds:15));

// wait for scanning to stop
await FlutterBluePlus.isScanning.where((val) => val == false).first;
```

--------------------------------

### Manage connection state listeners

Source: https://pub.dev/packages/flutter_blue_plus

Use the null-coalescing assignment operator to ensure only one listener is active and remember to cancel the subscription to prevent memory leaks.

```dart
// tip: using ??= makes it easy to only make new listener when currently null
final subscription ??= FlutterBluePlus.device.connectionState.listen((value) {
    // ...
});

// also, make sure you cancel the subscription when done!
subscription.cancel()
```

--------------------------------

### Save and Restore Device

Source: https://pub.dev/packages/flutter_blue_plus

Persists a device's remote ID to storage to allow reconnection without re-scanning.

```dart
final String remoteId = await File('/remoteId.txt').readAsString();
var device = BluetoothDevice.fromId(remoteId);
// AutoConnect is convenient because it does not "time out"
// even if the device is not available / turned off.
await device.connect(autoConnect: true);
```

--------------------------------

### Add dependency to pubspec.yaml

Source: https://pub.dev/packages/flutter_blue_plus_darwin/install

Manually add the package version to the dependencies section of your pubspec.yaml file.

```yaml
dependencies:
  flutter_blue_plus_darwin: ^9.0.3
```

--------------------------------

### Enable Fine Location in scan

Source: https://pub.dev/packages/flutter_blue_plus

Set the androidUsesFineLocation flag when initiating a scan.

```dart
// Start scanning
flutterBlue.startScan(timeout: Duration(seconds: 4), androidUsesFineLocation: true);
```

--------------------------------

### Read and write descriptors

Source: https://pub.dev/packages/flutter_blue_plus

Iterate through characteristic descriptors to read their values or perform write operations.

```dart
// Reads all descriptors
var descriptors = characteristic.descriptors;
for(BluetoothDescriptor d in descriptors) {
    List<int> value = await d.read();
    print(value);
}

// Writes to a descriptor
await d.write([0x12, 0x34])
```

--------------------------------

### Disable Swift Package Manager

Source: https://pub.dev/packages/flutter_blue_plus_darwin

Add this configuration to your pubspec.yaml to disable Swift Package Manager for the project.

```yaml
flutter:
  disable-swift-package-manager: true
```

--------------------------------

### device.disconnect()

Source: https://pub.dev/packages/flutter_blue_plus

Terminates the current connection to the Bluetooth device.

```APIDOC
## disconnect()

### Description
Disconnects from the currently connected Bluetooth device.
```

--------------------------------

### Disconnecting from a device

Source: https://pub.dev/packages/flutter_blue_plus_windows

Terminate the connection to the currently connected device.

```dart
device?.disconnect();
```

--------------------------------

### Read Characteristics

Source: https://pub.dev/packages/flutter_blue_plus

Iterates through service characteristics and reads values from those that support read operations.

```dart
// Reads all characteristics
var characteristics = service.characteristics;
for(BluetoothCharacteristic c in characteristics) {
    if (c.properties.read) {
        List<int> value = await c.read();
        print(value);
    }
}
```

--------------------------------

### FlutterBluePlus.setOperationQueueMode

Source: https://pub.dev/packages/flutter_blue_plus

Configures the operation queue mode for multi-device performance.

```APIDOC
## setOperationQueueMode(OperationQueueMode mode)

### Description
Sets the operation queue mode to allow BLE operations on different devices to run concurrently.

### Method
Synchronous Method

### Parameters
- **mode** (OperationQueueMode) - Required - The queue mode to set (e.g., OperationQueueMode.perDevice).
```

--------------------------------

### stopScan

Source: https://pub.dev/packages/flutter_blue_plus

Stop an existing scan for Ble devices.

```APIDOC
## stopScan

### Description
Stops an existing scan for Bluetooth Low Energy devices. This operation can fail.
```

--------------------------------

### Write Characteristic

Source: https://pub.dev/packages/flutter_blue_plus

Performs a standard write operation to a characteristic.

```dart
// Writes to a characteristic
await c.write([0x12, 0x34]);
```

--------------------------------

### Manage Characteristic Subscriptions

Source: https://pub.dev/packages/flutter_blue_plus

Use cancelWhenDisconnected to prevent multiple listeners and duplicate data events when subscribing to characteristic notifications.

```dart
final subscription = chr.onValueReceived.listen((value) {
    // ...
});

// make sure you have this line!
device.cancelWhenDisconnected(subscription);

await characteristic.setNotifyValue(true);
```

--------------------------------

### Use Last Value Stream

Source: https://pub.dev/packages/flutter_blue_plus

Utilize lastValueStream to receive updates from reads, writes, and notifications, including an initial re-emission upon listening.

```dart
final subscription = characteristic.lastValueStream.listen((value) {
    // lastValueStream` is updated:
    //   - anytime read() is called
    //   - anytime write() is called
    //   - anytime a notification arrives (if subscribed)
    //   - also when first listened to, it re-emits the last value for convenience.
});

// cleanup: cancel subscription when disconnected
device.cancelWhenDisconnected(subscription);

// enable notifications
await characteristic.setNotifyValue(true);
```

--------------------------------

### Perform Long Write

Source: https://pub.dev/packages/flutter_blue_plus

Writes large data chunks up to 512 bytes, requiring the peripheral to support the long write protocol.

```dart
/// allowLongWrite should be used with caution. 
///   1. it can only be used *with* response to avoid data loss
///   2. the peripheral device must support the 'long write' ble protocol.
///   3. Interrupted transfers can leave the characteristic in a partially written state
///   4. If the mtu is small, it is very very slow.
await c.write(data, allowLongWrite:true);
```

--------------------------------

### characteristic.setNotifyValue

Source: https://pub.dev/packages/flutter_blue_plus

Enables or disables notifications/indications for a specific characteristic.

```APIDOC
## setNotifyValue(bool notify)

### Description
Enables or disables notifications or indications for the characteristic. If a characteristic supports both, it defaults to notifications.

### Method
Async Method

### Parameters
- **notify** (bool) - Required - True to enable notifications/indications, false to disable.
```
Tokens:
Raw