### Installation Bundle Directory Setup

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Sets up the installation prefix to create a relocatable bundle in the build directory and ensures it starts clean.

```cmake
set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)
```

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

### Run Example App

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Navigate to the example directory and run the example app to test FlutterBluePlus functionality.

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

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

### Install Application Executable

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Installs the application executable to the root of the installation bundle.

```cmake
install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)
```

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

### Install Flutter Library

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Installs the main Flutter library file to the library directory within the installation bundle.

```cmake
install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)
```

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

### Install Bundled Plugin Libraries

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Installs any bundled libraries from plugins to the library directory within the installation bundle.

```cmake
foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)
```

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

### Install Native Assets

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Installs native assets provided by packages to the library directory within the installation bundle.

```cmake
set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/linux/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)
```

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

### Installation Paths for Bundle Data and Libraries

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Defines the destination directories within the installation bundle for data and libraries.

```cmake
set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")
```

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

### Install Flutter Assets

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Removes existing Flutter assets and installs new ones to the specified directory. This is part of the runtime component installation.

```cmake
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)
```

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

### Migrate to FlutterBluePlus.scanResults

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/MIGRATION.md

Example demonstrating how to use `FlutterBluePlus.scanResults` to find a specific device by name after calling `startScan`. It listens for results before starting the scan to avoid missing the target device.

```dart
Stream<BluetoothDevice?> myDeviceStream = FlutterBluePlus.scanResults
    .map((list) => list.first)
    .where((r) => r.advertisementData.advName == "myDeviceName")
    .map((r) => r.device);

// start listening before we call startScan so we do not miss the result
Future<BluetoothDevice?> myDeviceFuture = myDeviceStream.first
    .timeout(Duration(seconds: 10))
    .catchError((error) => null);

await FlutterBluePlus.startScan(timeout: Duration(seconds: 10), oneByOne:true);

BluetoothDevice? myDevice = await myDeviceFuture;
```

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

### Install ICU Data File

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Installs the ICU data file to the data directory within the installation bundle.

```cmake
install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)
```

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

### Install AOT Library (Non-Debug)

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Installs the Ahead-of-Time (AOT) compiled library to the runtime library directory, but only for non-Debug build types.

```cmake
if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

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

### Configure Flutter library and headers

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/flutter/CMakeLists.txt

Sets up the Flutter library path and includes necessary header files. It also defines the project build directory and the AOT (Ahead-Of-Time) compiled library path, making them available to parent scopes for installation.

```cmake
set(FLUTTER_LIBRARY "${EPHEMERAL_DIR}/libflutter_linux_gtk.so")

# Published to parent scope for install step.
set(FLUTTER_LIBRARY ${FLUTTER_LIBRARY} PARENT_SCOPE)
set(FLUTTER_ICU_DATA_FILE "${EPHEMERAL_DIR}/icudtl.dat" PARENT_SCOPE)
set(PROJECT_BUILD_DIR "${PROJECT_DIR}/build/" PARENT_SCOPE)
set(AOT_LIBRARY "${PROJECT_DIR}/build/lib/libapp.so" PARENT_SCOPE)
```

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

### startScan

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Starts a scan for Bluetooth Low Energy devices. This operation can fail.

```APIDOC
## startScan

### Description
Starts a scan for Ble devices.

### Method
`startScan`

### Parameters
None explicitly documented.

### Notes
Supported on Android, iOS/macOS, Linux, and Web. Marked as potentially failing (🔥).
```

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

### startScan

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/README.md

Starts a scan for Bluetooth Low Energy devices. This operation can fail and is available on Android, iOS/macOS, Linux, and Web.

```APIDOC
## startScan

### Description
Starts a scan for Ble devices.

### Method
Not specified (assumed to be a method call).

### Endpoint
N/A (SDK method)

### Parameters
N/A (specific parameters not detailed in source)

### Request Example
N/A (specific example not detailed in source)

### Response
N/A (specific response not detailed in source)
```

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

### Android Start Scan with Fine Location

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Enable fine location when starting a scan on Android by setting `androidUsesFineLocation` to true.

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

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

### iOS Restore State for Background Operation

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Set `restoreState` to true before starting any FBP work to ensure your app can be woken up by the system for background BLE operations.

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

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

### Get System Devices

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Retrieves a list of Bluetooth devices connected to the system. Note that you must connect your app to these devices before communication can occur. `withServices` is required on iOS.

```dart
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();
}
```

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

### Apply Standard Settings to Executable

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Applies the standard build settings defined in APPLY_STANDARD_SETTINGS to the application executable.

```cmake
apply_standard_settings(${BINARY_NAME})
```

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

### System Dependencies (GTK)

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Finds and checks for the GTK+ 3.0 library using PkgConfig.

```cmake
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)
```

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

### Cross-Building Sysroot Configuration

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Sets up the sysroot and find root path for cross-compiling Flutter applications.

```cmake
if(FLUTTER_TARGET_PLATFORM_SYSROOT)
  set(CMAKE_SYSROOT ${FLUTTER_TARGET_PLATFORM_SYSROOT})
  set(CMAKE_FIND_ROOT_PATH ${CMAKE_SYSROOT})
  set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
  set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
  set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
  set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
endif()
```

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

### setOptions

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Sets configurable Bluetooth options for the plugin.

```APIDOC
## setOptions

### Description
Set configurable bluetooth options.

### Method
`setOptions`

### Parameters
None explicitly documented.

### Notes
Supported on Android and iOS/macOS. Not supported on Linux or Web.
```

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

### Find and check GTK, GLIB, and GIO modules

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/flutter/CMakeLists.txt

Uses PkgConfig to find and check for the required GTK, GLIB, and GIO system-level dependencies. This is essential for building Flutter applications on Linux with GTK support.

```cmake
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)
pkg_check_modules(GLIB REQUIRED IMPORTED_TARGET glib-2.0)
pkg_check_modules(GIO REQUIRED IMPORTED_TARGET gio-2.0)
```

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

### turnOn

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Turns on the Bluetooth adapter. This operation can fail.

```APIDOC
## turnOn

### Description
Turns on the bluetooth adapter.

### Method
`turnOn`

### Parameters
None explicitly documented.

### Notes
Supported on Android, Linux. Not supported on iOS/macOS or Web. Marked as potentially failing (🔥).
```

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

### Get Connected Bluetooth Devices

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Retrieve a list of all Bluetooth devices currently connected to the application.

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

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

### Get MTU for Bluetooth Device

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Retrieve the Maximum Transmission Unit (MTU) for a Bluetooth device. This is useful for diagnosing issues with data splitting.

```dart
device.mtu
```

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

### Runtime Library Path

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Configures the runtime path for bundled libraries relative to the binary.

```cmake
set(CMAKE_INSTALL_RPATH "$ORIGIN/lib")
```

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

### turnOn

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/README.md

Turns on the Bluetooth adapter. This operation can fail and is available on Android, Linux.

```APIDOC
## turnOn

### Description
Turns on the bluetooth adapter.

### Method
Not specified (assumed to be a method call).

### Endpoint
N/A (SDK method)

### Parameters
N/A (specific parameters not detailed in source)

### Request Example
N/A (specific example not detailed in source)

### Response
N/A (specific response not detailed in source)
```

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

### Handle Initial Bluetooth Adapter State on iOS

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

On iOS, the adapter state may initially be 'unknown'. Wait for a short duration if the state is unknown to allow initialization.

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

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

### Define Application Executable

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Defines the main executable target, including source files and generated plugin registrant.

```cmake
add_executable(${BINARY_NAME}
  "main.cc"
  "my_application.cc"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
)
```

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

### Set Runtime Output Directory

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Configures the runtime output directory for the executable to a subdirectory to ensure correct resource loading.

```cmake
set_target_properties(${BINARY_NAME}
  PROPERTIES
    RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/intermediates_do_not_run"
)
```

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

### Enable and Use Auto Connect

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Configure a device to automatically connect when it becomes available. When using autoConnect, the connect() method returns immediately, so you must listen to the connection state to confirm connection.

```dart
await device.connect(autoConnect:true, mtu:null)

await device.connectionState.where((val) => val == BluetoothConnectionState.connected).first;

await device.disconnect()
```

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

### Check Bluetooth Support and Handle State Changes

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Verify if the device supports Bluetooth and listen for changes in the adapter's state (on/off). For Android, it's possible to programmatically turn on Bluetooth.

```dart
if (await FlutterBluePlus.isSupported == false) {
    print("Bluetooth not supported by this device");
    return;
}

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
    }
});

if (!kIsWeb && Platform.isAndroid) {
    await FlutterBluePlus.turnOn();
}

subscription.cancel();
```

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

### Project and Minimum CMake Version

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Sets the minimum required CMake version and the project name with supported languages.

```cmake
cmake_minimum_required(VERSION 3.10)
project(runner LANGUAGES CXX)
```

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

### Standard Build Settings Function

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Defines a function to apply standard compilation features, options, and definitions to a target.

```cmake
function(APPLY_STANDARD_SETTINGS TARGET)
  target_compile_features(${TARGET} PUBLIC cxx_std_14)
  target_compile_options(${TARGET} PRIVATE -Wall -Werror)
  target_compile_options(${TARGET} PRIVATE "$<$<NOT:$<CONFIG:Debug>>:-O3>")
  target_compile_definitions(${TARGET} PRIVATE "$<$<NOT:$<CONFIG:Debug>>:NDEBUG>")
endfunction()
```

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

### Wait for Bluetooth Adapter to Turn On

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Ensure the Bluetooth adapter is fully on before proceeding. This snippet waits for the adapter state to become 'on'.

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

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

### Application ID Definition

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Adds a preprocessor definition for the application ID.

```cmake
add_definitions(-DAPPLICATION_ID="${APPLICATION_ID}")
```

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

### adapterState

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Provides a stream of Bluetooth adapter state changes (on/off).

```APIDOC
## adapterState

### Description
Stream of on & off states of the bluetooth adapter.

### Method
`adapterState`

### Parameters
None explicitly documented.

### Notes
Supported on Android, iOS/macOS, Linux. Not supported on Web. Marked as a stream (🌀).
```

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

### Integrating Mockable Class in MyApp

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/MOCKING.md

Demonstrates how to instantiate and use the `FlutterBluePlusMockable` class within your application's root widget. This instance can then be passed down to other widgets.

```dart
void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  MyApp({Key? key}) : super(key: key);
  //instance of FlutterBluePlus that will be passed
  //throughout the app as necessary
  FlutterBluePlusMockable bluePlusMockable = FlutterBluePlusMockable();//<--

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My app',
      theme: ThemeData(
        primarySwatch: Colors.lightGreen,
      ),
      home:  FindDevicesScreen(
        bluePlusMockable: bluePlusMockable,
      );
    );
  }
}
```

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

### getPhySupport

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Retrieves the supported Bluetooth PHY (Physical Layer) codings.

```APIDOC
## getPhySupport

### Description
Get supported bluetooth phy codings.

### Method
`getPhySupport`

### Parameters
None explicitly documented.

### Notes
Supported on Android. Not supported on iOS/macOS, Linux, or Web.
```

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

### Define custom command for Flutter tool backend

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/flutter/CMakeLists.txt

A custom command is defined to run the Flutter tool backend script. This command is set up to execute every time by using a dummy output file '_phony_'. It generates the Flutter library and its headers.

```cmake
add_custom_command(
  OUTPUT ${FLUTTER_LIBRARY} ${FLUTTER_LIBRARY_HEADERS}
    ${CMAKE_CURRENT_BINARY_DIR}/_phony_
  COMMAND ${CMAKE_COMMAND} -E env
    ${FLUTTER_TOOL_ENVIRONMENT}
    "${FLUTTER_ROOT}/packages/flutter_tools/bin/tool_backend.sh"
      ${FLUTTER_TARGET_PLATFORM} ${CMAKE_BUILD_TYPE}
  VERBATIM
)
```

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

### adapterStateNow

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Retrieves the current synchronous state of the Bluetooth adapter.

```APIDOC
## adapterStateNow

### Description
Current state of the bluetooth adapter.

### Method
`adapterStateNow`

### Parameters
None explicitly documented.

### Notes
Supported on Android, iOS/macOS, Linux. Not supported on Web. Marked as synchronous (⚡).
```

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

### Link Application Libraries

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Links the application executable against the Flutter library and GTK.

```cmake
target_link_libraries(${BINARY_NAME} PRIVATE flutter)
target_link_libraries(${BINARY_NAME} PRIVATE PkgConfig::GTK)
```

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

### Build Configuration Mode

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Sets the default build type to 'Debug' if not already defined, allowing 'Profile' and 'Release' as options.

```cmake
if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
  set(CMAKE_BUILD_TYPE "Debug" CACHE
    STRING "Flutter build mode" FORCE)
  set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS
    "Debug" "Profile" "Release")
endif()
```

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

### Manage Connection State Listener Subscription

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Ensures that only one listener is active for connection state changes and demonstrates how to cancel the subscription when done to prevent multiple listeners.

```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()
```

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

### Set Log Level and Listen to Logs

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/README.md

Configure the log level for verbose output and optionally listen to logs. This is useful for debugging and understanding data flow.

```dart
FlutterBluePlus.setLogLevel(LogLevel.verbose, color:false);

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

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

### systemDevices

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Retrieves a list of devices connected to the system, even by other applications. This operation can fail.

```APIDOC
## systemDevices

### Description
List of devices connected to the system, even by other apps.

### Method
`systemDevices`

### Parameters
None explicitly documented.

### Notes
Supported on Android, iOS/macOS, Linux. Not supported on Web. Marked as potentially failing (🔥).
```

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

### Add Flutter Subdirectory

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Includes the Flutter build rules from the managed directory.

```cmake
add_subdirectory(${FLUTTER_MANAGED_DIR})
```

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

### Manage Bluetooth Adapter State Listener Subscription

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Avoid multiple listeners for adapter state by managing the subscription. Ensure the subscription is cancelled when no longer needed.

```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()
```

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

### isSupported

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Checks whether the device supports Bluetooth functionality.

```APIDOC
## isSupported

### Description
Checks whether the device supports Bluetooth.

### Method
`isSupported`

### Parameters
None explicitly documented.

### Notes
Supported on Android, iOS/macOS, Linux, and Web.
```

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

### Read and Write Bluetooth Descriptors

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Read all descriptors for a characteristic and print their values. Also demonstrates writing a list of integers to a descriptor.

```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])
```

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

### Android Proguard Configuration

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Add this line to your `proguard-rules.pro` file to prevent release build errors related to missing fields.

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

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

### Add Flutter library interface target

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/flutter/CMakeLists.txt

Creates an INTERFACE library target named 'flutter' and configures its include directories and link libraries. This includes system dependencies found via PkgConfig and the main Flutter library.

```cmake
add_library(flutter INTERFACE)
target_include_directories(flutter INTERFACE
  "${EPHEMERAL_DIR}"
)
target_link_libraries(flutter INTERFACE "${FLUTTER_LIBRARY}")
target_link_libraries(flutter INTERFACE
  PkgConfig::GTK
  PkgConfig::GLIB
  PkgConfig::GIO
)
```

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

### Create and Remove Bluetooth Bond (Android)

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/README.md

Forces the bonding popup to show sooner on Android. The platform usually handles bonding automatically, so calling this is often unnecessary. It also shows how to remove an existing bond. A subscription to bond state changes is included for monitoring.

```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();
```

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

### Modern CMake Policy

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Explicitly opts into modern CMake behaviors to avoid warnings with recent CMake versions.

```cmake
cmake_policy(SET CMP0063 NEW)
```

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

### Include Generated Plugin CMake Rules

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Includes the CMake rules for building and registering plugins, which are generated by Flutter.

```cmake
include(flutter/generated_plugins.cmake)
```

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

### Custom StartScanWithResult Extension for FlutterBluePlus

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/MIGRATION.md

Provides an extension method to `startScan` that returns a `Future<List<ScanResult>>`, allowing you to collect all scan results upon completion. This replaces the previous behavior where `startScan` returned a list.

```dart
extension Scan on FlutterBluePlus {
  static Future<List<ScanResult>> startScanWithResult({
    List<Guid> withServices = const [],
    Duration? timeout,
    bool androidUsesFineLocation = false,
  }) async {
    if (FlutterBluePlus.isScanningNow) {
      throw Exception("Another scan is already in progress");
    }

    List<ScanResult> output = [];

    var subscription = FlutterBluePlus.scanResults.listen((result) {
      output = result;
    }, onError: (e, stackTrace) {
      throw Exception(e);
    });

    FlutterBluePlus.startScan(
      withServices: withServices,
      timeout: timeout,
      removeIfGone: null,
      oneByOne: false,
      androidUsesFineLocation: androidUsesFineLocation,
    );

    // wait scan complete
    await FlutterBluePlus.isScanning.where((e) => e == false).first;

    subscription.cancel();

    return output;
  }
}
```

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

### BluetoothDevice API

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Provides methods and properties for interacting with a Bluetooth device.

```APIDOC
## BluetoothDevice API

### Description
Provides methods and properties for interacting with a Bluetooth device, including connection management, service discovery, and device information.

### Methods & Properties

- **platformName** (string): The platform preferred name of the device.
- **advName** (string): The advertised name of the device found during scanning.
- **connect()**: Establishes a connection to the device.
- **disconnect()**: Cancels an active or pending connection to the device.
- **isConnected** (boolean): Is this device currently connected to *your app*?
- **isDisconnected** (boolean): Is this device currently disconnected from *your app*?
- **connectionState** (Stream<ConnectionState>): Stream of connection changes for the Bluetooth Device.
- **discoverServices()**: Discover services offered by the device.
- **servicesList** (List<BluetoothService>): The current list of available services.
- **onServicesReset** (Stream<void>): Emits when the services have changed and must be rediscovered.
- **mtu** (Stream<int>): Stream of current mtu value + changes.
- **mtuNow** (int): The current mtu value.
- **readRssi()**: Read RSSI from a connected device.
- **requestMtu(int mtu)**: Request to change the MTU for the device.
- **requestConnectionPriority(ConnectionPriority priority)**: Request to update a high priority, low latency connection.
- **bondState** (Stream<BondState>): Stream of device bond state. Can be useful on Android.
- **createBond()**: Force a system pairing dialogue to show, if needed.
- **removeBond()**: Remove Bluetooth Bond of device.
- **setPreferredPhy(PreferredPhy phy)**: Set preferred RX and TX phy for connection and phy options.
- **clearGattCache()**: Clear android cache of service discovery results.
```

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

### Custom Split Write Extension

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/README.md

Implement a custom extension to write unlimited data by splitting it into chunks based on the device's MTU. Use with caution, as it can lead to partial reads, requires response, and the characteristic must support split data.

```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);
    }
  }
}
```

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

### Split Write for Unlimited Data

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Implement a splitWrite extension to write unlimited data by chunking it. Use with caution as it can lead to partial reads, requires response, and the characteristic must support split data.

```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);
    }
  }
}
```

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

### systemDevices

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/README.md

Retrieves a list of devices connected to the system, even by other applications. This operation can fail and is available on Android, iOS/macOS, and Linux.

```APIDOC
## systemDevices

### Description
List of devices connected to the system, even by other apps.

### Method
Not specified (assumed to be a method call).

### Endpoint
N/A (SDK method)

### Parameters
N/A (specific parameters not detailed in source)

### Request Example
N/A (specific example not detailed in source)

### Response
N/A (specific response not detailed in source)
```

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

### Executable and Application ID

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Defines the executable name and the unique GTK application identifier for the application.

```cmake
set(BINARY_NAME "flutter_blue_plus_example")
set(APPLICATION_ID "com.lib.flutter_blue_plus_example")
```

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

### iOS Bluetooth Usage Description

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Add the `NSBluetoothAlwaysUsageDescription` key to your `Info.plist` to explain why the app needs Bluetooth access.

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

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

### Define list_prepend function for CMake < 3.10

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/flutter/CMakeLists.txt

This function mimics the behavior of list(TRANSFORM ... PREPEND ...) which is not available in CMake version 3.10. It prepends a given prefix to each element in a list.

```cmake
function(list_prepend LIST_NAME PREFIX)
    set(NEW_LIST "")
    foreach(element ${${LIST_NAME}})
        list(APPEND NEW_LIST "${PREFIX}${element}")
    endforeach(element)
    set(${LIST_NAME} "${NEW_LIST}" PARENT_SCOPE)
endfunction()
```

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

### Create and Remove Bond (Android Only)

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Allows forcing the bonding popup to show sooner on Android. It's generally not necessary as the platform handles it automatically. Includes listening to bond state changes and removing a bond.

```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();
```

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

### connectedDevices

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Retrieves a list of devices currently connected to your application.

```APIDOC
## connectedDevices

### Description
List of devices connected to *your app*.

### Method
`connectedDevices`

### Parameters
None explicitly documented.

### Notes
Supported on Android, iOS/macOS, Linux, and Web. Marked as synchronous (⚡).
```

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

### onScanResults

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

A stream that provides live scan results for discovered BLE devices. This stream can fail.

```APIDOC
## onScanResults

### Description
Stream of live scan results.

### Method
`onScanResults`

### Parameters
None explicitly documented.

### Notes
Supported on Android, iOS/macOS, Linux, and Web. Marked as a stream (🌀) and potentially failing (🔥).
```

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

### isScanningNow

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Synchronously checks if a scan is currently running.

```APIDOC
## isScanningNow

### Description
Is a scan currently running?

### Method
`isScanningNow`

### Parameters
None explicitly documented.

### Notes
Supported on Android, iOS/macOS, Linux, and Web. Marked as synchronous (⚡).
```

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

### Flutter Managed Directory

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Sets the path to the Flutter managed directory, typically containing generated files.

```cmake
set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
```

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

### onBondStateChanged

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

A stream that emits events about bond state changes for all devices.

```APIDOC
## onBondStateChanged

### Description
Stream of bond state changes of *all devices*.

### Method
`onBondStateChanged`

### Parameters
None explicitly documented.

### Notes
Supported on Android, Linux. Not supported on iOS/macOS or Web. Marked as a stream (🌀).
```

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

### onDescriptorWritten

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

A stream that emits events for descriptor value writes for all devices.

```APIDOC
## onDescriptorWritten

### Description
Stream of descriptor value writes of *all devices*.

### Method
`onDescriptorWritten`

### Parameters
None explicitly documented.

### Notes
Supported on Android, iOS/macOS, Linux, and Web. Marked as a stream (🌀).
```

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

### Clone FlutterBluePlus Repository

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Clone the FlutterBluePlus repository to your local machine for debugging. Add the local path to your pubspec.yaml to use your modified version.

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

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

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

### Set Minimum SDK Version for Android

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Updates the `minSdkVersion` in `android/app/build.gradle` to 21, which is required for flutter_blue_plus compatibility on Android.

```dart
android {
  defaultConfig {
     minSdkVersion: 21
```

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

### Search System Devices for Connection

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Searches for system-connected Bluetooth devices and attempts to connect to a specific device if found. Useful when a device might be connected by another app.

```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
    }
}
```

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

### setLogLevel

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Configures the log level for the plugin. This is useful for debugging.

```APIDOC
## setLogLevel

### Description
Configure plugin log level.

### Method
`setLogLevel`

### Parameters
None explicitly documented.

### Notes
Supported on Android, iOS/macOS, and Linux. Not supported on Web.
```

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

### Clone FlutterBluePlus Repository

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/README.md

Clone the FlutterBluePlus repository to your local machine for debugging. This allows you to make direct modifications to the library's code.

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

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

### onDiscoveredServices

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

A stream that emits events when services are discovered for all devices.

```APIDOC
## onDiscoveredServices

### Description
Stream of services discovered of *all devices*.

### Method
`onDiscoveredServices`

### Parameters
None explicitly documented.

### Notes
Supported on Android, iOS/macOS, Linux, and Web. Marked as a stream (🌀).
```

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

### Scan for Bluetooth Devices

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Listen for scan results and initiate a scan with optional filters for services and device names. It's recommended to use scan filters to optimize performance.

```dart
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));

FlutterBluePlus.cancelWhenScanComplete(subscription);

await FlutterBluePlus.adapterState.where((val) => val == BluetoothAdapterState.on).first;

await FlutterBluePlus.startScan(
  withServices:[Guid("180D")], // match any of the specified services
  withNames:["Bluno"], // *or* any of the specified names
  timeout: Duration(seconds:15));

await FlutterBluePlus.isScanning.where((val) => val == false).first;
```

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

### onCharacteristicWritten

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

A stream that emits events for characteristic value writes for all devices.

```APIDOC
## onCharacteristicWritten

### Description
Stream of characteristic value writes of *all devices*.

### Method
`onCharacteristicWritten`

### Parameters
None explicitly documented.

### Notes
Supported on Android, iOS/macOS, Linux, and Web. Marked as a stream (🌀).
```

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

### onCharacteristicReceived

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

A stream that emits events for characteristic value reads for all devices.

```APIDOC
## onCharacteristicReceived

### Description
Stream of characteristic value reads of *all devices*.

### Method
`onCharacteristicReceived`

### Parameters
None explicitly documented.

### Notes
Supported on Android, iOS/macOS, Linux, and Web. Marked as a stream (🌀).
```

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

### Connect and Disconnect from a Bluetooth Device

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Manage the connection state of a Bluetooth device, including listening for disconnections and initiating connection or disconnection. Ensure services are re-discovered after a disconnection.

```dart
var subscription = device.connectionState.listen((BluetoothConnectionState state) async {
    if (state == BluetoothConnectionState.disconnected) {
        print("${device.disconnectReason?.code} ${device.disconnectReason?.description}");
    }
});

device.cancelWhenDisconnected(subscription, delayed:true, next:true);

await device.connect();

await device.disconnect();

subscription.cancel();
```

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

### Add Bluetooth Permissions for Android

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Configures necessary Bluetooth permissions in `android/app/src/main/AndroidManifest.xml` for Android 12 and lower, including scan, connect, and location permissions.

```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" />
```

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

### Add Flutter Assemble Dependency

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/example/linux/CMakeLists.txt

Ensures that the Flutter assembly process is completed before the application executable is built.

```cmake
add_dependencies(${BINARY_NAME} flutter_assemble)
```

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

### Add flutter_blue_plus Plugin

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Adds the flutter_blue_plus plugin to your Flutter project's pubspec.yaml file. It's recommended to pin to a specific version for stability.

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

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

### turnOff

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/packages/flutter_blue_plus/README.md

Turns off the Bluetooth adapter. This operation can fail.

```APIDOC
## turnOff

### Description
Turns off the bluetooth adapter.

### Method
`turnOff`

### Parameters
None explicitly documented.

### Notes
Supported on Android, Linux. Not supported on iOS/macOS or Web. Marked as potentially failing (🔥).
```

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

### Add Local FlutterBluePlus Path to pubspec.yaml

Source: https://github.com/chipweinberger/flutter_blue_plus/blob/master/README.md

After cloning, update your project's `pubspec.yaml` to use the local path of the FlutterBluePlus repository. This ensures your app uses your modified version.

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