{"id":20037382,"url":"https://github.com/animo/react-native-ble-didcomm","last_synced_at":"2025-05-05T06:30:44.872Z","repository":{"id":63691262,"uuid":"553530209","full_name":"animo/react-native-ble-didcomm","owner":"animo","description":"React Native Bluetooth Low Energy SDK for DIDComm","archived":false,"fork":false,"pushed_at":"2025-01-06T13:02:49.000Z","size":1477,"stargazers_count":5,"open_issues_count":5,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-08T18:39:47.822Z","etag":null,"topics":["ble","bluetooth","didcomm","react-native","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/animo.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2022-10-18T11:03:43.000Z","updated_at":"2025-01-06T13:00:54.000Z","dependencies_parsed_at":"2023-12-06T22:28:27.859Z","dependency_job_id":"2bf4fce8-54d0-449a-a4a6-b46da3a1136b","html_url":"https://github.com/animo/react-native-ble-didcomm","commit_stats":{"total_commits":57,"total_committers":7,"mean_commits":8.142857142857142,"dds":0.4035087719298246,"last_synced_commit":"a6da2db0b77012d68b8132f16174028fc3caa34a"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/animo%2Freact-native-ble-didcomm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/animo%2Freact-native-ble-didcomm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/animo%2Freact-native-ble-didcomm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/animo%2Freact-native-ble-didcomm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/animo","download_url":"https://codeload.github.com/animo/react-native-ble-didcomm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252451358,"owners_count":21749926,"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","didcomm","react-native","typescript"],"created_at":"2024-11-13T10:19:16.701Z","updated_at":"2025-05-05T06:30:44.518Z","avatar_url":"https://github.com/animo.png","language":"TypeScript","funding_links":[],"categories":["🛠 Tools \u0026 Technologies"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://res.cloudinary.com/animo-solutions/image/upload/v1656578320/animo-logo-light-no-text_ok9auy.svg\"\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://res.cloudinary.com/animo-solutions/image/upload/v1656578320/animo-logo-dark-no-text_fqqdq9.svg\"\u003e\n   \u003cimg alt=\"Animo Logo\" height=\"250px\" /\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\" \u003e\u003cb\u003eReact Native Ble DIDComm\u003c/b\u003e\u003c/h1\u003e\n\n\u003ch4 align=\"center\"\u003ePowered by Animo \u0026 ID Crypt Global Ltd\u003c/h4\u003e\u003cbr\u003e\n\n\u003c!-- TODO: Add relevant badges, like CI/CD, license, codecov, etc. --\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://typescriptlang.org\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg\" alt=\"TypeScript\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/Apache-2.0\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-Apache_2.0-yellowgreen.svg\" alt=\"Apache 2.0 License\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://badge.fury.io/js/@animo-id%2Freact-native-ble-didcomm\"\u003e\n    \u003cimg src=\"https://badge.fury.io/js/@animo-id%2Freact-native-ble-didcomm.svg\" alt=\"npm version\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#introduction\"\u003eIntroduction\u003c/a\u003e \n  \u0026nbsp;|\u0026nbsp;\n  \u003ca href=\"#getting-started\"\u003eGetting started\u003c/a\u003e \n  \u0026nbsp;|\u0026nbsp;\n  \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e \n  \u0026nbsp;|\u0026nbsp;\n  \u003ca href=\"#development\"\u003eDevelopment\u003c/a\u003e \n  \u0026nbsp;|\u0026nbsp;\n  \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e \n  \u0026nbsp;|\u0026nbsp;\n  \u003ca href=\"#contributing\"\u003eLicense\u003c/a\u003e \n\u003c/p\u003e\n\n---\n\n\u003e Refer to [docs](./docs) for some more in-depth documentation in the newer, and easier to use, API.\n\u003e The [example](./example) application shows how this can be used.\n\n## Introduction\n\nThis package can be used as a transport for [DIDComm](https://didcomm.org) messages over Bluetooth Low Energy (BLE).\nBefore using this package, roles must be established. With BLE you have a \"central\" and \"peripheral\".\nThe peripheral advertises that it is able to connect with any central that is looking for the same unique identifier\n(DIDComm UUIDs are defined here [didcomm bluetooth - identifiers](https://github.com/decentralized-identity/didcomm-bluetooth/blob/main/spec.md#identifiers)).\nA central can then scan for any peripheral advertising the DIDComm service UUID. When the central finds the peripheral, it can connect and establish a connection.\nNote that this does not establish a DIDComm connection, just the underlying BLE connection. After this, as defined in the examples below, the peripheral and central\ncan listen to incoming messages and send messages to the other participant.\n\n## Getting Started\n\nFirst, you need to add the dependency to your project:\n\n```sh\npnpm add @animo-id/react-native-ble-didcomm\n```\n\n### Android\n\nIf you are using [Expo](https://expo.dev/), you can add the plugin to your Expo app config (app.json, app.config.json or app.config.js) plugins array:\n\n```json\n{\n  \"expo\": {\n    \"plugins\": [\"@animo-id/react-native-ble-didcomm\"]\n  }\n}\n```\n\nIf you are not using Expo, add the following to your `android/app/src/main/AndroidManifest.xml`:\n\n```diff\n+   \u003cuses-permission android:name=\"android.permission.INTERNET\" /\u003e\n+   \u003cuses-permission android:name=\"android.permission.BLUETOOTH\"\n+                    android:maxSdkVersion=\"30\" /\u003e\n+   \u003cuses-permission android:name=\"android.permission.BLUETOOTH_ADMIN\"\n+                    android:maxSdkVersion=\"30\" /\u003e\n+   \u003cuses-permission android:name=\"android.permission.BLUETOOTH_SCAN\" /\u003e\n+   \u003cuses-permission android:name=\"android.permission.BLUETOOTH_ADVERTISE\" /\u003e\n+   \u003cuses-permission android:name=\"android.permission.BLUETOOTH_CONNECT\" /\u003e\n+   \u003cuses-permission android:name=\"android.permission.ACCESS_BACKGROUND_LOCATION\" /\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\nEnsure that the device has both 'Bluetooth' and 'Location' turned on.\n\n### iOS\n\nRun `pod install` in the `ios/` directory\n\nIf you are using [Expo](https://expo.dev/), you need to add the following to your Expo app config (app.json, app.config.json or app.config.js):\n\n```json\n{\n  \"ios\": {\n    \"infoPlist\": {\n      \"NSBluetoothAlwaysUsageDescription\": \"Allow \u003cYOUR_APP_NAME\u003e to use bluetooth for offline proof sharing\"\n    }\n  }\n}\n```\n\nIf you are not using Expo, add the following to your `ios/\u003cYOUR_APP_NAME\u003e/Info.plist`:\n\n```diff\n+   \u003ckey\u003eNSBluetoothAlwaysUsageDescription\u003c/key\u003e\n+   \u003cstring\u003eAllow $(PRODUCT_NAME) to use bluetooth for offline proof sharing\u003c/string\u003e\n```\n\nThese messages can be customized to your app needs.\n\n## Usage\n\nAn example can be found here: [example](./example/src/App.tsx)\n\n### Make sure the correct permissions are requested on android:\n\n```typescript\nawait PermissionsAndroid.requestMultiple([\n  'android.permission.ACCESS_FINE_LOCATION',\n  'android.permission.BLUETOOTH_CONNECT',\n  'android.permission.BLUETOOTH_SCAN',\n  'android.permission.BLUETOOTH_ADVERTISE',\n  'android.permission.ACCESS_COARSE_LOCATION'\n])\n```\n\n### Setting up the listeners:\n\n```typescript\nReact.useEffect(() =\u003e {\n  const onDiscoverPeripheralListener = central.registerOnDiscoveredListener(\n    ({ identifier }: { identifier: string }) =\u003e {\n      console.log(`Discovered: ${identifier}`)\n      setPeripheralId(identifier)\n    }\n  )\n\n  const onConnectedPeripheralListener = central.registerOnConnectedListener(\n    ({ identifier }: { identifier: string }) =\u003e {\n      console.log(`Connected to: ${identifier}`)\n      setConnected(true)\n    }\n  )\n\n  const onConnectedCentralListener = peripheral.registerOnConnectedListener(\n    console.log\n  )\n\n  const onDisconnectedCentralListener =\n    peripheral.registerOnDisconnectedListener(console.log)\n\n  const onDisconnectedPeripheralListener =\n    central.registerOnDisconnectedListener(console.log)\n\n  const onReceivedNotificationListener = central.registerMessageListener(\n    console.log\n  )\n\n  const onReceivedWriteWithoutResponseListener =\n    peripheral.registerMessageListener(console.log)\n\n  return () =\u003e {\n    onDiscoverPeripheralListener.remove()\n    onConnectedPeripheralListener.remove()\n    onConnectedCentralListener.remove()\n    onReceivedNotificationListener.remove()\n    onReceivedWriteWithoutResponseListener.remove()\n    onDisconnectedCentralListener.remove()\n    onDisconnectedPeripheralListener.remove()\n  }\n}, [])\n```\n\n### Start advertising (peripheral):\n\n```typescript\nimport {\n  Peripheral,\n  DEFAULT_DIDCOMM_SERVICE_UUID,\n  DEFAULT_DIDCOMM_MESSAGE_CHARACTERISTIC_UUID,\n  DEFAULT_DIDCOMM_INDICATE_CHARACTERISTIC_UUID\n} from '@animo-id/react-native-ble-didcomm'\n\nconst peripheral = new Peripheral()\n\nawait peripheral.start()\nawait peripheral.setService({\n  serviceUUID: DEFAULT_DIDCOMM_SERVICE_UUID,\n  messagingUUID: DEFAULT_DIDCOMM_MESSAGE_CHARACTERISTIC_UUID,\n  indicationUUID: DEFAULT_DIDCOMM_INDICATE_CHARACTERISTIC_UUID\n})\nawait peripheral.advertise()\n```\n\n### Start scanning (central):\n\n```typescript\nimport {\n  Central,\n  DEFAULT_DIDCOMM_SERVICE_UUID,\n  DEFAULT_DIDCOMM_MESSAGE_CHARACTERISTIC_UUID,\n  DEFAULT_DIDCOMM_INDICATE_CHARACTERISTIC_UUID\n} from '@animo-id/react-native-ble-didcomm'\n\nconst central = new Central()\n\nawait central.start()\nawait central.setService({\n  serviceUUID: DEFAULT_DIDCOMM_SERVICE_UUID,\n  messagingUUID: DEFAULT_DIDCOMM_MESSAGE_CHARACTERISTIC_UUID,\n  indicationUUID: DEFAULT_DIDCOMM_INDICATE_CHARACTERISTIC_UUID\n})\nawait central.scan()\n```\n\n### Connect (central):\n\n```typescript\n// identifier can be retrieved from the `onDiscoverPeripheralListener`\n// as shown above with the listeners\n\nawait central.connect(identifier)\n```\n\n### Send message (central):\n\n```typescript\nawait central.sendMessage('Hello World!')\n```\n\n### Send indication / message (peripheral):\n\n```typescript\nawait peripheral.sendMessage('Hello World!')\n```\n\n## Development\n\nWhen developing new features, you can use the application inside the `example/` folder.\n\nTo get started you can run the following commands from the root of the project:\n\n```sh\npnpm example\n\npnpm example start\n\npnpm example android\n\npod install --project-directory=example/ios\npnpm example ios\n```\n\n## Contributing\n\nIs there something you'd like to fix or add? Great, we love community\ncontributions! To get involved, please follow our [contribution\nguidelines](./CONTRIBUTING.md).\n\n## License\n\nThis project is licensed under the [Apache 2.0\nLicense](https://opensource.org/licenses/Apache-2.0).\n\n## Credits\n\nThe initial work for this library was funded and started by [ID\nCrypt Global Ltd](https://www.idcrypt.global).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanimo%2Freact-native-ble-didcomm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanimo%2Freact-native-ble-didcomm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanimo%2Freact-native-ble-didcomm/lists"}