{"id":13599917,"url":"https://github.com/deviceplug/btleplug","last_synced_at":"2025-05-14T13:06:13.887Z","repository":{"id":37396948,"uuid":"232967656","full_name":"deviceplug/btleplug","owner":"deviceplug","description":"Rust Cross-Platform Host-Side Bluetooth LE Access Library","archived":false,"fork":false,"pushed_at":"2025-04-20T20:18:55.000Z","size":1131,"stargazers_count":918,"open_issues_count":88,"forks_count":162,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-04-20T20:30:54.740Z","etag":null,"topics":["android","bluetooth","bluetooth-le","bluetooth-low-energy","ios","linux","macos","rust","windows"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deviceplug.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","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},"funding":{"github":"qdot","patreon":"qdot","ko_fi":"qdot76367"}},"created_at":"2020-01-10T04:47:59.000Z","updated_at":"2025-04-20T05:22:58.000Z","dependencies_parsed_at":"2023-12-14T12:28:11.423Z","dependency_job_id":"ef51356c-1db3-41b1-bc31-82a5d56e9409","html_url":"https://github.com/deviceplug/btleplug","commit_stats":{"total_commits":668,"total_committers":64,"mean_commits":10.4375,"dds":0.7065868263473054,"last_synced_commit":"1937ff5badba24c2a857e48c2c38a1c2a1ecf6b3"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deviceplug%2Fbtleplug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deviceplug%2Fbtleplug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deviceplug%2Fbtleplug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deviceplug%2Fbtleplug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deviceplug","download_url":"https://codeload.github.com/deviceplug/btleplug/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254149949,"owners_count":22022851,"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":["android","bluetooth","bluetooth-le","bluetooth-low-energy","ios","linux","macos","rust","windows"],"created_at":"2024-08-01T17:01:18.065Z","updated_at":"2025-05-14T13:06:13.829Z","avatar_url":"https://github.com/deviceplug.png","language":"Rust","readme":"# btleplug\n\n[![Crates.io Version](https://img.shields.io/crates/v/btleplug)](https://crates.io/crates/btleplug)\n[![docs.rs page](https://docs.rs/btleplug/badge.svg)](https://docs.rs/btleplug)\n[![Crates.io Downloads](https://img.shields.io/crates/d/btleplug)](https://crates.io/crates/btleplug)\n[![Crates.io License](https://img.shields.io/crates/l/btleplug)](https://crates.io/crates/btleplug)\n\n[![Discord](https://img.shields.io/discord/738080600032018443.svg?logo=discord)](https://discord.gg/QGhMFzR)\n\n[![Github donate button](https://img.shields.io/badge/github-donate-ff69b4.svg)](https://www.github.com/sponsors/qdot)\n\nbtleplug is an async Rust BLE library, supporting Windows 10, macOS, Linux, iOS, and Android\n(including Flutter, see below for more info). \n\nIt grew out of several earlier abandoned libraries for various platforms\n([rumble](https://github.com/mwylde/rumble), [blurmac](https://github.com/servo/devices), etc...),\nwith the goal of building a fully cross platform library. If you're curious about how the library grew, [you can read more on that in this blog post](https://nonpolynomial.com/2023/10/30/how-to-beg-borrow-steal-your-way-to-a-cross-platform-bluetooth-le-library/).\n\nbtleplug is meant to be _host/central mode only_. If you are interested in peripheral BTLE (i.e.\nacting like a Bluetooth LE device instead of connecting to one), check out\n[bluster](https://github.com/dfrankland/bluster/) or [ble-peripheral-rust](https://github.com/rohitsangwan01/ble-peripheral-rust/).\n\nThis library **DOES NOT SUPPORT BLUETOOTH 2/CLASSIC**. There are no plans to add BT2/Classic\nsupport.\n\n## Platform Status\n\n- **Linux / Windows / macOS / iOS / Android**\n  - Device enumeration and characteristic/services implemented and working.\n  - Please file bugs and missing features if you find them.\n- **WASM/WebBluetooth**\n  - WebBluetooth is possible, and a PR is in, but needs review.\n  - [Tracking issue here](https://github.com/deviceplug/btleplug/issues/13)\n  - Please hold off on filing more issues until base implementation is\n    landed.\n\n### Platform Feature Table\n\n- X: Completed and released\n- O: In development\n- Blank: Not started\n\n| Feature                               | Windows | MacOS / iOS | Linux | Android |\n| ------------------------------------- | ------- | ----------- | ----- | ------- |\n| Bring Up Adapter                      | X       | X           | X     | X       |\n| Handle Multiple Adapters              |         |             | X     |         |\n| Discover Devices                      | X       | X           | X     | X       |\n| └ Discover Services                   | X       | X           | X     | X       |\n| └ Discover Characteristics            | X       | X           | X     | X       |\n| └ Discover Descriptors                | X       | X           | X     | X       |\n| └ Discover Name                       | X       | X           | X     | X       |\n| └ Discover Manufacturer Data          | X       | X           | X     | X       |\n| └ Discover Service Data               | X       | X           | X     | X       |\n| └ Discover MAC address                | X       |             | X     | X       |\n| GATT Server Connect                   | X       | X           | X     | X       |\n| GATT Server Connect Event             | X       | X           | X     | X       |\n| GATT Server Disconnect                | X       | X           | X     | X       |\n| GATT Server Disconnect Event          | X       | X           | X     | X       |\n| Write to Characteristic               | X       | X           | X     | X       |\n| Read from Characteristic              | X       | X           | X     | X       |\n| Subscribe to Characteristic           | X       | X           | X     | X       |\n| Unsubscribe from Characteristic       | X       | X           | X     | X       |\n| Get Characteristic Notification Event | X       | X           | X     | X       |\n| Read Descriptor                       | X       | X           | X     | X       |\n| Write Descriptor                      | X       | X           | X     | X       |\n| Retrieve MTU                          |         |             |       |         |\n| Retrieve Connection Interval          |         |             |       |         |\n\n## Library Features\n\n#### Serialization/Deserialization\n\nTo enable implementation of serde's `Serialize` and `Deserialize` across some common types in the `api` module, use the `serde` feature.\n\n```toml\n[dependencies]\nbtleplug = { version = \"0.11\", features = [\"serde\"] }\n```\n\n## Build/Installation Notes for Specific Platforms\n\n### macOS\n\nTo use Bluetooth on macOS Big Sur (11) or later, you need to either package your\nbinary into an application bundle with an `Info.plist` including\n`NSBluetoothAlwaysUsageDescription`, or (for a command-line application such as\nthe examples included with `btleplug`) enable the Bluetooth permission for your\nterminal. You can do the latter by going to _System Preferences_ → _Security \u0026\nPrivacy_ → _Privacy_ → _Bluetooth_, clicking the '+' button, and selecting\n'Terminal' (or iTerm or whichever terminal application you use).\n\n### Android\n\nDue to requiring a hybrid Rust/Java build, btleplug for Android requires a somewhat complicated\nsetup.\n\nSome information on performing the build is available in the [original issue for Android support in btlplug](https://github.com/deviceplug/btleplug/issues/8). \n\nA quick overview of the build process:\n\n- For java, you will need the java portion of\n  [jni-utils-rs](https://github.com/deviceplug/jni-utils-rs) available either in a Maven repository\n  or locally (if locally, you'll need to check out btleplug and change the gradle file).\n- Either build the java portion of btleplug, in the `src/droidplug/java` directory, using the\n  included gradle files, and them to a Maven repo, or have the Java portion of your android app point to that as a local implementation.\n- For Rust, the build should go as normal, though we recommend using `cargo-ndk` to build. Output\n  the jniLibs and make sure they end up in the right place in your app.\n\nProguard optimization can be an issue when using btleplug, as the .aar file generated by the java\ncode in btleplug is only accessed by native code, and can be optimized out as part of dead code\nremoval and resource shrinking. To fix this, changes will need to be made to your build.gradle file, and proguard rules will need to be defined.\n\nFor build.gradle:\n```groovy\n    buildTypes {\n        release {\n            // TODO: Add your own signing config for the release build.\n            // Signing with the debug keys for now, so `flutter run --release` works.\n            signingConfig signingConfigs.debug\n\n            shrinkResources true\n            minifyEnabled true\n\n            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'\n\n        }\n    }\n```\n\nproguard-rules.pro:\n```\n#Flutter Wrapper - Only needed if using flutter\n-keep class io.flutter.app.** { *; }\n-keep class io.flutter.plugin.**  { *; }\n-keep class io.flutter.util.**  { *; }\n-keep class io.flutter.view.**  { *; }\n-keep class io.flutter.**  { *; }\n-keep class io.flutter.plugins.**  { *; }\n\n#btleplug resources\n-keep class com.nonpolynomial.** { *; }\n-keep class io.github.gedgygedgy.** { *; }\n```\n\n### iOS\n\nAs the Corebluetooth implementation is shared between macOS and iOS, btleplug on iOS should \"just\nwork\", and seems to be stable. How this is built can vary based on your app setup and what language\nyou're binding to, but sample instructions are as follows ([taken from\nhere](https://github.com/deviceplug/btleplug/issues/12#issuecomment-1007671555)):\n\n- Write a rust library (static) that uses btleplug and exposes an FFI API to C\n- Use cbindgen to generate a C header file for that API\n- Use cargo-lipo to build a universal static lib\n- Drag the header file and the library into your Xcode project\n- Add NSBluetoothAlwaysUsageDescription to your Info.plist file\n\nThere are also some examples in the Flutter shim listed below.\n\n### Flutter\n\nWhile we don't specifically support Flutter, there's a template repo available at\n[https://github.com/trobanga/flutter_btleplug](https://github.com/trobanga/flutter_btleplug). This\ntemplate has builds for both Android and iOS using btleplug.\n\nAs flutter compilation tends to be complex across platforms, we cannot help with flutter build issues.\n\n### Tauri\n\nWhile we don't specifically support Tauri, there's a plugin available at\n[https://github.com/MnlPhlp/tauri-plugin-blec](https://github.com/MnlPhlp/tauri-plugin-blec). Please note that all Tauri questions should go to the plugin repo before coming here, we cannot help with Tauri issues as none of this project's developers use Tauri.\n\n## Alternative Libraries\n\nEveryone has different bluetooth needs, so if btleplug doesn't fit yours, try these other libraries by the rust community!\n\n- [Bluest](https://github.com/alexmoon/bluest) - Cross Platform BLE library (Windows/macOS/iOS/Linux)\n- [Bluey](https://github.com/rib/bluey) - Cross Platform BLE library (Windows/Android)\n- [Bluer](https://crates.io/crates/bluer) - Official Rust interface for Bluez on Linux, with more\n  features since it only supports one platform (we use\n  [Bluez-async](https://crates.io/crates/bluez-async) internally.)\n  \n## License\n\nBTLEPlug is covered under a BSD 3-Clause License, with some parts from\nRumble/Blurmac covered under MIT/Apache dual license, and BSD 3-Clause\nlicenses, respectively. See LICENSE.md for more info and copyright\ninformation.\n","funding_links":["https://github.com/sponsors/qdot","https://patreon.com/qdot","https://ko-fi.com/qdot76367","https://www.github.com/sponsors/qdot"],"categories":["Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeviceplug%2Fbtleplug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeviceplug%2Fbtleplug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeviceplug%2Fbtleplug/lists"}