ble_peripheral

Description:

ble peripheral

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();
copied to clipboard
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();
copied to clipboard
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",
);
copied to clipboard
Stop advertising
await BlePeripheral.stopAdvertising();
copied to clipboard
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
// Called when central subscribes to a characteristic
BlePeripheral.setCharacteristicSubscriptionChangeCallback(CharacteristicSubscriptionChangeCallback callback);

// Android only, Called when central connected/disconnected
BlePeripheral.setConnectionStateChangeCallback(ConnectionStateChangeCallback callback);
copied to clipboard
To update value of subscribed characteristic, on Apple and Android you can pass deviceId as well, to update characteristic for specific device only, else all devices subscribed to this characteristic will be notified
BlePeripheral.updateCharacteristic(characteristicId: characteristicTest,value: utf8.encode("Test Data"));
copied to clipboard
Other available callback handlers
// Called when advertisement started, stopped or 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);

// Called when mtu changed, on Apple and Windows, this will be called when a device subscribes to a characteristic
BlePeripheral.setMtuChangeCallback(MtuChangeCallback callback);

// Only available on Android, Called when central paired/unpaired
BlePeripheral.setBondStateChangeCallback(BondStateCallback callback);
copied to clipboard
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" />
copied to clipboard
Ask permissions using permission_handler plugin
IOS/Macos #
Add permission in info.plist
<key>NSBluetoothAlwaysUsageDescription</key>
<string>For advertise as ble peripheral</string>
copied to clipboard
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!