{"id":19775118,"url":"https://github.com/dotintent/flutterblelib","last_synced_at":"2026-01-11T04:52:57.570Z","repository":{"id":41862260,"uuid":"121622800","full_name":"dotintent/FlutterBleLib","owner":"dotintent","description":"Bluetooth Low Energy library for Flutter with support for simulating peripherals","archived":false,"fork":false,"pushed_at":"2024-05-20T04:31:08.000Z","size":3602,"stargazers_count":529,"open_issues_count":122,"forks_count":195,"subscribers_count":35,"default_branch":"develop","last_synced_at":"2024-05-21T21:15:09.851Z","etag":null,"topics":["ble","bluetooth-low-energy","flutter"],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dotintent.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-02-15T11:38:32.000Z","updated_at":"2024-06-18T16:50:47.265Z","dependencies_parsed_at":"2024-06-18T16:50:38.647Z","dependency_job_id":"6b29b1f7-48eb-4b35-9dbe-6740411d0914","html_url":"https://github.com/dotintent/FlutterBleLib","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotintent%2FFlutterBleLib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotintent%2FFlutterBleLib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotintent%2FFlutterBleLib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotintent%2FFlutterBleLib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dotintent","download_url":"https://codeload.github.com/dotintent/FlutterBleLib/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248633908,"owners_count":21136937,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ble","bluetooth-low-energy","flutter"],"created_at":"2024-11-12T05:14:55.842Z","updated_at":"2026-01-11T04:52:57.563Z","avatar_url":"https://github.com/dotintent.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Frontside](https://img.shields.io/static/v1?label=Facilitated%20by\u0026message=frontside.io\u0026color=blue)](#facilitated-by-frontside)\n[![Build Status](https://travis-ci.org/Polidea/FlutterBleLib.svg?branch=master)](https://travis-ci.org/Polidea/FlutterBleLib)\n[![pub package](https://img.shields.io/pub/vpre/flutter_ble_lib.svg)](https://pub.dev/packages/flutter_ble_lib)\n\n![Flutter BLE library logo](site/flutter-ble-lib-logo.png)\n\n# FlutterBleLib\n\nA library for all your Bluetooth Low Energy needs in Flutter. Internally utilises Polidea's\n[MultiPlatformBleAdapter](https://github.com/Polidea/MultiPlatformBleAdapter),\nwhich runs on [RxAndroidBle](https://github.com/Polidea/RxAndroidBle)\nand [RxBluetoothKit](https://github.com/Polidea/RxBluetoothKit).\n\n## BLE Simulator\n\nThis library supports [BLEmulator](https://github.com/Polidea/blemulator_flutter), the BLE simulator.\nThe simulation allows one to develop without physical smartphone or BLE peripheral and use one's production BLE–related code in automated testing.\n\n## Installation\n\nTo use this plugin, add `flutter_ble_lib` as a [dependency in your pubspec.yaml file](https://flutter.dev/docs/development/packages-and-plugins/using-packages).\n\n### Android\n\nSet `minSDKVersion` in `[project]/android/app/build.gradle` file to 18.\n\n```gradle\ndefaultConfig {\n  ...\n  minSdkVersion 18\n  ...\n}\n```\n\nSupport for Bluetooth Low Energy has been added in API 18, hence the library requires `minSDKVersion` to be set to 18. If BLE is not core to your application, [you can override it](https://stackoverflow.com/questions/27335889/how-do-i-ignore-minsdkversion-of-library-in-android-studio) and handle support detection in your code.\n\n**Notice:** You don't need to add any permissions related to BLE to the `AndroidManifest.xml`, because they are already declared in the library's native module. However, you still need to request `ACCESS_FINE_LOCATION` permission at runtime to be able to scan for peripheral. See [example's code](https://github.com/Polidea/FlutterBleLib/blob/202c6fe48300be207f80567ca4bee5b6fbc83eb5/example/lib/devices_list/devices_bloc.dart#L80) and [example's pubspec](https://github.com/Polidea/FlutterBleLib/blob/202c6fe48300be207f80567ca4bee5b6fbc83eb5/example/pubspec.yaml#L20).\n\n### iOS\n\nGo to `[project]/ios` directory and run `pod install`.\n\nAdd [Privacy - Bluetooth Always Usage Description](https://developer.apple.com/documentation/bundleresources/information_property_list/nsbluetoothalwaysusagedescription) key to `[project]/ios/Runner/Info.plist` file.\n\n```xml\n...\n\u003ckey\u003eNSBluetoothAlwaysUsageDescription\u003c/key\u003e\n\u003cstring\u003eYour own description of the purpose.\u003c/string\u003e\n...\n```\n\n#### Background mode\n\nTo support background capabilities add [The `bluetooth-central` Background Execution Mode](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/CoreBluetooth_concepts/CoreBluetoothBackgroundProcessingForIOSApps/PerformingTasksWhileYourAppIsInTheBackground.html#//apple_ref/doc/uid/TP40013257-CH7-SW6) key to `[project]/ios/Runner/Info.plist` file.\n\n```xml\n...\n\u003ckey\u003eUIBackgroundModes\u003c/key\u003e\n\u003carray\u003e\n  \u003cstring\u003ebluetooth-central\u003c/string\u003e\n\u003c/array\u003e\n...\n```\n\n## Usage\n\nThe library is organised around a few base entities, which are:\n\n- **BleManager**\n- **Peripheral**\n- **Service**\n- **Characteristic**\n- **Descriptor**\n\nYou have to create an instance _BleManager_ and initialise underlying native resources.\nUsing that instance you then obtain an instance of _Peripheral_,\nwhich can be used to run operations on the corresponding peripheral.\n\nAll operations passing the Dart-native bridge are asynchronous,\nhence all operations in the plugin return either Future or Stream.\n\nFor more informations, see [REFERENCE](https://github.com/Polidea/FlutterBleLib/blob/master/REFERENCE.md).\n\n**Notice:** this library will not handle any permissions for you. To be able to scan for peripherals on Android you need `ACCESS_FINE_LOCATION` [according to Android Developer Guide](https://developer.android.com/guide/topics/connectivity/bluetooth-le#permissions).\n\n### Initialising\n\n```dart\nBleManager bleManager = BleManager();\nawait bleManager.createClient(); //ready to go!\n// your peripheral logic\nbleManager.destroyClient(); //remember to release native resources when you're done!\n```\n\nFollowing snippets assume the library has been initialised.\n\n### Handling Bluetooth adapter state\n\n```dart\nenum BluetoothState {\n  UNKNOWN,\n  UNSUPPORTED,\n  UNAUTHORIZED,\n  POWERED_ON,\n  POWERED_OFF,\n  RESETTING,\n}\n\n\nbleManager.enableRadio(); //ANDROID-ONLY turns on BT. NOTE: doesn't check permissions\nbleManager.disableRadio() //ANDROID-ONLY turns off BT. NOTE: doesn't check permissions\nBluetoothState currentState = await bleManager.bluetoothState();\nbleManager.observeBluetoothState().listen((btState) {\n  print(btState);\n  //do your BT logic, open different screen, etc.\n});\n```\n\n### Scanning for peripherals\n\n```dart\nbleManager.startPeripheralScan(\n  uuids: [\n    \"F000AA00-0451-4000-B000-000000000000\",\n  ],\n).listen((scanResult) {\n  //Scan one peripheral and stop scanning\n  print(\"Scanned Peripheral ${scanResult.peripheral.name}, RSSI ${scanResult.rssi}\");\n  bleManager.stopPeripheralScan();\n});\n```\n\nThe snippet above starts peripheral scan and stops it after receiving first result.\nIt filters the scan results to those that advertise a service with specified UUID.\n\n**NOTE:** `isConnectable` and `overflowServiceUuids` fields of `ScanResult` are iOS-only and remain `null` on Android.\n\n\n### Connecting to saved peripheral\n\nYou can try to connect to a peripheral with known ID, be it previously scanned UUID on iOS or a MAC address on Android, and avoid the whole scanning operation in your application. To do so, you need to create an instance of `Peripheral` using:\n```dart\nPeripheral myPeripheral = bleManager.createUnsafePeripheral(\"\u003c known id \u003e\");\n```\nOnce you have the instance of the peripheral, you may proceed with the connection. But keep in mind \nthat [Android may still not find the peripheral without scanning it first](https://stackoverflow.com/questions/43476369/android-save-ble-device-to-reconnect-after-app-close/43482099#43482099).\n\n### Connecting to peripheral\n\nFirst you must obtain a _ScanResult_ from _BleManager.startPeripheralScan()_.\n\n```dart\nPeripheral peripheral = scanResult.peripheral;\nperipheral.observeConnectionState(emitCurrentValue: true, completeOnDisconnect: true)\n  .listen((connectionState) {\n    print(\"Peripheral ${scanResult.peripheral.identifier} connection state is $connectionState\");\n  });\nawait peripheral.connect();\nbool connected = await peripheral.isConnected();\nawait peripheral.disconnectOrCancelConnection();\n```\n\nThe snippet above starts observing the state of the connection to the peripheral,\nconnects to it, checks if it's connected and then disconnects from it.\n\n### Transactions\n\nMethods that do not have counterpart with opposite effect and are asynchronous accept\n`String transactionId` as an optional argument, to allow the user to cancel such an operation.\nThe Future returned to Dart will then finish with a _BleError(BleErrorCode.operationCancelled...)_,\n**but this will only discard the result of the operation, the operation itself will be executed either way**.\n\nFor example, if I decided that I no longer want to run discovery on the selected peripheral:\n\n```dart\n//assuming peripheral is connected\nperipheral.discoverAllServicesAndCharacteristics(transactionId: \"discovery\");\n//will return operation cancelled error after calling the below\nbleManager.cancelTransaction(\"discovery\");\n```\n\nEach new operation with the same _transactionId_ will cause the previous one to be cancelled with error, if it hasn't finished yet.\nIf _transactionId_ is set to null or it isn't specified at all, the library sets unique integer _transactionId_ to such operation.\n\n**NOTE:\nDo not to set integers as _transactionId_ as they are used by the library.**\n\n### Obtaining characteristics\n\nTo be able to operate on the peripheral, discovery of its services and characteristics must be run first.\n\n```dart\n//assuming peripheral is connected\nawait peripheral.discoverAllServicesAndCharacteristics();\nList\u003cService\u003e services = await peripheral.services(); //getting all services\nList\u003cCharacteristic\u003e characteristics1 = await peripheral.characteristics(\"F000AA00-0451-4000-B000-000000000000\");\nList\u003cCharacteristic\u003e characteristics2 = await services.firstWhere(\n  (service) =\u003e service.uuid == \"F000AA00-0451-4000-B000-000000000000\").characteristics();\n\n//characteristics1 and characteristics2 have the same contents\n```\n\nObjects representing characteristics have a unique identifer, so they point to one specific characteristic,\neven if there are multiple service/characteristic uuid matches.\n\n### Manipulating characteristics\n\nBelow are 3 methods of writing to a characteristic, which all result in the same effect given\nthere's only one service with specified UUID and only one characteristic with specified UUID.\n\n```dart\nperipheral.writeCharacteristic(\n  \"F000AA00-0451-4000-B000-000000000000\",\n  \"F000AA02-0451-4000-B000-000000000000\",\n  Uint8List.fromList([0]),\n  false); //returns Characteristic to chain operations more easily\n\nservice.writeCharacteristic(\n  \"F000AA02-0451-4000-B000-000000000000\",\n  Uint8List.fromList([0]),\n  false); //returns Characteristic to chain operations more easily\n\ncharacteristic.write(Uint8List.fromList([0]), false); //returns void\n```\n\nMonitoring or reading a characteristic from _Peripheral_/_Service_ level \nreturn _CharacteristicWithValue_ object, which is _Characteristic_ with additional `Uint8List value` property.\n \n ### Descriptor operations\n \nList of descriptors from a single characteristic can be obtained in a similar fashion to a list of characteristics from a single service, either from Peripheral, Service or Characteristic object.\nDescriptors can be read/written from Peripheral, Service or Characteristic by supplying necessary UUIDs, or from Descriptor object.\n\n**Note:** to enable monitoring of characteristic you should use `characteristic.monitor()` or `(peripheral/service).monitorCharacteristic()` instead of changing the value of the underlying descriptor yourself.\n \n## Facilitated by Frontside \n[Frontside](https://github.com/thefrontside) provided architectural advice and financial support for this library on behalf of [Resideo](https://github.com/resideo). \n\n## Maintained by\n\nThis library is maintained by [Polidea](https://www.polidea.com/?utm_source=Github\u0026utm_medium=Npaid\u0026utm_campaign=Main\u0026utm_term=Code\u0026utm_content=GH_NOP_MPG_COD_FBLE001)\n\n[Contact us](https://www.polidea.com/project/?utm_source=Github\u0026utm_medium=Npaid\u0026utm_campaign=Kontakt\u0026utm_term=Code\u0026utm_content=GH_NOP_KKT_COD_FBLE001)\n\n[Learn more about Polidea's BLE services](https://www.polidea.com/services/ble/?utm_source=Github\u0026utm_medium=Npaid\u0026utm_campaign=Tech_BLE\u0026utm_term=Code\u0026utm_content=GH_NOP_BLE_COD_FBLE001).\n\n#### Maintainers\n\nTBD\n\n## License\n\nCopyright 2019 Polidea Sp. z o.o\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n## More from Polidea\n\nCheck out other Polidea's BLE libraries:\n\n- [react-native-ble-plx](https://github.com/Polidea/react-native-ble-plx)\n- [RxAndroidBle](https://github.com/Polidea/RxAndroidBle)\n- [RxBluetoothKit](https://github.com/Polidea/RxBluetoothKit)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotintent%2Fflutterblelib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdotintent%2Fflutterblelib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotintent%2Fflutterblelib/lists"}