Skip to content

Commit 41e33dc

Browse files
berendsliedrechtberendsliedrecht
authored
docs: added documentation on usage of bleShareProof and bleRequestProof (#100)
Signed-off-by: Berend Sliedrecht <[email protected]>
1 parent 257cdd6 commit 41e33dc

File tree

4 files changed

+195
-0
lines changed

4 files changed

+195
-0
lines changed

‎README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,9 @@
4040

4141
---
4242

43+
> Refer to [docs](./docs) for some more in-depth documentation in the newer, and easier to use, API.
44+
> The [example](./example) application shows how this can be used.
45+
4346
## Introduction
4447

4548
This package can be used as a transport for [DIDComm](https://didcomm.org) messages over Bluetooth Low Energy (BLE).

‎docs/request.md

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# BLE Request Proof Function Documentation
2+
3+
## Overview
4+
5+
The `bleRequestProof` function is designed to facilitate a proof request over Bluetooth Low Energy (BLE).
6+
7+
## Function Signature
8+
9+
```typescript
10+
export const bleRequestProof = async (options: BleRequestProofOptions) => Promise<string>
11+
```
12+
13+
## Parameters
14+
15+
The function takes a single object parameter of type `BleRequestProofOptions` with the following properties:
16+
17+
- `agent: Agent` - An instance of the Agent class from the Credo framework.
18+
- `peripheral: Peripheral` - A Peripheral object representing the BLE device.
19+
- This can be retrieved with the `usePeripheral` hook as shown in the example.
20+
- `serviceUuid: string` - The UUID of the BLE service to use.
21+
- This UUID needs to be established out-of-band, i.e. by generating one and scanning a QR code.
22+
- `presentationTemplate: PresentationTemplate` - An object containing the proof request details.
23+
- `onFailure: () => Promise<void> | void` - A callback function to be called if the proof request fails.
24+
- `onConnected?: () => Promise<void> | void` - An optional callback function to be called when the BLE connection is established.
25+
- `onDisconnected?: () => Promise<void> | void` - An optional callback function to be called when the BLE connection is disconnected.
26+
27+
## Return Value
28+
29+
Proof record id
30+
31+
## Usage Example
32+
33+
```typescript
34+
import { Agent } from '@credo-ts/core';
35+
import { bleRequestProof, PresentationTemplate, usePeripheral } from '@animo-id/react-native-ble-didcomm';
36+
37+
const agent = new Agent(/* agent configuration */);
38+
const peripheral = usePeripheral();
39+
40+
const presentationTemplate: PresentationTemplate = {
41+
id: 'template-id',
42+
name: 'Proof Request Template',
43+
requestMessage: {
44+
anoncreds: {
45+
name: 'anon-request',
46+
version: '2.0',
47+
requested_attributes: { nameGroup: { name: 'name' } },
48+
requested_predicates: {
49+
ageGroup: { name: 'age', p_value: 20, p_type: '>' },
50+
},
51+
},
52+
},
53+
};
54+
55+
const serviceUuid = 'your-service-uuid';
56+
57+
try {
58+
const proofRecordId = await bleRequestProof({
59+
agent,
60+
peripheral,
61+
serviceUuid,
62+
presentationTemplate,
63+
onFailure: () => console.error('Proof request failed'),
64+
onConnected: () => console.log('BLE connected'),
65+
onDisconnected: () => console.log('BLE disconnected')
66+
});
67+
68+
console.log(`Proof record created with ID: ${proofRecordId}`);
69+
} catch (error) {
70+
console.error('Error in bleRequestProof:', error);
71+
}
72+
```
73+
74+
## Function Flow
75+
76+
1. Starts the BLE transport for the agent.
77+
2. Sets up the indication, message and service UUID as characteristics
78+
3. Sets up a disconnection notifier.
79+
4. Sends the proof request message when connected.
80+
5. Starts a message receiver for incoming messages.
81+
6. Waits for the proof to be received and processes it.
82+
7. Returns the proof record ID upon successful completion.
83+
84+
## Error Handling
85+
86+
If an error occurs during the execution of the function, it will:
87+
88+
1. Log the error using the agent's logger.
89+
2. Call the `onFailure` callback.
90+
3. Throw the error for the caller to handle.
91+
92+
## Peer Dependencies
93+
94+
- `@credo-ts/core`
95+
- `@credo-ts/anoncreds`
96+
- `react`
97+
- `react-native`
98+
99+
## Notes
100+
101+
- The function uses credo-ts for presentation exchange.
102+
- It's designed to work with Bluetooth Low Energy, so make sure your environment supports BLE operations.
103+
- The function handles the entire flow of requesting and receiving a proof over BLE, including connection management and message exchange.

‎docs/share.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# BLE Share Proof Function Documentation
2+
3+
## Overview
4+
5+
The `bleShareProof` function is designed to facilitate a response to a proof request over Bluetooth Low Energy (BLE).
6+
7+
## Function Signature
8+
9+
```typescript
10+
export const bleShareProof = async (options: BleShareProofOptions): Promise<string>
11+
```
12+
13+
## Parameters
14+
15+
The function takes a single object parameter of type `BleShareProofOptions` with the following properties:
16+
17+
- `agent: Agent` - An instance of the Agent class from the Credo framework.
18+
- `central: Central` - A Central object representing the BLE central device.
19+
- This can be retrieved with the `useCentral` hook as shown in the example.
20+
- `serviceUuid: string` - The UUID of the BLE service to use.
21+
- This UUID needs to be established out-of-band, i.e. by generating one and scanning a QR code.
22+
- `onFailure: () => Promise<void> | void` - A callback function to be called if the proof sharing fails.
23+
- `onConnected?: () => Promise<void> | void` - An optional callback function to be called when the BLE connection is established.
24+
- `onDisconnected?: () => Promise<void> | void` - An optional callback function to be called when the BLE connection is disconnected.
25+
26+
## Return Value
27+
28+
The function returns a Promise that resolves to `void` when the proof sharing process is complete.
29+
30+
## Usage Example
31+
32+
```typescript
33+
import { Agent } from '@credo-ts/core';
34+
import { bleShareProof, useCentral } from '@animo-id/react-native-ble-didcomm';
35+
36+
const agent = new Agent(/* agent configuration */);
37+
const central = useCentral();
38+
39+
const serviceUuid = 'your-service-uuid';
40+
41+
try {
42+
await bleShareProof({
43+
agent,
44+
central,
45+
serviceUuid,
46+
onFailure: () => console.error('Proof sharing failed'),
47+
onConnected: () => console.log('BLE connected'),
48+
onDisconnected: () => console.log('BLE disconnected')
49+
});
50+
51+
console.log('Proof sharing completed successfully');
52+
} catch (error) {
53+
console.error('Error in bleShareProof:', error);
54+
}
55+
```
56+
57+
## Function Flow
58+
59+
1. Starts the BLE transport for the agent (both inbound and outbound).
60+
2. Initializes the central device and starts scanning for peripherals.
61+
3. Sets up a disconnection notifier.
62+
4. Discovers and connects to a peripheral device.
63+
5. Notifies when connected.
64+
6. Shares the proof by:
65+
a. Receiving an out-of-band invitation.
66+
b. Automatically responding to the proof request.
67+
7. Handles the acknowledgment of the shared proof.
68+
69+
## Error Handling
70+
71+
If an error occurs during the execution of the function, it will:
72+
73+
1. Log the error using the agent's logger.
74+
2. Call the `onFailure` callback.
75+
3. Throw the error for the caller to handle.
76+
77+
## Peer Dependencies
78+
79+
- `@credo-ts/core`
80+
- `@credo-ts/anoncreds`
81+
- `react`
82+
- `react-native`
83+
84+
## Notes
85+
86+
- The function uses credo-ts for presentation exchange.
87+
- It's designed to work with Bluetooth Low Energy, so make sure your environment supports BLE operations.
88+
- The function handles the entire flow of requesting and receiving a proof over BLE, including connection management and message exchange.

‎library/src/bleShareProof.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ export const bleShareProof = async ({
4444

4545
const proofRecord = await shareProof(agent, central, serviceUuid)
4646
await handleAck(agent, central, proofRecord)
47+
return proofRecord.id
4748
} catch (e) {
4849
if (e instanceof Error) {
4950
agent.config.logger.error(e.message, { cause: e })

0 commit comments

Comments
 (0)