PiKVM 的 Apple 兼容性修复(KVMD 3.14):v2/v3/OTG 进入 Boot Menu 与 Recovery Mode 不再依赖 Arduino HID

原创2026-09-23 15:34:152,301 阅读
文章标签:文档嵌入式硬件开发

PiKVM 的 Apple 兼容性修复(KVMD 3.14):v2/v3/OTG 进入 Boot Menu 与 Recovery Mode 不再依赖 Arduino HID

本指南围绕 KVMD 3.14 版本发布的核心修复展开:自该版本起,PiKVM v2/v3 及所有基于 USB OTG 的构建,在 Apple 平台上进入启动选单(Boot Menu)与恢复模式(Recovery Mode)时,不再需要额外的 Arduino HID 硬件方案;同时部分 HP、DELL 主板的键盘兼容性也获得改善。读完本文,你将了解这一修复的前因后果、受影响的设备范围与已知限制,并掌握从 testing 软件源切回稳定源、完成 PiKVM OS 更新、校验自定义内核是否就绪的完整升级流程。

背景:Apple 平台上"进不去引导菜单"的历史难题

在 PiKVM 的长期使用中,Apple 设备一直是 HID(键盘/鼠标模拟)兼容性的重灾区。早在 KVMD 3.8(2021-07-10)发布说明 中就已记录过"首个 Epic Apple fix":

  • 对于 Intel 架构的 Mac,此前必须借助 Arduino HID 才能进入各种启动菜单(Option 或 Cmd+R);在启动管理器(Boot Manager)中相对鼠标可以工作,在恢复模式(Recovery Mode)中相对与绝对鼠标均可用。
  • 对于 Apple M1 芯片的 Mac,则使用 PiKVM 默认的 OTG HID,修复后不再出现"请再连接一个鼠标"的荒谬提示。

由于问题隐藏在 Apple 闭源驱动的实现细节里,开发者不得不购买硬件级 USB 协议分析仪来逆向研究协议行为——这也是该系列问题修复周期较长、被冠以"史诗级"称呼的原因。KVMD 3.14 正是这一系列工作的延续,其发布说明开宗明义:"我继续清除 USB 中的陈年 bug(I continue to eliminate ancient bugs from USB)"。

KVMD 3.14 修复了什么

根据 KVMD 3.14 发布说明,本次修复包含以下要点:

  1. Apple 设备:Boot Menu / Recovery Mode 不再需要 Arduino HID 对于 Apple 用户以及 v2/v3/OTG 用户,进入启动选单或恢复模式不再需要依赖 Arduino HID 这类外部硬件方案。此前为了完整远程控制一台 Mac(例如进入 Option 启动菜单、Cmd+R 恢复模式),用户必须在 DIY 构建中额外搭建 Arduino 键盘鼠标模拟器;现在默认的 USB HID 路径即可胜任。

  2. 部分"挑剔"的 HP / DELL 主板键盘兼容性改善 修复过程中同步改善了一些奇怪的 HP、DELL 主板上的兼容性。发布说明指出:"如果你之前在这些机器上插键盘没反应,现在它有很大机会正常工作(if you didn't have a keyboard there before, now it has all the chances to work)"。

  3. 已知限制:键盘唤醒挂起(suspend)尚未生效 发布说明明确提示:"使用键盘从挂起状态唤醒(wakeup from suspend using keyboard)尚未实现,但这只是时间问题"。规划涉及 Apple 键盘唤醒能力的部署时,需要将这一限制纳入预期。

为什么"不再需要 Arduino HID"意义重大

在 Arduino HID 文档 开头有明确的 legacy 警告:该方案是旧 DIY 构建使用的键盘鼠标模拟器,如今已被更现代、更易用的 Pico HID 取代。从仓库文档看,Arduino HID 的两条接入路径各有代价:

  • Serial(UART)HID:通过 type: serial 配置,需要占用树莓派 UART,并需在 /etc/kvmd/override.yaml 中配置 reset_pin、device 等参数,还要处理 udev 规则、禁用 getty、修改 /boot/cmdline.txt,并在 刷写步骤 中经历 make && make install 的完整流程。
  • SPI HID:通过 type: spi 配置,需要 dtoverlay=spi0-1cs、电平转换器和复位三极管等额外硬件。

而 KVMD 3.14 的意义正在于:默认 USB/OTG HID 路径在 Apple 引导场景下已经够用,普通 v2/v3 用户无需再为 Mac 专门搭建上述外部模拟器。这与后续仓库文档中"用 Pico HID(SPI)释放 UART 给串口控制台等其他用途"的设计取向一脉相承——把 HID 兼容性收敛到主路径上,减少外部硬件依赖。

更新前准备:从 testing 软件源切回稳定源

发布说明特别提醒了一条更新前置条件:

更新前:如果你使用了 testing 软件源,请先取消它,回到常规(稳定)设置。

PiKVM OS 基于 Arch Linux,testing 仓库通常用于提前体验未发布的功能包。KVMD 3.14 的 Apple 修复属于稳定渠道的正式发布,因此:

  1. 如果你曾将 PiKVM OS 切换到 testing 仓库,请在更新前恢复默认的稳定源配置;
  2. 确认当前处于稳定渠道后,再执行下述升级流程,避免混入未稳定的中间版本。

完整更新流程

发布说明给出的标准升级流程如下(在 PiKVM 的 SSH 或 Web 终端中执行):

rw
pacman -Syu
reboot

各步骤含义:

  • rw:PiKVM OS 的文件系统默认是只读的(保护 SD 卡与系统完整性),rw 将其临时切换为可读写,这是执行系统级变更的前提。变更完成后可用 ro 恢复只读,参见 配置指南。
  • pacman -Syu:同步软件源并升级全部系统软件包。在升级过程中 KVMD 会随系统一起更新到 3.14。
  • reboot:PiKVM 有十余个依赖配置的系统守护进程,重启是让更新与内核变更可靠生效的最简单方式。

校验并安装 PiKVM 自有内核

KVMD 3.14 的 HID 修复依赖 PiKVM 维护的自有稳定内核构建(pikvm-os-raspberrypi)。新发布的镜像已内置该内核,只有使用非常老的镜像且从未手动安装过的用户才需要补装。发布说明给出的检查方法:

  1. 检查是否已安装:

    pacman -Q | grep pikvm-os-raspberrypi
    
  2. 如果该命令没有任何输出,说明系统缺少 PiKVM 的自有内核,需要安装它(包名与上述检查的 pikvm-os-raspberrypi 对应),安装完成后再次 reboot 使内核生效。

对于老镜像,升级时还可能遇到内核依赖冲突:若 pacman -Syu 报告内核依赖错误,可参考 2020 年发布博客 中的做法——在 /etc/pacman.conf 中找到并取消注释 IgnorePkg,把报错的包(如 linux-raspberrypi linux-raspberrypi-headers 或 linux-raspberrypi4 linux-raspberrypi4-headers)加入其中,然后重新执行 pacman -Syu 并重启。

更新后的验证与配置检查

升级完成后,可以按以下步骤确认系统状态与 HID 配置:

  1. 确认版本与内核:再次执行 pacman -Q | grep pikvm-os-raspberrypi,确认内核包已列出;KVMD 主程序版本可通过 kvmd --version 类命令查看(以实际安装为准)。
  2. 校验 HID 配置:如需查看当前生效的 HID 配置,可运行 kvmd -m 查看完整配置树,或运行 kvmd -M 仅查看非默认覆盖项;两者都承担配置校验功能。若输出 ConfigError 之类的报错,说明 /etc/kvmd/override.yaml 存在语法问题,需要修正后重新校验(详见 配置指南)。
  3. 恢复只读并验证实际效果:确认配置无误后执行 ro 恢复只读模式,重启后连接目标机(Mac 或 HP/DELL 主机),实测进入 Boot Menu / Recovery Mode 时键盘鼠标是否直接可用、无需再插外部 HID。

小结

KVMD 3.14 延续了 KVMD 3.8 开启的 Apple 兼容性修复路线,把"进入 Boot Menu / Recovery Mode"这一关键运维场景从 Arduino HID 的附加依赖中解放出来,并顺带改善了部分 HP、DELL 主板的键盘识别。对普通 v2/v3/OTG 用户而言,升级路径清晰:切回稳定源 → rw → pacman -Syu → reboot,再按需确认 pikvm-os-raspberrypi 内核就绪即可。至于"键盘唤醒挂起"这一遗留限制,发布说明已明确列为后续工作,部署时留意即可。

登录后查看全文
pikvm