Flutter BLE Lib iOS 15

https://pub.dev/packages/flutter_ble_lib_ios_15/
Admin
Flutter BLE Lib iOS 15 is a Flutter library that supports Bluetooth Low Energy operations with iOS...
Tokens:5,810
Snippets:83
Trust Score:9.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Flutter BLE Lib Example App Setup

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

Sets up the main application widget for the flutter_ble_lib_example. It configures Fimber for debugging and defines routes for the DevicesListScreen and DeviceDetailsView. Ensure Fimber and Material are imported.

```dart
import 'package:fimber/fimber.dart';
import 'package:flutter/material.dart';
import 'package:flutter_ble_lib_example/devices_list/devices_bloc_provider.dart';
import 'package:flutter_ble_lib_example/devices_list/devices_list_view.dart';

import 'device_details/device_detail_view.dart';
import 'device_details/devices_details_bloc_provider.dart';

void main() {
  Fimber.plantTree(DebugTree());
  runApp(MyApp());
}

final RouteObserver<PageRoute> routeObserver = RouteObserver<PageRoute>();

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'FlutterBleLib example',
      theme: new ThemeData(
        primaryColor: new Color(0xFF0A3D91),
        accentColor: new Color(0xFFCC0000),
      ),
      initialRoute: "/",
      routes: <String, WidgetBuilder>{
        "/": (context) => DevicesBlocProvider(child: DevicesListScreen()),
        "/details": (context) =>
            DeviceDetailsBlocProvider(child: DeviceDetailsView()),
      },
      navigatorObservers: [routeObserver],
    );
  }
}
```

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

### Add flutter_ble_lib_ios_15 Dependency

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

Use this command to add the package to your Flutter project. It automatically updates your pubspec.yaml file and runs `flutter pub get`.

```bash
$ flutter pub add flutter_ble_lib_ios_15
```

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

### Import flutter_ble_lib_ios_15 Modules

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

Import the necessary classes from the flutter_ble_lib_ios_15 package into your Dart files to start using its BLE functionalities.

```dart
import 'package:flutter_ble_lib_ios_15/ble_manager.dart';
import 'package:flutter_ble_lib_ios_15/characteristic.dart';
import 'package:flutter_ble_lib_ios_15/descriptor.dart';
import 'package:flutter_ble_lib_ios_15/error/ble_error.dart';
import 'package:flutter_ble_lib_ios_15/flutter_ble_lib.dart';
import 'package:flutter_ble_lib_ios_15/peripheral.dart';
import 'package:flutter_ble_lib_ios_15/scan_result.dart';
import 'package:flutter_ble_lib_ios_15/service.dart';
```

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

### Scanning for Peripherals

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

Starts a peripheral scan, optionally filtering by service UUIDs. The scan stops after the first result is received. Note that `isConnectable` and `overflowServiceUuids` are iOS-only.

```APIDOC
## Scanning for Peripherals

### Description
Starts a peripheral scan, optionally filtering by service UUIDs. The scan stops after the first result is received. Note that `isConnectable` and `overflowServiceUuids` are iOS-only.

### Method
```dart
bleManager.startPeripheralScan(
  uuids: [
    "F000AA00-0451-4000-B000-000000000000",
  ],
).listen((scanResult) {
  //Scan one peripheral and stop scanning
  print("Scanned Peripheral ${scanResult.peripheral.name}, RSSI ${scanResult.rssi}");
  bleManager.stopPeripheralScan();
});
```
```

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

### Start and Stop Peripheral Scan

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

Initiates a peripheral scan, filters by service UUID, and stops scanning after the first result is received. Ensure the service UUID is correctly specified.

```dart
bleManager.startPeripheralScan(
  uuids: [
    "F000AA00-0451-4000-B000-000000000000",
  ],
).listen((scanResult) {
  //Scan one peripheral and stop scanning
  print("Scanned Peripheral ${scanResult.peripheral.name}, RSSI ${scanResult.rssi}");
  bleManager.stopPeripheralScan();
});

```

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

### Initialize and Destroy BleManager

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

Instantiate `BleManager`, call `createClient` to initialize native resources, and `destroyClient` to release them when done. This is a prerequisite for other BLE operations.

```dart
BleManager bleManager = BleManager();
await bleManager.createClient(); //ready to go!
// your peripheral logic
bleManager.destroyClient(); //remember to release native resources when you're done!

```

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

### Discovering Services and Characteristics

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

Discovers all services and characteristics of a connected peripheral. It also shows how to retrieve lists of services and characteristics by UUID.

```APIDOC
## Obtaining Characteristics

### Description
Discovers all services and characteristics of a connected peripheral. It also shows how to retrieve lists of services and characteristics by UUID.

### Method
```dart
//assuming peripheral is connected
await peripheral.discoverAllServicesAndCharacteristics();
List<Service> services = await peripheral.services(); //getting all services
List<Characteristic> characteristics1 = await peripheral.characteristics("F000AA00-0451-4000-B000-000000000000");
List<Characteristic> characteristics2 = await services.firstWhere(
  (service) => service.uuid == "F000AA00-0451-4000-B000-000000000000").characteristics();

//characteristics1 and characteristics2 have the same contents
```
```

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

### Connecting to a Peripheral

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

Observes the connection state, connects to a peripheral, checks its connection status, and then disconnects.

```APIDOC
## Connecting to Peripheral

### Description
Observes the connection state, connects to a peripheral, checks its connection status, and then disconnects.

### Method
```dart
Peripheral peripheral = scanResult.peripheral;
peripheral.observeConnectionState(emitCurrentValue: true, completeOnDisconnect: true)
  .listen((connectionState) {
    print("Peripheral ${scanResult.peripheral.identifier} connection state is $connectionState");
  });
await peripheral.connect();
bool connected = await peripheral.isConnected();
await peripheral.disconnectOrCancelConnection();
```
```

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

### Observe, Connect, and Disconnect Peripheral

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

Monitors the connection state of a peripheral, establishes a connection, verifies the connection status, and then disconnects. Ensure a ScanResult is obtained before proceeding.

```dart
Peripheral peripheral = scanResult.peripheral;
peripheral.observeConnectionState(emitCurrentValue: true, completeOnDisconnect: true)
  .listen((connectionState) {
    print("Peripheral ${scanResult.peripheral.identifier} connection state is $connectionState");
  });
await peripheral.connect();
bool connected = await peripheral.isConnected();
await peripheral.disconnectOrCancelConnection();

```

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

### Creating an Unsafe Peripheral Instance

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

Creates an instance of a Peripheral using its known ID (UUID on iOS, MAC address on Android) to attempt a connection without a prior scan. Note that Android may still require a scan.

```APIDOC
## Connecting to Saved Peripheral

### Description
Creates an instance of a Peripheral using its known ID (UUID on iOS, MAC address on Android) to attempt a connection without a prior scan. Note that Android may still require a scan.

### Method
```dart
Peripheral myPeripheral = bleManager.createUnsafePeripheral("< known id >");
```
```

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

### Specify MultiplatformBleAdapter Dependency

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

In your Podfile, specify the forked MultiplatformBleAdapter repository and tag to ensure compatibility with iOS 15.

```ruby
target 'Runner' do
  use_frameworks!
  use_modular_headers!
  pod 'MultiplatformBleAdapter', :git => 'https://github.com/below/MultiPlatformBleAdapter', :tag => '0.1.9'
  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

```

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

### Set Minimum SDK Version for Android

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

Ensure your Android project's `build.gradle` file sets `minSdkVersion` to 18 or higher, as required by the library for Bluetooth Low Energy support.

```gradle
defaultConfig {
  ...
  minSdkVersion 18
  ...
}

```

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

### Discover Services and Characteristics

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

Retrieves all services and characteristics for a connected peripheral. This is a prerequisite for most peripheral operations. Ensure the peripheral is connected before calling.

```dart
//assuming peripheral is connected
await peripheral.discoverAllServicesAndCharacteristics();
List<Service> services = await peripheral.services(); //getting all services
List<Characteristic> characteristics1 = await peripheral.characteristics("F000AA00-0451-4000-B000-000000000000");
List<Characteristic> characteristics2 = await services.firstWhere(
  (service) => service.uuid == "F000AA00-0451-4000-B000-000000000000").characteristics();

//characteristics1 and characteristics2 have the same contents

```

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

### Add Bluetooth Usage Description for iOS

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

Include the `NSBluetoothAlwaysUsageDescription` key in your `Info.plist` file to provide a description for Bluetooth usage on iOS.

```xml
...
<key>NSBluetoothAlwaysUsageDescription</key>
<string>Your own description of the purpose.</string>
...

```

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

### Writing to a Characteristic

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

Demonstrates three ways to write data to a characteristic: via the peripheral, via the service, or directly on the characteristic object. All methods achieve the same result if UUIDs match.

```APIDOC
## Manipulating Characteristics

### Description
Demonstrates three ways to write data to a characteristic: via the peripheral, via the service, or directly on the characteristic object. All methods achieve the same result if UUIDs match.

### Method
```dart
peripheral.writeCharacteristic(
  "F000AA00-0451-4000-B000-000000000000",
  "F000AA02-0451-4000-B000-000000000000",
  Uint8List.fromList([0]),
  false); //returns Characteristic to chain operations more easily

service.writeCharacteristic(
  "F000AA02-0451-4000-B000-000000000000",
  Uint8List.fromList([0]),
  false); //returns Characteristic to chain operations more easily

characteristic.write(Uint8List.fromList([0]), false); //returns void
```
```

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

### Create Unsafe Peripheral Instance

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

Creates a Peripheral instance using a known ID without prior scanning. Note that on Android, scanning might still be necessary to discover the peripheral.

```dart
Peripheral myPeripheral = bleManager.createUnsafePeripheral("< known id >");

```

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

### Handle Bluetooth Adapter State

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

Manage Bluetooth adapter states using `enableRadio`, `disableRadio` (Android-only), `bluetoothState`, and `observeBluetoothState`. Note that `enableRadio` and `disableRadio` do not check permissions.

```dart
enum BluetoothState {
  UNKNOWN,
  UNSUPPORTED,
  UNAUTHORIZED,
  POWERED_ON,
  POWERED_OFF,
  RESETTING,
}


bleManager.enableRadio(); //ANDROID-ONLY turns on BT. NOTE: doesn't check permissions
bleManager.disableRadio() //ANDROID-ONLY turns off BT. NOTE: doesn't check permissions
BluetoothState currentState = await bleManager.bluetoothState();
bleManager.observeBluetoothState().listen((btState) {
  print(btState);
  //do your BT logic, open different screen, etc.
});

```

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

### Enable Background Bluetooth Mode for iOS

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

Add the `bluetooth-central` Background Execution Mode to your `Info.plist` file to enable background Bluetooth capabilities.

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

```

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

### Declare Dependency in pubspec.yaml

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

This is how the dependency will appear in your `pubspec.yaml` file after running the `flutter pub add` command.

```yaml
dependencies:
  flutter_ble_lib_ios_15: ^2.5.2
```

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

### Fix Duplicate Import Warning

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

Addresses a 'Duplicate import' warning found in lib/flutter_ble_lib.dart. Ensure lints_core is used and run 'flutter analyze' to reproduce.

```dart
import 'src/_managers_for_classes.dart';
```

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

### Address Unnecessary Nullability Warning

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

Resolves a warning in lib/scan_result.dart where '?' is unnecessary for 'dynamic' type. Run 'flutter analyze' to verify.

```dart
Map<String, dynamic?> json,
```

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

### Transaction Management for Operations

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

Allows cancellation of asynchronous operations by providing a `transactionId`. If an operation with the same ID is already running, it will be cancelled. Using `null` or omitting `transactionId` assigns a unique ID.

```APIDOC
## Transactions

### Description
Allows cancellation of asynchronous operations by providing a `transactionId`. If an operation with the same ID is already running, it will be cancelled. Using `null` or omitting `transactionId` assigns a unique ID. Note that integers are reserved by the library.

### Method
```dart
//assuming peripheral is connected
peripheral.discoverAllServicesAndCharacteristics(transactionId: "discovery");
//will return operation cancelled error after calling the below
bleManager.cancelTransaction("discovery");
```
```

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

### Write to Characteristic

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

Provides three methods to write data to a Bluetooth characteristic. Ensure the peripheral, service, and characteristic UUIDs are correct. The `write` method on the `Characteristic` object returns void.

```dart
peripheral.writeCharacteristic(
  "F000AA00-0451-4000-B000-000000000000",
  "F000AA02-0451-4000-B000-000000000000",
  Uint8List.fromList([0]),
  false); //returns Characteristic to chain operations more easily

service.writeCharacteristic(
  "F000AA02-0451-4000-B000-000000000000",
  Uint8List.fromList([0]),
  false); //returns Characteristic to chain operations more easily

characteristic.write(Uint8List.fromList([0]), false); //returns void

```

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

### Cancel Asynchronous BLE Operation

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

Demonstrates how to cancel an ongoing asynchronous operation like discovering services using a transaction ID. The operation will be marked as cancelled, but may still complete execution.

```dart
//assuming peripheral is connected
peripheral.discoverAllServicesAndCharacteristics(transactionId: "discovery");
//will return operation cancelled error after calling the below
bleManager.cancelTransaction("discovery");

```
Tokens:
Raw