深入解析PyUSB:用Python轻松操控USB设备

在嵌入式系统、工业自动化、物联网（IoT）以及硬件交互开发中，与USB设备通信是一项常见但技术门槛较高的任务。传统上，开发者需使用 C/C++ 编写底层驱动或调用操作系统特定的 API（如 Windows 的 WinUSB、Linux 的 libusb），不仅代码复杂，还缺乏跨平台能力。

而 PyUSB 的出现，彻底改变了这一局面。作为 Python 生态中用于 USB 通信的核心库，PyUSB 提供了一套简洁、统一、跨平台的接口，让开发者无需深入操作系统内核，即可通过几行 Python 代码读写 USB 设备、控制端点、枚举设备信息，甚至实现自定义 HID（人机接口设备）或 CDC（通信设备类）协议。

本文将从基础概念、安装配置、核心 API、实战案例、调试技巧到高级应用，系统性地介绍 PyUSB，帮助你掌握如何用 Python 高效、安全地与 USB 设备交互。无论你是想读取 USB 温度传感器、控制 LED 灯带，还是开发自己的 USB 外设固件测试工具，PyUSB 都是你不可或缺的利器。

在深入 PyUSB 之前，有必要简要了解 USB 协议的基本结构，这有助于理解后续的代码逻辑。

一个 USB 设备由以下逻辑单元组成：

●设备（Device）：物理 USB 设备本身，具有唯一的 Vendor ID（VID）和 Product ID（PID）。

●配置（Configuration）：一个设备可有多个配置（通常为1），描述供电、接口数量等。

●接口（Interface）：功能单元，如一个 USB 音频设备可能包含“麦克风”和“扬声器”两个接口。

●端点（Endpoint）：数据传输的终点。分四种类型：

a.Control（控制）：用于设备配置和状态查询（端点0，双向）；

b.Bulk（批量）：高可靠、低实时性，如打印机、存储设备；

c.Interrupt（中断）：低延迟、小数据量，如键盘、鼠标；

d.Isochronous（同步）：高带宽、容忍丢包，如摄像头、音频流。

注意：PyUSB 主要操作 端点 来进行数据收发。

USB 协议定义了标准设备请求（如 GET_DESCRIPTOR、SET_CONFIGURATION），同时也允许厂商自定义命令。此外，USB-IF制定了多种设备类（Device Class） 规范，如：

●HID（Human Interface Device）：键盘、鼠标、游戏手柄；

●CDC（Communication Device Class）：虚拟串口（如 Arduino）；

●MSC（Mass Storage Class）：U 盘；

●DFU（Device Firmware Upgrade）：固件升级。

PyUSB 不依赖这些高层协议，它工作在传输层，因此适用于任何 USB 设备——包括没有标准驱动的“裸设备”。

PyUSB 是纯 Python 库，但依赖底层 USB 后端（backend）。安装命令如下：

pip install pyusb

注意：PyUSB 本身不包含后端实现，需额外安装支持库。

PyUSB 支持三种主流后端：

推荐使用 libusb1，因其跨平台性好、维护活跃。

Windows用户特别说明：

●下载 libusb-1.0.dll

●将DLL文件放入C:\Windows\System32或Python脚本同目录

●或使用 Zadig 工具为设备安装WinUSB驱动（关键步骤！）

注意：若未正确安装驱动，Windows 会阻止用户态程序访问 USB 设备，报错 Access denied 或 No backend available。

Linux 用户权限问题：

默认情况下，普通用户无权访问 /dev/bus/usb/*。

解决方法：

# 创建 udev 规则（以 VID=0x1234, PID=0x5678 为例）echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="1234", ATTR{idProduct}=="5678", MODE="0666"' | sudo tee /etc/udev/rules.d/99-myusb.rulessudo udevadm control --reload-rules && sudo udevadm trigger

PyUSB 的设计哲学是“简单即强大”。其核心模块为 usb.core 和 usb.util。

使用 usb.core.find() 查找设备：

import usb.coreimport usb.util# 方法1：通过 VID/PID 查找dev = usb.core.find(idVendor=0x1234, idProduct=0x5678)# 方法2：查找所有设备devices = usb.core.find(find_all=True)# 方法3：自定义查找函数def my_filter(dev):    return dev.idVendor == 0x1234and dev.manufacturer == "MyCompany"dev = usb.core.find(custom_match=my_filter)

若未找到，返回 None；若找到多个且未用 find_all=True，抛出 ValueError。

一旦获得 dev 对象（usb.core.Device 实例），可读取其描述符：

print(f"Manufacturer: {usb.util.get_string(dev, dev.iManufacturer)}")print(f"Product: {usb.util.get_string(dev, dev.iProduct)}")print(f"Serial: {usb.util.get_string(dev, dev.iSerialNumber)}")# 打印所有配置for cfg in dev:    print(f"Config {cfg.bConfigurationValue}")    for intf in cfg:        print(f"  Interface {intf.bInterfaceNumber}: {intf.bNumEndpoints} endpoints")        for ep in intf:            print(f"    EP {ep.bEndpointAddress:02x} ({'IN'if ep.bEndpointAddress & 0x80else'OUT'}), Type: {ep.bmAttributes & 0x03}")

注意：字符串描述符需通过 usb.util.get_string() 解码，直接访问 dev.iProduct 返回的是索引。

在Linux/macOS上，若设备已被系统驱动占用（如 HID  键盘被内核接管），需先分离内核驱动：

if dev.is_kernel_driver_active(0):  # 接口0    dev.detach_kernel_driver(0)

操作完成后，应重新附加驱动（良好实践）：

dev.attach_kernel_driver(0)

Windows通常无需此步骤（因使用 WinUSB 驱动时内核未接管）。

大多数设备只需使用默认配置：

dev.set_configuration()  # 使用第一个配置cfg = dev.get_active_configuration()intf = cfg[(0, 0)]       # 获取接口0，备用设置0

写数据（OUT 端点）：

# 假设端点地址为 0x01（OUT）ep_out = usb.util.find_descriptor(intf, custom_match=lambda e: \    usb.util.endpoint_direction(e.bEndpointAddress) == usb.util.ENDPOINT_OUT)if ep_out:    data = b'\x01\x02\x03\x04'    bytes_written = dev.write(ep_out.bEndpointAddress, data, timeout=1000)    print(f"Sent {bytes_written} bytes")

读数据（IN 端点）：

# 假设端点地址为 0x81（IN）ep_in = usb.util.find_descriptor(intf, custom_match=lambda e: \    usb.util.endpoint_direction(e.bEndpointAddress) == usb.util.ENDPOINT_IN)if ep_in:    try:        data = dev.read(ep_in.bEndpointAddress, ep_in.wMaxPacketSize, timeout=1000)        print(f"Received: {data}")    except usb.core.USBError as e:        if e.errno == 110:  # 超时            print("Read timeout")

关键参数：

●timeout：单位毫秒，避免无限阻塞；

●wMaxPacketSize：端点最大包长，可作为读缓冲区大小。

假设我们有一个基于 STM32 的 USB CDC 设备（虚拟串口），但希望绕过操作系统串口驱动，直接通过 PyUSB 控制。

首先，用 lsusb -v（Linux）或 USBTreeView（Windows）查看设备描述符：

Bus 001 Device 005: ID 0483:5740 STMicroelectronics Virtual COM PortDevice Descriptor:  bcdUSB               2.00  bDeviceClass          2 Communications  bDeviceSubClass       0  bDeviceProtocol       0  idVendor           0x0483 STMicroelectronics  idProduct          0x5740 Virtual COM Port  ...  Interface Descriptor:    bInterfaceNumber     0    bInterfaceClass      2 Communications    bInterfaceSubClass   2 Abstract (modem)    bInterfaceProtocol   1 AT-commands (v.25ter)    Endpoint Descriptor:      bEndpointAddress     0x81  EP 1 IN      bmAttributes            3        Transfer Type            Interrupt      wMaxPacketSize     0x0008    Endpoint Descriptor:      bEndpointAddress     0x01  EP 1 OUT      bmAttributes            2        Transfer Type            Bulk

可见，该设备有两个端点：0x81（IN，中断）、0x01（OUT，批量）。

import usb.coreimport usb.utilimport sys# 查找设备dev = usb.core.find(idVendor=0x0483, idProduct=0x5740)if dev is None:    raise ValueError('Device not found')# 分离内核驱动（Linux/macOS）if sys.platform != "win32":    if dev.is_kernel_driver_active(0):        dev.detach_kernel_driver(0)# 设置配置dev.set_configuration()# 获取接口cfg = dev.get_active_configuration()intf = cfg[(0, 0)]# 查找端点ep_out = usb.util.find_descriptor(    intf,    custom_match=lambda e: usb.util.endpoint_direction(e.bEndpointAddress) == usb.util.ENDPOINT_OUT)ep_in = usb.util.find_descriptor(    intf,    custom_match=lambda e: usb.util.endpoint_direction(e.bEndpointAddress) == usb.util.ENDPOINT_IN)ifnot ep_out ornot ep_in:    raise ValueError("Endpoints not found")# 发送 AT 命令command = b"AT\r\n"dev.write(ep_out.bEndpointAddress, command, timeout=1000)# 读取响应try:    response = dev.read(ep_in.bEndpointAddress, 64, timeout=1000)    print("Response:", response.tobytes().decode('utf-8', errors='replace'))except usb.core.USBError as e:    print("Read error:", e)

运行结果可能为：

Response: ATOK

此例展示了如何绕过 pyserial，直接与 CDC 设备通信，适用于需要低延迟或自定义协议的场景。

原因：未安装 libusb 或 DLL 未找到。

解决：

●Linux：sudo apt install libusb-1.0-0-dev

●Windows：将 libusb-1.0.dll 放入 PATH 或脚本目录；

●指定后端：usb.core.find(backend=usb.backend.libusb1.get_backend())

●Linux：检查 udev 规则，确保用户有权限；

●Windows：用 Zadig 为设备安装 WinUSB 驱动（替换原有驱动）；

●macOS：可能需要禁用 SIP 或使用 IOKit 后端（较少见）。

●检查端点方向是否正确（IN/OUT）；

●确认设备固件是否处于接收状态；

●增加 timeout 值；

●使用 USB 协议分析仪（如 Wireshark + USBPcap）抓包验证。

●在Windows上，HID 设备常被hidusb.sys占用，需用 Zadig 替换为 WinUSB；

●在Linux上，使用 detach_kernel_driver()。

PyUSB 可用于自动化测试嵌入式设备的 USB 功能。例如，验证设备在不同命令下的响应：

classUSBDeviceTester:    def __init__(self, vid, pid):        self.dev = usb.core.find(idVendor=vid, idProduct=pid)        assert self.dev, "Device not found"        self.dev.set_configuration()        self._setup_endpoints()    def _setup_endpoints(self):        cfg = self.dev.get_active_configuration()        intf = cfg[(0, 0)]        self.ep_out = ...  # find OUT        self.ep_in = ...   # find IN    def send_command(self, cmd: bytes) -> bytes:        self.dev.write(self.ep_out.bEndpointAddress, cmd, timeout=2000)        return self.dev.read(self.ep_in.bEndpointAddress, 256, timeout=2000).tobytes()    def test_led_on(self):        resp = self.send_command(b"LED ON\n")        assert b"OK" in resp, "LED ON failed"    def test_temperature(self):        resp = self.send_command(b"TEMP?\n")        temp = float(resp.strip())        assert 20 <= temp <= 30, f"Invalid temperature: {temp}"

此类框架可集成到 CI/CD 流程中，实现硬件回归测试。

七、PyUSB与其他库的对比

结论：PyUSB 是通用 USB 通信的首选。

PyUSB 以极简的 API 封装了复杂的 USB 通信细节，使 Python 开发者能够轻松进入硬件交互领域。无论是快速原型验证、自动化测试，还是构建跨平台的设备管理工具，PyUSB 都提供了强大而可靠的支持。

然而，能力越大，责任越大。直接操作 USB 设备意味着你需要理解端点、传输类型、描述符等概念，并谨慎处理权限与资源释放。建议在开发中始终遵循：

1、先枚举，再操作；

2、及时释放内核驱动；

3、设置合理超时；

4、异常处理全覆盖。

最后，记住：最好的 USB 代码，是那些即使设备拔掉也不会崩溃的代码。