USB Atlas

Important

Vibe meter: 100% AI slop

A native egui/eframe toy for exploring USB topology and describing physical hardware.

cargo run

On Linux, discovery reads /sys/bus/usb/devices without opening devices or requiring root. Other systems can use the demo and manual nodes until a discovery backend is added.

• Scan USB imports hubs, devices, port counts, and numbered upstream connections. Disconnected nodes stay in the diagram as offline, preserving annotations. Scanning is manual.
• Drag nodes around the dotted grid; toggle snapping. Hold the right mouse button during a left-button node drag to move all downstream children and grandchildren by the same amount. Release right mouse mid-drag to snap and drop the children, then move only the node again. Dropped children stay fixed while you finish moving the parent. Subtree drags preserve physical grouping, and snapping preserves relative spacing. Input and output sockets use grid coordinates, so grid snapping can make parent cables exactly horizontal. Connection circles face the other node: children to the right use a left input, and children to the left use a right input; parent port circles switch sides too. Scroll over the canvas to zoom around the cursor (20–400%); 95–105% snaps to exactly 100%. Drag with the right/middle button to pan. Arrange lays out the logical topology; Reset view resets zoom to 100% and centers the visible diagram when its bounding box fits the viewport, or aligns its top-left with a small margin when larger. The viewport center (in grid coordinates) and zoom are remembered with each diagram, so reopening restores the same view even after a window resize. First-time diagrams use automatic framing; controller badges are included in those bounds.
• Drop logical device B onto A to make a physical device containing both. Members remain visible inside a named outline. Drag a member outside the original outline to remove it. When only one member remains, the group dissolves and that member becomes a raw logical device again. Dropping into an existing group adds a member. USB connections are preserved. Drag the outline’s title to move the whole physical device.
• Drop a USB 2 hub onto a USB 3 hub (or the reverse) to represent one physical hub. A four-port pair becomes one card with four shared sockets. Blue denotes USB 3 support (usually including USB 2); orange denotes USB 2-only ports. Matching USB 2/3 cable paths are drawn once in blue. Logical port numbers are paired directly; each USB connection retains its original logical hub and port. Different port counts use the larger count, with each socket colored by its supported versions.
• Drag the unified hub card to move both logical hubs; hold right mouse to include downstream devices from both branches. Drag either USB 2 / USB 3 handle outside the card to split the pair into raw hubs again. The inspector lets you select either logical hub for editing or show both separately without ungrouping. Other physical groups retain their outline-and-members view.
• Controllers/root hubs are hidden by default. Top-level hubs and devices carry controller badges to their left, aligned with the top of the card. Badges show only the PCIe address in monospace, using orange for USB 2 and blue for USB 3 (including combined USB 2/3 paths); USB buses on the same PCI controller share a badge. Hover a badge or open Attached controller in the inspector for details. Nodes show vendor, advertised USB version, and link speed. The inspector also shows USB VID:PID, PCI model/address, hub protocol, serial, device revision, configuration current, power source, lanes, and runtime power state. Vendor/model names use optional local usb.ids and pci.ids databases with descriptor/numeric fallbacks.
• Controllers lets you show or hide each physical controller independently. Show node displays its logical controller/root-hub nodes on the canvas with their USB connections; disabling it returns to child-attached labels. Label toggles the address badges when the controller is hidden. Its children remain visible in either mode. USB 2/3 buses on the same PCI address share one setting. Choices persist with the live diagram, preserving every device’s connections and positions.
• Select a node to rename it, override its port count (e.g. a four-port hub), add notes, rename its physical group, or choose its upstream hub and port. Invalid ports, occupied ports, and cycles are rejected.
• + Hub and + Device add manually described hardware.
• Edit beside node moves the same editor into a floating window beside the selected node. The window can then be moved freely.
• Demo opens a separate scratch diagram, including a dock shown as a unified four-port USB 2 + USB 3 hub. It does not overwrite the live diagram.

The live document (including positions, annotations, viewport center, and zoom) is saved by eframe in the platform application-data directory on exit and periodically. The demo is not saved.

Modules

• model.rs: GUI-independent observations, annotations, connections, physical grouping, validation, and layout.
• discovery/: read-only sysfs adapter and optional hwdata vendor/model lookup returning structured hardware observations. Add another platform backend here.
• diagram.rs: GUI-independent projection from logical nodes to visible physical hub cards.
• ui/viewport.rs: cursor-anchored pan/zoom and coordinate transforms.
• ui/cards.rs: shared card geometry, port endpoints, and USB version colors.
• ui/canvas.rs: diagram drawing and gesture interpretation; returns grouping intentions.
• ui/controllers.rs: child-attached controller badges and inspector details.
• ui/hardware.rs: reusable read-only hardware facts view.
• ui/editor.rs: reusable editor widgets and connection/group/remove intentions; no sidebar or window assumptions.
• app.rs: view placement, action handling, live/demo documents, and persistence.

Prototype boundaries

The kernel reports logical hub ports, which may differ from the connectors printed on an enclosure. A USB 3 hub can expose separate USB 2 and USB 3 logical hubs; group those manually. Interfaces of a composite USB device are not separate nodes. Grouping one USB 2 hub and one USB 3 hub collapses their presentation into physical port rows. Pairing is a user declaration based on equal port numbers; no hardware identity or physical port correspondence is inferred automatically. The logical topology remains intact underneath.

Discovery currently identifies devices by bus/port path, so annotations follow a socket rather than following a serial-numbered device across sockets. Replacing a device in the same socket retains those annotations. There is no automatic hotplug refresh or cable dragging yet; edit connections in the inspector.

References: Linux USB sysfs ABI, eframe application API.

cargo test
cargo clippy -- -D warnings