Device Setup

All examples call the production API:

https://api.getmelody.io

with standard headers:

Authorization: Bearer <SESSION_TOKEN>
X-Device-Key: <DEVICE_KEY>
Content-Type: application/json

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. 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.

Field	Type	Description
`firmware_version`	`string`	Firmware build name (e.g. `"v1.0.0"`)
`type`	`string`	Device model (e.g. `"melody"`)
`hardware_revision`	`string`	Hardware revision identifier/number
`factory_activation_time`	`uint32`	Unix timestamp of factory activation (seconds)
`serial_number`	`string`	Device serial number, written once at the factory during registration
`firmware_status`	`string`	One of `up-to-date`, `update-available`, `update-required`

These change only after a firmware update.

Device Status (Read)

Dynamic operational data from the Melody device.

Field	Type	Range	Description
`device_time`	`uint64`	ms	Current device time in milliseconds (power-on time if no internet time source is available)
`battery_level`	`uint32`	0–100	Battery level (%)
`battery_voltage`	`float`	10.0–15.0	Battery voltage (V)
`temperature_sensor_1`	`float`	°C	PCB temperature near the charger section
`temperature_sensor_2`	`float`	°C	PCB temperature near the motor section
`wifi_connected`	`bool`	—	Whether the device is connected to a WiFi access point
`wifi_rssi`	`int32`	-100 to 10	WiFi RSSI signal strength (dB)
`ble_connected`	`bool`	—	Whether there is an active BLE client connection
`charging_status`	`uint32`	0–2	`0` = not charging, `1` = charging, `2` = charged

Device Settings (Read/Write)

Configurable parameters that control connectivity and naming.

Field	Type	Description
`device_name`	`string`	Human-readable device name (e.g. `"Melody Toy"`) shown in apps / BLE lists
`wifi_enabled`	`bool`	Enable or disable WiFi connectivity
`ble_enabled`	`bool`	Enable or disable BLE connectivity
`travel_mode`	`bool`	If enabled, device powers on after 3 seconds button hold. If disabled, powers on after 500ms
`intro_label`	`string`	Custom string shown after “Hello!” label on the intro screen
`client_name`	`string`	Client name set by the client after connection

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).

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.

Command	Value	Description
`START_CALIBRATION`	`1`	Start stroker calibration. Warn users to detach the device and confirm before execution.
`START_OTA`	`2`	Check for firmware updates. Requires user confirmation before applying an update.
`SET_CURRENT_SCREEN`	`3`	Navigate the device display to the specified screen. Pass `screen_id` in the request body.

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:

POST /device/maintenance/command
{
  "command": "SET_CURRENT_SCREEN",
  "screen_id": 6
}

Current Screen (Read)

Read the screen currently shown on the device display.

GET /device/screen

Response:

{ "screen_id": 6 }

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.

ID	Name
`2`	Main
`3`	Manual
`5`	Settings
`6`	WiFi
`7`	BLE
`8`	Range Adjustment
`9`	Speed Adjustment
`10`	Brightness
`11`	Info
`12`	Calibration
`13`	Firmware Update
`14`	OTP
`15`	Reset Settings

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:

Field	Type	Description
`free_heap_size`	`uint32`	Available heap memory in bytes
`external_flash_size`	`uint32`	External flash storage size in bytes
`debug_logging_enabled`	`bool`	Whether the device is currently emitting debug log frames

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.
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.

Getting started

Melody

Melody Streaming

Melody WiFi

Melody BLE

Device Information (Read)

Device Status (Read)

Device Settings (Read/Write)

Service Commands (Write)

Current Screen (Read)

Firmware Update State

Debug Information (Read)

Debug Logging (Write)

Usage Notes

​Device Information (Read)

​Device Status (Read)

​Device Settings (Read/Write)

​Service Commands (Write)

​Current Screen (Read)

​Firmware Update State

​Debug Information (Read)

​Debug Logging (Write)

​Usage Notes

Device Information (Read)

Device Status (Read)

Device Settings (Read/Write)

Service Commands (Write)

Current Screen (Read)

Firmware Update State

Debug Information (Read)

Debug Logging (Write)

Usage Notes