Services Reference

The Melody Device exposes several BLE services for configuration and low-latency control.

Device name (BLE): MEL-XXXXXXXXXXXX, where XXXXXXXXXXXX is the device’s 6-byte BLE MAC address in hexadecimal
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`	R/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/W (one-time write)	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	Device time (UTC epoch seconds)
`0x0002`	`uint8`	R, notify	Battery level (0–100%)
`0x0003`	`float`	R, notify	Battery voltage (10.0–15.0 V)
`0x0004`	`int8`	R, notify	WiFi RSSI (dB, -100 to 10)
`0x0005`	`float`	R, notify	Temperature sensor 1 (°C, near charger)
`0x0006`	`float`	R, notify	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, notify	Charging status (0 = not charging, 1 = charging, 2 = charged)
`0x000A`	`bool`	R/W, notify	Playback active. Writing one byte controls playback: `1` resumes (starts the motor and switches the screen to playback), `0` pauses

Live stroker position and velocity are not available over BLE. Read them over WiFi with GET /device/stroker/status — see Stroker Setup.

Service `0x1005` — Stroker Settings

Software motion limits, as a shift inward from each calibrated bound.

Char	Type	R/W	Size	Description
`0x0001`	`uint8`	R/W	1 byte	Low position shift
`0x0002`	`uint8`	R/W	1 byte	High position shift

Over BLE these are single-byte values. The firmware rejects any write that is not exactly 1 byte long, so sending a 4-byte float here silently fails. The equivalent WiFi API fields (StrokerSettings.low_position_shift / high_position_shift) are floats in millimeters.

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 (Haptic 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

Binary format for 0x0001 (little-endian):

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

The HDC service exposes 0x0001 only.

Service `0x2002` — HPS (Haptic Points 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)
`0x0007`	`bool`	R/W	1 byte	Stop the stream

Binary format for 0x0001 (per point, little-endian):

Bytes 0–1: Position (uint16, 0–10000)
Bytes 2–5: Time (uint32, ms)

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

Automatic up/down stroking loop with configurable range and speed.

Char	Type	R/W	Description
`0x0001`	`bool`	R/W	Play/pause (write `1` to start the loop)
`0x0002`	`float`	R/W	Velocity
`0x0003`	`float`	R/W	Low limit (must be `<` high limit)
`0x0004`	`float`	R/W	High limit (must be `>` low limit)

Service `0x1007` — Firmware Update

Firmware update availability and control.

Char	Type	R/W	Description
`0x0001`	`bool`	R	Firmware update available
`0x0002`	`bool`	R/W	Start firmware update (write `1` to begin)
`0x0003`	`uint8`	R, notify	Update progress (%)

Service `0x1008` — Device Settings

Device configuration settings.

Char	Type	R/W	Description
`0x0001`	`bool`	R/W	Travel mode (if enabled, device powers on after a 3s button hold, otherwise 500ms)
`0x0002`	`string`	R/W	Client name, set by the client after connecting (max 31 characters)

The client name is shown on the device’s info screen. Writes longer than the 32-byte buffer, including the terminator, are rejected.

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`	W	Current screen identifier — write to navigate the display
`0x0002`	`bool`	W	Start stroker calibration (write `1`)

Notes

Use the WiFi API for scripts, sessions and debug data; use BLE for low-latency local control.
Pick the protocol by the job: HPS for smooth real-time motion, HDC for a single interruptible move, HLC for a loop the firmware drives on its own.
Provision WiFi and read the OTP over BLE during first-time pairing.

Getting started

Melody

Melody Streaming

Melody WiFi

Melody BLE

Services Reference

Service `0x1001` — WiFi Setup

Service `0x1002` — Device Information

Service `0x1003` — Device Status

Service `0x1005` — Stroker Settings

Service `0x1006` — OTP

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

Service `0x2002` — HPS (Haptic Points Stream)

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

Service `0x1007` — Firmware Update

Service `0x1008` — Device Settings

Service `0x1009` — Debug Logs

Service `0x100A` — Service Commands

Notes

​Service 0x1001 — WiFi Setup

​Service 0x1002 — Device Information

​Service 0x1003 — Device Status

​Service 0x1005 — Stroker Settings

​Service 0x1006 — OTP

​Service 0x2001 — HDC (Haptic Direct Control)

​Service 0x2002 — HPS (Haptic Points Stream)

​Service 0x2003 — HLC (Haptic Loop Control)

​Service 0x1007 — Firmware Update

​Service 0x1008 — Device Settings

​Service 0x1009 — Debug Logs

​Service 0x100A — Service Commands

​Notes

Service `0x1001` — WiFi Setup

Service `0x1002` — Device Information

Service `0x1003` — Device Status

Service `0x1005` — Stroker Settings

Service `0x1006` — OTP

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

Service `0x2002` — HPS (Haptic Points Stream)

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

Service `0x1007` — Firmware Update

Service `0x1008` — Device Settings

Service `0x1009` — Debug Logs

Service `0x100A` — Service Commands

Notes