feat: Built-in Device Diagnostics & Support Bundle Export

[scheilch]

Feature: Built-in Device Diagnostics & Support Bundle

Problem

When users report issues (presets not playing, setup failures, connectivity problems), we currently need multiple back-and-forth exchanges asking for SSH output, logs, config files, etc. Most users are not comfortable with SSH. This slows down troubleshooting significantly (see #139).

Proposal

Build a diagnostic tool into the Web UI that collects all relevant system and device information, displays it for self-diagnosis, and optionally exports a support bundle that users can attach to GitHub issues.

Required Data Points

1. OCT Server Info (no device connection needed)

• OCT version, build date, commit hash
• station_descriptor_base_url (the URL Bose devices use to reach OCT)
• Host IP auto-detection result
• Container runtime info (Docker/Podman, host networking mode)
• Database status (SQLite path, size, preset count)
• Environment variables (sanitized - no secrets)
• Python version, OS info

2. Device Info (per discovered device)

• Device model, firmware version, MAC address (from /info)
• Current playback state (from /now_playing)
• Stored presets on device (from /presets)
• Network configuration (IP, connection type)
• Device reachability (ping/HTTP check)

3. Setup Status (requires SSH/USB stick)

• /etc/hosts content — verify OCT redirects are present and point to correct IP
• OverrideSdkPrivateCfg.xml — verify BMX URL override is set
• USB stick presence and contents (/usb/)
• Backup status (/usb/backups/)

4. Connectivity Checks (automated)

• OCT to Device: HTTP reachability on port 8090
• OCT to Device: WebSocket on port 8080
• Device to OCT: Verify device can reach OCT's BMX endpoints (simulate preset flow)
• DNS resolution: Does bmx.bose.com resolve to OCT IP?
• Stream URL test: Can OCT fetch the configured stream URL?

Implementation Plan

Backend (apps/backend/)

• New module: diagnostics/ with service, routes, models
• GET /api/diagnostics/server — OCT server info (always available)
• GET /api/diagnostics/device/{device_id} — device-specific diagnostics
• GET /api/diagnostics/device/{device_id}/setup — SSH-based setup verification
• GET /api/diagnostics/connectivity/{device_id} — run connectivity checks
• GET /api/diagnostics/bundle/{device_id} — generate full support bundle as JSON
• GET /api/diagnostics/bundle — generate bundle for all devices

Frontend (apps/frontend/)

• New page: /diagnostics (or /settings/diagnostics)
• Per-device diagnostic card with traffic-light indicators (green/yellow/red)
• "Run Full Check" button that executes all checks sequentially with progress
• "Export Support Bundle" button that downloads JSON file
• "Copy to Clipboard" for easy pasting into GitHub issues
• Results formatted as collapsible sections with details

Without USB Stick (limited mode)

• Server info, device info, preset data, connectivity checks all work without SSH
• Setup verification (hosts file, config file) requires SSH access — show warning
• Suggest SSH setup instructions if not available

With USB Stick (full mode)

• All of the above, plus:
• Full /etc/hosts verification
• OverrideSdkPrivateCfg.xml verification
• Backup status check
• Automatic fix suggestions (e.g., "hosts file missing OCT redirect, run Setup Wizard Step 6")

Support Bundle Format

{
  "generated_at": "2026-05-07T12:00:00Z",
  "oct_version": "1.2.0",
  "server": { "..." : "..." },
  "devices": [
    {
      "device_id": "...",
      "info": { "..." : "..." },
      "presets": [],
      "connectivity": { "..." : "..." },
      "setup_status": { "..." : "..." }
    }
  ],
  "checks": [
    { "name": "hosts_redirect", "status": "fail", "detail": "bmx.bose.com not in /etc/hosts" }
  ]
}

Acceptance Criteria

• User can view diagnostic info in the Web UI without SSH knowledge
• Traffic-light indicators show setup health at a glance
• Support bundle can be exported as JSON and attached to issues
• Works in both Docker and Raspi-image deployments
• Sensitive data (SSH keys, passwords) is never included in the bundle
• Backend endpoints are documented in openapi.yaml

Priority

High — this will significantly reduce support burden and improve user experience for non-technical users.

[oct-support]

Thank you for the feature suggestion! 💡

We've noted this as an enhancement request. The maintainer will review it and decide on prioritization.

You can check our existing issues to see if a similar feature has been discussed before.