Device Setup

This page describes how the WiFi API exposes device information, live status, configuration settings, service commands, and debug data for the Melody hardware device. All examples here assume you are calling the WiFi-related endpoints on:

https://api.getmelody.io

with standard headers:

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

Device Information (Read)

Static information about the connected Melody device.

Field	Type	Description
`firmwareVersion`	`string`	CI/CD firmware name (e.g. `"v0.0.3-6-g4210228-dirty"`)
`deviceType`	`string`	Device model (e.g. `"melody"`)
`hardwareRevision`	`string`	Hardware revision identifier/number
`factoryActivationTime`	`uint32`	Unix timestamp of factory activation

These values are typically returned by a device info or status endpoint and rarely change during normal operation (except firmware version after OTA).

Device Status (Read)

Dynamic operational data from the Melody device.

Field	Type	Range	Description
`deviceTime`	`int64`	ms	Current device time in milliseconds (power-on time if no internet time source is available)
`batteryLevel`	`uint32`	0–100	Battery level (%)
`batteryVoltage`	`float`	10.0–15.0	Battery voltage (V)
`temperatureSensor1`	`float`	°C	PCB temperature near the charger section
`temperatureSensor2`	`float`	°C	PCB temperature near the motor section
`wifiConnected`	`bool`	—	Whether the device is connected to a WiFi access point
`wifiRssi`	`int32`	-100 to 10	WiFi RSSI signal strength (dB)
`bleConnected`	`bool`	—	Whether there is an active BLE client connection

Use these fields to show battery state, thermal status, and connectivity health in your UI.

Device Settings (Read/Write)

Configurable parameters that control connectivity and naming.

Field	Type	Description
`deviceName`	`string`	Human-readable device name (e.g. `"Melody Toy"`) shown in apps / BLE lists
`wifiEnabled`	`bool`	Enable or disable WiFi connectivity
`bleEnabled`	`bool`	Enable or disable BLE connectivity
`travelMode`	`bool`	If enabled, device powers on after 3 seconds button hold. If disabled, powers on after 500ms
`introLabel`	`string`	Custom string shown after “Hello!” label on the intro screen
`clientName`	`string`	Client name set by the client after connection (max 64 chars)

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	Type	Description
`START_CALIBRATION`	`bool`	Start stroker calibration. Warn users to detach the device and confirm before execution.
`START_OTA`	`bool`	Check for firmware updates. Requires user confirmation before applying an update.
`START_OTP`	`bool`	Request an OTP token used for API authentication / secure pairing flows.
`POWER_DOWN`	`bool`	Shut down the device safely.
`SET_CURRENT_SCREEN`	`uint8`	Navigate the device display to the specified screen. Pass `screen_id` in the request body.

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 Info (Read)

Information about firmware update availability and state.

Field	Type	Description
`latestFirmwareVersion`	`string`	Latest available firmware version on the update server
`firmwareStatus`	`string`	One of: `up-to-date`, `update-available`, `update-required`

You can use these fields to show firmware banners in your UI and decide when to surface “Update available” prompts.

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.

Field	Type	Description
`freeHeapSize`	`uint32`	Available heap memory in bytes
`externalFlashSize`	`uint32`	External flash storage size in bytes
`deviceTokenRetrieveTime`	`uint32`	Unix timestamp when the device token was received
`debugLoggingEnabled`	`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. The server captures and stores these messages, which you can then view in the CMS. See the full guide: Debug Logging

Recommended Usage Patterns

Show user-facing status from: batteryLevel, batteryVoltage, temperatureSensor*, wifiConnected, bleConnected.
Offer configuration UI for: deviceName, wifiEnabled, bleEnabled.
Gate service commands behind confirmation dialogs for: startCalibration, startOta, powerDown.
Use setCurrentScreen to programmatically drive the device UI (e.g. open Settings or WiFi screen from your app).
Surface firmware prompts based on: firmwareStatus and latestFirmwareVersion.
Use debug information only in internal tools, logs, or support dashboards.
Enable debug logging only during development or support — it is not persisted and does not survive reconnects.

For exact endpoint URLs, request/response schemas, and error codes, see the WiFi API section in 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 Info (Read)

Debug Information (Read)

Debug Logging (Write)

Recommended Usage Patterns

​Device Information (Read)

​Device Status (Read)

​Device Settings (Read/Write)

​Service Commands (Write)

​Current Screen (Read)

​Firmware Update Info (Read)

​Debug Information (Read)

​Debug Logging (Write)

​Recommended Usage Patterns

Device Information (Read)

Device Status (Read)

Device Settings (Read/Write)

Service Commands (Write)

Current Screen (Read)

Firmware Update Info (Read)

Debug Information (Read)

Debug Logging (Write)

Recommended Usage Patterns