How timfish/usb_enumeration works
Project type and purpose
• usb_enumeration is an open-source, cross-platform Rust library (crate) whose sole responsibility is to enumerate USB devices on the host system and provide an event subscription interface.
• It is not a web service or a full-stack application, but rather a systems-level library that abstracts OS-specific USB enumeration APIs under one uniform Rust API.
File structure
• Cargo.toml, .rustfmt.toml, and .github/ workflows: standard Rust crate metadata, formatting, and CI.
• src/lib.rs: the public API surface (functions like enumerate and the Observer type).
• src/common.rs: shared types and utilities (e.g. UsbDevice struct, Event enum, channel setup).
• src/linux.rs, src/macos.rs, src/windows.rs: platform-specific implementations that call into each OS’s USB enumeration subsystem.
• No database, no networking, no front-end: everything lives in the library and the host OS.
README for additional insights
• Public API:
• enumerate(None, None) → returns Vec<UsbDevice>
• Observer → subscribe to change events on a background thread, communicates over an mpsc channel
• Internally, the Observer likely spins up a polling loop (with configurable interval) that invokes the same platform enumerator and diffs results to emit Initial, Connect, Disconnect events.
a. Main components:
• Consumer (the user’s Rust application code)
• usb_enumeration crate
– Public API layer (lib.rs)
– Shared domain (common.rs – UsbDevice, Event, channel)
– Platform adapters (linux.rs, macos.rs, windows.rs)
– Observer subsystem (background thread + mpsc channel)
• Underlying OS USB subsystem / system calls (WinAPI SetupDi*, libusb on Linux, IOKit on macOS)
b. Relationships and interactions:
1. Consumer calls usb_enumeration::enumerate() or constructs an Observer.
2. The Public API dispatches at compile time (via #[cfg]) to the proper platform adapter.
3. Platform adapter invokes native OS APIs to gather USB device info.
4. Data flows back as Vec<UsbDevice> or as Event messages over a channel.
5. The Observer component spawns a thread, on each tick it calls the same adapter, diffs the results, and sends Event::Connect/Disconnect/Initial through the channel to the Consumer.
c. Architectural patterns / design principles:
– Adapter pattern: each OS gets its own adapter module behind a uniform trait or API.
– Single responsibility: common.rs for data types, adapters for OS specifics, lib.rs for API orchestration.
– Observer pattern for event subscription, implemented via Rust channels and a background thread.
d. Relevant technologies:
– Rust standard library threads and channels (std::sync::mpsc or crossbeam)
– Conditional compilation (#[cfg(target_os = "...")])
– OS-specific APIs: WinAPI SetupDi*, libusb or direct syscalls on Linux, IOKit on macOS
Detail without overthinking
• Compile-time dispatch to the appropriate adapter.
• Observer’s polling loop and channel.
• Keep it simple: the goal is to leave no piece of the library architecture undocumented.