React Native Ble DIDComm
Powered by Animo & ID Crypt Global Ltd
Introduction | Getting started | Usage | Development | Contributing | License
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:
yarn 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:
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 Global Ltd.