BLE provides low-latency wireless control with automatic reconnection and state synchronization.
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
Characteristic reference
Command characteristics (writable)
Use these characteristics to send commands and configure the OSSM.Primary command characteristic
| Property | Value |
|---|---|
| UUID | 522b443a-4f53-534d-1000-420badbabe69 |
| Properties | READ, WRITE |
| Purpose | Send commands to control OSSM behavior |
| Command | Parameter | Value Range | Description |
|---|---|---|---|
set:speed:<value> | speed | 0-100 | Set stroke speed percentage |
set:stroke:<value> | stroke | 0-100 | Set stroke length percentage |
set:depth:<value> | depth | 0-100 | Set penetration depth percentage |
set:sensation:<value> | sensation | 0-100 | Set sensation intensity percentage |
set:pattern:<value> | pattern | 0-6 | Set stroke pattern (see patterns) |
go:simplePenetration | - | - | Switch to simple penetration mode from the menu |
go:strokeEngine | - | - | Switch to stroke engine mode from the menu |
go:menu | - | - | Return to main menu from either mode |
| Response | Meaning |
|---|---|
ok:<original_command> | Command executed successfully |
fail:<original_command> | Command failed (check format or current state) |
Speed knob configuration characteristic
| Property | Value |
|---|---|
| UUID | 522b443a-4f53-534d-1010-420badbabe69 |
| Properties | READ, WRITE |
| Purpose | Configure whether the physical speed knob limits BLE speed commands |
| Value | Description |
|---|---|
true, 1, t | Speed knob acts as upper limit (default) |
false, 0, f | Speed knob and BLE speed are independent |
- Knob as limit (default)
- Independent mode
When set to
true, BLE speed commands (0-100) are treated as a percentage of the current physical knob position.Example: Knob at 50%, BLE command set:speed:80 → Effective speed = 40%This mode provides a hardware safety limit that users can control physically.| Response | Meaning |
|---|---|
true or false | Current configuration value |
error:invalid_value | Invalid input provided |
State characteristics (read-only)
Subscribe to these characteristics to monitor the OSSM’s current state.Current state characteristic
| Property | Value |
|---|---|
| UUID | 522b443a-4f53-534d-2000-420badbabe69 |
| Properties | READ, NOTIFY |
| Purpose | Monitor current OSSM state and settings |
Available states
Available states
| State | Description |
|---|---|
idle | Initializing |
homing | Homing sequence active |
homing.forward | Forward homing in progress |
homing.backward | Backward homing in progress |
menu | Main menu displayed |
menu.idle | Menu idle state |
simplePenetration | Simple penetration mode |
simplePenetration.idle | Simple penetration idle |
simplePenetration.preflight | Pre-flight checks |
strokeEngine | Stroke engine mode |
strokeEngine.idle | Stroke engine idle |
strokeEngine.preflight | Pre-flight checks |
strokeEngine.pattern | Pattern selection |
update | Update mode |
update.checking | Checking for updates |
update.updating | Update in progress |
update.idle | Update idle |
wifi | WiFi setup mode |
wifi.idle | WiFi setup idle |
help | Help screen |
help.idle | Help idle |
error | Error state |
error.idle | Error idle |
error.help | Error help |
restart | Restart state |
- 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
| Property | Value |
|---|---|
| UUID | 522b443a-4f53-534d-3000-420badbabe69 |
| Properties | READ |
| Purpose | Get available stroke patterns |
Pattern description characteristic
| Property | Value |
|---|---|
| UUID | 522b443a-4f53-534d-3010-420badbabe69 |
| Properties | READ, WRITE |
| Purpose | Get descriptions for individual stroke patterns |
1
Write the pattern index
Write the index number (0-6) to the characteristic.
2
Read the description
Read the characteristic to receive the pattern description string.
| Pattern | Index | Description |
|---|---|---|
| Simple Stroke | 0 | Acceleration, coasting, deceleration equally split; no sensation |
| Teasing Pounding | 1 | Speed shifts with sensation; balances faster strokes |
| Robo Stroke | 2 | Sensation varies acceleration; from robotic to gradual |
| Half’n’Half | 3 | Full and half depth strokes alternate; sensation affects speed |
| Deeper | 4 | Stroke depth increases per cycle; sensation sets count |
| Stop’n’Go | 5 | Pauses between strokes; sensation adjusts length |
| Insist | 6 | Modifies length, maintains speed; sensation influences direction |
Device information service
The OSSM implements the standard BLE Device Information Service for identification.| Characteristic | UUID | Value |
|---|---|---|
| Service | 180A | Device Information Service |
| Manufacturer Name | 2A29 | ”Research And Desire” |
| System ID | 2A23 | 88:1A:14:FF:FE:34:29:63 |
UUID namespace structure
The OSSM uses a structured UUID namespace for organized expansion.Service UUID
Namespace ranges
| Range | Hex Range | Description |
|---|---|---|
| 0x0 | 0x0000–0x0FFF | Reserved for system messages |
| 0x1 | 0x1000–0x1FFF | Commands and configuration |
| 0x2 | 0x2000–0x2FFF | State information |
| 0x3 | 0x3000–0x3FFF | Pattern information |
| 0x4 | 0x4000–0x4FFF | GPIO pin setting |
| 0x5–0xD | 0x5000–0xDFFF | Reserved for future use |
| 0xE | 0xE000–0xEFFF | Reserved for statistics |
| 0xF | 0xF000–0xFFFF | Experimental / sandbox (volatile) |
Current characteristic assignments
- Commands (0x1xxx)
- State (0x2xxx)
- Patterns (0x3xxx)
Connection management
Advertising
| Setting | Value |
|---|---|
| Device Name | OSSM |
| Service UUIDs | Primary service + Device Information Service |
| Advertising Interval | 20-40ms (optimized for reliability) |
| Auto-restart | Advertising resumes when all clients disconnect |
Security
| Setting | Value |
|---|---|
| Pairing | ”Just Works” (no authentication required) |
| Encryption | BLE Secure Connections enabled |
| Bonding | Disabled (no persistent pairing) |
The OSSM uses “Just Works” pairing for ease of use. Anyone within BLE range can connect when the device is advertising.
Client implementation guide
Connection flow
Follow these steps to establish a connection and begin controlling your OSSM:1
Scan for the device
Scan for BLE devices with the name “OSSM”.
Device appears in scan results.
2
Connect to the device
Initiate a GATT connection to the OSSM.
3
Discover services
Discover all services and characteristics on the device.
Primary service UUID
522b443a-4f53-534d-0001-420badbabe69 is found.4
Subscribe to state notifications
Enable notifications on the state characteristic to receive real-time updates.
5
Read initial state
Read the current state and pattern list to initialize your application.
6
Send commands
Begin sending commands to control the OSSM.
Best practices
Command handling
- Validate command format before sending
- Handle both
ok:andfail:responses - Implement retry logic for critical commands
- Monitor state changes to confirm command execution
State monitoring
- Subscribe to state characteristic notifications
- Parse JSON state updates reliably
- Handle state transitions appropriately
- Implement timeout handling for missing updates
Example code
Troubleshooting
Connection fails
Connection fails
Symptoms: Unable to discover or connect to the OSSM.Solutions:
- Ensure the OSSM is powered on and within range (~10 meters)
- Check that no other device is currently connected to the OSSM
- Restart the OSSM to reset the BLE stack
- Try moving closer to the device
Commands not working
Commands not working
Symptoms: Commands return
fail: or have no effect.Solutions:- Verify the command format matches the specification exactly
- Check that the OSSM is in a state that accepts commands (e.g.,
strokeEngineorsimplePenetration) - Use
go:strokeEngineorgo:simplePenetrationfirst if in menu state - Read the current state to understand which commands are valid
No state updates
No state updates
Symptoms: State characteristic never updates after subscribing.Solutions:
- Verify notification subscription was successful
- Check that your BLE library supports notifications
- Ensure you’re reading notifications from the correct characteristic UUID
- Try disconnecting and reconnecting
Invalid responses
Invalid responses
Symptoms: Receiving unexpected or malformed data.Solutions:
- Ensure you’re decoding responses as UTF-8 text
- Verify JSON parsing handles the state format correctly
- Check for encoding issues in your BLE library

