Skip to main content
The Debug Logging feature lets you turn on verbose log output from a connected Melody device, capture those logs on the server, and inspect them in the CMS — without needing a serial cable or physical access to the device.

​
How It Works

CMS toggle / API call
        │
        ▼
POST /api/cms/devices/{id}/debug-logging   (Manager)
        │  resolves active subscription, proxies to broadcast
        ▼
POST /device/debug/logging   (Broadcast → Device over WebSocket)
        │  DeviceRemoteControl SET DebugInformation { debug_logging_enabled }
        ▼
        Device confirms (same proto message echoed back)

        ── when logging is on ──►

Device emits FrameType_DEBUG_LOG frames (type 21)
        │  DebugLogMessage { message: string }
        ▼
Broadcast forwards to Manager
        │  POST /api/internal/device/debug-log
        ▼
Stored in DB per device (newest-first, max 1000 entries)

​
Enabling / Disabling Logging

Use the SDK endpoint (requires an active device connection): 
POST /device/debug/logging
Authorization: Bearer <YOUR_DEVICE_TOKEN>
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. After a reconnect the device reverts to its firmware default (logging off). You must re-enable after each reconnect if needed.

​
Receiving Log Frames (Device → Server)

While logging is enabled, the device sends unsolicited WebSocket frames:
FieldValue
Frame typeDEBUG_LOG = 21
Protobuf messageDebugLogMessage
Fieldmessage (string)
The server intercepts these frames automatically — no client-side handling is required. Each message is stored in the database with a timestamp.

​
Viewing Logs in the CMS

  1. Open CMS → Devices and click any device.
  2. Switch to the Debug Logs tab.
  3. Use the Enable debug logging toggle to activate/deactivate logging on the connected device.
  4. Logs appear in the table (newest first), auto-refreshing every 10 seconds while the tab is open.
  5. Use Clear all logs to delete all stored log entries for this device.
The CMS stores up to 1000 log entries per device. Older entries are automatically trimmed when the limit is reached.

​
CMS REST API

If you need programmatic access to stored logs:
MethodEndpointDescription
GET/api/cms/devices/{id}/debug-logsList logs. Supports limit and offset query params (default limit: 50, max: 500).
DELETE/api/cms/devices/{id}/debug-logsDelete all stored logs for the device.
GET response shape: 
{
  "logs": [
    {
      "id": 42,
      "device_id": 7,
      "log_message": "motor init ok",
      "created_at": "2026-04-08T10:00:00Z"
    }
  ],
  "total_count": 1,
  "limit": 50,
  "offset": 0
}

​
Constraints & Notes

  • Logging toggle only works when the device is currently connected (has an active subscription on the broadcast server).
  • The state is not saved — toggling off and on is fire-and-forget per connection.
  • Log entries are stored server-side only; the device does not buffer them locally.
  • Retention is 1000 entries per device, trimmed automatically on insert.