Ble Peripheral #

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.

Usage #

Make sure to initialize first ( You must have required bluetooth permissions to initialize )

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
        ],
      ),
    ],
  ),
);

// To get list of added services
await BlePeripheral.getServices();

// To remove any specific services
await BlePeripheral.removeService(String serviceId);

// To remove all added services
await BlePeripheral.clearServices();

Start advertising, get result in [setAdvertisingStatusUpdateCallback]

/// set callback for advertising state
BlePeripheral.setAdvertisingStatusUpdateCallback((bool advertising, String? error) {
  print("AdvertisingStatus: $advertising Error $error")
});

// 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 and Windows only, Called when central subscribes to a characteristic
BlePeripheral.setCharacteristicSubscriptionChangeCallback(CharacteristicSubscriptionChangeCallback callback);

Other available callback handlers

// Called when advertisement started/failed
BlePeripheral.setAdvertisingStatusUpdateCallback(AdvertisementStatusUpdateCallback 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 and Windows, Called when mtu changed
BlePeripheral.setMtuChangeCallback(MtuChangeCallback callback);

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

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 #

Should work out of box on Windows

Note #

Feel free to contribute or report any bug!