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 | uint64 | R | Device time (ms) |
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 |
đ 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 normalized percentage form.
| Char | Type | R/W | Description |
|---|---|---|---|
0x0001 | uint32 | R/W | Low position shift (0â100%, default 0) |
0x0002 | uint32 | R/W | High position shift (0â100%, default 0) |
đ 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 |
- Bytes 0â1: Position (
uint16, 0â10000) - Bytes 2â3: Time (
uint16, ms, 0â65535)
đ 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 | uint32 | R/W | Velocity (0â100% of max speed) |
0x0002 | uint32 | R/W | Low limit (0â99%, must be < high limit) |
0x0003 | uint32 | R/W | High limit (1â100%, must be > low limit) |
0x0004 | bool | W | Play (write 1 to start loop) |
0x0005 | bool | W | Pause (write 1 to stop loop) |
đ 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.