Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getmelody.io/llms.txt

Use this file to discover all available pages before exploring further.

The Melody Device is the interactive haptics hardware we engineered in‑house, paired with the Melody sensation‑scripting ecosystem.
Default Bluetooth (BLE) broadcast name is MEL-############, where ############ - are the 6-byte device BLE MAC address. All command and scripting integrations are handled through the single production API: Melody API: https://api.getmelody.io

​
Glossary

​
General Terms

TermMeaning
HDCHaptics Direct Control
HSCHaptics Script Control
HPSHaptics Points Stream
HLCHaptics Loop Control
OTAOver‑the‑air update
OTPOne‑time password
GATTGeneric Attribute Profile (BLE)

​
Device Components

ComponentDescription
StrokerLinear actuator providing haptic motion
Hall sensorMagnetic position sensor used for calibration
EncoderMotor feedback sensor for positional accuracy
PCBPrinted circuit board, contains temperature and thermal safety sensors

​
Position Terminology

ConceptDescription
Position (angle)Stroker position expressed in radians (0 to 2π)
Position (ranged)Normalized position (0–100% or 0–10000 points)
Calibration limitsPhysical min/max detected during hardware calibration
User limitsSoftware range bound within calibration limits
Position shiftUser defined offset relative to calibrated bounds

​
Velocity Terminology

ConceptDescription
Velocity (angle)Stroker angular velocity (radians/second)
Velocity (ranged)Normalized velocity (0–100% of max hardware speed)
Max velocityHardware maximum safe velocity
User max velocitySoftware enforced speed cap

​
Playback States

StateMeaning
IDLENo active playback
MANUALDevice controlled via physical buttons
WIFIControlled via WiFi API
BLEControlled via BLE API

​
Data Ranges

ParameterTypeRangeUnits
Position (ranged)uint16/uint320–10000points (0.01% resolution)
Position (angle)float0 → 2πradians
Velocity (ranged)uint8/uint320–100% of max
Velocity (angle)floatvariesrad/s
Battery leveluint80–100%
Battery voltagefloat10.0–15.0V
Temperaturefloatvaries°C
Timeuint16/uint32/uint64variesmilliseconds

​
Device Modes

​
Active Control Modes

Playback mode is selected using the physical mode button on the device.
ModeRequirementsBehavior
WiFi ModeRequires bearer device token from Melody serverDevice controlled through WiFi API
BLE ModeNearby BLE pairingDevice controlled directly through BLE commands
Offline ModeNo connectivityLocal pattern and script playback inside the app

​
Service / Maintenance Modes

Stroker motion is disabled during service modes for safety.
Service ModeDescription
CALIBRATIONDetects lowest and highest mechanical bounds, identifies hall sensor positions.
OTA UpdateFirmware update initiated from the device menu or WiFi API. Requires explicit user confirmation.
OTP RetrievalGenerates short‑lived one‑time secrets during onboarding or device binding. Initiated from device or API.

​
Playback Protocols

​
HDC (Haptics Direct Control)

Supported Transports: WiFi, BLE
Direct position control where you define a target position and movement duration. Best for:
  • Manual control
  • UI‑driven or interactive applications
  • Simple positional motion

​
HSC (Haptics Script Control)

Supported: WiFi only
Device downloads a motion script from a remote URL, while the server orchestrates start, stop, pause, and seek. Best for:
  • Pre‑recorded video or VR content
  • Scripted and synchronized playback

​
HPS (Haptics 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. Best for:
  • Real‑time streaming experiences
  • Dynamically generated motion content
  • External timeline drivers

​
HLC (Haptics Loop Control)

Supported Transports: WiFi, BLE
Automatic stroking loop inside a defined motion range at a set velocity. Best for:
  • Continuous rhythmic sensation loops
  • Automatic repeating motion patterns

​
API Coverage Summary

FeatureWiFi APIBLE API
Device information✓✓
Device status✓✓
Stroker status✓✓
Stroker settings✓✓
WiFi setup✓✓
OTP token✓✓
HDC control✓✓
HSC control✓✗
HPS control✓✓
HLC control✓✓
Debug information✓✗
Server connection✓✗
Calibration info✓✗

​
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 + uint64 time BLE: uint16 pos + uint32 time (6 bytes, packed)
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

ProtocolWiFiBLE
HDC Timeuint32 (≈ 65 years max)uint16 (≤ 65535 ms, ≈ 65 seconds)
HPS Stream Timeuint64 (unlimited timeline)uint32 (≤ 49 days continuous stream)

​
Ecosystem Philosophy

Melody was designed to be:
  • Universal – partner devices behave consistently via shared command schemas
  • Seekable – timeline‑driven playback state control
  • Smooth – motion interpolation derived automatically from point streams
  • Secure – protected by JWT bearer authentication as defined in OpenAPI
Hardware + Engine + SDK + Media Scripting = One ecosystem.
Developers implement once, creators script once — every supported device feels in sync.
Next: explore how to upload scripts, start sessions, and stream motion in the dedicated API reference tabs.