{"id":13632115,"url":"https://github.com/dotintent/react-native-ble-plx","last_synced_at":"2026-02-18T22:02:55.414Z","repository":{"id":37485000,"uuid":"64301246","full_name":"dotintent/react-native-ble-plx","owner":"dotintent","description":"React Native BLE library","archived":false,"fork":false,"pushed_at":"2026-02-18T08:05:10.000Z","size":9250,"stargazers_count":3357,"open_issues_count":43,"forks_count":550,"subscribers_count":75,"default_branch":"master","last_synced_at":"2026-02-18T12:49:54.139Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","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-pre-3.0.0.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":"2016-07-27T10:57:27.000Z","updated_at":"2026-02-18T08:05:14.000Z","dependencies_parsed_at":"2024-04-22T02:39:28.248Z","dependency_job_id":"31875a48-03fa-46b5-b27b-77f811d94113","html_url":"https://github.com/dotintent/react-native-ble-plx","commit_stats":{"total_commits":751,"total_committers":56,"mean_commits":"13.410714285714286","dds":0.5752330226364847,"last_synced_commit":"951aa80b2864c72f4c0300da7726ba4ed86c04eb"},"previous_names":["polidea/react-native-ble-plx"],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/dotintent/react-native-ble-plx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotintent%2Freact-native-ble-plx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotintent%2Freact-native-ble-plx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotintent%2Freact-native-ble-plx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotintent%2Freact-native-ble-plx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dotintent","download_url":"https://codeload.github.com/dotintent/react-native-ble-plx/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotintent%2Freact-native-ble-plx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29596333,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T20:59:56.587Z","status":"ssl_error","status_checked_at":"2026-02-18T20:58:41.434Z","response_time":162,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2024-08-01T22:02:52.315Z","updated_at":"2026-02-18T22:02:55.406Z","avatar_url":"https://github.com/dotintent.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg\n    alt=\"react-native-ble-plx library logo\"\n    src=\"docs/logo.png\"\n    height=\"300\"\n    style=\"margin-top: 20px; margin-bottom: 20px;\"\n  /\u003e\n\u003c/h1\u003e\n\n## About this library\n\nIt supports:\n\n- [observing device's Bluetooth adapter state](https://github.com/dotintent/react-native-ble-plx/wiki/Bluetooth-Adapter-State)\n- [scanning BLE devices](https://github.com/dotintent/react-native-ble-plx/wiki/Bluetooth-Scanning)\n- [making connections to peripherals](https://github.com/dotintent/react-native-ble-plx/wiki/Device-Connecting)\n- [discovering services/characteristics](https://github.com/dotintent/react-native-ble-plx/wiki/Device-Service-Discovery)\n- [reading](https://github.com/dotintent/react-native-ble-plx/wiki/Characteristic-Reading)/[writing](https://github.com/dotintent/react-native-ble-plx/wiki/Characteristic-Writing) characteristics\n- [observing characteristic notifications/indications](https://github.com/dotintent/react-native-ble-plx/wiki/Characteristic-Notifying)\n- [reading RSSI](https://github.com/dotintent/react-native-ble-plx/wiki/RSSI-Reading)\n- [negotiating MTU](https://github.com/dotintent/react-native-ble-plx/wiki/MTU-Negotiation)\n- [background mode on iOS](\u003chttps://github.com/dotintent/react-native-ble-plx/wiki/Background-mode-(iOS)\u003e)\n- turning the device's Bluetooth adapter on\n\nIt does NOT support:\n\n- bluetooth classic devices.\n- communicating between phones using BLE (Peripheral support)\n- [bonding peripherals](https://github.com/dotintent/react-native-ble-plx/wiki/Device-Bonding)\n- [beacons](https://github.com/dotintent/react-native-ble-plx/wiki/=-FAQ:-Beacons)\n\n## Table of Contents\n\n1. [Compatibility](#compatibility)\n2. [Recent Changes](#recent-changes)\n3. [Documentation \u0026 Support](#documentation--support)\n4. [Configuration \u0026 Installation](#configuration--installation)\n5. [Troubleshooting](#troubleshooting)\n6. [Contributions](#contributions)\n\n## Compatibility\n\nFor old RN versions (\u003c0.60) please check [old README](./docs/README_V1.md) (1.x)\nfor the old instructions or [migration guide](./docs/MIGRATION_V1.md).\n\n| React Native | 3.1.2              |\n| ------------ | ------------------ |\n| 0.74.1       | :white_check_mark: |\n| 0.69.6       | :white_check_mark: |\n| Expo 51      | :white_check_mark: |\n\n## Recent Changes\n\n**3.2.0**\n\n- Added Android Instance checking before calling its method, an error will be visible on the RN side\n- Added information related to Android 14 to the documentation.\n- Changed destroyClient, cancelTransaction, setLogLevel, startDeviceScan, stopDeviceScan calls to promises to allow error reporting if it occurs.\n- Fixed one of the functions calls that clean up the BLE instance after it is destroyed.\n\n[Current version changes](CHANGELOG.md)\n[All previous changes](CHANGELOG-pre-3.0.0.md)\n\n## Documentation \u0026 Support\n\nInterested in React Native project involving Bluetooth Low Energy? [We can help you!](https://withintent.com/?utm_source=github\u0026utm_medium=github\u0026utm_campaign=external_traffic)\n\n[Documentation can be found here](https://dotintent.github.io/react-native-ble-plx/).\n\nContact us at [intent](https://withintent.com/contact-us/?utm_source=github\u0026utm_medium=github\u0026utm_campaign=external_traffic).\n\n## Configuration \u0026 Installation\n\n### Expo SDK 43+\n\n\u003e Tested against Expo SDK 49\n\u003e This package cannot be used in the \"Expo Go\" app because [it requires custom native code](https://docs.expo.io/workflow/customizing/).\n\u003e First install the package with yarn, npm, or [`npx expo install`](https://docs.expo.io/workflow/expo-cli/#expo-install).\n\nAfter installing this npm package, add the [config plugin](https://docs.expo.io/guides/config-plugins/) to the [`plugins`](https://docs.expo.io/versions/latest/config/app/#plugins) array of your `app.json` or `app.config.js`:\n\n```json\n{\n  \"expo\": {\n    \"plugins\": [\"react-native-ble-plx\"]\n  }\n}\n```\n\nThen you should build the version using native modules (e.g. with `npx expo prebuild` command).\nAnd install it directly into your device with `npx expo run:android`.\n\nYou can find more details in the [\"Adding custom native code\"](https://docs.expo.io/workflow/customizing/) guide.\n\n## API\n\nThe plugin provides props for extra customization. Every time you change the props or plugins, you'll need to rebuild (and `prebuild`) the native app. If no extra properties are added, defaults will be used.\n\n- `isBackgroundEnabled` (_boolean_): Enable background BLE support on Android. Adds `\u003cuses-feature android:name=\"android.hardware.bluetooth_le\" android:required=\"true\"/\u003e` to the `AndroidManifest.xml`. Default `false`.\n- `neverForLocation` (_boolean_): Set to true only if you can strongly assert that your app never derives physical location from Bluetooth scan results. The location permission will be still required on older Android devices. Note, that some BLE beacons are filtered from the scan results. Android SDK 31+. Default `false`. _WARNING: This parameter is experimental and BLE might not work. Make sure to test before releasing to production._\n- `modes` (_string[]_): Adds iOS `UIBackgroundModes` to the `Info.plist`. Options are: `peripheral`, and `central`. Defaults to undefined.\n- `bluetoothAlwaysPermission` (_string | false_): Sets the iOS `NSBluetoothAlwaysUsageDescription` permission message to the `Info.plist`. Setting `false` will skip adding the permission. Defaults to `Allow $(PRODUCT_NAME) to connect to bluetooth devices`.\n\n\u003e Expo SDK 48 supports iOS 13+ which means `NSBluetoothPeripheralUsageDescription` is fully deprecated. It is no longer setup in `@config-plugins/react-native-ble-plx@5.0.0` and greater.\n\n#### Example\n\n```json\n{\n  \"expo\": {\n    \"plugins\": [\n      [\n        \"react-native-ble-plx\",\n        {\n          \"isBackgroundEnabled\": true,\n          \"modes\": [\"peripheral\", \"central\"],\n          \"bluetoothAlwaysPermission\": \"Allow $(PRODUCT_NAME) to connect to bluetooth devices\"\n        }\n      ]\n    ]\n  }\n}\n```\n\n### Legacy Expo (SDK \u003c 43)\n\n1. Make sure your Expo project is ejected (formerly: detached). You can read how to do it [here](https://docs.expo.dev/expokit/eject/). (only for Expo SDK \u003c 43)\n2. Follow steps for iOS/Android.\n\n### iOS ([example setup](https://github.com/Cierpliwy/SensorTag))\n\n1. `npm install --save react-native-ble-plx`\n1. Enter `ios` folder and run `pod update`\n1. Add `NSBluetoothAlwaysUsageDescription` in `info.plist` file. (it is a requirement since iOS 13)\n1. If you want to support background mode:\n   - In your application target go to `Capabilities` tab and enable `Uses Bluetooth LE Accessories` in\n     `Background Modes` section.\n   - Pass `restoreStateIdentifier` and `restoreStateFunction` to `BleManager` constructor.\n\n### Android ([example setup](https://github.com/Cierpliwy/SensorTag))\n\n1. `npm install --save react-native-ble-plx`\n1. In top level `build.gradle` make sure that min SDK version is at least 23:\n\n   ```groovy\n   buildscript {\n       ext {\n           ...\n           minSdkVersion = 23\n           ...\n   ```\n\n1. In `build.gradle` make sure to add jitpack repository to known repositories:\n\n   ```groovy\n   allprojects {\n       repositories {\n         ...\n         maven { url 'https://www.jitpack.io' }\n       }\n   }\n   ```\n\n1. In `AndroidManifest.xml`, add Bluetooth permissions and update `\u003cuses-sdk/\u003e`:\n\n   ```xml\n   \u003cmanifest xmlns:android=\"http://schemas.android.com/apk/res/android\"\u003e\n\n      ...\n\n      \u003c!-- Android \u003e= 12 --\u003e\n      \u003cuses-permission android:name=\"android.permission.BLUETOOTH_SCAN\" /\u003e\n      \u003cuses-permission android:name=\"android.permission.BLUETOOTH_CONNECT\" /\u003e\n      \u003c!-- Android \u003c 12 --\u003e\n      \u003cuses-permission android:name=\"android.permission.BLUETOOTH\" android:maxSdkVersion=\"30\" /\u003e\n      \u003cuses-permission android:name=\"android.permission.BLUETOOTH_ADMIN\" android:maxSdkVersion=\"30\" /\u003e\n      \u003c!-- common --\u003e\n      \u003cuses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\" /\u003e\n\n      \u003c!-- Add this line if your application always requires BLE. More info can be found on:\n          https://developer.android.com/guide/topics/connectivity/bluetooth-le.html#permissions\n        --\u003e\n      \u003cuses-feature android:name=\"android.hardware.bluetooth_le\" android:required=\"true\"/\u003e\n\n       ...\n   ```\n\n1. (Optional) In SDK 31+ You can remove `ACCESS_FINE_LOCATION` (or mark it as `android:maxSdkVersion=\"30\"` ) from `AndroidManifest.xml` and add `neverForLocation` flag into `BLUETOOTH_SCAN` permissions which says that you will not use location based on scanning eg:\n\n   ```xml\n    \u003cuses-permission android:name=\"android.permission.INTERNET\" /\u003e\n    \u003c!-- Android \u003e= 12 --\u003e\n    \u003cuses-permission android:name=\"android.permission.BLUETOOTH_SCAN\" android:usesPermissionFlags=\"neverForLocation\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.BLUETOOTH_CONNECT\" /\u003e\n    \u003c!-- Android \u003c 12 --\u003e\n    \u003cuses-permission android:name=\"android.permission.BLUETOOTH\" android:maxSdkVersion=\"30\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.BLUETOOTH_ADMIN\" android:maxSdkVersion=\"30\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\" android:maxSdkVersion=\"30\" /\u003e\n\n       ...\n   ```\n\n   With `neverForLocation` flag active, you no longer need to ask for `ACCESS_FINE_LOCATION` in your app\n\n## Troubleshooting\n\n## Contributions\n\n- Special thanks to @EvanBacon for supporting the expo config plugin.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotintent%2Freact-native-ble-plx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdotintent%2Freact-native-ble-plx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotintent%2Freact-native-ble-plx/lists"}