Device Registry

The device registry is the core system that maps Bluetooth Low Energy (BLE) service UUIDs to device factories. When RADR scans for devices, it uses service UUIDs to determine which factory should create the device instance.

Architecture Overview

RADR uses a two-tier registry system:

┌─────────────────────────────────────────────────────────────┐
│                    Device Registry                          │
│                                                             │
│  ┌─────────────────────┐    ┌─────────────────────────────┐│
│  │   Hardcoded Devices │    │      Dynamic Devices        ││
│  │   (Custom Factory)  │    │   (ButtplugIOFactory)       ││
│  │                     │    │                             ││
│  │  Service UUID →     │    │  registry.json →            ││
│  │  Lambda → Device    │    │  Service UUID →             ││
│  │                     │    │  Spec files → Device        ││
│  └─────────────────────┘    └─────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

The registry is populated once at device startup via initRegistry().

Registry Structure

The registry is a global map that associates service UUIDs with factory functions:

std::unordered_map<std::string, DeviceFactory> registry;

Where DeviceFactory is defined as:

typedef Device *(*DeviceFactory)(const NimBLEAdvertisedDevice *advertisedDevice);

Key Functions

Hardcoded Devices

Hardcoded devices are registered directly in initRegistry() with a lambda factory. This approach is used for devices with custom protocols that require specialized handling.

OSSM Example

registry.emplace(
    OSSM_SERVICE_ID,  // "522B443A-4F53-534D-0001-420BADBABE69"
    [](const NimBLEAdvertisedDevice *advertisedDevice) -> Device * {
        return new OSSM(advertisedDevice);
    });

The OSSM uses a custom BLE protocol with multiple characteristics for speed, depth, sensation, and stroke control. This requires a dedicated device class rather than the generic ButtplugIO implementation.

When to Use Hardcoded Registration

Use hardcoded registration when:

• The device uses a custom protocol not covered by Buttplug.io
• You need specialized UI or control logic
• The device requires unique characteristic handling

Dynamic Devices (ButtplugIO)

Dynamic devices are loaded from the data/registry.json file on the filesystem. This allows adding support for new devices without modifying code.

registry.json Structure

The registry maps service UUIDs to arrays of protocol spec files:

{
  "0000fff0-0000-1000-8000-00805f9b34fb": ["/protocols/lovense.json"],
  "88f80580-0000-01e6-aace-0002a5d5c51b": ["/protocols/kiiroo-v2.json"],
  "51361500-c5e7-47c7-8a6e-47ebc99d80e8": ["/protocols/satisfyer.json"]
}

Each entry maps a BLE service UUID (key) to one or more protocol specification files (value array).

Factory Flow

When a device with a registered service UUID is discovered:

1. ButtplugIODeviceFactory reads registry.json from LittleFS
2. Retrieves the list of spec files for the service UUID
3. For each spec file:
   • Loads and parses the JSON configuration
   • Matches the advertised device name against communication[0].btle.names patterns
   • Extracts TX/RX characteristics for the service UUID
4. Creates a LovenseDevice instance with the matched configuration

Protocol Spec File Format

Spec files follow the Buttplug.io v4 format:

{
  "defaults": {
    "name": "Lovense Device",
    "features": [...]
  },
  "configurations": [
    {
      "identifier": ["B"],
      "name": "Max",
      "features": [...]
    }
  ],
  "communication": [{
    "btle": {
      "names": ["LVS-*", "LOVE-*"],
      "services": {
        "0000fff0-0000-1000-8000-00805f9b34fb": {
          "tx": "0000fff2-0000-1000-8000-00805f9b34fb",
          "rx": "0000fff1-0000-1000-8000-00805f9b34fb"
        }
      }
    }
  }]
}

Device Discovery Flow

┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  BLE Scan    │────▶│  Get Service │────▶│  Lookup in   │────▶│   Factory    │
│  Discovers   │     │    UUID      │     │   Registry   │     │   Creates    │
│   Device     │     │              │     │              │     │   Device     │
└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘

1. Scan: RADR scans for BLE devices
2. Extract UUID: Gets the advertised service UUID
3. Registry Lookup: getDeviceFactory(serviceUUID) finds the factory
4. Create Device: Factory instantiates the appropriate device class

Adding New Device Support

Option A: Dynamic (Buttplug.io Registry)

For devices compatible with the Buttplug.io protocol:

data/protocols/your-device.json

{
  "your-service-uuid": ["/protocols/your-device.json"]
}

Option B: Hardcoded (Custom Protocol)

For devices requiring custom protocol handling:

registry.emplace(
    YOUR_SERVICE_UUID,
    [](const NimBLEAdvertisedDevice *adv) -> Device * {
        return new YourDevice(adv);
    });

Development Workflow

Updating the Registry (Development)

When developing locally, use PlatformIO's "Upload Filesystem" feature to flash the data/ directory to LittleFS:

1. Modify data/registry.json or add spec files to data/protocols/
2. In VS Code with PlatformIO, click Upload Filesystem (or run pio run --target uploadfs)
3. The device will use the updated registry on next boot

Updating the Registry (Production)

The planned workflow for production devices:

1. Navigate to Settings > Look for updates on the device
2. RADR checks for registry updates from the server
3. Updated registry.json and protocol files are downloaded OTA
4. New device support is available without a full firmware update

Key Source Files

Further Reading