README.md

React Native Ble DIDComm

Powered by Animo & ID Crypt

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

---

Introduction

This package can be used as a transport for DIDComm messages over Bluetooh 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:

yarn add react-native-ble-didcomm

Android

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" />

iOS

Run pod install in the ios/ directory

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 = bleDidcommEmitter.addListener(
    'onDiscoverPeripheral',
    console.log
  )

  const onConnectedPeripheralListener = bleDidcommEmitter.addListener(
    'onConnectedPeripheral',
    console.log
  )

  const onReceivedNotificationListener = bleDidcommEmitter.addListener(
    'onReceivedNotification',
    console.log
  )

  const onReceivedWriteWithoutResponseListener = bleDidcommEmitter.addListener(
    'onReceivedWriteWithoutResponse',
    console.log
  )

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

Start advertising (peripheral):

import { startPeripheral, advertise } from 'react-native-ble-didcomm'

await startPeripheral()
await advertise()

Start scanning (central):

import { startCentral, scan } from 'react-native-ble-didcomm'

await startCentral()
await scan()

Connect (central):

import { connect } from 'react-native-ble-didcomm'

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

await connect(peripheralId)

Send message (central):

import { write } from 'react-native-ble-didcomm'

await write('Hello World!')

Send indication / message (peripheral):

import { notify } from 'react-native-ble-didcomm'

await notify('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:

yarn example

yarn example start

yarn example android

pod install --project-directory=example/ios
yarn 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.