解决Raspberry Pi Zero 2 W USB Gadget的BrokenPipeError错误

先确认基础权限与设备路径 #

• 必须用sudo运行脚本，HID设备需要root权限才能写入，普通用户会触发权限问题间接导致传输端点关闭。
• 直接复用旧脚本里的HID设备路径（比如/dev/hidg0），新脚本如果写错路径，会直接导致连接失败。

检查键值映射与HID报告格式 #

• 对比旧脚本的手动按键逻辑，确保keys.json里的映射是USB HID扫描码（比如a对应0x04，b对应0x05），而不是ASCII码。如果用了ASCII码，写入的无效数据会导致设备端点断开。
• 严格遵循HID报告格式：Bad USB的标准报告是8字节，按下按键时发送[0, 扫描码, 0, 0, 0, 0, 0, 0]，松开时必须发送全0的报告。新脚本如果漏了松开动作，或者报告格式错误，会触发设备异常。

代码层面的具体修复 #

• 打开HID设备时用二进制写入模式wb，不要用文本模式w，避免自动转义破坏报告结构：

  hid_device = open('/dev/hidg0', 'wb')
  

• 增加异常处理与设备重连逻辑，同时确保脚本结束时正确关闭设备：

  import time
  
  def send_key(scan_code):
      try:
          # 发送按下指令
          hid_device.write(b'\x00' + bytes([scan_code]) + b'\x00\x00\x00\x00\x00\x00')
          time.sleep(0.05)
          # 发送松开指令
          hid_device.write(b'\x00\x00\x00\x00\x00\x00\x00\x00')
          time.sleep(0.05)
      except BrokenPipeError:
          # 重连设备
          global hid_device
          hid_device.close()
          hid_device = open('/dev/hidg0', 'wb')
          send_key(scan_code)  # 重试发送
  
  # 初始化设备
  hid_device = open('/dev/hidg0', 'wb')
  
  # 读取ExText.txt和keys.json的逻辑...
  # 假设解析后得到key_code，调用send_key(key_code)
  
  # 脚本结束时关闭设备
  hid_device.close()
  

验证键值映射的准确性 #

• 把新脚本从keys.json解析出的键值，和旧脚本里手动写的扫描码逐一对比，确保完全匹配。如果是ASCII码，要提前转成对应的HID扫描码。

内容的提问来源于stack exchange，提问作者Thatoneham