Protocole BLE

L'OSSM utilise Bluetooth Low Energy (BLE) pour le contrôle et la surveillance sans fil. Vous pouvez créer des applications client qui se connectent à l'OSSM pour envoyer des commandes et recevoir des mises à jour d'état en temps réel.

Avant de commencer

Pour vous connecter à votre OSSM via BLE, assurez-vous :

• Votre appareil prend en charge Bluetooth Low Energy (BLE 4.0+)
• L'OSSM est sous tension et n'est pas connecté à un autre client BLE
• Vous êtes à environ 10 mètres de l'appareil

Architecture des services

L'OSSM implémente un service BLE personnalisé avec de multiples caractéristiques organisées en groupes fonctionnels.

UUID du service principal

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

Les caractéristiques sont organisées par plages d'espaces de noms pour faciliter l'expansion et la découverte.

Référence des caractéristiques

Caractéristiques des commandes (inscriptibles)

Utilisez ces caractéristiques pour envoyer des commandes et configurer l'OSSM.

Caractéristique de commande principale

Format de commande

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

Commandes disponibles

Format de réponse

Caractéristique de configuration du bouton de vitesse

Valeurs de configuration

Format de réponse

Caractéristique de configuration de compensation de latence

Valeurs de configuration

Format de réponse

Caractéristique de configuration WiFi

Format d'écriture

set:wifi:<ssid>|<password>

Le caractère pipe (|) est utilisé comme délimiteur entre le SSID et le mot de passe. Cela permet à la fois au SSID et au mot de passe de contenir des deux-points.

Format de lecture (JSON)

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

Lorsqu'il n'est pas connecté, le champ ssid contiendra le dernier SSID enregistré (le cas échéant), ip sera vide et rssi sera 0.

Format de réponse

Exemple d'utilisation

// 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 }

Caractéristiques de l'état (lecture seule)

Abonnez-vous à ces caractéristiques pour surveiller l'état actuel de l'OSSM.

Caractéristique de l'état actuel

Format JSON d'état

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

Comportement de notification

• Les changements d'état déclenchent des notifications immédiates
• Notifications périodiques toutes les 1 000 ms lorsqu'aucun changement d'état ne se produit
• Les notifications s'arrêtent lorsqu'aucun client n'est connecté

Caractéristiques des informations sur les motifs

Caractéristique de la liste des motifs

Format de réponse

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

Caractéristique de description du motif

Pour récupérer une description de motif :

Descriptions des motifs

Commandes de streaming (expérimental)

En mode streaming (go:streaming), l'OSSM accepte les commandes de position en temps réel qui permettent une lecture synchronisée avec du contenu externe tel que des funscripts.

Commande de position du flux

Exemples de commandes

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

Comment ça marche

1. Entrez en mode streaming avec go:streaming
2. L'OSSM effectue son référencement jusqu’à la position 0 (complètement rétractée)
3. Envoyez des commandes stream:<pos>:<time> pour contrôler le mouvement
4. Le firmware calcule la vitesse requise pour atteindre la position cible dans le temps spécifié
5. Le mouvement utilise une accélération maximale pour une sensation de réactivité

Exigences

• Version du micrologiciel 3.0 ou ultérieure
• OSSM doit être en mode streaming (état : streaming ou streaming.idle)
• Commandes envoyées via la caractéristique de commande principale

Caractéristiques GPIO

Caractéristique de contrôle GPIO

Écrivez les commandes au format <pin>:<state> où la broche est 1-4 et l'état est high/low ou 1/0.

Mappage des broches :

Format de réponse :

Émulation Fleshy Thrust Sync (tests uniquement)

Le micrologiciel OSSM peut éventuellement émuler le protocole BLE Fleshy Thrust Sync (FTS) pour les tests de compatibilité avec des applications telles que faptap.net. Cette fonctionnalité est désactivée par défaut et nécessite la compilation du firmware avec l’option de compilation PRETEND_TO_BE_FLESHY_THRUST_SYNC.

Service FTS

Format de protocole binaire

FTS utilise un format binaire compact plutôt que des commandes texte :

Mappage de position : 0 = entièrement rétracté, 180 = entièrement étendu

Format du temps/de la durée : entier non signé de 16 bits en gros-boutiste (ordre des octets du réseau)

Exemple

Pour passer à la position 90 (étendue à 50 %) en 250 ms :

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

Pourquoi ce n'est pas recommandé

• Le protocole FTS est une spécification tierce non contrôlée par le projet OSSM
• Les modifications de protocole dans les applications compatibles FTS peuvent rompre la compatibilité
• Le protocole de streaming OSSM natif (stream:pos:time) est préféré pour les nouvelles intégrations
• Cette fonctionnalité existe principalement pour tester la compatibilité avec les écosystèmes FTS existants

Service d'informations sur les appareils

L'OSSM implémente le service d'informations sur les appareils BLE standard pour l'identification.

Structure de l'espace de noms UUID

L'OSSM utilise un espace de noms UUID structuré pour une expansion organisée.

UUID du service

0x0001 = Service UUID

Plages d'espaces de noms

Affectations de caractéristiques actuelles

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

Gestion des connexions

Diffusion BLE

Sécurité

Sécurité de déconnexion

Lorsqu'une connexion BLE est perdue de manière inattendue, l'OSSM réduit automatiquement la vitesse pour éviter un fonctionnement incontrôlable.

Comportement de décélération :

1. Connexion perdue détectée
2. Délai d'une seconde — permet de brèves interruptions de signal sans déclenchement
3. Rampe de 2 secondes — la vitesse diminue de la valeur actuelle à zéro à l'aide d'une courbe sinusoïdale à accélération/décélération progressive
4. L'appareil continue à vitesse nulle jusqu'à ce qu'il soit reconnecté ou arrêté manuellement

Considérations pour les clients :

• Mettre en œuvre une surveillance des connexions pour détecter rapidement les déconnexions
• Envisagez une logique de reconnexion automatique
• Les commandes locales (potentiomètre, encodeur) restent actives pendant et après la déconnexion
• Les utilisateurs peuvent arrêter manuellement via le bouton de vitesse ou appuyer longuement pour un arrêt d'urgence

Guide de mise en œuvre client

Flux de connexion

Suivez ces étapes pour établir une connexion et commencer à contrôler votre OSSM :

Meilleures pratiques

Exemple de code

// 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())

Dépannage

Informations de débogage