BLE Services Reference
The Melody device exposes several BLE services for configuration and low-latency control.- Device name (BLE):
MEL-############, where############- 6-byte BLE MAC address. - UUID width: 16-bit
- Byte order: Little-endian
Service 0x1001 — WiFi Setup
Configure WiFi credentials and read available access point list.
| Char | Type | R/W | Description |
|---|---|---|---|
0x0001 | string | W | SSID (write "" to clear) |
0x0002 | string | W | Password (write "" to clear) |
0x0003 | bool | R/W | Update AP list (write 1, wait until it returns 0) |
0x0004 | string[128] | R | AP list, newline (\n) separated, \0 terminated |
Service 0x1002 — Device Information
Static device metadata and identifiers.
| Char | Type | R/W | Description |
|---|---|---|---|
0x0001 | string | R | Device name (e.g., "Melody") |
0x0002 | string | R | Device type (e.g., "melody") |
0x0003 | string | R | Firmware version (CI/CD name) |
0x0004 | string | R | Hardware revision |
0x0005 | uint32 | R | Factory activation time (Unix timestamp) |
0x0006 | string | R/W | Factory serial number (one-time write) |
0x0007 | string | R | BLE MAC address |
Service 0x1003 — Device Status
Live operational status and power / temperature information.
| Char | Type | R/W | Description |
|---|---|---|---|
0x0001 | uint32 | R/W | Device time (UTC epoch seconds) |
0x0002 | uint8 | R | Battery level (0–100%) |
0x0003 | float | R | Battery voltage (10.0–15.0 V) |
0x0004 | int32 | R | WiFi RSSI (dB, -100 to 10) |
0x0005 | float | R | Temperature sensor 1 (°C, near charger) |
0x0006 | float | R | Temperature sensor 2 (°C, near motor) |
0x0007 | bool | W | Power down (write 1 to shut down the device) |
0x0008 | bool | R | Connected to WiFi and server |
0x0009 | uint8 | R | Charging status (0 = not charging, 1 = charging, 2 = charged) |
Service 0x1004 — Stroker Status
Current motion and target state of the stroker actuator.
| Char | Type | R/W | Description |
|---|---|---|---|
0x0001 | float | R | Current position (rad) |
0x0002 | int32 | R | Current position (points, 0–10000) |
0x0003 | float | R | Target position (rad) |
0x0004 | int32 | R | Target position (points, 0–10000) |
0x0005 | float | R | Current velocity (rad/s) |
0x0006 | int32 | R | Current velocity (points/s) |
Service 0x1005 — Stroker Settings
Software motion limits in millimeters.
| Char | Type | R/W | Description |
|---|---|---|---|
0x0001 | float | R/W | Low position shift (mm) |
0x0002 | float | R/W | High position shift (mm) |
Service 0x1006 — OTP
Generate and read short-lived OTP codes for secure pairing / token flows.
| Char | Type | R/W | Description |
|---|---|---|---|
0x0001 | bool | R/W | Update OTP (write 1, wait for 0 when ready) |
0x0002 | string[6] | R | OTP token (6 characters) |
Service 0x2001 — HDC (Haptics Direct Control)
Immediate position control. New commands interrupt current movement (not queued).
| Char | Type | R/W | Size | Description |
|---|---|---|---|---|
0x0001 | uint16[2] | W | 4 bytes | Position + time command |
0x0002 | uint16[2] | W | 4 bytes | Position + velocity command |
0x0001 (little-endian):
- Bytes 0–1: Position (
uint16, 0–10000) - Bytes 2–3: Time (
uint16, ms, 0–65535)
0x0002 (little-endian):
- Bytes 0–1: Position (
uint16, 0–10000) - Bytes 2–3: Velocity (
uint16)
Service 0x2002 — HPS (Haptics Point Stream)
Stream position/time points. Velocity is calculated from time delta between points.Minimum 2 points required for valid motion. Limits:
- Max 64 points/message
- Max 128 points total buffer
| Char | Type | R/W | Size | Description |
|---|---|---|---|---|
0x0001 | [uint16, uint32] array | W | 6 bytes/point | Add points (position + time) |
0x0002 | bool | R/W | 1 byte | Play/pause |
0x0003 | bool | W | 1 byte | Flush buffer |
0x0004 | bool | R/W | 1 byte | Loop enable |
0x0005 | float | R/W | 4 bytes | Playback rate |
0x0006 | uint32 | W | 4 bytes | Sync timestamp (ms) |
0x0001 (per point, little-endian):
- Bytes 0–1: Position (
uint16, 0–10000) - Bytes 2–5: Time (
uint32, ms)
Service 0x2003 — HLC (Haptics Loop Control)
Automatic up/down stroking loop with configurable range and speed.
| Char | Type | R/W | Description |
|---|---|---|---|
0x0001 | float | R/W | Velocity |
0x0002 | float | R/W | Low limit (must be < high limit) |
0x0003 | float | R/W | High limit (must be > low limit) |
0x0004 | bool | W | Play (write 1 to start loop) |
0x0005 | bool | W | Pause (write 1 to stop loop) |
Service 0x1007 — Firmware Update
Firmware update availability and control.
| Char | Type | R/W | Description |
|---|---|---|---|
0x0001 | bool | R | Firmware update available |
0x0002 | bool | W | Start firmware update (write 1 to begin) |
Service 0x1008 — Device Settings
Device configuration settings.
| Char | Type | R/W | Description |
|---|---|---|---|
0x0001 | bool | R/W | Travel mode (if enabled, device powers on after 3s button hold) |
Service 0x1009 — Debug Logs
Debug logging control and data streaming.
| Char | Type | R/W | Description |
|---|---|---|---|
0x0001 | bool | R/W | Enable debug log streaming |
0x0002 | string | R | Debug log data (notify) |
Service 0x100A — Service Commands
System-level service commands.
| Char | Type | R/W | Description |
|---|---|---|---|
0x0001 | uint8 | R/W | Current screen identifier |
Notes & Best Practices
- Always respect little-endian ordering for all numeric values.
- Use WiFi API for higher-level orchestration (scripts, sessions, debug) and BLE for low-latency or local control.
- For robust apps:
- Use HPS for smooth real-time motion.
- Reserve HDC for simple, interruptible target moves.
- Configure HLC as a simple, automatic loop mode driven by firmware.
- OTP and WiFi setup over BLE are ideal for first-time device provisioning and pairing flows.