> ## Documentation Index
> Fetch the complete documentation index at: https://docs.researchanddesire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bluetooth Communication

> BLE protocol details and device communication for RADR

This document covers the Bluetooth Low Energy (BLE) communication protocols used by RADR to communicate with supported devices.

## BLE Overview

RADR uses Bluetooth Low Energy (BLE) for all device communication. As a BLE central device, RADR scans for and connects to peripheral devices like the OSSM and Lovense toys.

| Parameter      | Value       |
| -------------- | ----------- |
| BLE Role       | Central     |
| Device Name    | OSSM-REMOTE |
| Transmit Power | 9 dBm       |
| Stack          | NimBLE      |

## Scan Parameters

| Parameter     | Value              |
| ------------- | ------------------ |
| Scan Interval | 100ms              |
| Scan Window   | 100ms              |
| Scan Type     | Active             |
| Scan Duration | 5000ms (5 seconds) |

During active scanning, RADR sends scan request packets to devices to retrieve their full advertising data, including device names.

## Connection Parameters

RADR uses optimized connection parameters for responsive control:

| Parameter           | Value  | Description                            |
| ------------------- | ------ | -------------------------------------- |
| Min Interval        | 12     | 15ms minimum connection interval       |
| Max Interval        | 12     | 15ms maximum connection interval       |
| Latency             | 0      | No slave latency (immediate responses) |
| Supervision Timeout | 150    | 1500ms timeout for lost connections    |
| Connect Timeout     | 5000ms | Maximum time to establish connection   |

The 15ms connection interval provides responsive control with minimal latency between encoder turns and device response.

## Device Discovery

RADR identifies supported devices by their advertised service UUIDs:

### Research And Desire Devices

| Device | Service UUID                           |
| ------ | -------------------------------------- |
| OSSM   | `522B443A-4F53-534D-0001-420BADBABE69` |
| LKBX   | Pending implementation                 |
| DTT    | Pending implementation                 |

### Lovense Devices

| Device | Service UUID                           |
| ------ | -------------------------------------- |
| Domi 2 | `57300001-0023-4BD4-BBD5-A6920E4C5653` |
| Other  | Via Buttplug.io registry               |

### Buttplug.io Devices

Devices supported via the Buttplug.io protocol are identified using UUIDs from the dynamic registry (`registry.json`). This registry can be updated via firmware updates without code changes.

## OSSM Protocol

RADR communicates with OSSM using a custom BLE protocol:

### Service Structure

```
Service: 522B443A-4F53-534D-0001-420BADBABE69
├── Position Characteristic
├── Speed Characteristic
├── Depth Characteristic
├── Sensation Characteristic
├── Stroke Characteristic
└── Pattern Characteristic
```

### Command Format

Commands are sent as byte arrays to the appropriate characteristic:

| Parameter | Data Type | Range         |
| --------- | --------- | ------------- |
| Speed     | uint8\_t  | 0-100         |
| Depth     | uint8\_t  | 0-100         |
| Sensation | uint8\_t  | 0-100         |
| Stroke    | uint8\_t  | 0-100         |
| Pattern   | uint8\_t  | Pattern index |

### Pattern Selection

Patterns are selected by index:

| Index | Pattern Name     |
| ----- | ---------------- |
| 0     | Simple Stroke    |
| 1     | Teasing Pounding |
| 2     | Robo Stroke      |
| 3     | Half'n'Half      |
| 4     | Deeper           |
| 5     | Stop'n'Go        |
| 6     | Insist           |

## Lovense Protocol

For Lovense devices with direct integration (Domi), RADR uses the Lovense BLE protocol:

### Vibration Control

```
Command: Vibrate:{level};
Level: 0-16
```

### Battery Query

```
Command: Battery;
Response: {percentage}
```

### Power Control

```
Command: PowerOff;
```

## Buttplug.io Devices

For devices supported via Buttplug.io, RADR implements a subset of the Buttplug protocol:

* **Vibrate** — Set vibration level (0-1 float, mapped to device range)
* **Linear** — For thrusting devices
* **Rotate** — For rotating devices

Not all devices support all commands. RADR queries device capabilities during connection.

## Connection Recovery

If RADR loses connection to a device:

1. **Detection** — Connection loss detected within supervision timeout (1500ms)
2. **Reconnection** — Automatic reconnection attempt within 2-5 seconds
3. **Safety** — For OSSM, gradual ramp-down during disconnection
4. **Failure** — After failed reconnection, return to main menu

## Security

RADR uses open BLE connections without pairing or bonding:

* No PIN required
* No encryption (commands are plaintext)
* Single connection at a time

<Warning>
  BLE communications are not encrypted. Use RADR in private settings where radio interception is not a concern.
</Warning>

## Debugging

For BLE debugging during development:

1. Use a BLE sniffer (nRF Connect, Wireshark with BLE adapter)
2. Enable serial logging in firmware (`LOG_LEVEL_DEBUG`)
3. Monitor connection events and characteristic writes

## Further Reading

<CardGroup cols={2}>
  <Card title="NimBLE Documentation" icon="book" href="https://mynewt.apache.org/latest/network/index.html">
    NimBLE stack documentation.
  </Card>

  <Card title="Buttplug.io Protocol" icon="book" href="https://buttplug-spec.docs.buttplug.io/">
    Buttplug device protocol specification.
  </Card>
</CardGroup>