{"id":28267191,"url":"https://github.com/goldenm-software/layrz_ble","last_synced_at":"2026-05-14T07:04:17.774Z","repository":{"id":266996029,"uuid":"899959629","full_name":"goldenm-software/layrz_ble","owner":"goldenm-software","description":"A simple way to interact with BLE devices in Flutter.","archived":false,"fork":false,"pushed_at":"2026-03-31T23:34:19.000Z","size":845,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-01T01:42:23.143Z","etag":null,"topics":["android","ble","bluetooth","flutter","ios","layrz","macos","web","windows"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/layrz_ble","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goldenm-software.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,"zenodo":null}},"created_at":"2024-12-07T13:40:33.000Z","updated_at":"2025-05-21T08:16:44.000Z","dependencies_parsed_at":"2025-04-14T03:23:52.920Z","dependency_job_id":"56311877-5e60-4edd-bb8d-b68077b8b247","html_url":"https://github.com/goldenm-software/layrz_ble","commit_stats":null,"previous_names":["goldenm-software/layrz_ble","goldenm-software/layrz_ble_dart"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/goldenm-software/layrz_ble","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goldenm-software%2Flayrz_ble","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goldenm-software%2Flayrz_ble/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goldenm-software%2Flayrz_ble/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goldenm-software%2Flayrz_ble/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goldenm-software","download_url":"https://codeload.github.com/goldenm-software/layrz_ble/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goldenm-software%2Flayrz_ble/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33012816,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["android","ble","bluetooth","flutter","ios","layrz","macos","web","windows"],"created_at":"2025-05-20T15:10:20.457Z","updated_at":"2026-05-14T07:04:17.762Z","avatar_url":"https://github.com/goldenm-software.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# layrz_ble\n\n[![Pub version](https://img.shields.io/pub/v/layrz_ble?logo=flutter)](https://pub.dev/packages/layrz_ble)\n[![Pub Points](https://img.shields.io/pub/points/layrz_ble)](https://pub.dev/packages/layrz_ble/score)\n[![likes](https://img.shields.io/pub/likes/layrz_ble?logo=flutter)](https://pub.dev/packages/layrz_ble/score)\n[![GitHub license](https://img.shields.io/github/license/goldenm-software/layrz_ble?logo=github)](https://github.com/goldenm-software/layrz_ble)\n\nA simple way to interact with BLE devices in Flutter.\n\n## Why should I use this library?\n\nOther libraries on the market are either too complex to use, or does not fully support functionalities like reading service data from the advertisement, or crop the manufacturer data, our objective is provide a fully functional library, with all of the ideal capabilities of a BLE library for Flutter.\n\nFor example, most of the libraries out there requires services and characteristics discovered before interacting with the device, but we auto-discover that for you, in this way, you will never forget about the services and characteristics of the device.\n\n## Functionalities available per platform\n\n### Scanning and connecting\n\n| Feature | Android | iOS | macOS | Windows | Web | Linux | Method(s) | \n| --- | --- | --- | --- | --- | --- | --- | --- |\n| Scan for BLE devices | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | `startScan`, `stopScan` and `onScan` |\n| Connect to BLE devices | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | `connect` and `onEvent` |\n| Disconnect from BLE devices | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | `disconnect` and `onEvent` |\n| Negotiate a new MTU | ✅ | ✅ | ✅ | 🟨 | ❌ | 🟨 | `setMtu` |\n| Get services and characteristics | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | `discoverServices` |\n| Read from characteristics | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | `readCharacteristic` |\n| Write to characteristics | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | `writeCharacteristic` |\n| Subscribe to characteristic notifications | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | `startNotify`, `stopNotify` and `onNotify` |\n| Multi-connection support | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | Read below |\n\n### Advertising and GATT server\n\n| Feature | Android | iOS | macOS | Windows | Web | Linux | Method(s) | \n| --- | --- | --- | --- | --- | --- | --- | --- |\n| Advertise (On Bluetooth 4 or 5) | ✅* | ❌ | ❌ | ❌ | ❌ | ❌ | `startAdvertise` and `stopAdvertise` |\n| Services and characteristics | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | `respondReadRequest` and `respondWriteRequest` |\n| Notifications | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | `sendNotification` |\n\n* On Android, the stop advertisement does not disconnect the connected devices. Be careful with that.\n\n### Languages used\n| Platform | Language |\n| --- | --- |\n| Android | Kotlin |\n| iOS | Swift |\n| macOS | Swift |\n| Windows | C++ |\n| Web | Dart |\n| Linux | Dart |\n\n### Multiple connections\nWe're not expecting to extend the support of multiple connections on this library at the moment, feel free to add it in your platform and send us a pull request, we're happy to review it and merge it.\n\n### MTU thing...\n🟨 : Well, Windows (Directly on C++) and Linux (through [`bluez` package](https://pub.dev/packages/bluez)) does not support the capability to negotiate the MTU, but yes to return the max MTU allowed, so, when you call `setMtu` you will receive the max allowed from the APIs, not a negotiated value. And why this value is important? Well, you have a size limit of the things that you want to send to your device, knowing the MTU helps to adjusts your packets sizes before sending it to the device.\n\n❌ : Web does not support neither negotiate nor getting the MTU, so, when you call `setMtu` you will receive a `null` value. Why a `null` instead of an error? Well, right now (early 2025) the Web Bluetooth API does not support the MTU, but it's on the roadmap to be implemented, so, we are returning a `null` value to indicate that the feature is not available yet, hopefully, this will change in the future.\n\n## Minimum requirements\n### Android\n\n6.0 Marshmallow (API Level 23) or later. Be careful with the permissions!.\n\n### iOS\n\niOS 14.0 or later.\n\n### macOS\n\n11.0 Big Sur or later.\n\n### Windows\n\nWindows 10.0 or later (Like as the versions supported by [Flutter](https://docs.flutter.dev/reference/supported-platforms)).\n\n### Web\n\nChromium-based browsers:\n- Google Chrome 56 or later\n- Microsoft Edge 79 or later\n- Opera 43 or later\n- Google Chrome Android 56 or later\n- Samsung Internet 6.0 or later\n\nUnfortunatelly, neither of these browsers supports Bluetooth API:\n- Mozilla Firefox\n- Apple Safari\n- Google Android WebView\n- Apple iOS WebView\n\n### Linux\n\nWe think that any Linux distribution supported by [Flutter](https://docs.flutter.dev/reference/supported-platforms) with [`bluez`](https://www.bluez.org/) stack installed should work, but we tested on Ubuntu 24.04 LTS.\n\n## Usage\nTo use this plugin, add `layrz_ble` as a [dependency in your pubspec.yaml file](https://flutter.dev/docs/development/packages-and-plugins/using-packages).\n\n```yaml\ndependencies:\n  flutter:\n    sdk: flutter\n  layrz_ble: ^latest_version\n```\n\nThen you can import the package in your Dart code:\n\n```dart\nimport 'package:layrz_ble/layrz_ble.dart';\n\n/// ...\n\nfinal ble = LayrzBle();\n\n/// Listen for events\n///\n/// `BleEvent` is from this package\nble.onEvent.listen((BleEvent event) {\n  debugPrint(event);\n});\n\n/// Listen for device discovery\n///\n/// `BleDevice` is from `layrz_models` package, but we exported it here for convenience\nble.onScan.listen((BleDevice device) {\n  debugPrint(device);\n});\n\n/// Listen for notifications\n///\n/// `BleCharacteristicNotification` is from this package\nble.onNotify.listen((BleCharacteristicNotification notification) {\n  debugPrint(notification);\n});\n\n/// GATT events, only for advertising\n///\n/// This class is a sealed class, so, you should use `gattUpdate is \u003cclass\u003e` to check the type of the event\n/// \n/// `GattConnected` triggers when a device is connected to the GATT server\n/// `GattDisconnected` triggers when a device is disconnected from the GATT server\n/// `GattReadRequest` triggers when a device requested to read a characteristic from the GATT server\n/// `GattWriteRequest` triggers when a device requested to write a characteristic from the GATT server\n/// `GattMtuChanged` triggers when the devices negotiates new the MTU size\nble.onGattUpdate.listen((BleGattUpdate gattUpdate) {\n  debugPrint(gattUpdate);\n});\n\n/// Check capabilities returns `true` if the device is capable of BLE, `false` otherwise\nfinal bool capabilities = await ble.checkCapabilities();\n\n/// Check scan permissions\nfinal bool permissions = await ble.checkScanPermissions();\n\n/// Check advertise permissions\nfinal bool permissions = await ble.checkAdvertisePermissions();\n\n/// Scan for BLE devices\nfinal bool startResult = await ble.startScan();\n\n/// Stop scanning\nfinal bool stopResult = await ble.stopScan();\n\n/// Advertise\nfinal bool advertise = await ble.startAdvertise(\n  manufacturerData: [ // \u003c- Defines the manufacturer data to be advertised\n    const BleManufacturerData(\n      companyId: 0xffff,\n      data: [0xff],\n    ),\n  ],\n  serviceData: [ // \u003c- Defines the service data to be advertised\n    const BleServiceData(\n      uuid: 0xffff,\n      data: [0xff],\n    ),\n  ],\n  canConnect: true, // \u003c- Indicates that the advertisement is connectable\n  allowBluetooth5: true, // \u003c- Indicates that the advertisement can use Bluetooth 5 features if is available\n  servicesSpecs: [ // \u003c- Defines the services and characteristics to be advertised\n    const BleService(\n      uuid: '00000000-0000-0000-0000-000000000001',\n      characteristics: [\n        BleCharacteristic(\n          uuid: '00000000-0000-0000-0000-000000000002',\n          properties: [\n            BleProperty.read,\n            BleProperty.notify,\n          ],\n        ),\n        BleCharacteristic(\n          uuid: '00000000-0000-0000-0000-000000000003',\n          properties: [BleProperty.write],\n        ),\n      ],\n    )\n  ],\n);\n```\n\n### Disclaimer about some classes used on this library\n\nPart of the classes used on this library are from the [`layrz_models`](https://pub.dev/packages/layrz_models) package.\n\n```dart\nBleDevice         // Defines the BLE device itself, and of course the packet data separated on manufacturer and service data\nBleService        // Defines the service, with the UUID and the characteristics\nBleCharacteristic // Defines the characteristic, with the UUID and the properties (In a enum format to be easy to use)\nBleProperty       // Defines the properties of the characteristic, with the most common properties defined.\n```\n\nOf course, if you think that you need more attributes, or do you want to add other, feel free to request it on [layrz_ble](https://github.com/goldenm-software/layrz_ble) repository or in the [layrz_models](https://github.com/goldenm-software/layrz_models) repository if you already has the changes done on the `layrz_ble` package. We are open to contributions and suggestions.\n\n## Permissions and requirements\n\nBefore getting into the platform specific permissions, always raises the question \"How can I handle the permissions on my Flutter app?\". Well, you can use the [`permission_handler`](https://pub.dev/packages/permission_handler) package to handle the permissions on your Flutter app, or you can handle them manually with native code, the choice is yours.\n\n### Android\n```xml\n\u003cmanifest xmlns:android=\"http://schemas.android.com/apk/res/android\"\u003e\n  \u003c!-- Location is required for BLE scan, required since Android 10 (API Level 29) --\u003e\n  \u003cuses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\" /\u003e\n  \u003cuses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\" /\u003e\n\n  \u003c!-- Of course, Bluetooth --\u003e\n  \u003cuses-permission android:name=\"android.permission.BLUETOOTH\" /\u003e\n\n  \u003c!--\n  Required for BLE scan \n  \n  Uses or BLUETOOTH_SCAN or BLUETOOTH_ADMIN permission depending on the API level.\n  If your app has a minSdkVersion of 31 or above, you should use BLUETOOTH_SCAN permission only,\n  otherwise we strongly recommend using both as shown below.\n  --\u003e\n\n  \u003c!-- android:usesPermissionFlags=\"neverForLocation\" is for tell Android that you dont want location,\n       but if you want to scan iBeacons or smart tags, you need to enable this --\u003e\n  \u003cuses-permission\n    android:name=\"android.permission.BLUETOOTH_SCAN\"\n    android:usesPermissionFlags=\"neverForLocation\"\n    android:minSdkVersion=\"31\" /\u003e \u003c!-- This permission is only for API level 31 or above --\u003e\n    \n  \u003cuses-permission\n    android:name=\"android.permission.BLUETOOTH_ADMIN\"\n    android:maxSdkVersion=\"30\" /\u003e \u003c!-- This permission is only for API level 30 or below --\u003e\n\n  \u003c!-- Required for BLE connection, in all API Levels --\u003e\n  \u003cuses-permission android:name=\"android.permission.BLUETOOTH_CONNECT\" /\u003e\n\n  \u003c!-- If you want to advertise and create a GATT server, you'll need to add this lines --\u003e\n  \u003c!-- Required for BLE advertising --\u003e\n  \u003cuses-permission\n    android:name=\"android.permission.BLUETOOTH_ADVERTISE\"\n    android:minSdkVersion=\"23\" /\u003e\n\n  \u003cuses-feature android:name=\"android.hardware.bluetooth_le\" android:required=\"true\" /\u003e\n\n  \u003c!-- ... --\u003e\n\u003c/manifest\u003e\n```\n\n### iOS\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\"\u003e\n\u003cplist version=\"1.0\"\u003e\n\u003cdict\u003e\n  \u003c!-- ... --\u003e\n  \u003c!-- Required for BLE --\u003e\n  \u003ckey\u003eNSBluetoothAlwaysUsageDescription\u003c/key\u003e\n  \u003cstring\u003eThe app need access to the Bluetooth to extract sensor values and diagnostics of the devices\u003c/string\u003e\n  \u003ckey\u003eNSBluetoothPeripheralUsageDescription\u003c/key\u003e\n  \u003cstring\u003eThe app need access to the Bluetooth to do a remote configuration of the devices compatible with\u003c/string\u003e\n  \u003c!-- ... --\u003e\n\u003c/dict\u003e\n\u003c/plist\u003e\n```\n\n### macOS\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\"\u003e\n\u003cplist version=\"1.0\"\u003e\n\u003cdict\u003e\n  \u003c!-- ... --\u003e\n  \u003c!-- Required for BLE --\u003e\n  \u003ckey\u003eNSBluetoothAlwaysUsageDescription\u003c/key\u003e\n  \u003cstring\u003eThis app uses Bluetooth to connect to your device.\u003c/string\u003e\n  \u003c!-- ... --\u003e\n\u003c/dict\u003e\n\u003c/plist\u003e\n```\n\n### Windows\nIf you use [`msix` package](https://pub.dev/packages/msix) to build your Windows app, you need to declare the permission for Bluetooth, this is an example of how to do it on your pubspec.yaml\n\n```yaml\nmsix_config:\n  capabilities: bluetooth,radios\n```\n\nMore information about the capabilities on Windows can be found on [Microsoft documentation](https://learn.microsoft.com/en-us/windows/uwp/packaging/app-capability-declarations)\n\n### Web\nNothing to do here :)\n\n### Linux\nYour platform should have `bluez` stack installed to work, otherwise the lib will not work.\n\n## Roadmap\n⬜ Permission support for each platform\n\n## FAQ\n\n### Why on some platforms I'm getting an UUID instead of a Mac Address?\nOn web, Bluetooth API does not allow developers to access the MAC Address of the devices, instead, it returns a randomly generated string for the device. Be careful with this string, is not an unique identifier along the time and devices. More information on [mdn BluetoothDevice id property](https://developer.mozilla.org/en-US/docs/Web/API/BluetoothDevice/id).\n\nOn Apple ecosystem (aka, iOS, iPadOS and macOS), Apple privacy policies are very strict, and they don't allow developers to access the MAC Address of the devices, instead, Apple OSs return a UUID for the device. Be careful with this UUID, is not an unique identifier along the time and devices. More information on [Apple Developer CBPeripheral entity documentation](https://developer.apple.com/documentation/corebluetooth/cbperipheral)\n\n### In Web, why I need to supply the services and characteristics?\nThis is a limitation of the Web Bluetooth API, you need to supply the services and characteristics to interact with the device. This is a security measure to prevent malicious websites to interact with your devices.\n\n### What's the target of the advertisement segment of this library?\nWe are targeting to provide support for Android at the moment, later maybe we will add support for other platforms, but right now, we are focusing on Android.\n\n### Why is this package called `layrz_ble`?\nAll packages developed by [Layrz](https://layrz.com) are prefixed with `layrz_`, check out our other packages on [pub.dev](https://pub.dev/publishers/goldenm.com/packages).\n\n### I need to pay to use this package?\n\u003cb\u003eNo!\u003c/b\u003e This library is free and open source, you can use it in your projects without any cost, but if you want to support us, give us a thumbs up here in [pub.dev](https://pub.dev/packages/layrz_ble) and star our [Repository](https://github.com/goldenm-software/layrz_ble)!\n\n### Can I contribute to this package?\n\u003cb\u003eYes!\u003c/b\u003e We are open to contributions, feel free to open a pull request or an issue on the [Repository](https://github.com/goldenm-software/layrz_ble)!\n\n### I have a question, how can I contact you?\nIf you need more assistance, you open an issue on the [Repository](https://github.com/goldenm-software/layrz_ble) and we're happy to help you :)\n\n## License\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\nThis project is maintained by [Golden M](https://goldenm.com) with authorization of [Layrz LTD](https://layrz.com).\n\n## Who are you? / Want to work with us?\n\u003cb\u003eGolden M\u003c/b\u003e is a software and hardware development company what is working on a new, innovative and disruptive technologies. For more information, contact us at [sales@goldenm.com](mailto:sales@goldenm.com) or via WhatsApp at [+(507)-6979-3073](https://wa.me/50769793073?text=\"From%20layrz_ble%20flutter%20library.%20Hello\").\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoldenm-software%2Flayrz_ble","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoldenm-software%2Flayrz_ble","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoldenm-software%2Flayrz_ble/lists"}