README.md

React Native Ble DIDComm

Powered by Animo & ID Crypt Global Ltd

Introduction  |  Getting started  |  Usage  |  Development  |  Contributing  |  License

---

Refer to docs for some more in-depth documentation in the newer, and easier to use, API. The example application shows how this can be used.

Introduction

This package can be used as a transport for DIDComm messages over Bluetooth Low Energy (BLE). Before using this package, roles must be established. With BLE you have a "central" and "peripheral". The peripheral advertises that it is able to connect with any central that is looking for the same unique identifier (DIDComm UUIDs are defined here didcomm bluetooth - identifiers). A 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. Note 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 can listen to incoming messages and send messages to the other participant.

Getting Started

First, you need to add the dependency to your project:

pnpm add @animo-id/react-native-ble-didcomm

Android

If you are using Expo, you can add the plugin to your Expo app config (app.json, app.config.json or app.config.js) plugins array:

{
  "expo": {
    "plugins": ["@animo-id/react-native-ble-didcomm"]
  }
}

If you are not using Expo, add the following to your android/app/src/main/AndroidManifest.xml:

+   <uses-permission android:name="android.permission.INTERNET" />
+   <uses-permission android:name="android.permission.BLUETOOTH"
+                    android:maxSdkVersion="30" />
+   <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"
+                    android:maxSdkVersion="30" />
+   <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
+   <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
+   <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+   <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
+   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Ensure that the device has both 'Bluetooth' and 'Location' turned on.

iOS

Run pod install in the ios/ directory

If you are using Expo, you need to add the following to your Expo app config (app.json, app.config.json or app.config.js):

{
  "ios": {
    "infoPlist": {
      "NSBluetoothAlwaysUsageDescription": "Allow <YOUR_APP_NAME> to use bluetooth for offline proof sharing"
    }
  }
}

If you are not using Expo, add the following to your ios/<YOUR_APP_NAME>/Info.plist:

+   <key>NSBluetoothAlwaysUsageDescription</key>
+   <string>Allow $(PRODUCT_NAME) to use bluetooth for offline proof sharing</string>

These messages can be customized to your app needs.

Usage

An example can be found here: example

Make sure the correct permissions are requested on android:

await PermissionsAndroid.requestMultiple([
  'android.permission.ACCESS_FINE_LOCATION',
  'android.permission.BLUETOOTH_CONNECT',
  'android.permission.BLUETOOTH_SCAN',
  'android.permission.BLUETOOTH_ADVERTISE',
  'android.permission.ACCESS_COARSE_LOCATION'
])

Setting up the listeners:

React.useEffect(() => {
  const onDiscoverPeripheralListener = central.registerOnDiscoveredListener(
    ({ identifier }: { identifier: string }) => {
      console.log(`Discovered: ${identifier}`)
      setPeripheralId(identifier)
    }
  )

  const onConnectedPeripheralListener = central.registerOnConnectedListener(
    ({ identifier }: { identifier: string }) => {
      console.log(`Connected to: ${identifier}`)
      setConnected(true)
    }
  )

  const onConnectedCentralListener = peripheral.registerOnConnectedListener(
    console.log
  )

  const onDisconnectedCentralListener =
    peripheral.registerOnDisconnectedListener(console.log)

  const onDisconnectedPeripheralListener =
    central.registerOnDisconnectedListener(console.log)

  const onReceivedNotificationListener = central.registerMessageListener(
    console.log
  )

  const onReceivedWriteWithoutResponseListener =
    peripheral.registerMessageListener(console.log)

  return () => {
    onDiscoverPeripheralListener.remove()
    onConnectedPeripheralListener.remove()
    onConnectedCentralListener.remove()
    onReceivedNotificationListener.remove()
    onReceivedWriteWithoutResponseListener.remove()
    onDisconnectedCentralListener.remove()
    onDisconnectedPeripheralListener.remove()
  }
}, [])

Start advertising (peripheral):

import {
  Peripheral,
  DEFAULT_DIDCOMM_SERVICE_UUID,
  DEFAULT_DIDCOMM_MESSAGE_CHARACTERISTIC_UUID,
  DEFAULT_DIDCOMM_INDICATE_CHARACTERISTIC_UUID
} from '@animo-id/react-native-ble-didcomm'

const peripheral = new Peripheral()

await peripheral.start()
await peripheral.setService({
  serviceUUID: DEFAULT_DIDCOMM_SERVICE_UUID,
  messagingUUID: DEFAULT_DIDCOMM_MESSAGE_CHARACTERISTIC_UUID,
  indicationUUID: DEFAULT_DIDCOMM_INDICATE_CHARACTERISTIC_UUID
})
await peripheral.advertise()

Start scanning (central):

import {
  Central,
  DEFAULT_DIDCOMM_SERVICE_UUID,
  DEFAULT_DIDCOMM_MESSAGE_CHARACTERISTIC_UUID,
  DEFAULT_DIDCOMM_INDICATE_CHARACTERISTIC_UUID
} from '@animo-id/react-native-ble-didcomm'

const central = new Central()

await central.start()
await central.setService({
  serviceUUID: DEFAULT_DIDCOMM_SERVICE_UUID,
  messagingUUID: DEFAULT_DIDCOMM_MESSAGE_CHARACTERISTIC_UUID,
  indicationUUID: DEFAULT_DIDCOMM_INDICATE_CHARACTERISTIC_UUID
})
await central.scan()

Connect (central):

// identifier can be retrieved from the `onDiscoverPeripheralListener`
// as shown above with the listeners

await central.connect(identifier)

Send message (central):

await central.sendMessage('Hello World!')

Send indication / message (peripheral):

await peripheral.sendMessage('Hello World!')

Development

When developing new features, you can use the application inside the example/ folder.

To get started you can run the following commands from the root of the project:

pnpm example

pnpm example start

pnpm example android

pod install --project-directory=example/ios
pnpm example ios

Contributing

Is there something you'd like to fix or add? Great, we love community contributions! To get involved, please follow our contribution guidelines.

License

This project is licensed under the Apache 2.0 License.

Credits

The initial work for this library was funded and started by ID Crypt Global Ltd.