BLE-Protokoll

Das OSSM nutzt Bluetooth Low Energy (BLE) zur drahtlosen Steuerung und Überwachung. Sie können Clientanwendungen erstellen, die eine Verbindung zum OSSM herstellen, um Befehle zu senden und Statusaktualisierungen in Echtzeit zu empfangen.

Bevor Sie beginnen

Um über BLE eine Verbindung zu Ihrem OSSM herzustellen, stellen Sie sicher:

• Ihr Gerät unterstützt Bluetooth Low Energy (BLE 4.0+)
• Der OSSM ist eingeschaltet und nicht mit einem anderen BLE-Client verbunden
• Sie befinden sich in einem Umkreis von ca. 10 Metern um das Gerät

Servicearchitektur

Das OSSM implementiert einen benutzerdefinierten BLE-Dienst mit mehreren Merkmalen, die in Funktionsgruppen organisiert sind.

UUID des primären Dienstes

522b443a-4f53-534d-0001-420badbabe69

Die Merkmale sind zur einfachen Erweiterung und Entdeckung nach Namensraumbereichen organisiert.

Referenz der Merkmale

Befehlsmerkmale (beschreibbar)

Nutzen Sie diese Merkmale, um Befehle zu senden und den OSSM zu konfigurieren.

Primäres Befehlsmerkmal

Befehlsformat

set:<parameter>:<value>
go:<state>

Verfügbare Befehle

Antwortformat

Konfigurationsmerkmal des Geschwindigkeitsknopfs

Konfigurationswerte

Antwortformat

Konfigurationsmerkmal für die Latenzkompensation

Konfigurationswerte

Antwortformat

WiFi-Konfigurationsmerkmal

Format schreiben

set:wifi:<ssid>|<password>

Das Pipe-Zeichen (|) wird als Trennzeichen zwischen SSID und Passwort verwendet. Dadurch können sowohl SSID als auch Passwort Doppelpunkte enthalten.

Format lesen (JSON)

{
  "connected": true,
  "ssid": "NetworkName",
  "ip": "192.168.1.100",
  "rssi": -45
}

Wenn keine Verbindung besteht, enthält das Feld ssid die zuletzt gespeicherte SSID (falls vorhanden), ip ist leer und rssi ist 0.

Antwortformat

Beispielverwendung

// Configure WiFi
const wifiCommand = "set:wifi:MyNetwork|MyPassword123";
await commandChar.writeValue(new TextEncoder().encode(wifiCommand));

// Read the response
const response = await commandChar.readValue();
console.log(new TextDecoder().decode(response)); // "ok:wifi:connected"

// Check WiFi status
const wifiConfigChar = await service.getCharacteristic(
  "522b443a-4f53-534d-1020-420badbabe69"
);
const statusValue = await wifiConfigChar.readValue();
const status = JSON.parse(new TextDecoder().decode(statusValue));
console.log(status);
// { "connected": true, "ssid": "MyNetwork", "ip": "192.168.1.100", "rssi": -45 }

Zustandsmerkmale (schreibgeschützt)

Abonnieren Sie diese Merkmale, um den aktuellen Zustand des OSSM zu überwachen.

Aktuelles Zustandsmerkmal

JSON-Format des Zustands

{
  "state": "<state_name>",
  "speed": 0-100,
  "stroke": 0-100,
  "sensation": 0-100,
  "depth": 0-100,
  "pattern": 0-6
}

Benachrichtigungsverhalten

• Zustandsänderungen lösen sofortige Benachrichtigungen aus
• Regelmäßige Benachrichtigungen alle 1000 ms, wenn keine Statusänderung auftritt
• Benachrichtigungen werden gestoppt, wenn keine Clients verbunden sind

Musterinformationsmerkmale

Merkmal der Musterliste

Antwortformat

[
  { "name": "Simple Stroke", "idx": 0 },
  { "name": "Teasing Pounding", "idx": 1 },
  { "name": "Robo Stroke", "idx": 2 },
  { "name": "Half'n'Half", "idx": 3 },
  { "name": "Deeper", "idx": 4 },
  { "name": "Stop'n'Go", "idx": 5 },
  { "name": "Insist", "idx": 6 }
]

Musterbeschreibungsmerkmal

So rufen Sie eine Musterbeschreibung ab:

Musterbeschreibungen

Streaming-Befehle (experimentell)

Im Streaming-Modus (go:streaming) akzeptiert das OSSM Echtzeit-Positionsbefehle, die eine synchronisierte Wiedergabe mit externen Inhalten wie Funscripts ermöglichen.

Stream-Positionsbefehl

Beispielbefehle

stream:0:200      # Move to 0% (retracted) in 200ms
stream:100:150    # Move to 100% (extended) in 150ms
stream:50:300     # Move to 50% (mid-stroke) in 300ms

Wie es funktioniert

1. Wechseln Sie mit go:streaming in den Streaming-Modus
2. Das OSSM fährt Position 0 an (vollständig eingefahren)
3. Senden Sie stream:<pos>:<time>-Befehle, um die Bewegung zu steuern
4. Die Firmware berechnet die erforderliche Geschwindigkeit, um die Zielposition innerhalb der vorgegebenen Zeit zu erreichen
5. Die Bewegung nutzt maximale Beschleunigung für ein reaktionsfreudiges Gefühl

Anforderungen

• Firmware-Version 3.0 oder höher
• OSSM muss sich im Streaming-Modus befinden (Status: streaming oder streaming.idle).
• Befehle, die über das primäre Befehlsmerkmal gesendet werden

GPIO-Merkmale

GPIO-Steuermerkmal

Schreiben Sie Befehle im Format <pin>:<state>, wobei Pin 1-4 ist und der Status high/low oder 1/0 ist.

Pin-Zuordnung:

Antwortformat:

Fleshy Thrust Sync-Emulation (nur zum Testen)

Die OSSM-Firmware kann optional das Fleshy Thrust Sync (FTS) BLE-Protokoll für Kompatibilitätstests mit Anwendungen wie faptap.net emulieren. Diese Funktion ist standardmäßig deaktiviert und erfordert das Kompilieren der Firmware mit dem Flag PRETEND_TO_BE_FLESHY_THRUST_SYNC.

FTS-Dienst

Binäres Protokollformat

FTS verwendet ein kompaktes Binärformat anstelle von Textbefehlen:

Positionszuordnung: 0 = vollständig eingefahren, 180 = vollständig ausgefahren

Zeitformat: 16-Bit-Ganzzahl ohne Vorzeichen im Big-Endian (Netzwerk-Byte-Reihenfolge)

Beispiel

Um in 250 ms auf Position 90 (50 % ausgefahren) zu gelangen:

Byte 0: 0x5A (90 decimal - position)
Byte 1: 0x00 (250 >> 8 = 0)
Byte 2: 0xFA (250 & 0xFF = 250)

Warum nicht empfohlen

• Das FTS-Protokoll ist eine Spezifikation eines Drittanbieters, die nicht vom OSSM-Projekt kontrolliert wird
• Protokolländerungen in FTS-kompatiblen Anwendungen können die Kompatibilität beeinträchtigen
• Für neue Integrationen wird das native OSSM-Streaming-Protokoll (stream:pos:time) bevorzugt
• Diese Funktion dient hauptsächlich zum Testen der Kompatibilität mit bestehenden FTS-Ökosystemen

Geräteinformationsdienst

Das OSSM implementiert den Standard-BLE-Geräteinformationsdienst zur Identifizierung.

UUID-Namespace-Struktur

Das OSSM verwendet einen strukturierten UUID-Namespace für die organisierte Erweiterung.

Dienst-UUID

0x0001 = Service UUID

Namespacebereiche

Aktuelle Merkmalszuordnungen

522b443a-4f53-534d-1000-420badbabe69  # Primary command
522b443a-4f53-534d-1010-420badbabe69  # Speed knob configuration
522b443a-4f53-534d-1020-420badbabe69  # WiFi configuration

522b443a-4f53-534d-2000-420badbabe69  # Current state

522b443a-4f53-534d-3000-420badbabe69  # Pattern list
522b443a-4f53-534d-3010-420badbabe69  # Pattern description

522b443a-4f53-534d-4000-420badbabe69  # GPIO control

Verbindungsmanagement

Advertising

Sicherheit

Sicherheit bei Verbindungstrennung

Wenn eine BLE-Verbindung unerwartet verloren geht, verringert das OSSM automatisch die Geschwindigkeit, um einen außer Kontrolle geratenen Betrieb zu verhindern.

Ramp-Down-Verhalten:

1. Verbindungsverlust festgestellt
2. 1 Sekunde Verzögerung – ermöglicht kurze Signalausfälle ohne Auslösung
3. 2-Sekunden-Rampe – Die Geschwindigkeit nimmt mithilfe der Ease-in-out-Sinuskurve vom aktuellen Wert auf Null ab
4. Das Gerät fährt mit der Geschwindigkeit Null weiter, bis es wieder verbunden oder manuell gestoppt wird

Überlegungen für Clients:

• Implementieren Sie eine Verbindungsüberwachung, um Verbindungsabbrüche schnell zu erkennen
• Erwägen Sie die automatische Wiederverbindungslogik
• Die lokalen Bedienelemente (Potentiometer, Encoder) bleiben während und nach der Trennung aktiv
• Benutzer können manuell über den Geschwindigkeitsknopf anhalten oder für einen Notstopp lange drücken

Leitfaden zur Client-Implementierung

Verbindungsfluss

Befolgen Sie diese Schritte, um eine Verbindung herzustellen und mit der Steuerung Ihres OSSM zu beginnen:

Best Practices

Beispielcode

// Connect to OSSM
const device = await navigator.bluetooth.requestDevice({
  filters: [{ name: "OSSM" }],
  optionalServices: ["522b443a-4f53-534d-0001-420badbabe69"],
});

const server = await device.gatt.connect();
const service = await server.getPrimaryService(
  "522b443a-4f53-534d-0001-420badbabe69"
);

// Get characteristics
const commandChar = await service.getCharacteristic(
  "522b443a-4f53-534d-1000-420badbabe69"
);
const stateChar = await service.getCharacteristic(
  "522b443a-4f53-534d-2000-420badbabe69"
);
const speedKnobConfigChar = await service.getCharacteristic(
  "522b443a-4f53-534d-1010-420badbabe69"
);
const wifiConfigChar = await service.getCharacteristic(
  "522b443a-4f53-534d-1020-420badbabe69"
);
const patternsChar = await service.getCharacteristic(
  "522b443a-4f53-534d-3000-420badbabe69"
);

// Subscribe to state updates
await stateChar.startNotifications();
stateChar.addEventListener("characteristicvaluechanged", (event) => {
  const state = JSON.parse(new TextDecoder().decode(event.target.value));
  console.log("State update:", state);
});

// Configure speed knob behavior (true = knob as limit, false = independent)
await speedKnobConfigChar.writeValue(new TextEncoder().encode("true"));

// Configure WiFi
await wifiConfigChar.writeValue(new TextEncoder().encode("set:wifi:MyNetwork|MyPassword123"));

// Check WiFi status
const wifiStatus = await wifiConfigChar.readValue();
console.log("WiFi:", JSON.parse(new TextDecoder().decode(wifiStatus)));

// Send a command
const command = "set:speed:75";
await commandChar.writeValue(new TextEncoder().encode(command));

// Read available patterns
const patterns = await patternsChar.readValue();
const patternList = JSON.parse(new TextDecoder().decode(patterns));
console.log("Available patterns:", patternList);

import asyncio
import json
from bleak import BleakClient

SERVICE_UUID = "522b443a-4f53-534d-0001-420badbabe69"
COMMAND_UUID = "522b443a-4f53-534d-1000-420badbabe69"
STATE_UUID = "522b443a-4f53-534d-2000-420badbabe69"
SPEED_KNOB_UUID = "522b443a-4f53-534d-1010-420badbabe69"
WIFI_CONFIG_UUID = "522b443a-4f53-534d-1020-420badbabe69"

def state_callback(sender, data):
    """Handle state update notifications."""
    state = json.loads(data.decode())
    print(f"State update: {state}")

async def connect_to_ossm():
    async with BleakClient("OSSM") as client:
        # Subscribe to state updates
        await client.start_notify(STATE_UUID, state_callback)

        # Configure speed knob behavior
        await client.write_gatt_char(
            SPEED_KNOB_UUID,
            "true".encode()  # Knob acts as upper limit
        )

        # Configure WiFi
        await client.write_gatt_char(
            WIFI_CONFIG_UUID,
            "set:wifi:MyNetwork|MyPassword123".encode()
        )

        # Check WiFi status
        wifi_status = await client.read_gatt_char(WIFI_CONFIG_UUID)
        print(f"WiFi status: {json.loads(wifi_status.decode())}")

        # Send a command
        command = "set:speed:75"
        await client.write_gatt_char(COMMAND_UUID, command.encode())

        # Keep connection alive to receive notifications
        await asyncio.sleep(10)

asyncio.run(connect_to_ossm())

Fehlerbehebung

Debug-Informationen