ble_peripheral 2.2.0 ble_peripheral: ^2.2.0 copied to clipboard
Ble peripheral is a Flutter plugin that allows you to use your device as Bluetooth Low Energy (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();
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!