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

引言：为什么需要 PyUSB？

在嵌入式系统、工业自动化、物联网（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 都是你不可或缺的利器。

一、USB 基础知识回顾

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

1.1 USB 设备层级模型

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

• 设备（Device）：物理 USB 设备本身，具有唯一的 Vendor ID（VID）和 Product ID（PID）。
• 配置（Configuration）：一个设备可有多个配置（通常为1），描述供电、接口数量等。
• 接口（Interface）：功能单元，如一个 USB 音频设备可能包含“麦克风”和“扬声器”两个接口。
• 端点（Endpoint）：数据传输的终点。分四种类型：
  • Control（控制）：用于设备配置和状态查询（端点0，双向）；
  • Bulk（批量）：高可靠、低实时性，如打印机、存储设备；
  • Interrupt（中断）：低延迟、小数据量，如键盘、鼠标；
  • Isochronous（同步）：高带宽、容忍丢包，如摄像头、音频流。

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

1.2 标准请求与 Class 规范

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 安装与环境配置

2.1 安装 PyUSB

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

pipinstallpyusb

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

2.2 后端选择与配置

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"'|sudotee/etc/udev/rules.d/99-myusb.rulessudoudevadm control --reload-rules&&sudoudevadm trigger

三、PyUSB 核心 API 详解

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

3.1 枚举与查找设备

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

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

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

3.2 设备信息获取

一旦获得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)}")# 打印所有配置forcfgindev:print(f"Config{cfg.bConfigurationValue}")forintfincfg:print(f" Interface{intf.bInterfaceNumber}:{intf.bNumEndpoints}endpoints")forepinintf:print(f" EP{ep.bEndpointAddress:02x}({'IN'ifep.bEndpointAddress&0x80else'OUT'}), Type:{ep.bmAttributes&0x03}")

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

3.3 声明接口与释放内核驱动

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

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

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

dev.attach_kernel_driver(0)

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

3.4 设置配置与声明接口

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

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

3.5 端点通信：读写数据

写数据（OUT 端点）：

# 假设端点地址为 0x01（OUT）ep_out=usb.util.find_descriptor(intf,custom_match=lambdae:\ usb.util.endpoint_direction(e.bEndpointAddress)==usb.util.ENDPOINT_OUT)ifep_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=lambdae:\ usb.util.endpoint_direction(e.bEndpointAddress)==usb.util.ENDPOINT_IN)ifep_in:try:data=dev.read(ep_in.bEndpointAddress,ep_in.wMaxPacketSize,timeout=1000)print(f"Received:{data}")exceptusb.core.USBErrorase:ife.errno==110:# 超时print("Read timeout")

关键参数：

• timeout：单位毫秒，避免无限阻塞；
• wMaxPacketSize：端点最大包长，可作为读缓冲区大小。

四、实战案例：与自定义 USB 设备通信

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

4.1 设备信息分析

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

Bus 001 Device 005: ID 0483:5740 STMicroelectronics Virtual COM Port Device 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，批量）。

4.2 编写通信脚本

importusb.coreimportusb.utilimportsys# 查找设备dev=usb.core.find(idVendor=0x0483,idProduct=0x5740)ifdevisNone:raiseValueError('Device not found')# 分离内核驱动（Linux/macOS）ifsys.platform!="win32":ifdev.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=lambdae:usb.util.endpoint_direction(e.bEndpointAddress)==usb.util.ENDPOINT_OUT)ep_in=usb.util.find_descriptor(intf,custom_match=lambdae:usb.util.endpoint_direction(e.bEndpointAddress)==usb.util.ENDPOINT_IN)ifnotep_outornotep_in:raiseValueError("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'))exceptusb.core.USBErrorase:print("Read error:",e)

运行结果可能为：

Response: AT OK

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

五、常见问题与调试技巧

5.1 “No backend available” 错误

• 原因：未安装 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())

5.2 “Access denied” 或 “Operation not permitted”

• Linux：检查 udev 规则，确保用户有权限；
• Windows：用 Zadig 为设备安装 WinUSB 驱动（替换原有驱动）；
• macOS：可能需要禁用 SIP 或使用 IOKit 后端（较少见）。

5.3 读写超时或无响应

• 检查端点方向是否正确（IN/OUT）；
• 确认设备固件是否处于接收状态；
• 增加timeout值；
• 使用 USB 协议分析仪（如 Wireshark + USBPcap）抓包验证。

5.4 设备被系统占用

• 在 Windows 上，HID 设备常被hidusb.sys占用，需用 Zadig 替换为 WinUSB；
• 在 Linux 上，使用detach_kernel_driver()。

六、高级应用：构建 USB 测试框架

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

classUSBDeviceTester:def__init__(self,vid,pid):self.dev=usb.core.find(idVendor=vid,idProduct=pid)assertself.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 OUTself.ep_in=...# find INdefsend_command(self,cmd:bytes)->bytes:self.dev.write(self.ep_out.bEndpointAddress,cmd,timeout=2000)returnself.dev.read(self.ep_in.bEndpointAddress,256,timeout=2000).tobytes()deftest_led_on(self):resp=self.send_command(b"LED ON\n")assertb"OK"inresp,"LED ON failed"deftest_temperature(self):resp=self.send_command(b"TEMP?\n")temp=float(resp.strip())assert20<=temp<=30,f"Invalid temperature:{temp}"

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

七、PyUSB 与其他库的对比

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

结语：让 Python 成为你的 USB 开发利器

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

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

1. 先枚举，再操作；
2. 及时释放内核驱动；
3. 设置合理超时；
4. 异常处理全覆盖。

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