USBscope

USBscope is a live USB event dashboard for CachyOS / ArchLinux. It ships a small system daemon that tails kernel USB logs and tracks connected USB devices, then exposes that data over D-Bus to a desktop UI and tray app. The result is a real-time view of what is happening on your USB bus, plus a quick way to surface errors as they happen.

Why it is useful

• Debug flaky peripherals by correlating hotplug events with kernel messages.
• Catch error bursts quickly via tray notifications and a visible error timeline.
• Get an at-a-glance view of currently connected devices with vendor/product IDs.
• Export filtered logs to CSV for bug reports or deeper analysis.

What it does

• Tails kernel logs (journalctl -k -f) and classifies USB-related events.
• Monitors the live USB device list via udev.
• Publishes events and device snapshots over the system D-Bus.
• Provides a Qt UI with filtering, search, timeline visualization, and CSV export.
• Provides a tray icon for quick status and error burst notifications.

Log filtering

• Text search: free-text filter on the log message column.
• Presets: quickly switch between all events, USB-only, errors-only, or USB errors.
• Date range: optionally restrict visible events between two timestamps.

Timeline view

• Visualizes USB events over time using the same color scheme as the log table.
• Zoom with Ctrl+mouse wheel for horizontal time scaling.
• Pan the view with middle-click drag or Shift+left-click drag.
• Clicking an event in the timeline recenters the log view on the matching row.

Components

• usbscoped: daemon that reads kernel logs and udev, emits D-Bus signals.
• usbscope-ui: Qt desktop app with log table, device list, and timeline view.
• usbscope-tray: tray app that watches for USB errors and shows notifications.
• usbscopecore: shared library for USB event/device types and D-Bus helpers.

How it works (high level)

1. usbscoped tails kernel logs and parses each line into a structured UsbEvent.
2. It tracks connected USB devices via udev enumeration and hotplug updates.
3. Events and device snapshots are broadcast on D-Bus (org.cachyos.USBscope1).
4. The UI and tray clients subscribe to those signals and request history on startup.

Build

Dependencies: Qt6 (Core, Widgets, DBus), CMake, a C++17 compiler.

sudo pacman -S --needed cmake make gcc qt6-base qt6-tools 

git clone https://github.com/infinityabundance/USBscope.git
cd USBscope
cmake -S . -B build
cmake --build build

Run

Launch the UI:

./build/usbscope-ui

There is also a sample systemd service file at data/usbscoped.service.

Hacking

If you want to read or modify the code, see HACKING.md for a short contributor-oriented overview.

D-Bus API

Interface: org.cachyos.USBscope1 on the session bus by default.

If the session bus is unavailable, USBscope falls back to the system bus. You can also force system bus use with:

USBSCOPE_BUS=system usbscope-ui
USBSCOPE_BUS=system usbscoped
USBSCOPE_BUS=system usbscope-tray

Note: system bus registration may require an appropriate D-Bus policy.

Methods:

• GetVersion()
• GetRecentEvents(limit)
• GetCurrentDevices()
• GetStateSummary()

Signals:

• LogEvent
• DevicesChanged
• ErrorBurst