Skip to main content
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.

Service 0x1002 — Device Information

Static device metadata and identifiers.

Service 0x1003 — Device Status

Live operational status and power / temperature information.
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.
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.

Service 0x2001 — HDC (Haptic Direct Control)

Immediate position control. New commands interrupt current movement (not queued). 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
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.

Service 0x1007 — Firmware Update

Firmware update availability and control.

Service 0x1008 — Device Settings

Device configuration settings. The client name is shown on the device’s info screen. Writes longer than the 32-byte buffer, including the terminator, are rejected. The inactivity timeout takes exactly 4 bytes; any other length is rejected with ATT error 0x0D (Invalid Attribute Value Length). A value outside the range is rejected with 0x13 (Value Not Allowed) and the device keeps the previous one. Reading or writing any characteristic counts as activity; an idle connection or notifications alone do not. See Inactivity timeout for what else keeps the device on. The playback labels are UTF-8 with no terminator. Write an empty value to clear one. A write longer than 20 bytes is rejected with ATT error 0x0D (Invalid Attribute Value Length) and the label does not change. The labels hold the same values as the WiFi settings and are lost on restart — see Playback screen labels. Write printable ASCII only (codes 32–126). The device accepts other bytes over BLE but the screen font has no glyphs for them, and a label that is not valid UTF-8 — for example, text cut to 20 bytes in the middle of a multi-byte character — makes the WiFi API fail to read the device settings until the label is rewritten or the device restarts.

Service 0x1009 — Debug Logs

Debug logging control and data streaming.

Service 0x100A — Service Commands

System-level service commands.

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.