1. 为什么你需要pyusb？一个真实的故事

几年前，我接手了一个智能硬件项目，需要从一台定制的人脸识别门禁机上读取数据。这玩意儿通过USB连接，厂家只给了一个C语言的SDK。我的任务是用Python写一个后台服务，定时去拉取记录。一开始我想，这还不简单？找个串口库或者用pyserial呗。结果一接上电脑傻眼了，设备管理器里它压根儿不是COM口，而是一个“通用USB设备”。用厂家提供的测试工具能通信，但换成Python，连门都摸不着。

那段时间我几乎翻遍了所有论坛，试过用ctypes硬调那个晦涩的C库，也试过一些封装不完整的第三方包，过程极其痛苦。直到我发现了pyusb。它不是什么新潮的框架，而是Python社区里一个老牌的、对底层libusb库的封装。简单来说，libusb是一个跨平台的、用户态的USB设备访问库，它让你不用写内核驱动就能和USB设备“对话”。而pyusb就是它在Python世界里的“翻译官”。

如果你也遇到过以下情况，那这篇文章就是为你写的：

• 你的USB设备（比如特定的传感器、开发板、工业控制器）在电脑上不显示为串口或磁盘。
• 你需要用Python脚本自动化地和USB设备交换数据，而不是依赖厂商的GUI工具。
• 你的项目需要在Windows开发机和Linux生产服务器上都能运行。

pyusb能帮你直接与设备的**端点（Endpoint）**通信，发送控制指令，读写批量数据。听起来很底层？别怕，我会带你从环境配置这个最“坑”的起点开始，用最直白的方式，搞定Windows和Linux两大平台，最后让你亲手写代码和你的USB设备打个招呼。

2. 跨平台配置：绕开“没有可用后端”这个大坑

几乎所有新手用pyusb跑第一个例子时，都会迎面撞上这个错误：usb.core.NoBackendError: No backend available。这就像你买了一台最新款的游戏主机，却发现没配电源线。pyusb本身只是个“外壳”，它需要依赖一个叫做后端（Backend） 的实体来干活，这个实体就是libusb库。

所以，我们的第一步不是写代码，而是给你的操作系统“配电源线”。Windows和Linux的配法完全不同，这也是跨平台开发第一个要克服的障碍。

2.1 Windows下的“傻瓜式”部署

Windows系统没有自带libusb，我们需要手动把它请进来。我强烈推荐下面这种方法，比修改环境变量更稳。

第一步：安装pyusb 打开你的命令行（CMD或PowerShell），用pip安装，这步很简单。

pip install pyusb

第二步：获取libusb后端库 你需要一个动态链接库文件：libusb-1.0.dll。最靠谱的来源是官方的Windows预编译包。

1. 访问 libusb 官网的下载页面（搜索“libusb releases github”就能找到）。
2. 找到最新版本，下载名字里带 windows.7z 或 msvc 的压缩包，比如 libusb-1.0.XX-windows.7z。
3. 解压后，你会看到一堆文件夹。我们需要的是 MS64\dll\libusb-1.0.dll（如果你的系统是64位，绝大多数情况都是）。

第三步：放置DLL文件的“黄金位置” 把找到的 libusb-1.0.dll 文件复制到哪里？有三种选择，我按推荐顺序排列：

1. 放到你的项目目录里（推荐给初学者/单项目）：在你的Python脚本旁边，新建一个叫 lib 的文件夹，把DLL放进去。这样做的好处是项目完全自包含，拷贝到任何Windows电脑都能跑，不污染系统。我们待会儿的代码示例就用这种方式。
2. 放到Python解释器的根目录下：就是和 python.exe 同一个文件夹。这样，这台电脑上所有用这个Python环境的项目都能共享这个后端。
3. 放到系统目录（传统方法，但需要管理员权限）：复制到 C:\Windows\System32\。这是最全局的方式，但我不太推荐，因为可能需要管理员权限，而且容易引起版本冲突。

注意：一定要匹配你的Python位数。如果你用64位的Python，就一定要用 MS64 下的DLL；如果用32位Python，则用 MS32 下的。混用会导致程序崩溃。

2.2 Linux下的“一行命令”搞定

Linux配置起来就友好多了，因为libusb通常就在软件源里。打开你的终端。

对于Debian/Ubuntu及其衍生系统：

sudo apt update
sudo apt install libusb-1.0-0-dev

这个 -dev 版本非常重要，它包含了编译和链接所需的头文件和库文件，而不仅仅是运行时库。

对于RHEL/CentOS/Fedora系统：

# CentOS/RHEL 7/8
sudo yum install libusb1-devel
# 或者用dnf（新版本）
sudo dnf install libusbx-devel

# Fedora
sudo dnf install libusb-devel

安装完成后，系统就已经准备好了后端，pyusb会自动发现它，不需要像Windows那样指定路径。这是Linux作为服务器环境的一个便利之处。

2.3 验证后端是否配置成功：一个万能测试脚本

环境配好了没？别猜，写个脚本测一下。创建一个 test_backend.py 文件，输入以下代码：

import usb.core
import usb.backend.libusb1

# 尝试自动发现后端（Linux下通常这样就行）
try:
    backend = usb.backend.libusb1.get_backend()
    print(f"✅ 后端自动加载成功: {backend}")
except Exception as e:
    print(f"❌ 自动加载失败: {e}")
    # 尝试手动指定路径（Windows常用方式）
    # 假设DLL放在项目./lib/目录下
    try:
        backend = usb.backend.libusb1.get_backend(find_library=lambda x: "./lib/libusb-1.0.dll")
        print(f"✅ 通过手动指定路径加载后端成功: {backend}")
    except Exception as e2:
        print(f"❌ 手动加载也失败了: {e2}")
        print("请检查libusb-1.0.dll文件是否存在且路径正确。")

# 尝试列出所有USB设备（终极测试）
try:
    devices = usb.core.find(find_all=True)
    device_list = list(devices)
    print(f"\n🔍 系统中共发现 {len(device_list)} 个USB设备。")
    if device_list:
        print("前几个设备信息如下：")
        for dev in device_list[:3]: # 只打印前三个，避免刷屏
            print(f"  - {dev}")
except Exception as e:
    print(f"\n⚠️  设备枚举测试失败，后端可能仍有问题: {e}")

在Windows上，如果你把DLL放在项目./lib/下，运行这个脚本。在Linux上，直接运行。如果能看到“后端加载成功”并列出一些设备（比如你的键盘、鼠标），那么恭喜你，最艰难的一关已经过了！

3. 实战第一步：找到你的设备，和它建立连接

现在环境通了，我们来玩真的。和USB设备打交道的第一步永远是识别和寻址。USB世界不像网络有IP地址，它靠两个ID来认人：供应商ID（idVendor） 和产品ID（idProduct）。这两个ID通常都是十六进制数。

怎么获取这两个ID呢？有几种方法：

• 看产品说明书或厂商官网：这是最正规的途径。
• 在Linux下用 lsusb 命令：插上设备，在终端输入 lsusb，你会看到类似 Bus 002 Device 003: ID 1234:5678 My Device Corp. 的输出，这里的 1234:5678 就是 idVendor:idProduct。
• 在Windows设备管理器中查看：找到设备，右键“属性” -> “详细信息” -> “硬件Id”，你会看到类似 USB\VID_1234&PID_5678 的字符串。

假设我们有一个ESP32-S2开发板，它的ID是 idVendor=0x303a, idProduct=0x0002。让我们写代码找到它。

import usb.core
import usb.backend.libusb1

# 1. 准备后端（Windows需要指定路径，Linux通常不需要）
# 这里演示Windows项目内携带DLL的方式，Linux用户可以注释掉backend参数
backend = usb.backend.libusb1.get_backend(find_library=lambda x: "./lib/libusb-1.0.dll")

# 2. 使用find函数精准定位设备
# 传入vendor id和product id
device = usb.core.find(backend=backend, idVendor=0x303a, idProduct=0x0002)

# 3. 判断是否找到
if device is None:
    print("❌ 未找到指定的USB设备。请检查：")
    print("   - 设备是否已连接？")
    print("   - Vendor ID和Product ID是否正确？")
    print("   - 驱动程序是否正常？（对于某些设备，可能需要安装特定的驱动或使用zadig工具替换驱动为libusb）")
else:
    print(f"✅ 成功找到设备！")
    print(f"   设备对象: {device}")
    # 打印一些基础信息
    print(f"   厂商ID (idVendor): 0x{device.idVendor:04x}")
    print(f"   产品ID (idProduct): 0x{device.idProduct:04x}")
    print(f"   总线地址: Bus {device.bus} Address {device.address}")
    print(f"   设备速度: {device.speed}")

运行这段代码，如果成功，你会看到一串设备描述符信息。这一步的device对象，就是你后续所有操作的“手柄”。

踩坑提示：在Windows上，某些设备（特别是那些需要专属驱动的）默认会被系统驱动占用。pyusb是无法访问被其他驱动“锁住”的设备的。这时候你需要一个叫 Zadig 的工具，把设备驱动替换成 libusb-win32 或 libusbK。这是一个关键步骤，很多人在Windows上卡住就是因为这个。

4. 深入核心：理解配置、接口与端点通信模型

找到设备只是握了个手，真正要办事，你得理解USB的通信模型。别被吓到，我们可以把它想象成一个公司：

• 设备（Device）：就是整个公司。
• 配置（Configuration）：公司可能有不同的运营模式（比如省电模式、高性能模式）。一个设备一次只能激活一种配置。
• 接口（Interface）：公司里的不同部门（比如销售部、技术部）。一个配置下可以有多个接口。
• 端点（Endpoint）：部门里的具体沟通渠道（比如技术部的技术支持电话、销售部的订单传真）。端点是数据实际进出的地方，每个端点都有一个地址和方向（输入IN/输出OUT）。

对我们编程来说，最常打交道的就是端点。USB有四种传输类型，对应不同的端点：

• 控制传输（Control Transfer）：用于发送配置、查询等关键指令。每个设备都有一个默认的控制端点（地址0）。
• 批量传输（Bulk Transfer）：用于传输大量、对时间不敏感但要求准确的数据，比如U盘读写。
• 中断传输（Interrupt Transfer）：用于传输小量、需要及时响应的数据，比如键盘按键。
• 同步传输（Isochronous Transfer）：用于传输实时性要求高的流数据，比如摄像头视频，允许一定的数据错误。

让我们看看如何用代码探索这个“公司结构”，并做好通信准备：

# 承接上一节，假设device已经成功找到

# 1. 设置设备配置（通常使用默认的第一个配置）
try:
    device.set_configuration()
    print("✅ 设备配置已设置。")
except usb.core.USBError as e:
    print(f"⚠️  设置配置时出错（可能已设置）: {e}")

# 2. 获取当前激活的配置
cfg = device.get_active_configuration()
print(f"\n📄 当前激活的配置索引: {cfg.bConfigurationValue}")

# 3. 遍历配置下的所有接口
interface_number = 0 # 我们通常使用第一个接口
print(f"\n🔧 正在检查接口 {interface_number}...")
try:
    intf = cfg[(interface_number, 0)] # (接口号， 备用设置号)
    print(f"   接口 {interface_number} 已找到。")
except KeyError:
    print(f"   接口 {interface_number} 不存在。")
    exit()

# 4. 声明内核驱动分离（在Linux上非常重要！）
# 这一步是告诉操作系统：“这个设备现在归我的程序管，你别插手。”
try:
    if device.is_kernel_driver_active(interface_number):
        print(f"   检测到内核驱动占用接口 {interface_number}，正在分离...")
        device.detach_kernel_driver(interface_number)
        print("   分离成功。")
except (NotImplementedError, usb.core.USBError) as e:
    # Windows上没有此概念，会抛出NotImplementedError，忽略即可
    print(f"   内核驱动分离步骤跳过（{e}）。")

# 5. 声明我们要使用这个接口
try:
    usb.util.claim_interface(device, interface_number)
    print(f"   已成功声明占用接口 {interface_number}。")
except usb.core.USBError as e:
    print(f"❌ 声明接口失败: {e}")
    print("   可能是程序没有权限，或者接口已被其他程序占用。")

# 6. 探索该接口下的所有端点
print(f"\n📡 接口 {interface_number} 下的端点信息：")
for endpoint in intf:
    print(f"   端点地址: 0x{endpoint.bEndpointAddress:02x}", end=" ")
    # 判断方向：最高位为1是IN（设备到主机），0是OUT（主机到设备）
    direction = "IN" if usb.util.endpoint_direction(endpoint.bEndpointAddress) == usb.util.ENDPOINT_IN else "OUT"
    print(f"  方向: {direction}", end=" ")
    # 判断传输类型
    attr = endpoint.bmAttributes
    transfer_type = attr & 0x03
    type_map = {0: "控制", 1: "同步", 2: "批量", 3: "中断"}
    print(f"  类型: {type_map.get(transfer_type, '未知')}", end=" ")
    print(f"  最大包大小: {endpoint.wMaxPacketSize}")

这段代码运行后，你就摸清了设备内部的结构，并且为后续的数据通信铺平了道路。特别是声明接口这一步，是避免“资源被占用”错误的关键。

5. 数据收发实战：与端点对话的完整示例

理论说再多，不如动手发条指令。我们假设要和设备进行简单的批量传输（Bulk Transfer）。你需要根据你的设备手册，找到正确的端点地址和数据格式。这里我以一个虚拟的“回声”设备为例，我们向一个OUT端点发送数据，然后从一个IN端点读取回复。

# 承接上文，假设我们已经声明了接口，并且知道了端点地址
# 假设：
#   - 批量OUT端点地址: 0x01 (用于发送数据)
#   - 批量IN端点地址: 0x81 (用于接收数据) - 注意最高位是1，表示IN端点

out_endpoint_addr = 0x01
in_endpoint_addr = 0x81

# 要发送的数据，比如一个简单的命令报文
# 这里示例：发送字符串 "HelloUSB" 的字节形式
data_to_send = b'HelloUSB'
print(f"📤 准备发送数据: {data_to_send}")

try:
    # 1. 写入数据到OUT端点
    # write方法返回实际写入的字节数
    bytes_written = device.write(out_endpoint_addr, data_to_send, timeout=1000) # 超时设为1000毫秒
    print(f"✅ 数据发送成功，发送字节数: {bytes_written}")

    # 2. 从IN端点读取数据
    # 先尝试读取，指定一个预期的最大长度，比如64字节
    read_size = 64
    data_received = device.read(in_endpoint_addr, read_size, timeout=1000)
    print(f"📥 数据接收成功，接收字节数: {len(data_received)}")
    print(f"   原始字节数据: {data_received}")
    # 尝试解码为字符串（如果是文本的话）
    try:
        print(f"   解码为字符串: {data_received.decode('utf-8', errors='ignore')}")
    except:
        pass

except usb.core.USBError as e:
    print(f"❌ USB通信出错: {e}")
    # 常见的错误有超时（设备没响应）、管道错误（端点不对）等
    if e.errno == 110: # 操作超时
        print("   错误原因：操作超时，设备未在规定时间内响应。")
    elif e.errno == 32: # 管道错误
        print("   错误原因：管道错误，可能是端点地址不正确或设备状态异常。")
finally:
    # 6. 通信完毕，释放接口（非常重要！）
    print("\n🧹 通信结束，清理资源...")
    try:
        usb.util.release_interface(device, interface_number)
        print("   接口已释放。")
        # 如果是Linux，可以重新附着内核驱动（如果需要）
        # device.attach_kernel_driver(interface_number)
    except usb.core.USBError as e:
        print(f"   释放接口时出错: {e}")

这个例子展示了最基本的读写流程。实际项目中，数据格式可能是复杂的二进制结构，你需要用Python的 struct 模块来打包和解包。超时参数 timeout 也至关重要，设得太短容易误判设备无响应，设得太长程序会假死，需要根据设备特性调整。

6. 进阶技巧与跨平台调试心得

搞定了基础通信，你可能会遇到更复杂的需求。这里分享几个我踩过坑才总结出来的经验。

处理控制传输（Control Transfer）：很多设备的初始化、查询状态命令是通过控制端点（地址0）发送的。pyusb提供了 ctrl_transfer 方法，参数比较多：

# ctrl_transfer(bmRequestType, bRequest, wValue, wIndex, 数据 或 长度)
# 例如：发送一个获取设备描述符的请求（这是一个标准USB请求）
# bmRequestType: 0x80 表示方向是IN，类型是标准，接收者是设备
# bRequest: 0x06 是GET_DESCRIPTOR请求
# wValue: 高位是描述符类型（0x01设备描述符），低位是索引0
# wIndex: 语言ID，通常为0
# 最后是期望返回的数据长度（这里是18字节）
descriptor = device.ctrl_transfer(0x80, 0x06, 0x0100, 0, 18)
print(f"设备描述符: {descriptor}")

解读这些参数需要查阅USB协议规范或你的设备手册，这是最考验功底的地方。

跨平台路径处理的技巧：为了让代码在Windows和Linux上都能无缝运行，我们可以写一个智能的后端加载函数。

import sys
import os

def get_usb_backend():
    """智能获取USB后端，跨平台兼容"""
    backend = None
    try:
        # 首先尝试让pyusb自动发现（在Linux上通常成功）
        backend = usb.backend.libusb1.get_backend()
    except:
        pass

    if backend is None:
        # 自动发现失败，尝试手动加载
        lib_path = None
        if sys.platform == "win32":
            # Windows: 假设dll在项目根目录的lib子文件夹下
            lib_path = "./lib/libusb-1.0.dll"
            # 更健壮的做法：可以遍历几个可能的位置
            possible_paths = ["./lib/libusb-1.0.dll",
                              "./lib/libusb-1.0/libusb-1.0.dll"]
            for path in possible_paths:
                if os.path.exists(path):
                    lib_path = path
                    break
        elif sys.platform.startswith("linux"):
            # Linux: 库文件通常叫 libusb-1.0.so.0 或 .so.1
            # 可以尝试常见路径，或者让系统查找
            lib_path = "libusb-1.0.so.0"
        # 对于macOS，可能是 "libusb-1.0.0.dylib"

        if lib_path and os.path.exists(lib_path):
            print(f"🔧 正在从指定路径加载后端: {lib_path}")
            try:
                backend = usb.backend.libusb1.get_backend(find_library=lambda x: lib_path)
            except Exception as e:
                print(f"❌ 从指定路径加载失败: {e}")
        else:
            print("⚠️  未找到可用的libusb后端库文件。")
    return backend

# 在代码中使用
backend = get_usb_backend()
if backend:
    device = usb.core.find(backend=backend, ...)
else:
    print("无法初始化USB后端，请检查环境配置。")

调试是重中之重：USB通信黑盒性很强，一定要善用工具。

• Linux下的 lsusb -v：这个命令能打印出设备极其详尽的描述符信息，是所有端点和接口的“地图”，写代码前一定要看。
• Windows下的USB设备树查看器：可以用官方工具或第三方软件查看设备详情和占用情况。
• 逻辑分析仪或USB协议分析仪：如果条件允许，这是终极调试利器，能直接看到总线上传输的每一个数据包，帮你验证程序发出的数据是否正确。
• 在代码中大量使用 try...except 并打印具体的 usb.core.USBError：根据错误码（e.errno）去查libusb的错误含义，能快速定位是权限问题、超时问题还是协议问题。

最后，记得资源管理。像打开文件一样，claim_interface 之后，一定要在 finally 块里或者使用上下文管理器（如果pyusb支持的话）确保 release_interface 被调用。否则，设备可能会被锁住，需要重新插拔才能恢复。

配置pyusb环境就像给一把精密的锁配钥匙，过程可能有点繁琐，但一旦配好，你就获得了一种直接与硬件对话的强大能力。从简单的数据采集到复杂的设备控制，这套工具链都能胜任。我自己的那个人脸识别门禁项目，最后就是用pyusb稳定跑了两年多，期间还迁移过服务器。遇到问题别慌，多查设备手册，多看看libusb和pyusb的官方文档，社区的积累比你想象的要多。