Manual / Help
Diagnostics
OpenFollow’s built-in self-check surface. Shows live health for the web server, peer discovery, and logging, and produces a downloadable text bundle that captures everything needed to triage an issue.
Diagnostics is a section inside the Overview tab and refreshes every 5 seconds. The bundle download, peer test, and log tail are one-click actions on the same page.
Live summary cards
Four cards across the top of the section. Each card shows a status chip in the header and a few key metrics underneath.
Web server
- Configured – the configured web port.
- Serving on – the port the server actually bound to. If port 80 was unavailable, OpenFollow falls back to one of the backups (
8080,2010) and this row shows which. - Uptime – how long the OpenFollow process has been running.
- Status chip – OK when configured matches serving; fallback when the server is on a backup port.
Beacon sender
Health of the outgoing peer-discovery beacon. If this card is unhealthy, peers won’t see this server.
- Last sent – timestamp of the most recent beacon.
- Errors – running send-error count.
- Sent count – total beacons sent since the process started.
Beacon receiver
Health of the incoming peer-discovery listener. If this is unhealthy, this server won’t see other peers.
- Peers seen – number of OpenFollow peers currently known on the LAN.
- Last packet – timestamp of the most recent received beacon.
- Packets total – running count of packets the receiver has consumed.
Logs
Tells you where the operating logs are coming from. The chip reads journalctl on a properly-installed Linux host (preferred), or in-memory ring when journalctl isn’t available – typically a host where the systemd journal isn’t reachable.
If journalctl is expected but unavailable, a yellow warning banner appears above the cards explaining why.
Bundle & tools
Four actions live below the cards.
Download diagnostics bundle
One click produces a UTF-8 text file with everything needed to debug a misbehaving installation. The browser saves it as openfollow-diagnostics-<system-name>-<timestamp>.txt; OpenFollow also writes a copy to disk on the host (best-effort – failures don’t break the download).
The button is a plain HTML anchor – it works without HTMX or JavaScript.
What the bundle contains
The bundle is sectioned plain text, easy to skim, easy to paste into an issue. Every section is independent – a collector that fails on a degraded host renders [unavailable: <reason>] instead of crashing the whole bundle.
| Section | Contents |
|---|---|
| Service (A) | Configured / display web port, process uptime, PID, restart count. |
| Discovery (B) | Beacon sender + receiver health, list of known peers, primary network interface IP. |
| Configuration (C) | The full saved configuration, with the web PIN redacted. A diff against defaults so it’s obvious what’s been customised. |
| Recent failures (D) | A failure-focused view: the last log lines (up to 2000, from journalctl or the in-memory ring, with auth signatures stripped), a WARNING-and-above extract from the past 24 hours, recent background error reports and rejected-request counts, and the last worker-thread error reports. |
| Runtime versions (E1) | Python, OpenFollow, GTK 3, and key dependency versions, plus git HEAD / branch / dirty flag if running from a checkout. |
| Detection stack (E2) | Whether the optional Person Detection backends are installed and which engine is selected. |
| OS / CPU / Memory + disk (E3–E5) | Distribution, kernel, CPU model, RAM, mount points, free space. |
| Storage breakdown (E5b) | Per-filesystem mount table with fill % and inode use, plus the largest known directories. Surfaces an SD card filling up because the NVMe isn’t actually mounted, or inode exhaustion, when free space alone looks fine – the usual SD-card-full triage. |
| System health (E6) | Throttling state, undervoltage flags (Pi), thermal events. |
| Network interfaces (E7) | List of interfaces with IPs, MTU, link state. |
| USB devices (E8) | USB device table with vendor/product IDs and an OpenFollow column classifying each device as MIDI, gamepad, camera, or unclaimed – cross-referenced against the running subsystems so you can see what OpenFollow can actually use, with a totals line and a note on any degraded subsystem. |
| Gamepad controllers (E9) | Per-connected-pad runtime snapshot: input mode (game-controller vs raw joystick), name, GUID, axis/button/hat counts, and calibration match / MISMATCH against the stored mapping. MISMATCH means the wizard was run on a different physical unit or in a different controller mode (most often: XInput not selected) – re-run the button detection wizard. |
| Recent I/O activity (F) | Recent OSC sends and MIDI received; the inbound-OSC and outbound-MIDI lines read [not applicable] when nothing applies. |
| Device permissions (G) | The station's privilege status – a summary of which device operations run without a password, which still prompt, and which are unavailable, plus the per-capability list. |
Privacy
Always-on redactions (no toggle):
- The web PIN – replaced with
***when set, or(empty)when no PIN is configured. - Auth signature values – stripped from any matching log line.
Everything else (IPs, hostnames, paths, USB descriptors) is in the bundle as-is. Review before sharing publicly.
Test peer connectivity
Probes every known peer on its advertised port and returns a small results table:
- Green chip – peer responded with HTTP status and round-trip time in ms.
- Red chip – peer unreachable, with the error reason.
Non-private destination IPs are refused with “non-private IP refused”. See Networking & Security for the private-IP allowlist.
If the table is empty (“No peers known yet”), wait for discovery or check the Beacon receiver card above.
Show recent log tail
Pulls the last 100 lines from the live log source (journalctl when available, otherwise the in-memory ring) and shows them inline. The first line of the output identifies the source ([source: journalctl] or [source: ring]). Auth signatures are redacted before display.
You can fetch more lines – up to 2000 – from the diagnostics panel if you need a longer tail.
Restart application
Restarts the OpenFollow process (not the OS). Confirms first, then reloads the page once the server comes back. Use after changing settings that require a restart (network port changes, Person Detection engine, etc.).
Bundles on disk
Each bundle download also writes a copy to a default location on the host (auto-pruned). Available via SSH when the web UI isn't reachable.
Filing a useful bug report
Attach (or paste) a fresh diagnostics bundle. If reproducible, include the steps from a clean state. See the broader checklist in Troubleshooting.