Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/animo/react-native-ble-didcomm
React Native Bluetooth Low Energy SDK for DIDComm
https://github.com/animo/react-native-ble-didcomm
ble bluetooth didcomm react-native typescript
Last synced: 3 days ago
JSON representation
React Native Bluetooth Low Energy SDK for DIDComm
- Host: GitHub
- URL: https://github.com/animo/react-native-ble-didcomm
- Owner: animo
- License: apache-2.0
- Created: 2022-10-18T11:03:43.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-04T10:14:18.000Z (about 1 month ago)
- Last Synced: 2024-10-04T10:16:34.918Z (about 1 month ago)
- Topics: ble, bluetooth, didcomm, react-native, typescript
- Language: TypeScript
- Homepage:
- Size: 1.47 MB
- Stars: 5
- Watchers: 4
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
![Animo Logo]()
React Native Ble DIDComm
Powered by Animo & ID Crypt Global Ltd
Introduction
|
Getting started
|
Usage
|
Development
|
Contributing
|
License
---
> Refer to [docs](./docs) for some more in-depth documentation in the newer, and easier to use, API.
> The [example](./example) application shows how this can be used.
## Introduction
This package can be used as a transport for [DIDComm](https://didcomm.org) 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](https://github.com/decentralized-identity/didcomm-bluetooth/blob/main/spec.md#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:
```sh
pnpm add @animo-id/react-native-ble-didcomm
```
### Android
If 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:
```json
{
"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`:
```diff
+
+
+
+
+
+
+
+
+
```
Ensure that the device has both 'Bluetooth' and 'Location' turned on.
### iOS
Run `pod install` in the `ios/` directory
If 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):
```json
{
"ios": {
"infoPlist": {
"NSBluetoothAlwaysUsageDescription": "Allow to use bluetooth for offline proof sharing"
}
}
}
```
If you are not using Expo, add the following to your `ios//Info.plist`:
```diff
+ NSBluetoothAlwaysUsageDescription
+ Allow $(PRODUCT_NAME) to use bluetooth for offline proof sharing
```
These messages can be customized to your app needs.
## Usage
An example can be found here: [example](./example/src/App.tsx)
### Make sure the correct permissions are requested on android:
```typescript
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:
```typescript
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):
```typescript
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):
```typescript
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):
```typescript
// identifier can be retrieved from the `onDiscoverPeripheralListener`
// as shown above with the listeners
await central.connect(identifier)
```
### Send message (central):
```typescript
await central.sendMessage('Hello World!')
```
### Send indication / message (peripheral):
```typescript
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:
```sh
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](./CONTRIBUTING.md).
## License
This project is licensed under the [Apache 2.0
License](https://opensource.org/licenses/Apache-2.0).
## Credits
The initial work for this library was funded and started by [ID
Crypt Global Ltd](https://www.idcrypt.global).