Skip to main content
The Melody Device is the haptic hardware, together with the scripting and playback layer that drives it. The device advertises over Bluetooth as MEL-XXXXXXXXXXXX, where XXXXXXXXXXXX is the device’s 6-byte BLE MAC address in hexadecimal. Commands from your application go through the production API: Melody API: https://api.getmelody.io

​
Glossary

​
General Terms

The stroker is the linear actuator that moves; every position field on this site refers to it.

​
Position Terminology

​
Velocity Terminology

​
Playback States

​
Data Ranges

​
Device Modes

​
Active Control Modes

Playback mode is selected using the physical mode button on the device.

​
Service / Maintenance Modes

Stroker motion is disabled during service modes for safety.

​
Playback Protocols

​
HDC (Haptic Direct Control)

Supported Transports: WiFi, BLE
Direct position control where you define a target position and movement duration.

​
HSC (Haptic Script Control)

Supported: WiFi only
You upload a funscript to POST /device/hsc/upload; the server parses it and pushes the points to the device, then orchestrates start, stop, pause, and seek.

​
HPS (Haptic Points Stream)

Supported Transports: WiFi, BLE
Stream timestamped motion points; the device calculates velocity using time deltas between sequential points. Requirements: Min 2 points to compute motion velocity.

​
HLC (Haptic Loop Control)

Supported Transports: WiFi, BLE
Automatic stroking loop inside a defined motion range at a set velocity.

​
API Coverage Summary

Over BLE, “server connection” is exposed as a status characteristic you can read, but the connection itself is configured over the WiFi API.

​
WiFi vs BLE Protocol Differences

​
Command Size & Encoding

  • WiFi API uses 32/64-bit values (flexible numeric types, larger payloads)
  • BLE API uses packed binary (optimized for MTU limits of ~512 bytes)
Examples:
  • HDC Command WiFi: 2×uint32 (8 bytes) BLE: 2×uint16 (4 bytes, packed binary)
  • HPS Point Stream WiFi: uint32 pos + uint32 time BLE: uint16 pos + uint32 time (6 bytes, packed)
Over BLE, points are written in batches of up to 64 points (384 bytes) per write. Why: BLE has strict MTU limits and requires compact data types.

​
Position Range

  • Both transports use 0–10000 ranged position values
  • Resolution: 0.01% of full motion range
  • BLE uses uint16 (max 65535, enough for range)
  • WiFi uses 32-bit values for protocol flexibility

​
Time Limits by Protocol

Next: see the API Reference for uploading scripts, starting sessions, and streaming motion.