Skip to content

Commit

Permalink
docs: added documentation on usage of bleShareProof and bleRequestProof
Browse files Browse the repository at this point in the history
Signed-off-by: Berend Sliedrecht <[email protected]>
  • Loading branch information
berendsliedrecht committed Oct 3, 2024
1 parent a282608 commit 90d657f
Show file tree
Hide file tree
Showing 4 changed files with 196 additions and 0 deletions.
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,9 @@

---

> 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).
Expand Down
104 changes: 104 additions & 0 deletions docs/request.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
# BLE Request Proof Function Documentation

## Overview

The `bleRequestProof` function is designed to facilitate a proof request over Bluetooth Low Energy (BLE).

## Function Signature

```typescript
export const bleRequestProof = async (options: BleRequestProofOptions) => Promise<string>
```

## Parameters

The function takes a single object parameter of type `BleRequestProofOptions` with the following properties:

- `agent: Agent` - An instance of the Agent class from the Credo framework.
- `peripheral: Peripheral` - A Peripheral object representing the BLE device.
- This can be retrieved with the `usePeripheral` hook as shown in the example.
- `serviceUuid: string` - The UUID of the BLE service to use.
- This UUID needs to be established out-of-band, i.e. by generating one and scanning a QR code.
- `presentationTemplate: PresentationTemplate` - An object containing the proof request details.
- `onFailure: () => Promise<void> | void` - A callback function to be called if the proof request fails.
- `onConnected?: () => Promise<void> | void` - An optional callback function to be called when the BLE connection is established.
- `onDisconnected?: () => Promise<void> | void` - An optional callback function to be called when the BLE connection is disconnected.

## Return Value

Proof record id

## Usage Example

```typescript
import { Agent } from '@credo-ts/core';
import { bleRequestProof, PresentationTemplate, usePeripheral } from '@animo-id/react-native-ble-didcomm';
import { YourPeripheralImplementation } from './your-peripheral-implementation';

const agent = new Agent(/* agent configuration */);
const peripheral = usePeripheral();

const presentationTemplate: PresentationTemplate = {
id: 'template-id',
name: 'Proof Request Template',
requestMessage: {
anoncreds: {
name: 'anon-request',
version: '2.0',
requested_attributes: { nameGroup: { name: 'name' } },
requested_predicates: {
ageGroup: { name: 'age', p_value: 20, p_type: '>' },
},
},
},
};

const serviceUuid = 'your-service-uuid';

try {
const proofRecordId = await bleRequestProof({
agent,
peripheral,
serviceUuid,
presentationTemplate,
onFailure: () => console.error('Proof request failed'),
onConnected: () => console.log('BLE connected'),
onDisconnected: () => console.log('BLE disconnected')
});

console.log(`Proof record created with ID: ${proofRecordId}`);
} catch (error) {
console.error('Error in bleRequestProof:', error);
}
```

## Function Flow

1. Starts the BLE transport for the agent.
2. Sets up the indication, message and service UUID as characteristics
3. Sets up a disconnection notifier.
4. Sends the proof request message when connected.
5. Starts a message receiver for incoming messages.
6. Waits for the proof to be received and processes it.
7. Returns the proof record ID upon successful completion.

## Error Handling

If an error occurs during the execution of the function, it will:

1. Log the error using the agent's logger.
2. Call the `onFailure` callback.
3. Throw the error for the caller to handle.

## Peer Dependencies

- `@credo-ts/core`
- `@credo-ts/anoncreds`
- `react`
- `react-native`

## Notes

- The function uses credo-ts for presentation exchange.
- It's designed to work with Bluetooth Low Energy, so make sure your environment supports BLE operations.
- The function handles the entire flow of requesting and receiving a proof over BLE, including connection management and message exchange.
88 changes: 88 additions & 0 deletions docs/share.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# BLE Share Proof Function Documentation

## Overview

The `bleShareProof` function is designed to facilitate a response to a proof request over Bluetooth Low Energy (BLE).

## Function Signature

```typescript
export const bleShareProof = async (options: BleShareProofOptions): Promise<string>
```
## Parameters
The function takes a single object parameter of type `BleShareProofOptions` with the following properties:
- `agent: Agent` - An instance of the Agent class from the Credo framework.
- `central: Central` - A Central object representing the BLE central device.
- This can be retrieved with the `useCentral` hook as shown in the example.
- `serviceUuid: string` - The UUID of the BLE service to use.
- This UUID needs to be established out-of-band, i.e. by generating one and scanning a QR code.
- `onFailure: () => Promise<void> | void` - A callback function to be called if the proof sharing fails.
- `onConnected?: () => Promise<void> | void` - An optional callback function to be called when the BLE connection is established.
- `onDisconnected?: () => Promise<void> | void` - An optional callback function to be called when the BLE connection is disconnected.
## Return Value
The function returns a Promise that resolves to `void` when the proof sharing process is complete.
## Usage Example
```typescript
import { Agent } from '@credo-ts/core';
import { bleShareProof, useCentral } from '@animo-id/react-native-ble-didcomm';

const agent = new Agent(/* agent configuration */);
const central = useCentral();

const serviceUuid = 'your-service-uuid';

try {
await bleShareProof({
agent,
central,
serviceUuid,
onFailure: () => console.error('Proof sharing failed'),
onConnected: () => console.log('BLE connected'),
onDisconnected: () => console.log('BLE disconnected')
});

console.log('Proof sharing completed successfully');
} catch (error) {
console.error('Error in bleShareProof:', error);
}
```

## Function Flow

1. Starts the BLE transport for the agent (both inbound and outbound).
2. Initializes the central device and starts scanning for peripherals.
3. Sets up a disconnection notifier.
4. Discovers and connects to a peripheral device.
5. Notifies when connected.
6. Shares the proof by:
a. Receiving an out-of-band invitation.
b. Automatically responding to the proof request.
7. Handles the acknowledgment of the shared proof.

## Error Handling

If an error occurs during the execution of the function, it will:

1. Log the error using the agent's logger.
2. Call the `onFailure` callback.
3. Throw the error for the caller to handle.

## Peer Dependencies

- `@credo-ts/core`
- `@credo-ts/anoncreds`
- `react`
- `react-native`

## Notes

- The function uses credo-ts for presentation exchange.
- It's designed to work with Bluetooth Low Energy, so make sure your environment supports BLE operations.
- The function handles the entire flow of requesting and receiving a proof over BLE, including connection management and message exchange.
1 change: 1 addition & 0 deletions library/src/bleShareProof.ts
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ export const bleShareProof = async ({

const proofRecord = await shareProof(agent, central, serviceUuid)
await handleAck(agent, central, proofRecord)
return proofRecord.id
} catch (e) {
if (e instanceof Error) {
agent.config.logger.error(e.message, { cause: e })
Expand Down

0 comments on commit 90d657f

Please sign in to comment.