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

All characteristics must be interpreted using little-endian byte ordering.

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

Binary format for 0x0001 (little-endian):

Bytes 0–1: Position (uint16, 0–10000)
Bytes 2–3: Time (uint16, ms, 0–65535)

Binary format for 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)

Binary format for 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)

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)
`0x0002`	`string`	R/W	Client name set by client after connection (max 64 chars)

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.

Getting started

Melody

Melody Streaming

Melody WiFi

Melody BLE

Services Reference

BLE Services Reference

Service `0x1001` — WiFi Setup

Service `0x1002` — Device Information

Service `0x1003` — Device Status

Service `0x1004` — Stroker Status

Service `0x1005` — Stroker Settings

Service `0x1006` — OTP

Service `0x2001` — HDC (Haptics Direct Control)

Service `0x2002` — HPS (Haptics Point Stream)

Service `0x2003` — HLC (Haptics Loop Control)

Service `0x1007` — Firmware Update

Service `0x1008` — Device Settings

Service `0x1009` — Debug Logs

Service `0x100A` — Service Commands

Notes & Best Practices

​BLE Services Reference

​Service 0x1001 — WiFi Setup

​Service 0x1002 — Device Information

​Service 0x1003 — Device Status

​Service 0x1004 — Stroker Status

​Service 0x1005 — Stroker Settings

​Service 0x1006 — OTP

​Service 0x2001 — HDC (Haptics Direct Control)

​Service 0x2002 — HPS (Haptics Point Stream)

​Service 0x2003 — HLC (Haptics Loop Control)

​Service 0x1007 — Firmware Update

​Service 0x1008 — Device Settings

​Service 0x1009 — Debug Logs

​Service 0x100A — Service Commands

​Notes & Best Practices

BLE Services Reference

Service `0x1001` — WiFi Setup

Service `0x1002` — Device Information

Service `0x1003` — Device Status

Service `0x1004` — Stroker Status

Service `0x1005` — Stroker Settings

Service `0x1006` — OTP

Service `0x2001` — HDC (Haptics Direct Control)

Service `0x2002` — HPS (Haptics Point Stream)

Service `0x2003` — HLC (Haptics Loop Control)

Service `0x1007` — Firmware Update

Service `0x1008` — Device Settings

Service `0x1009` — Debug Logs

Service `0x100A` — Service Commands

Notes & Best Practices