我要评论引言：为什么需要 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）。安装命令如下：
pip install pyusb
注意：pyusb 本身不包含后端实现，需额外安装支持库。
2.2 后端选择与配置
pyusb 支持三种主流后端：
| 后端 | 适用系统 | 安装方式 |
|---|---|---|
| libusb1 | linux / macos / windows | sudo apt install libusb-1.0-0-dev (linux) 或 libusb.org 下载 windows dll |
| libusb0 | 旧版 linux / windows | 已基本淘汰，不推荐 |
| openusb | solaris | 极少使用 |
推荐使用 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.rules
sudo udevadm control --reload-rules && sudo udevadm trigger
三、pyusb 核心 api 详解
pyusb 的设计哲学是“简单即强大”。其核心模块为 usb.core 和 usb.util。
3.1 枚举与查找设备
使用 usb.core.find() 查找设备：
import usb.core
import 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 == 0x1234 and dev.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)}")
# 打印所有配置
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 & 0x80 else 'out'}), type: {ep.bmattributes & 0x03}")
注意：字符串描述符需通过 usb.util.get_string() 解码，直接访问 dev.iproduct 返回的是索引。
3.3 声明接口与释放内核驱动
在 linux/macos 上，若设备已被系统驱动占用（如 hid 键盘被内核接管），需先 分离内核驱动：
if dev.is_kernel_driver_active(0): # 接口0
dev.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=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：端点最大包长，可作为读缓冲区大小。
四、实战案例：与自定义 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 编写通信脚本
import usb.core
import usb.util
import 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
)
if not ep_out or not 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: 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 功能。例如，验证设备在不同命令下的响应：
class usbdevicetester:
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 协议细节 | 自定义设备、协议开发 |
| pyserial | 简单易用 | 仅限 cdc/串口设备 | arduino、esp32 通信 |
hidapi（via hid） | 专为 hid 优化 | 仅支持 hid 类 | 键盘、游戏手柄 |
| libusb-py | 更底层 | 已停止维护 | 不推荐 |
结论：pyusb 是通用 usb 通信的首选。
结语：让 python 成为你的 usb 开发利器
pyusb 以极简的 api 封装了复杂的 usb 通信细节，使 python 开发者能够轻松进入硬件交互领域。无论是快速原型验证、自动化测试，还是构建跨平台的设备管理工具，pyusb 都提供了强大而可靠的支持。
然而，能力越大，责任越大。直接操作 usb 设备意味着你需要理解端点、传输类型、描述符等概念，并谨慎处理权限与资源释放。建议在开发中始终遵循：
- 先枚举，再操作；
- 及时释放内核驱动；
- 设置合理超时；
- 异常处理全覆盖。
最后，记住：最好的 usb 代码，是那些即使设备拔掉也不会崩溃的代码。
到此这篇关于深入解析python如何利用pyusb轻松操控usb设备的文章就介绍到这了,更多相关python pyusb控制usb设备内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网！
发表评论