Crate usbwatch_rs

USBWatch

A cross-platform USB device monitoring library and command-line tool.

USBWatch provides real-time monitoring of USB device connection and disconnection events on Linux, Windows, and macOS. It offers both a library API for integration into other applications and a standalone command-line tool.

Features

• Cross-platform: Linux (sysfs), Windows (Win32 APIs), macOS (IOKit)
• Real-time monitoring: Detect USB events as they happen
• Multiple output formats: Plain text and JSON
• File logging: Save events to log files
• Coloured output: Modern, readable CLI output
• Async/await support: Built with Tokio for efficient I/O
• Device handle traits: Access platform-specific device handles for advanced operations
• Install/uninstall commands: Manage CLI tool from the command line

Quick Start

Command Line Usage

# Monitor USB devices with default output
usbwatch

# Monitor with JSON output
usbwatch --json

# Monitor and log to file
usbwatch --logfile usb-events.log

# Monitor with coloured output (default if supported)
usbwatch

# Install or uninstall the CLI tool
usbwatch install
usbwatch uninstall

Library Usage

use usbwatch_rs::{UsbWatcher, UsbDeviceInfo, AsDeviceHandle, DeviceHandle};
use tokio::sync::mpsc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (tx, mut rx) = mpsc::channel(100);
    let watcher = UsbWatcher::new(tx)?;

    // Start monitoring in a background task
    tokio::spawn(async move {
        if let Err(e) = watcher.start_monitoring().await {
            eprintln!("Monitoring error: {}", e);
        }
    });

    // Process device events
    while let Some(device_info) = rx.recv().await {
        println!("Device event: {}", device_info);
        // Access platform-specific device handle
        match device_info.as_device_handle() {
            #[cfg(target_os = "linux")]
            DeviceHandle::Linux { sysfs_path, device_node } => {
                println!("Linux sysfs path: {}", sysfs_path);
                if let Some(node) = device_node {
                    println!("Device node: {}", node);
                }
            }
            #[cfg(target_os = "windows")]
            DeviceHandle::Windows { instance_id, interface_path } => {
                println!("Windows instance ID: {}", instance_id);
                if let Some(path) = interface_path {
                    println!("Interface path: {}", path);
                }
            }
            #[cfg(target_os = "macos")]
            DeviceHandle::Macos { device_id } => {
                println!("macOS device ID: {}", device_id);
            }
            _ => {
                println!("No platform-specific handle available");
            }
        }
    }

    Ok(())
}

Library API Highlights

• UsbWatcher - Cross-platform watcher for USB device events
• UsbDeviceInfo - Struct containing device metadata and event info
• DeviceHandle - Enum for platform-specific device handles
• AsDeviceHandle - Trait for accessing device handles from device info
• create_watcher - Convenience function for watcher creation
• monitor_with_callback - High-level async monitoring with callback
• monitor_for_duration - Collect events for a fixed duration

Platform Support

• Linux: Uses sysfs filesystem (/sys/bus/usb/devices)
• Windows: Uses Win32 Device Installation APIs

Error Handling

All public APIs use Result types for proper error handling. Platform-specific errors are wrapped in boxed std::error::Error for consistency.

Re-exports

pub use device_info::AsDeviceHandle;

pub use device_info::DeviceEventType;

pub use device_info::DeviceHandle;

pub use device_info::UsbDeviceInfo;

pub use logger::logger_task;

pub use logger::Logger;

pub use watcher::UsbWatcher;

Modules

device_info

USB device information structures and event types.

logger

Event logging and output formatting for USB device monitoring.

watcher

Cross-platform USB device monitoring implementations.

Constants

DESCRIPTION

Library description

NAME

Library name

VERSION

Library version information

Functions

create_watcher

Create a new USB watcher with the given channel sender.

is_supported

Check if USB monitoring is supported on the current platform.

monitor_for_duration

Start monitoring USB devices and collect events into a vector.

monitor_with_callback

Start monitoring USB devices with a callback function.

platform_info

Get information about the current platform’s USB monitoring implementation.

Type Aliases

Result

A result type for USB monitoring operations