Debug Logging

Turn on verbose logging from a connected Melody device, capture it on the server, and read it back — no serial cable, no physical access.

How It Works

POST /device/debug/logging  { "enabled": true }
        │
        ▼
Device starts emitting FrameType_DEBUG_LOG frames (type 21)
        │  DebugLogMessage { message: string }
        ▼
Melody stores them per device, newest first, up to 1000 entries

It costs the device bandwidth and battery, so leave it on only while you are chasing a problem.

Enabling / Disabling Logging

The device must be connected:

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

{
  "enabled": true
}

Response (200 OK) — current DebugInformation from the device:

{
  "free_heap_size": 180000,
  "external_flash_size": 4194304,
  "debug_logging_enabled": true
}

404 — device is not currently connected to the server.

This setting is not persisted on the device: it lives in memory, survives a dropped WebSocket, and is lost when the device restarts. After a restart, turn it on again.

Receiving Log Frames (Device → Server)

While logging is enabled, the device sends unsolicited WebSocket frames:

Field	Value
Frame type	`DEBUG_LOG = 21`
Protobuf message	`DebugLogMessage`
Field	`message` (string)

Melody collects these frames for you — there is nothing to handle on the client side. Each message is stored with a timestamp.

Reading the stored logs

Logs are kept on the Melody side, not on the device. To get the captured output, turn logging on, reproduce the problem, then ask support for the logs of that device and the time window you care about.

Constraints & Notes

The toggle only works while the device is currently connected.
Log entries are stored server-side only; the device does not buffer them locally.
Retention is 1000 entries per device, trimmed automatically on insert.

Getting started

Melody

Melody Streaming

Melody WiFi

Melody BLE

How It Works

Enabling / Disabling Logging

Receiving Log Frames (Device → Server)

Reading the stored logs

Constraints & Notes

​How It Works

​Enabling / Disabling Logging

​Receiving Log Frames (Device → Server)

​Reading the stored logs

​Constraints & Notes

How It Works

Enabling / Disabling Logging

Receiving Log Frames (Device → Server)

Reading the stored logs

Constraints & Notes