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 afterinactivity_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/sessionand/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
/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.
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 viaPOST /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.IDs1(Intro),4(Playback),16(Battery Warning), and17(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 fromfirmware_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_CALIBRATIONandSTART_OTAbehind a confirmation dialog — both move the stroker or restart the device. - Changing
wifi_enabledorble_enabledcan drop the very connection carrying the request. - A device left idle for
inactivity_timeoutseconds 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.