Skip to main content
All examples call the production API:
with standard headers:
On the status endpoints, a field at its zero value is missing from the response. battery_level: 0 and ble_connected: false do not appear in the JSON at all. Read an absent field as its zero value, not as “unknown”, and do not mark these fields required in a generated client.Affected: GET /device/status, GET /device/stroker/status, GET /device/stroker/calibration, GET /device/hsc/status, GET /device/debug/info, GET /device/debug/logging.The settings endpoints behave differently: there an absent field means the device did not report it, and an explicit false is a real value. The exceptions are inactivity_timeout, which the device leaves out when it is 0 — see Inactivity timeout — and the playback labels, left out when empty. Every field is present on GET /device/info, GET /device/screen, GET /device/hdc/status, GET /device/hps/status, GET /device/hlc/status.

Device Information (Read)

Static information about the connected Melody device. These change only after a firmware update.

Device Status (Read)

Dynamic operational data from the Melody device.

Device Settings (Read/Write)

Configurable parameters that control connectivity, naming, power and the playback screen. GET /device/settings returns the whole set. POST /device/settings is a partial update: send only the fields you are changing and the rest keep their current value. false and "" are values, not omissions — {"wifi_enabled": false} turns WiFi off, while a body without wifi_enabled leaves it alone. null means the same as leaving the field out — to clear a string, send "". A field the request does not recognise is rejected with 400, so a misspelled name never passes as “leave this one alone”. When updating settings, make sure your UI clearly reflects any changes that could disconnect the current control channel (for example, disabling WiFi while using WiFi).

Inactivity timeout

The device switches itself off after inactivity_timeout seconds with nothing happening. Any of these restarts the countdown:
  • a button press
  • the motor running (playback, calibration) or a firmware update in progress
  • any command the device receives over WiFi, which covers every /device/* request except /device/session and /device/server-time (the server answers those itself); the server’s clock-sync and latency frames do not count
  • a BLE client reading or writing a characteristic; an idle connection or notifications alone do not count
Because these requests count, polling /device/status keeps the device on. Poll only while someone is using it. The value is stored on the device, survives a restart and takes effect right away. POST /device/settings rejects anything other than 0 or 60–86400 with 400. Firmware older than v0.6.9 ignores the field, yet the POST response still repeats it back, so a 200 does not prove the device took it. Read it back with GET /device/settings: when inactivity_timeout is missing there, the device either has it set to 0 (never) or runs older firmware.

Playback screen labels

While a script plays, the device shows the Script Playback screen. Two settings set its text:
  • playback_mode_label — the screen title. Empty shows the default “Script Playback”.
  • playback_source_label — the line under the title, for example the name of the video. Empty shows nothing.
Each label takes up to 20 characters of printable ASCII (codes 32–126), the only ones the screen font has. POST /device/settings rejects a longer label, or one with any other character, with 400; transliterate or drop such characters before sending. About 20 mixed-case characters fit on the screen; wide text, such as 20 capital letters, does not. The device keeps the labels in memory and loses them on restart, so set them again when playback starts. BLE reads and writes the same values (service 0x1008, characteristics 0x0004 and 0x0005): a label set over one API is returned by the other. Firmware without playback labels ignores both fields, yet the POST response still repeats them back, so a 200 does not prove the device took them. Read them back with GET /device/settings: a label missing there is either empty or not supported by the device.

Service Commands (Write)

Service commands trigger specific system-level actions on the device. Send them via POST /device/maintenance/command with a JSON body containing command and, where applicable, additional parameters.
Important: Calibration and OTA may move the stroker or restart the device. Always require explicit user confirmation before triggering these commands.
Two actions that are sometimes expected here are handled elsewhere: request an OTP with POST /device/otp/generate (see OTP via WebSocket for the WebSocket alternative), and power the device down through the BLE Device Status characteristic 0x1003 → 0x0007. Example — navigate to WiFi screen:

Current Screen (Read)

Read the screen currently shown on the device display.
Response:
Available screen IDs:
IDs 1 (Intro), 4 (Playback), 16 (Battery Warning), and 17 (Overheat Warning) are intentionally omitted — these screens are shown automatically by the device and cannot be navigated to directly.

Firmware Update State

Firmware update state is read from firmware_status in the Device Information response (one of up-to-date, update-available, update-required). Use it to show an update banner in your UI.

Debug Information (Read)

Debug data is exposed for diagnostics and should not normally be shown to end users.
It is especially useful during development, QA, or support tooling.
Returned by GET /device/debug/info:

Debug Logging (Write)

You can instruct a connected device to start emitting real-time log messages over WebSocket. Melody captures and stores them for you — see Debug Logging.

Usage Notes

  • Put START_CALIBRATION and START_OTA behind a confirmation dialog — both move the stroker or restart the device.
  • Changing wifi_enabled or ble_enabled can drop the very connection carrying the request.
  • A device left idle for inactivity_timeout seconds powers off and drops its connection.
  • Debug logging lives in memory and is lost when the device restarts, so turn it on only while you need it.
For endpoint URLs, request and response schemas, and error codes, see the Melody API Reference.