Documentation Index
Fetch the complete documentation index at: https://docs.getmelody.io/llms.txt
Use this file to discover all available pages before exploring further.
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:
with standard headers:
Authorization: Bearer <YOUR_JWT_TOKEN>
Content-Type: application/json
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 |
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 |
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 |
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. |
POST /device/maintenance/command
{
"command": "SET_CURRENT_SCREEN",
"screen_id": 6
}
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.
| 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 |
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.
