BLE Protocol

The OSSM uses Bluetooth Low Energy (BLE) for wireless control and monitoring. You can build client applications that connect to the OSSM to send commands and receive real-time state updates.

Before you begin

To connect to your OSSM via BLE, ensure:

• Your device supports Bluetooth Low Energy (BLE 4.0+)
• The OSSM is powered on and not connected to another BLE client
• You're within approximately 10 meters of the device

Service architecture

The OSSM implements a custom BLE service with multiple characteristics organized into functional groups.

Primary service UUID

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

Characteristics are organized by namespace ranges for easy expansion and discovery.

Characteristic reference

Command characteristics (writable)

Use these characteristics to send commands and configure the OSSM.

Primary command characteristic

Command format

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

Available commands

Response format

Speed knob configuration characteristic

Configuration values

Response format

Latency compensation configuration characteristic

Configuration values

Response format

WiFi configuration characteristic

Write format

set:wifi:<ssid>|<password>

The pipe character (|) is used as a delimiter between SSID and password. This allows both SSID and password to contain colons.

Read format (JSON)

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

When not connected, the ssid field will contain the last saved SSID (if any), ip will be empty, and rssi will be 0.

Response format

Example usage

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

State characteristics (read-only)

Subscribe to these characteristics to monitor the OSSM's current state.

Current state characteristic

State JSON format

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

Notification behavior

• State changes trigger immediate notifications
• Periodic notifications every 1000ms when no state change occurs
• Notifications stop when no clients are connected

Pattern information characteristics

Pattern list characteristic

Response format

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

Pattern description characteristic

To retrieve a pattern description:

Pattern descriptions

Streaming commands (experimental)

When in streaming mode (go:streaming), the OSSM accepts real-time position commands that enable synchronized playback with external content such as funscripts.

Stream position command

Example commands

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

How it works

1. Enter streaming mode with go:streaming
2. The OSSM homes to position 0 (fully retracted)
3. Send stream:<pos>:<time> commands to control motion
4. The firmware calculates the required speed to reach the target position within the specified time
5. Motion uses maximum acceleration for responsive feel

Requirements

• Firmware version 3.0 or later
• OSSM must be in streaming mode (state: streaming or streaming.idle)
• Commands sent via the primary command characteristic

GPIO characteristics

GPIO control characteristic

Write commands in the format <pin>:<state> where pin is 1-4 and state is high/low or 1/0.

Pin mapping:

Response format:

Fleshy Thrust Sync emulation (testing only)

The OSSM firmware can optionally emulate the Fleshy Thrust Sync (FTS) BLE protocol for compatibility testing with applications like faptap.net. This feature is disabled by default and requires compiling firmware with the PRETEND_TO_BE_FLESHY_THRUST_SYNC flag.

FTS service

Binary protocol format

FTS uses a compact binary format rather than text commands:

Position mapping: 0 = fully retracted, 180 = fully extended

Time format: 16-bit unsigned integer in big-endian (network byte order)

Example

To move to position 90 (50% extended) in 250ms:

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

Why not recommended

• The FTS protocol is a third-party specification not controlled by the OSSM project
• Protocol changes in FTS-compatible applications may break compatibility
• The native OSSM streaming protocol (stream:pos:time) is preferred for new integrations
• This feature exists primarily for testing compatibility with existing FTS ecosystems

Device information service

The OSSM implements the standard BLE Device Information Service for identification.

UUID namespace structure

The OSSM uses a structured UUID namespace for organized expansion.

Service UUID

0x0001 = Service UUID

Namespace ranges

Current characteristic assignments

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

Connection management

Advertising

Security

Disconnection safety

When a BLE connection is lost unexpectedly, the OSSM automatically ramps down speed to prevent runaway operation.

Ramp-down behavior:

1. Connection lost detected
2. 1 second delay — allows for brief signal dropouts without triggering
3. 2 second ramp — speed decreases from current value to zero using ease-in-out-sine curve
4. Device continues at zero speed until reconnected or manually stopped

Client considerations:

• Implement connection monitoring to detect disconnects quickly
• Consider automatic reconnection logic
• Local controls (potentiometer, encoder) remain active during and after disconnect
• Users can manually stop via the speed knob or long-press for emergency stop

Client implementation guide

Connection flow

Follow these steps to establish a connection and begin controlling your OSSM:

Best practices

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

Troubleshooting

Debug information