Ble Peripheral

ble_peripheral version

Ble peripheral is a Flutter plugin that allows you to use your device as Bluetooth Low Energy (BLE) peripheral

This is an OS-independent plugin for creating a BLE Generic Attribute Profile (GATT) server to broadcast user-defined services and characteristics. This is particularly useful when prototyping and testing servers on different devices with the goal of ensuring that expected behavior matches across all systems.

Setup

Android

Add required bluetooth permissions in your AndroidManifest.xml file:

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />

Ask permissions using permission_handler plugin

IOS/Macos

Add permission in info.plist

<key>NSBluetoothAlwaysUsageDescription</key>
<string>For advertise as ble peripheral</string>

For MacOS, make sure to enable bluetooth from xcode

Windows

Requires Nuget for Winrt api's

Usage

Make sure to initialize first

await BlePeripheral.initialize();

Add services before starting advertisement

String serviceBattery = "0000180F-0000-1000-8000-00805F9B34FB";

await BlePeripheral.addService(
  BleService(
    uuid: serviceBattery,
    primary: true,
    characteristics: [
      BleCharacteristic(
        uuid: "00002A19-0000-1000-8000-00805F9B34FB",
        properties: [
          CharacteristicProperties.read.index,
          CharacteristicProperties.notify.index
        ],
        value: null,
        permissions: [
          AttributePermissions.readable.index
        ],
      ),
    ],
  ),
);

Start advertising, get result in setAdvertingStartedCallback

/// set callback for advertising state
BlePeripheral.setAdvertingStartedCallback((String? error) {
  if(error != null){
    print("AdvertisingFailed: $error")
  }else{
    print("AdvertingStarted");
  }
});

// Start advertising
await BlePeripheral.startAdvertising(
  services: [serviceBattery],
  localName: "TestBle",
);

Stop advertising

await BlePeripheral.stopAdvertising();

Ble communication

This callback is common for android and Apple, simply tells us when a central device is available, on Android, we gets a device in setConnectionStateChangeCallback when a central device is ready to use, on iOS we gets a device in setCharacteristicSubscriptionChangeCallback when a central device is ready to use

// Common for Android/Apple
BlePeripheral.setBleCentralAvailabilityCallback((String deviceId,bool isAvailable) {
  Get.log("OnDeviceAvailabilityChange: $deviceId : $isAvailable");
});

// Android only, Called when central connected
BlePeripheral.setConnectionStateChangeCallback(ConnectionStateChangeCallback callback);

// Apple only, Called when central subscribes to a characteristic
BlePeripheral.setCharacteristicSubscriptionChangeCallback(CharacteristicSubscriptionChangeCallback callback);

Other available callback handlers

// Called when advertisement started/failed
BlePeripheral.setAdvertingStartedCallback(AdvertisementCallback callback);

// Called when Bluetooth radio on device turned on/off
BlePeripheral.setBleStateChangeCallback(BleStateCallback callback);

// Called when Central device tries to read a characteristics
BlePeripheral.setReadRequestCallback(ReadRequestCallback callback);

// When central tries to write to a characteristic
BlePeripheral.setWriteRequestCallback(WriteRequestCallback callback);

// Called when service added successfully
BlePeripheral.setServiceAddedCallback(ServiceAddedCallback callback);

// Only available on Android, Called when mtu changed
BlePeripheral.setMtuChangeCallback(MtuChangeCallback callback);

// Only available on Android, Called when central paired/unpaired
BlePeripheral.setBondStateChangeCallback(BondStateCallback callback);

TODO

Complete windows implementation

Note

Still under development, api's might change, this is just the initial version, feel free to contribute or report any bug!

Libraries

ble_peripheral