企业官网建设流程全解析

OpenPuck是一款运行在 NRF52840 Pro Micro 上的开源固件，它模仿 Steam Controller 2 的 Puck 无线接收器，并额外提供 Xbox 和 Switch 等模式。在 Linux 上使用它的 WebUSB 配置面板时，一个高频问题就是：设备明明选对了，面板却提示Disconnected（已断开）。别急——这几乎总是WebUSB 权限问题导致的，按本文 3 步即可修复。

为什么 Linux 下会显示 Disconnected？

在 Windows 上，浏览器可以直接打开 USB 设备；但 Linux 出于安全考虑，默认不允许普通用户访问原始 USB 设备（raw USB）。

OpenPuck 通过 WebUSB 提供配置面板（切换模式、映射背键、升级固件都靠它），浏览器需要直接读取/dev/bus/usb/下的设备节点。如果你的用户不在对应的访问组里，浏览器一打开设备就会被系统拒绝，前端表现就是选择正确设备后仍然显示 "disconnected"。

💡 记住这个判断标准：Windows 正常、Linux 报 Disconnected → 90% 是权限问题，不是固件坏了。

修复步骤 1：查看浏览器设备日志，确认是权限错误

修复前先"验伤"，避免改错方向：

1. 在 Chrome / Chromium / Edge 地址栏输入chrome://device-log/（Chromium 用chromium://device-log，Edge 用edge://device-log）。
2. 重新在配置面板里选择一次 OpenPuck 设备。
3. 观察日志输出。

如果看到下面这条错误，就确认是权限问题：

Failed to open /dev/bus/usb/xxx/xxx: Operation not permitted

看到Operation not permitted就可以放心继续，按下面两步授权即可。

修复步骤 2：创建 udev 规则文件，放行 OpenPuck 的 USB Vendor ID

udev 规则按USB Vendor ID匹配设备。OpenPuck 在不同模式下会以不同厂商身份枚举（Steam 模式是 Valve 的 ID，Xbox 模式是 Microsoft 的 ID，Switch 模式是 Nintendo 的 ID……），所以规则要覆盖它枚举过的所有 Vendor ID。

各模式对应的 Vendor ID 参考表：

操作步骤：

1. 以 root 身份创建规则文件/etc/udev/rules.d/50-openpuck.rules。
2. 将 docs/WEBUSB_LINUX.md 中的规则内容写入该文件，大致形如：

SUBSYSTEM=="usb", ATTR{idVendor}=="28de", MODE="0664", GROUP="plugdev" SUBSYSTEM=="usb", ATTR{idVendor}=="045e", MODE="0664", GROUP="plugdev" SUBSYSTEM=="usb", ATTR{idVendor}=="057e", MODE="0664", GROUP="plugdev" # ……其余模式对应行，完整清单以官方文档为准

3. 保存退出。

✂️ 如果你只用 Steam / Lizard 模式，只保留28de（Valve）那一行就够了；其余规则是为各模拟模式准备的，因为 USB 身份会随模式切换而变化。

修复步骤 3：把当前用户加入 plugdev 组并重新加载规则

规则文件只是声明"plugdev 组的成员可以访问"，还需要两件事让它生效：

1. 把当前用户加入plugdev组

sudo usermod -a -G plugdev $USER

2. 重新加载 udev 规则（或直接重启）

sudo udevadm control --reload-rules

3. 拔下再插上 OpenPuck

重新插拔后，浏览器应就能在Steam Controller 模式下正常连接面板了。此时状态从 Disconnected 变为已连接，即可开始切换模式、调整背键映射等操作。

⚠️ 特殊情况：Chromium 是通过 Snap 安装的

如果你用 Snap 方式安装了 Chromium，它还有一层独立的应用沙箱权限，需要额外放行 raw-usb：

snap connect chromium:raw-usb

完成后再按上面流程重插设备即可。

修复没生效？按这份清单自查

相关文档与模块速查

总结

Linux 下 OpenPuck 面板显示Disconnected的三步修复流程：

1. 验证：chrome://device-log/中确认Operation not permitted，锁定为权限问题；
2. 授权：创建/etc/udev/rules.d/50-openpuck.rules，放行 OpenPuck 各模式的 Vendor ID；
3. 生效：sudo usermod -a -G plugdev $USER+sudo udevadm control --reload-rules，Snap 版 Chromium 补一句snap connect chromium:raw-usb，重插设备收工。

完成后，你就可以在 WebUSB 面板里自由切换 Steam / Xbox / Switch 等模式了。🎮