Skip to main content
Melody is a haptic device, together with the API and scripting layer that drives it. The device plays motion that is either streamed to it in real time or loaded as a script and driven along a timeline. Position, velocity and timing mean the same thing on both paths — over the WiFi API through the Melody server, and over BLE directly from an app next to the device. The wire formats differ: REST and Protobuf on one side, GATT characteristics on the other.

​
How it works

The device connects to the Melody server over WiFi. Your application talks to the same server with a short-lived session token and a device key, and the server relays commands to the device. An app sitting next to the device can also drive it locally over BLE, without the server. Motion comes in four shapes: a single move to a position (HDC), a stream of points the device interpolates between (HPS), a script the server plays along a timeline (HSC), and a loop the firmware runs on its own (HLC).

​
The pieces

​
Hardware

Melody Device — a haptic device with a linear actuator (the stroker), position and temperature sensing, and both BLE and WiFi connectivity. It runs motion scripts and streamed motion, and it enforces its own calibration and safety limits.

​
APIs

  • Melody API — the cloud REST API at api.getmelody.io. Your application authenticates here and controls linked devices.
  • WiFi API — the device’s local protobuf API, used to set up the device, read its state, and bring it online.
  • BLE API — the device’s GATT services, used for discovery, pairing, WiFi provisioning, and direct motion control.

​
Supported Device Connectivity

Both transports share the same motion semantics. Where they differ is payload encoding and the numeric limits that follow from it — BLE packs commands into compact binary to fit its MTU, while the WiFi API uses wider types. The device overview lists the differences protocol by protocol.

​
API Domains

The device endpoints are grouped by what they control:
  • Device Information — identity, capabilities, status, active session, settings, and communication mode
  • Haptic Direct Control (HDC) — move to a target position over a set time
  • Haptic Points Stream (HPS) — stream timestamped motion points with on-device smoothing
  • Haptic Script Control (HSC) — upload a script and drive it with start, seek, pause, and stop
  • Haptic Loop Control (HLC) — loop between two positions at a set velocity
  • Stroker — live position and velocity, calibration bounds, and user position limits
  • OTP — short-lived secrets for linking a device to an organization
  • Maintenance & Debug — service commands such as calibration and OTA, diagnostics, and debug logging
For endpoint definitions, payload schemas, and parameter descriptions, see the Melody API Reference.