usbutils

usbutils is a collection of tools for Linux and BSD systems designed to query the types of USB devices connected to a host machine.

Important Note: These tools are intended to be run on a USB host (the machine receiving the connection), not on the USB device itself.

To build and install usbhid-dump, use the standard autotools workflow. If you are building from a Git tree, you must run ./bootstrap first.

1. Run ./configure && make to build the binary.
2. Run make install to install it to the system.

Alternatively, you can run the utility directly from the source directory without installation using src/usbhid-dump.

usbhid-dump is a utility based on libusb 1.0 used to dump USB HID device report descriptors and the data streams (reports) sent by specific device interfaces.

⚠️ Critical Safety Warning

When running as a superuser, always limit your device selection using options like --address or --model. If you do not limit the selection, usbhid-dump will attempt to dump every possible device. If you are using a USB keyboard to control your terminal, it may be detached, causing you to lose control of your system.

If a keyboard is detached, wait for the interrupt transfer timeout (default is 60 seconds) for the process to abort automatically before touching the keyboard.

Basic Usage Example

To dump both the descriptor and the stream for a specific device at bus 2, address 3:

sudo usbhid-dump --entity=all --address=2:3

Before building, ensure that libusb and libudev are installed on your system.

You can build the project using two different methods:

Method 1: Using autogen.sh (Recommended for raw repo clones)

This script automates the build process and places the resulting binaries in the build/ subdirectory.

Method 2: Using Meson (Manual build)

If you prefer to build manually using the Meson build system, follow these steps:

1. Setup the build directory.
2. Enter the build directory.
3. Compile the project.

# Method 1: Using autogen.sh
./autogen.sh

# Method 2: Using Meson
meson setup build
cd build/
meson compile

The lsusb.py utility displays information about USB buses and the devices connected to them. It enhances the standard lsusb (8) command by providing additional details such as interface speeds, driver bindings, Linux device paths, and endpoint details. It uses the usb.ids file to map vendor and product IDs to human-readable names.

lsusb.py [options]

The usbhid-dump utility uses libusb to extract report descriptors and data streams from USB Human Interface Device (HID) interfaces.

⚠️ Critical Warning

usbhid-dump detaches kernel drivers from the interfaces it dumps to use them exclusively. This means no other program (including the kernel) will receive input from those devices while the tool is running.

If you dump a stream from your USB keyboard, you will lose control of your terminal. If this happens, stop typing and wait for the stream timeout to expire. Once the timeout is reached, the keyboard will be reattached to the kernel driver and control will be restored.

The utility outputs data in chunks. Each chunk is preceded by an empty line and a header in the following format:

BUS:DEVICE:INTERFACE:ENTITY TIMESTAMP

• BUS: Bus number.
• DEVICE: Device address.
• INTERFACE: Interface number.
• ENTITY: Either DESCRIPTOR or STREAM.
• TIMESTAMP: Seconds since epoch.

Following the header, the data is presented as hex bytes.

• Descriptor chunks: Contain the full report descriptor.
• Stream chunks: Contain a full report. Note that if a report exceeds the endpoint's wMaxPacketSize, it will be split across multiple chunks.

To reset a device, you must first identify it. Running usbreset without arguments provides a list of connected devices. You can target a device using one of the following four formats:

• Vendor and Product IDs: VVVV:PPPP (e.g., 1234:5678)
• Bus and Device Number: BBB/DDD (e.g., 001/002)
• Serial Number: SN:SERIAL (e.g., SN:ABCDEF0)
• Product Name: The exact product name string (e.g., "USB2.0 Hub")

See the examples below for specific syntax.

usb-devices is a shell script used to display details of USB buses and the devices connected to them. It is primarily used as a fallback when the standard usb/devices file is unavailable in the filesystem.

Key differences from the usb/devices file:

• It only lists active interfaces (those marked with a * in the original usb/devices file) and their endpoints.
• The output format and sorting may differ from the raw kernel files.

Exit Codes:

• Returns a non-zero exit code if sysfs is not mounted.

The usbreset utility sends a USB port reset to a specific USB device. This is useful for recovering unresponsive or erratic USB hardware.

If run without arguments, usbreset displays usage information and a list of all connected USB devices, including their vendor/product IDs, bus/device numbers, and product names. This list can be used to identify the correct identifier for the reset command.

If the specified device is not found, the command returns a non-zero exit code.

usbreset [device]

You can pipe the output of usbhid-dump into hidrd-convert (from the hidrd project) to transform raw hex descriptors into a human-readable specification. This requires using xxd to convert the hex stream back into binary format first.

Example command to convert descriptors for a device at bus 2, address 3, interface 0:

sudo usbhid-dump -a2:3 -i0 | grep -v : | xxd -r -p | hidrd-convert -o spec