PyUSB

Warnings

• gotcha PyUSB is a wrapper around a low-level USB library (e.g., libusb-1.0), which must be installed separately on your system. PyUSB will not function without a compatible backend.
  Fix: Install `libusb-1.0` on your operating system. For example: - Debian/Ubuntu: `sudo apt-get install libusb-1.0-0-dev` - macOS (Homebrew): `brew install libusb` - Windows: Download binaries from the libusb website and ensure they are in your system's PATH or explicitly specified using `usb.backend.libusb1.get_backend()`.
• gotcha On Linux, accessing USB devices often requires root privileges or specific udev rules to grant non-root users access. Without correct permissions, `usb.core.find()` will fail to locate devices.
  Fix: Run your Python script as root (`sudo python your_script.py`) or, for a more secure approach, create a udev rule (e.g., `/etc/udev/rules.d/99-mydevice.rules`) that grants access to specific devices and add your user to the relevant group. Example rule: `SUBSYSTEM=="usb", ATTR{idVendor}=="<vendor_id>", ATTR{idProduct}=="<product_id>", MODE="0666", GROUP="plugdev"`.
• breaking As of PyUSB 1.3.0, the minimum required Python version is 3.9. Attempting to install or run PyUSB 1.3.0+ on older Python versions (e.g., 3.8, 3.7, 3.6) will result in installation failures or runtime errors.
  Fix: Upgrade your Python environment to version 3.9 or newer. If you must use an older Python version, restrict your PyUSB dependency to `<1.3.0` (e.g., `pip install 'pyusb<1.3.0'`).
• breaking Version 1.3.0 introduced a regression in `ctrl_transfer` where supplied read buffers were discarded, potentially leading to incorrect or unexpected behavior when pre-allocating buffers for control reads. This was fixed in 1.3.1.
  Fix: Upgrade to PyUSB 1.3.1 or newer to ensure `ctrl_transfer` correctly utilizes supplied read buffers. If stuck on 1.3.0, avoid pre-allocating read buffers for `ctrl_transfer` and rely on the function to return a newly allocated buffer.
• gotcha The hashability of `Device` objects was broken in PyUSB 1.2.0, making them unsuitable for use in sets or as dictionary keys. This was restored in 1.2.1. Additionally, `Device.__eq__()` was implemented in 1.2.0, changing how device objects are compared.
  Fix: If you rely on `Device` objects being hashable (e.g., storing them in sets or using them as dict keys), ensure you are on PyUSB 1.2.1 or newer. Be aware of the `__eq__` implementation changes when comparing device objects between 1.1.x and 1.2.x+.

Install

• pip install pyusb Install PyUSB

Imports

• core

  import usb.core

• util

  import usb.util

• backend

  import usb.backend.libusb1 as libusb1

  Commonly aliased for convenience when selecting specific backends.

Quickstart

This quickstart demonstrates how to find an attached USB device, retrieve its manufacturer and product strings, and properly dispose of resources. Replace `dev = usb.core.find()` with specific `idVendor` and `idProduct` for a targeted search.

import usb.core
import usb.util

# Find the first USB device available. 
# For a real application, you'd specify idVendor and idProduct, e.g.,
# dev = usb.core.find(idVendor=0x046d, idProduct=0xc077) # Example: Logitech mouse

dev = usb.core.find() # Finds any device

if dev is None:
    print("No USB device found. Ensure a device is connected and permissions are set.")
else:
    print(f"Device found: Bus {dev.bus}, Address {dev.address}")
    try:
        # Try to get manufacturer and product strings
        # These indices (iManufacturer, iProduct) might be 0 or invalid on some devices
        manufacturer = usb.util.get_string(dev, dev.iManufacturer)
        product = usb.util.get_string(dev, dev.iProduct)
        print(f"  Manufacturer: {manufacturer}")
        print(f"  Product: {product}")
    except Exception as e:
        print(f"  Could not read device strings (permissions or device issue): {e}")

    # Always remember to dispose resources when done with the device
    usb.util.dispose_resources(dev)
    print("Resources disposed.")