BLE-protocol

De OSSM maakt gebruik van Bluetooth Low Energy (BLE) voor draadloze bediening en monitoring. U kunt clienttoepassingen bouwen die verbinding maken met de OSSM om opdrachten te verzenden en realtime statusupdates te ontvangen.

Voordat u begint

Om verbinding te maken met uw OSSM via BLE, zorg ervoor dat:

• Uw apparaat ondersteunt Bluetooth Low Energy (BLE 4.0+)
• De OSSM is ingeschakeld en niet verbonden met een andere BLE-client
• U bevindt zich binnen ongeveer 10 meter van het apparaat

Service-architectuur

De OSSM implementeert een aangepaste BLE-service met meerdere kenmerken, georganiseerd in functionele groepen.

Primaire service-UUID

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

Kenmerken zijn georganiseerd door naamruimtebereiken voor eenvoudige uitbreiding en ontdekking.

Referentie van de kenmerken

Opdrachtkenmerken (schrijfbaar)

Gebruik deze kenmerken om opdrachten te verzenden en de OSSM te configureren.

Primair commandokenmerk

Opdrachtformaat

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

Beschikbare opdrachten

Reactieformaat

Configuratiekenmerk van de snelheidsknop

Configuratiewaarden

Reactieformaat

Configuratiekenmerk voor latentiecompensatie

Configuratiewaarden

Reactieformaat

Configuratiekenmerk voor WiFi

Schrijfformaat

set:wifi:<ssid>|<password>

Het pipe-teken (|) wordt gebruikt als scheidingsteken tussen SSID en wachtwoord. Hierdoor kunnen zowel de SSID als het wachtwoord dubbele punten bevatten.

Leesformaat (JSON)

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

Als er geen verbinding is, bevat het veld ssid de laatst opgeslagen SSID (indien aanwezig), ip is leeg en rssi is 0.

Reactieformaat

Voorbeeldgebruik

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

Statuskenmerken (alleen-lezen)

Abonneer u op deze kenmerken om de huidige status van de OSSM te controleren.

Kenmerk van de huidige toestand

JSON-indeling van de toestand

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

Meldingsgedrag

• Statuswijzigingen leiden tot onmiddellijke meldingen
• Periodieke meldingen elke 1000 ms als er geen statuswijziging plaatsvindt
• Meldingen stoppen als er geen clients zijn verbonden

Kenmerken van patrooninformatie

Kenmerk van de patroonlijst

Reactieformaat

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

Kenmerk voor patroonbeschrijvingen

Een patroonbeschrijving ophalen:

Patroonbeschrijvingen

Streamingopdrachten (experimenteel)

In de streamingmodus (go:streaming) accepteert de OSSM real-time positieopdrachten die gesynchroniseerd afspelen met externe inhoud zoals funscripts mogelijk maken.

Commando voor streampositie

Voorbeeldopdrachten

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

Hoe het werkt

1. Ga naar de streamingmodus met go:streaming
2. De OSSM homet naar positie 0 (volledig ingetrokken)
3. Verzend stream:<pos>:<time>-opdrachten om beweging te besturen
4. De firmware berekent de vereiste snelheid om de doelpositie binnen de opgegeven tijd te bereiken
5. De beweging gebruikt maximale versnelling voor een responsief gevoel

Vereisten

• Firmwareversie 3.0 of hoger
• OSSM moet in streamingmodus staan ​​(status: streaming of streaming.idle)
• Commando's verzonden via het primaire commandokenmerk

GPIO-kenmerken

GPIO-besturingskenmerk

Schrijf opdrachten in het formaat <pin>:<state>, waarbij pin 1-4 is en de status high/low of 1/0 is.

Pin-toewijzing:

Reactieformaat:

Fleshy Thrust Sync-emulatie (alleen testen)

De OSSM-firmware kan optioneel het Fleshy Thrust Sync (FTS) BLE-protocol emuleren voor compatibiliteitstests met applicaties zoals faptap.net. Deze functie is standaard uitgeschakeld en vereist het compileren van firmware met de vlag PRETEND_TO_BE_FLESHY_THRUST_SYNC.

FTS-service

Binair protocolformaat

FTS gebruikt een compact binair formaat in plaats van tekstopdrachten:

Positietoewijzing: 0 = volledig ingetrokken, 180 = volledig uitgeschoven

Tijdnotatie: 16-bit geheel getal zonder teken in big-endian (volgorde van netwerkbytes)

Voorbeeld

Om binnen 250 ms naar positie 90 (50% uitgeschoven) te gaan:

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

Waarom niet aanbevolen

• Het FTS-protocol is een specificatie van derden die niet wordt beheerd door het OSSM-project
• Protocolwijzigingen in FTS-compatibele applicaties kunnen de compatibiliteit verbreken
• Het native OSSM-streamingprotocol (stream:pos:time) heeft de voorkeur voor nieuwe integraties
• Deze functie is voornamelijk bedoeld voor het testen van de compatibiliteit met bestaande FTS-ecosystemen

Apparaatinformatiedienst

De OSSM implementeert de standaard BLE-apparaatinformatieservice voor identificatie.

UUID-naamruimtestructuur

De OSSM gebruikt een gestructureerde UUID-naamruimte voor georganiseerde uitbreiding.

Service-UUID

0x0001 = Service UUID

Naamruimtebereiken

Huidige kenmerktoewijzingen

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

Verbindingsbeheer

Advertising

Beveiliging

Veiligheid bij verbreking

Wanneer een BLE-verbinding onverwacht wordt verbroken, verlaagt de OSSM automatisch de snelheid om ongecontroleerde werking te voorkomen.

Uitloopgedrag:

1. Verbindingsverlies gedetecteerd
2. 1 seconde vertraging — zorgt voor korte signaaluitval zonder triggering
3. 2 seconden afbouw — de snelheid neemt af van de huidige waarde naar nul met een ease-in-out-sinecurve
4. Het apparaat blijft op nulsnelheid totdat het opnieuw wordt aangesloten of handmatig wordt gestopt

Overwegingen voor clients:

• Implementeer verbindingsmonitoring om verbroken verbindingen snel te detecteren
• Overweeg automatische herverbindingslogica
• Lokale bedieningselementen (potentiometer, encoder) blijven actief tijdens en na het ontkoppelen
• Gebruikers kunnen handmatig stoppen via de snelheidsknop of lang indrukken voor een noodstop

Implementatiehandleiding voor clients

Verbindingsproces

Volg deze stappen om een ​​verbinding tot stand te brengen en uw OSSM te bedienen:

Beste praktijken

Voorbeeldcode

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

Problemen oplossen

Foutopsporingsinformatie