Geräteregistrierung

Die Geräteregistrierung ist das Kernsystem, das die UUIDs der Bluetooth-Low-Energy-(BLE-)Dienste den Gerätefabriken zuordnet. Wenn RADR nach Geräten sucht, verwendet es Dienst-UUIDs, um zu bestimmen, welche Factory die Geräteinstanz erstellen soll.

Architekturübersicht

RADR verwendet ein zweistufiges Registrierungssystem:

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

Die Registrierung wird beim Start des Geräts einmalig über initRegistry() gefüllt.

Registrierungsstruktur

Die Registrierung ist eine globale Map, die Dienst-UUIDs mit Factory-Funktionen verknüpft:

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

Dabei ist DeviceFactory wie folgt definiert:

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

Schlüsselfunktionen

Fest codierte Geräte

Fest codierte Geräte werden direkt in initRegistry() mit einer Lambda-Factory registriert. Dieser Ansatz wird für Geräte mit benutzerdefinierten Protokollen verwendet, die eine spezielle Verarbeitung erfordern.

OSSM-Beispiel

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

OSSM verwendet ein benutzerdefiniertes BLE-Protokoll mit mehreren Characteristics zur Steuerung von Geschwindigkeit, Tiefe, Sensation und Hub. Daher ist eine eigene Geräteklasse statt der generischen ButtplugIO-Implementierung erforderlich.

Wann sollte die fest codierte Registrierung verwendet werden?

Verwenden Sie die fest codierte Registrierung, wenn:

• Das Gerät verwendet ein benutzerdefiniertes Protokoll, das nicht von Buttplug.io unterstützt wird
• Sie benötigen eine spezielle Benutzeroberfläche oder Steuerlogik
• Das Gerät erfordert eine spezielle Verarbeitung der Characteristics

Dynamische Geräte (ButtplugIO)

Dynamische Geräte werden aus der Datei data/registry.json im Dateisystem geladen. Dadurch kann Unterstützung für neue Geräte hinzugefügt werden, ohne den Code zu ändern.

registry.json-Struktur

Die Registrierung ordnet Dienst-UUIDs Arrays mit Protokollspezifikationsdateien zu:

{
  "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"]
}

Jeder Eintrag ordnet eine BLE-Dienst-UUID (Schlüssel) einer oder mehreren Protokollspezifikationsdateien (Wertearray) zu.

Ablauf der Factory

Wenn ein Gerät mit einer registrierten Dienst-UUID erkannt wird:

1. ButtplugIODeviceFactory liest registry.json von LittleFS
2. Ruft die Liste der Spezifikationsdateien für die Dienst-UUID ab
3. Für jede Spezifikationsdatei:
   • Lädt und analysiert die JSON-Konfiguration
   • Vergleicht den beworbenen Gerätenamen mit den Mustern in communication[0].btle.names
   • Extrahiert die TX/RX-Characteristics für die Dienst-UUID
4. Erstellt eine LovenseDevice-Instanz mit der passenden Konfiguration

Protokollspezifikationsdateiformat

Spezifikationsdateien folgen dem 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"
        }
      }
    }
  }]
}

Geräteerkennungsablauf

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

1. Scan: RADR sucht nach BLE-Geräten
2. UUID extrahieren: Ruft die UUID des beworbenen Dienstes ab
3. Registrierungssuche: getDeviceFactory(serviceUUID) findet die Fabrik
4. Gerät erstellen: Die Factory instanziiert die entsprechende Geräteklasse

Unterstützung für neue Geräte hinzufügen

Option A: Dynamisch (Buttplug.io-Registry)

Für Geräte, die mit dem Buttplug.io-Protokoll kompatibel sind:

data/protocols/your-device.json

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

Option B: Fest codiert (benutzerdefiniertes Protokoll)

Für Geräte, die eine benutzerdefinierte Protokollverarbeitung erfordern:

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

Entwicklungsworkflow

Aktualisieren der Registrierung (Entwicklung)

Wenn Sie lokal entwickeln, verwenden Sie die Funktion „Upload Filesystem“ von PlatformIO, um das Verzeichnis data/ auf LittleFS zu flashen:

1. Ändern Sie data/registry.json oder fügen Sie Spezifikationsdateien zu data/protocols/ hinzu
2. Klicken Sie in VS Code mit PlatformIO auf Upload Filesystem (oder führen Sie pio run --target uploadfs aus).
3. Das Gerät verwendet beim nächsten Start die aktualisierte Registrierung

Aktualisieren der Registrierung (Produktion)

Der geplante Workflow für Produktionsgeräte:

1. Navigieren Sie auf dem Gerät zu Settings > Look for updates
2. RADR sucht nach Registrierungsaktualisierungen vom Server
3. Aktualisierte registry.json- und Protokolldateien werden OTA heruntergeladen
4. Die Unterstützung neuer Geräte ist ohne ein vollständiges Firmware-Update verfügbar

Wichtige Quelldateien

Weiterführende Literatur