Apparaatregister

Het apparaatregister is het kernsysteem dat de UUID's van Bluetooth Low Energy (BLE)-services koppelt aan apparaatfabrieken. Wanneer RADR naar apparaten scant, gebruikt het service-UUID's om te bepalen welke fabriek de apparaatinstantie moet maken.

Architectuuroverzicht

RADR maakt gebruik van een registersysteem met twee niveaus:

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

Het register wordt één keer gevuld bij het opstarten van het apparaat via initRegistry().

Registerstructuur

Het register is een globale map die service-UUID's koppelt aan fabrieksfuncties:

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

Hierbij is DeviceFactory als volgt gedefinieerd:

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

Kernfuncties

Hardgecodeerde apparaten

Hardgecodeerde apparaten worden rechtstreeks in initRegistry() geregistreerd met een lambda-fabriek. Deze aanpak wordt gebruikt voor apparaten met aangepaste protocollen die gespecialiseerde verwerking vereisen.

OSSM-voorbeeld

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

OSSM maakt gebruik van een aangepast BLE-protocol met meerdere kenmerken voor snelheid, diepte, sensatie en slagregeling. Daarom is een speciale apparaatklasse nodig in plaats van de generieke ButtplugIO-implementatie.

Wanneer moet u hardgecodeerde registratie gebruiken?

Gebruik hardgecodeerde registratie wanneer:

• het apparaat een aangepast protocol gebruikt dat niet door Buttplug.io wordt ondersteund
• u een gespecialiseerde gebruikersinterface of besturingslogica nodig hebt
• het apparaat een speciale verwerking van kenmerken vereist

Dynamische apparaten (ButtplugIO)

Dynamische apparaten worden geladen vanuit het bestand data/registry.json op het bestandssysteem. Hierdoor kan ondersteuning voor nieuwe apparaten worden toegevoegd zonder de code te wijzigen.

registry.json-structuur

Het register koppelt service-UUID's aan arrays met protocolspecificatiebestanden:

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

Elke invoer koppelt een BLE-service-UUID (sleutel) aan een of meer protocolspecificatiebestanden (waardenarray).

Fabrieksverloop

Wanneer een apparaat met een geregistreerde service-UUID wordt ontdekt:

1. ButtplugIODeviceFactory leest registry.json van LittleFS
2. Haalt de lijst met spec-bestanden op voor de service-UUID
3. Voor elk specificatiebestand:
   • Laadt en parseert de JSON-configuratie
   • Vergelijkt de geadverteerde apparaatnaam met de patronen in communication[0].btle.names
   • Extraheert de TX/RX-kenmerken voor de service-UUID
4. Creëert een LovenseDevice-instantie met de overeenkomende configuratie

Bestandsindeling van protocolspecificaties

Specificatiebestanden volgen het Buttplug.io v4-formaat:

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

Apparaatdetectieverloop

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

1. Scan: RADR zoekt naar BLE-apparaten
2. UUID extraheren: Haalt de geadverteerde service-UUID op
3. Register opzoeken: getDeviceFactory(serviceUUID) vindt de fabriek
4. Apparaat maken: De fabriek maakt een instantie van de juiste apparaatklasse

Ondersteuning voor nieuwe apparaten toevoegen

Optie A: Dynamisch (Buttplug.io-register)

Voor apparaten die compatibel zijn met het Buttplug.io-protocol:

data/protocols/your-device.json

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

Optie B: Hardgecodeerd (aangepast protocol)

Voor apparaten die aangepaste protocolverwerking vereisen:

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

Ontwikkelingsworkflow

Het register bijwerken (ontwikkeling)

Wanneer u lokaal ontwikkelt, gebruikt u de functie "Upload Filesystem" van PlatformIO om de map data/ naar LittleFS te flashen:

1. Wijzig data/registry.json of voeg spec-bestanden toe aan data/protocols/
2. Klik in VS Code met PlatformIO op Upload Filesystem (of voer pio run --target uploadfs uit)
3. Het apparaat gebruikt het bijgewerkte register wanneer het de volgende keer opstart

Het register bijwerken (productie)

De geplande workflow voor productieapparaten:

1. Navigeer naar Settings > Look for updates op het apparaat
2. RADR controleert op registerupdates van de server
3. Bijgewerkte registry.json en protocolbestanden worden OTA gedownload
4. Ondersteuning voor nieuwe apparaten is beschikbaar zonder een volledige firmware-update

Belangrijke bronbestanden

Verder lezen