简介这是一份面向嵌入式开发与Python自动化测试初学者的跨平台HID设备控制脚本集解决LinuxUbuntu和Windows环境下Python直接读写USB HID设备的实操难题。资源包含4个文件3个Python脚本1份说明文档总大小仅4KB轻量易集成核心脚本分别适配Ubuntu基于pyusbsudo权限与Windows基于pywinusb另含屏幕点击模拟示例及详细环境配置指引覆盖Python2.7Ubuntu与Python3.9Windows双栈验证调试完毕可直接运行。已有1525人学习下载适用于USB HID类硬件调试、自动化测试、自定义外设控制等场景。读者可快速获得开箱即用的跨平台控制能力、模块安装避坑指南、权限配置要点及典型HID通信流程实现逻辑显著降低HID底层交互的学习门槛。1. Python 控制 HID 设备不是“插上就能读”LinuxUbuntu与 Windows 双平台实操中90% 的失败源于权限、驱动和 hidapi 绑定差异你手头有一块自定义 HID 设备比如带自定义报告描述符的 USB 温湿度传感器、工业 IO 模块或加密狗想用 Python 快速验证通信——不是写驱动而是直接发 Report ID、读取输入报告、写入输出报告。但刚pip install hid就卡在 Windows 找不到设备或 Ubuntu 下PermissionError: [Errno 13] Access denied更常见的是hid.enumerate()返回空列表或device.write()后device.read()一直阻塞。这不是代码写错了而是 HID 在两个平台底层行为根本不同Windows 默认由系统 HID 类驱动接管但需绕过 WinUSB/Composite 设备枚举陷阱Ubuntu 则默认将 HID 设备挂载为/dev/hidraw*但普通用户无读写权限且libusb与hidraw后端选择直接影响 report 处理逻辑。本文不讲内核模块开发只聚焦「用标准 Python 官方支持库在 Ubuntu 22.04/24.04 和 Windows 10/11 上让同一份脚本稳定读写 HID 报告」——所有命令、配置、权限修复、设备过滤逻辑均经实测附可直接运行的例程含带 Report ID 的复合设备处理。2. 选对库是前提为什么 hidapi hid 是当前最稳的跨平台组合而非 pyusb 或 raw /dev/hidraw2.1 不选 pyusb 的三个硬伤HID 协议层缺失、Report ID 处理反直觉、Windows 驱动冲突pyusb 虽强大但它是 USB 协议栈底层封装不理解 HID 报告描述符HID Descriptor结构。这意味着你必须手动解析bInterfaceClass0x03,bInterfaceSubClass0x00/0x01再计算中断端点地址写入输出报告时需自行拼接 Report ID 字节若设备要求而 pyusb 的ctrl_transfer()或write()对 Report ID 位置无语义识别在 Windows 上pyusb 默认尝试用 libusb-win32 或 WinUSB 驱动但 HID 类设备常被系统强制绑定hidusb.sys导致usb.core.find()找到设备却无法 claim interface报错USBError: [Errno 13] Access denied (insufficient permissions)。提示pyusb适合开发 USB 自定义协议设备如 CDC ACM、Bulk-only 传输但对标准 HID 设备它把简单问题复杂化。除非你明确需要绕过 HID 协议栈做原始端点操作否则不推荐。2.2 为什么 hidapi python-hid 是双平台最优解自动后端切换、原生 Report ID 支持、权限抽象统一python-hid即hid包是hidapiC 库的 Python 绑定其核心优势在于自动后端选择在 Linux 下默认使用hidraw内核 HID 子系统暴露的字符设备在 Windows 下使用windows后端调用hid.dllAPI无需用户干预Report ID 透明处理device.write(data)会自动在data前插入 Report ID若设备描述符声明了非零 Report IDdevice.read(size)返回的数据也已剥离 Report ID 字节权限模型抽象Linux 下通过 udev 规则赋予/dev/hidraw*访问权Windows 下依赖系统 HID 驱动规避了 libusb 的驱动替换风险。验证安装是否成功# Ubuntu 终端执行确保已安装 libhidapi-libusb0 $ python3 -c import hid; print(hid.enumerate()) # 若返回空列表说明未找到 HID 设备或权限不足见 3.1 节# Windows PowerShell 执行管理员权限非必需但首次可能需确认驱动 PS python -c import hid; print(hid.enumerate()) # 正常应返回包含 vendor_id, product_id, path 的字典列表2.3 安装命令与平台关键依赖对照表平台必装系统级依赖Python 包安装命令关键说明Ubuntu 22.04/24.04sudo apt update sudo apt install -y libhidapi-libusb0 libhidapi-hidraw0pip3 install hidlibhidapi-hidraw0提供/dev/hidraw*后端libhidapi-libusb0为备用当 hidraw 不可用时Windows 10/11无系统自带hid.dllpip install hid若报ImportError: DLL load failed需安装 Microsoft Visual C Redistributable for Visual Studio 2015-2022WSL2Ubuntu同原生 Ubuntupip3 install hid注意WSL2 无法直接访问 USB 设备必须通过 Windows 端工具如 usbipd绑定不建议用于 HID 开发注意不要使用pip install pyhid或pip install hidapi这是旧版绑定已弃用。hid包在 PyPI 上名称为hidGitHub 仓库为libusb/hidapi的官方 Python 绑定。3. LinuxUbuntu下绕过权限墙udev 规则 设备过滤让普通用户稳定读写/dev/hidraw*3.1 为什么sudo python script.py不是解决方案安全与工程实践双否定临时用sudo运行脚本看似能解决PermissionError但带来两个致命问题安全风险Python 脚本若含网络请求、文件写入或 eval提权后危害放大部署失效systemd 服务、crontab 或 GUI 应用如 Qt 程序调用 Python无法继承 sudo 权限必然失败。根本解法是通过 udev 规则将特定 VID:PID 的 HID 设备节点权限开放给plugdev组。3.2 三步定位设备并编写 udev 规则3.2.1 第一步用lsusb和hid-recorder确认 VID:PID 与接口类型插入设备执行$ lsusb -v 2/dev/null | grep -A 10 idVendor\|idProduct\|bInterfaceClass.*03找到类似输出Bus 001 Device 012: ID 04d8:003f Microchip Technology, Inc. bInterfaceClass 3 Human Interface Device bInterfaceSubClass 0 No Subclass bInterfaceProtocol 0 None此处04d8:003f即 Vendor ID 和 Product ID。3.2.2 第二步创建 udev 规则文件精准匹配 HID 接口新建/etc/udev/rules.d/99-hid-device.rules# 匹配 VID:PID 且为 HID 类接口的设备设置 MODE0664GROUPplugdev SUBSYSTEMusb, ATTRS{idVendor}04d8, ATTRS{idProduct}003f, MODE0664, GROUPplugdev # 同时匹配 hidraw 设备节点确保 /dev/hidraw* 权限同步 KERNELhidraw*, SUBSYSTEMhidraw, ATTRS{idVendor}04d8, ATTRS{idProduct}003f, MODE0664, GROUPplugdev提示ATTRS{}表示从父 USB 设备获取属性KERNELhidraw*匹配内核生成的 hidraw 节点。务必用ATTRS{idVendor}而非ENV{ID_VENDOR_ID}后者在某些 udev 版本中不可靠。3.2.3 第三步重载规则并验证权限# 重载规则并触发重新扫描 $ sudo udevadm control --reload-rules $ sudo udevadm trigger # 拔插设备检查 /dev/hidraw* 权限 $ ls -l /dev/hidraw* # 正常输出应类似crw-rw-r-- 1 root plugdev 243, 0 Jun 10 14:22 /dev/hidraw0 # 将当前用户加入 plugdev 组需重新登录生效 $ sudo usermod -a -G plugdev $USER3.3 Python 脚本中设备过滤避免枚举到键盘鼠标等系统 HID 设备hid.enumerate()返回所有 HID 设备包括你的目标设备、键盘、鼠标、触摸板。必须按 VID:PID 过滤import hid def find_my_device(vid0x04d8, pid0x003f): devices hid.enumerate(vid, pid) if not devices: raise RuntimeError(fNo HID device found with VID:0x{vid:04x} PID:0x{pid:04x}) # 优先选择第一个通常只有一个或按 serial_number 进一步筛选 return devices[0] # 使用 info find_my_device() print(fFound device: {info[manufacturer_string]} {info[product_string]}) device hid.Device(pathinfo[path]) # 显式传入 path避免自动匹配歧义注意hid.Device(vid, pid)构造方式在多设备同 VID:PID 时不可靠强烈推荐用path初始化确保连接唯一性。4. Windows 下突破“设备未就绪”与“Access is denied”驱动状态检查、Report ID 强制模式与超时控制4.1 Windows 设备管理器中的三个关键状态如何判断 HID 驱动是否真正加载在 Windows 中即使设备物理连接正常hid.enumerate()仍可能返回空列表。必须人工验证打开「设备管理器」→ 展开「人体学输入设备」或「通用串行总线设备」找到你的设备右键 → 「属性」→ 「详细信息」→ 选择「硬件 Ids」确认存在HID\VID_04D8PID_003F格式 ID注意大小写不敏感关键检查切换到「驱动程序」选项卡 → 「驱动程序详细信息」确认.sys文件为hidusb.sys标准 HID 驱动或winusb.sys若你主动替换了驱动若显示「此设备运转正常」但 Python 仍找不到大概率是设备被系统识别为「复合设备」Composite Device其 HID 接口隐藏在USB\VID_XXXXPID_YYYYMI_XX下需在hid.enumerate()中指定interface_number。4.2 复合设备Composite Device的 interface_number 识别与指定许多 HID 设备如带 HIDMSC 的 U 盘、带 HIDCDC 的调试器将多个功能集成在一个 USB 设备中。此时hid.enumerate()默认只返回主接口需显式指定interface_number# 先枚举所有接口包括非 HID all_devices hid.enumerate() for d in all_devices: print(fPath: {d[path]}, VID:PID: {d[vendor_id]:04x}:{d[product_id]:04x}, fInterface: {d.get(interface_number, N/A)}) # 假设你的 HID 功能在 interface_number1则 devices hid.enumerate(0x04d8, 0x003f, interface_number1) if devices: device hid.Device(pathdevices[0][path])提示interface_number从 0 开始计数HID 接口通常为 0 或 1。若不确定用USBViewWindows SDK 工具或lsusb -vLinux查看bInterfaceNumber字段。4.3 Windows 下 write/read 超时与 Report ID 强制模式解决“卡死”和“数据错位”Windows HID 驱动默认 read 超时为无限等待若设备未响应device.read(64)将永久阻塞。必须显式设置import time device hid.Device(pathinfo[path]) device.set_nonblocking(True) # 启用非阻塞模式推荐 # 或者用带超时的 readhid 1.0.4 支持 try: data device.read(64, timeout_ms1000) # 1秒超时 except OSError as e: if Timeout in str(e): print(Read timeout, device may not respond) raise # 强制 Report ID 模式当设备描述符未正确声明 Report ID 时 # 发送数据前手动在 data 前插入 Report ID 字节如 Report ID 1 report_id 1 payload bytes([report_id]) b\x00\x01\x02 # 示例Report ID 3字节数据 device.write(payload)注意set_nonblocking(True)是最简方案read()将立即返回[]空列表而非阻塞。业务逻辑需自行处理空读。5. 实战一个跨平台 HID 读写例程支持 Report ID、自动重连、错误分类与日志5.1 完整可运行脚本hid_control.py#!/usr/bin/env python3 # -*- coding: utf-8 -*- 跨平台 HID 控制脚本Ubuntu Windows 支持自动 VID:PID 过滤、Report ID 处理、超时控制、断线重连 用法python hid_control.py --vid 0x04d8 --pid 0x003f --read --write 010203 import sys import time import argparse import logging from typing import Optional, List, Union try: import hid except ImportError: print(Error: hid package not installed. Run pip install hid) sys.exit(1) # 配置日志 logging.basicConfig(levellogging.INFO, format%(asctime)s - %(levelname)s - %(message)s) logger logging.getLogger(__name__) class HIDController: def __init__(self, vid: int, pid: int, interface_number: Optional[int] None): self.vid vid self.pid pid self.interface_number interface_number self.device: Optional[hid.Device] None self._reconnect_delay 1.0 # 秒 def connect(self) - bool: 连接设备失败时返回 False try: devices hid.enumerate(self.vid, self.pid) if self.interface_number is not None: devices [d for d in devices if d.get(interface_number) self.interface_number] if not devices: logger.warning(fNo device found with VID:0x{self.vid:04x} PID:0x{self.pid:04x}) return False # 优先选择第一个按 serial 排序更稳如有 devices.sort(keylambda x: x.get(serial_number, )) info devices[0] self.device hid.Device(pathinfo[path]) self.device.set_nonblocking(True) logger.info(fConnected to {info[manufacturer_string]} {info[product_string]} f(Serial: {info.get(serial_number, N/A)})) return True except Exception as e: logger.error(fConnect failed: {e}) return False def disconnect(self): 安全断开 if self.device: try: self.device.close() except: pass self.device None def write_report(self, data: Union[bytes, List[int]], report_id: int 0) - bool: 写入报告自动处理 Report ID if not self.device: logger.error(Not connected. Call connect() first.) return False if isinstance(data, list): data bytes(data) if report_id ! 0: data bytes([report_id]) data try: written self.device.write(data) logger.debug(fWrote {written} bytes: {data.hex()}) return True except Exception as e: logger.error(fWrite failed: {e}) return False def read_report(self, size: int 64, timeout_ms: int 1000) - Optional[bytes]: 读取报告带超时 if not self.device: return None try: # hid 1.0.4 支持 timeout_ms 参数 data self.device.read(size, timeout_mstimeout_ms) if data: logger.debug(fRead {len(data)} bytes: {bytes(data).hex()}) return bytes(data) else: logger.debug(Read returned empty (non-blocking)) return None except Exception as e: logger.error(fRead failed: {e}) return None def run_cycle(self, read_size: int 64, write_data: Optional[str] None, report_id: int 0, max_retries: int 3): 主循环连接 → 写可选→ 读可选→ 断开 retries 0 while retries max_retries: if not self.connect(): retries 1 logger.warning(fConnection attempt {retries}/{max_retries}, retrying in {self._reconnect_delay}s...) time.sleep(self._reconnect_delay) continue # 写入数据 if write_data: try: hex_bytes bytes.fromhex(write_data) self.write_report(hex_bytes, report_idreport_id) except ValueError: logger.error(fInvalid hex string: {write_data}) return # 读取响应 if read_size 0: response self.read_report(sizeread_size, timeout_ms500) if response: print(fResponse: {response.hex()}) self.disconnect() return # 成功执行一次即退出 logger.error(Max retries exceeded. Exiting.) if __name__ __main__: parser argparse.ArgumentParser(descriptionCross-platform HID device controller) parser.add_argument(--vid, typestr, requiredTrue, helpVendor ID in hex (e.g., 0x04d8)) parser.add_argument(--pid, typestr, requiredTrue, helpProduct ID in hex (e.g., 0x003f)) parser.add_argument(--interface, typeint, defaultNone, helpInterface number for composite devices) parser.add_argument(--read, actionstore_true, helpRead from device) parser.add_argument(--write, typestr, defaultNone, helpHex string to write (e.g., 010203)) parser.add_argument(--report-id, typeint, default0, helpReport ID to prepend (default: 0)) parser.add_argument(--size, typeint, default64, helpRead buffer size (default: 64)) args parser.parse_args() # 解析 VID/PID try: vid int(args.vid, 0) pid int(args.pid, 0) except ValueError: logger.error(VID/PID must be hex (e.g., 0x04d8) or decimal) sys.exit(1) controller HIDController(vid, pid, interface_numberargs.interface) controller.run_cycle( read_sizeargs.size if args.read else 0, write_dataargs.write, report_idargs.report_id, max_retries3 )5.2 使用示例与典型场景验证场景 1Ubuntu 下读取 HID 输入报告如传感器数据# 假设设备 VID:PID 0x04d8:0x003f期望读取 8 字节 $ python hid_control.py --vid 0x04d8 --pid 0x003f --read --size 8 # 输出Response: 0102030405060708场景 2Windows 下发送带 Report ID 的控制指令# 发送 Report ID1 数据 0x00 0x01 到设备 PS python hid_control.py --vid 0x04d8 --pid 0x003f --write 0001 --report-id 1场景 3复合设备HIDMSC中指定 interface_number1$ python hid_control.py --vid 0x04d8 --pid 0x003f --interface 1 --read5.3 错误码快速对照表根据日志定位根本原因日志关键词可能原因解决动作No device foundLinuxudev 规则未生效Windows设备管理器中未识别为 HIDLinux 检查ls -l /dev/hidraw*Windows 检查硬件 IDsAccess deniedLinux用户未加入plugdev组Windows驱动被禁用Linux 运行sudo usermod -a -G plugdev $USERWindows 启用设备Read returned empty设备未响应、非阻塞模式下无数据、超时过短增大timeout_ms或检查设备固件是否进入休眠Write failed: ...数据长度超限HID 报告最大 64 字节、Report ID 错误查阅设备报告描述符确认最大包长与 Report ID 值6. 进阶技巧用hid-describe解析报告描述符精准匹配输入/输出报告长度与 Report ID6.1 为什么必须看报告描述符hid.enumerate()不告诉你“这个设备到底能收多长数据”hid.enumerate()只返回设备基础信息但 HID 通信成败取决于报告描述符Report Descriptor——它定义了输入报告Input Report最大字节数决定read()缓冲区大小输出报告Output Report最大字节数决定write()数据长度上限是否启用 Report ID以及每个 Report ID 对应的报告结构。若盲目read(64)而设备实际输入报告仅 8 字节多余字节将被丢弃或阻塞若write()数据超过输出报告长度设备可能静默忽略。6.2 在 Linux 下用hid-desc工具导出并解析描述符# 安装 hid-tools含 hid-desc $ sudo apt install -y hid-tools # 导出当前连接的 HID 设备描述符需设备已连接且有权限 $ sudo hid-desc /dev/hidraw0 my_device_desc.txt # 查看关键字段 $ grep -A 5 Usage Page my_device_desc.txt # 输出示例 # Usage Page (Desktop), ; Generic desktop controls (01h) # Usage (Keyboard), ; Keyboard (06h) # Collection (Application), # Report ID (1), ; ← 关键此设备使用 Report ID1 # Report Count (8), ; ← 输入报告共 8 字节 # Report Size (1), ; ← 每个字段 1 bit需结合后续逻辑6.3 报告描述符核心字段速查指南针对开发者描述符字段含义对 Python 脚本的影响Report ID (n)声明此 Collection 使用 Report ID nwrite()前必须 prepentbytes([n])read()返回数据首字节即为 nReport Count (m)当前 Report 中字段数量结合Report Size (k)可算总字节数(m * k) / 8向上取整Input/Output/Feature定义数据流向read()对应Inputwrite()对应OutputLogical Minimum/Maximum数据值范围Python 中需校验write()数据是否在此范围内避免设备拒绝提示完整解析需用hidrd工具sudo apt install hidrd或在线解析器如 USB HID Descriptor Tool 但日常调试hid-desc的文本输出已足够定位 Report ID 和字节数。至此你已掌握在 Ubuntu 与 Windows 上用 Python 稳定控制 HID 设备的全链路从库选型依据、Linux 权限固化、Windows 驱动诊断、跨平台脚本编写到报告描述符级的精准控制。下一步把hid_control.py集成进你的数据采集服务或自动化测试框架——真正的 HID 自动化始于可复现的最小可靠单元。本文还有配套的精品资源点击获取