企业官网建设流程全解析

• 文档
• 教程

KVMD 3.8（2021 年 7 月发布）是 PiKVM 历史上针对 Apple 平台的一次标志性修复：它解决了长期困扰用户的"Intel Mac 无法在启动菜单中移动鼠标、恢复模式强制要求外接鼠标"两大顽疾，并让 M1 Mac 在使用默认 OTG HID 时不再被荒谬的提示页拦截。本文以这次发布为核心，结合仓库中的 鼠标模式文档、Arduino HID 文档 与 固件刷写文档，从绝对/相对鼠标原理讲起，完整还原修复内容、配置方法和升级步骤，帮助读者理解并复现"用 PiKVM 完全远程操控 Mac"的完整链路。

一、背景：为什么以前无法完全远程控制 Mac

在 KVMD 3.8 之前，PiKVM 在 Apple 平台上一直存在与鼠标、键盘相关的历史问题，导致"完全远程控制 Mac"成为不可能：

• 启动菜单（Boot Menu）中鼠标不可用：进入 macOS 的启动选择界面后，模拟鼠标无法驱动光标移动，用户无法远程选择启动磁盘；
• 恢复模式（Recovery Mode）强制要求物理鼠标：即使光标本身可以工作，系统仍会显示要求"再连接一个鼠标"的界面，远程会话被硬性卡住；
• 由于上述缺陷叠加，此前无法在不接触 Mac 实体机的情况下完成启动项切换、恢复模式操作等关键运维动作。

该问题深藏在 Apple 驱动内部，而 macOS 是闭源系统，没有其他途径探知内核层到底发生了什么。据发布说明记载，作者为此专门采购了一台硬件 USB 协议分析仪（花费近 $1500）来抓取真实 HID 交互过程，最终定位并绕过了这一驱动行为。

二、预备知识：绝对鼠标与相对鼠标两种模式

要理解这次修复的技术含义，必须先分清 PiKVM 模拟指针设备的两种模式（详见 docs/mouse.md）：

• 绝对模式（Absolute）：输入设备直接上报目标坐标(X, Y)，光标应当移动到哪个位置由设备指定。触摸屏、绘图板就是这种工作方式。
• 相对模式（Relative）：输入设备只上报相对当前位置的偏移(dX, dY)，设备本身并不知道光标当前在屏幕何处。普通物理鼠标就是这种工作方式。

PiKVM 默认使用绝对定位，因为它对用户和上层软件最方便；但 BIOS/UEFI 以及某些特殊启动环境并不总是支持绝对鼠标。为此 PiKVM 提供了相对模式支持，可通过配置开启。

使用相对模式时有两点体验上的注意：

• 在 Web UI 的流窗口中点击一次后，浏览器会独占捕获鼠标；按Esc后浏览器释放鼠标。
• 相对模式会产生大量移动事件，可能受网络质量影响，或被 BIOS/UEFI 驱动缓慢处理。PiKVM 通过"向量求和"对事件做优化，并可在 Web 菜单System -> Squash mouse moves中开关；若遇到鼠标加速异常可尝试关闭该项。另外，相对模式当时尚未被 PiKVM VNC 服务器 支持，也不支持移动端浏览器。

三、KVMD 3.8 修复了什么：两条平台各自的解法

KVMD 3.8 的修复策略按 Mac 平台架构分两条路径：

3.1 Intel Mac：配合 Arduino HID 进入启动菜单

对于基于 Intel 的 Mac，使用 Arduino HID（键盘鼠标模拟器）即可进入不同的启动菜单（如按Option选择启动磁盘，或按Cmd+R进入恢复模式）：

• 在启动管理器（Boot Manager）中，相对鼠标现在可以正常工作；
• 在恢复模式（Recovery Mode）中，相对鼠标与绝对鼠标均可正常工作。

也就是说，只要在旧式 DIY PiKVM 方案中接入 Arduino HID，并配合 KVMD 3.8 使用相对模式，就能在 macOS 的启动阶段完全接管鼠标。

3.2 M1 Mac：直接使用默认 OTG HID

对于搭载 Apple Silicon（M1）的 Mac，无需额外硬件，直接使用默认的 OTG HID 即可：

• 不再出现那个荒谬的"请再连接一个鼠标"的提示画面；
• 进入恢复模式时不再需要物理外设，远程会话可以一路操作到底。

值得说明的是，这一行为依赖 HID 在目标机电源循环期间的持续供电能力。仓库中 Pico HID 零件清单 也指出：保持按键在目标机重启期间持续按下，对 macOS 进入启动菜单尤为重要，这也是该文档强烈建议加装 1N5819 二极管的原因。

四、动手配置：为 Mac 场景启用合适的鼠标模式

无论使用 Arduino HID 还是 OTG HID，都需要在 PiKVM OS 中按需配置鼠标模式。PiKVM OS 的文件系统默认只读，所有自定义配置都写入/etc/kvmd/override.yaml（主默认值位于/usr/lib/kvmd/main.yaml，切勿直接编辑，机制详见 docs/config.md）。

4.1 开启双模式（可在 Web UI 中实时切换）

在System菜单中无需重启即可在绝对/相对鼠标之间切换，但对兼容性考虑默认关闭。开启方法：

1. 用命令rw将文件系统切换为可写；
2. 编辑/etc/kvmd/override.yaml，加入：

kvmd: hid: mouse_alt: device: /dev/kvmd-hid-mouse-alt

3. 执行reboot，重启后同样重启被控电脑。

4.2 单相对模式（Intel Mac 启动菜单场景推荐）

如果只需要相对鼠标，配置如下：

kvmd: hid: mouse: absolute: false mouse_alt: device: ""

4.3 最大化 BIOS/UEFI 兼容性

若 BIOS/UEFI 仍检测不到鼠标，可进一步禁用水平滚轮：

kvmd: hid: mouse: absolute: false horizontal_wheel: false mouse_alt: device: ""

改完后执行reboot生效。此外，kvmd -M可用于校验 override 配置的语法（详细说明见 docs/config.md）。

五、Intel Mac 路径的关键硬件：Arduino HID 部署

Arduino HID 是旧式 DIY PiKVM（V0/V1）时代的标准键盘鼠标模拟器，基于 ATMega32u4 的 Arduino Pro Micro / Micro。它支持两种连接方式，配置位置均在/etc/kvmd/override.yaml的kvmd/hid段。

5.1 Serial HID（串口方案）

适合除 Pi Zero W 外的树莓派，需先确保版本支持。在 override 中加入：

kvmd: hid: type: serial reset_pin: 4 device: /dev/kvmd-hid

并创建 udev 规则/etc/udev/rules.d/99-kvmd-extra.rules：

KERNEL=="ttyAMA0", SYMLINK+="kvmd-hid"

还需systemctl disable getty@ttyAMA0.service，并从/boot/cmdline.txt中移除console=ttyAMA0,115200或console=serial0,115200及kgdboc=...参数。

5.2 SPI HID（SPI 方案）

SPI 方案的优势是不占用与蓝牙共享的 UART 引脚、无需禁用蓝牙。需在/boot/config.txt中加入dtoverlay=spi0-1cs，然后配置：

kvmd: hid: type: spi chip: 0 bus: 0 sw_cs_pin: 7 reset_pin: 25 reset_inverted: true

保存后systemctl restart kvmd，并清理浏览器缓存。

5.3 固件编译选项：动态切换相对/绝对鼠标

Arduino HID 固件通过platformio-avr.ini中的构建标志决定功能。默认配置启用动态模式切换：

[_common] build_flags = -DHID_PS2_KBD_CLOCK_PIN=7 -DHID_PS2_KBD_DATA_PIN=5 -DHID_USB_CHECK_ENDPOINT # ----- The default config with dynamic switching ----- -DHID_DYNAMIC -DHID_WITH_USB -DHID_SET_USB_KBD -DHID_SET_USB_MOUSE_ABS # ----- PS2 keyboard only ----- # -DHID_WITH_PS2 # -DHID_SET_PS2_KBD # ----- PS2 keyboard + USB absolute mouse ----- # -DHID_WITH_USB # -DHID_WITH_PS2 # -DHID_SET_PS2_KBD # -DHID_SET_USB_MOUSE_ABS # ----- PS2 keyboard + USB relative mouse ----- # -DHID_WITH_USB # -DHID_WITH_PS2 # -DHID_SET_PS2_KBD # -DHID_SET_USB_MOUSE_REL

例如要用 USB 鼠标 + PS/2 键盘，就取消对应组合的注释、注释掉默认块。这正是 KVMD 3.8 中"启动管理器相对鼠标可用"所依赖的能力：动态切换使固件能在不同启动阶段提供不同鼠标模式。完整接线图与零件清单见 docs/arduino_hid.md，SPI 连接的示意图见docs/arduino_hid/arduino_spi_hid.png、串口方案见docs/arduino_hid/arduino_serial_hid.jpg。

六、刷写 Arduino HID 固件

Intel Mac 路径要生效，需要重刷固件。通用刷写步骤（详见 docs/flashing_hid.md）：

# rw # systemctl stop kvmd # cp -r /usr/share/kvmd/hid/arduino ~ # cd ~/arduino # make # make install # reboot

SPI 方式用make spi代替make，且无需断开 RESET 线（串口刷写时需要断开）。新版镜像不再预装刷写工具，需先安装：

pacman -S platformio-core avrdude

七、升级到 KVMD 3.8 并验证

在树莓派控制台（SSH 或 Web Terminal）执行标准升级流程：

rw pacman -Syu reboot

升级完成后务必重新刷写 Arduino HID 固件（对应章节六），否则 Intel Mac 路径的新鼠标行为不会生效。升级后即可验证：

• Intel Mac：开机按住Option进入启动管理器，确认相对鼠标可驱动光标；进入恢复模式后确认相对/绝对两种模式均可使用；
• M1 Mac：使用默认 OTG HID 进入恢复模式，确认不再出现"请连接另一个鼠标"的提示。

八、演进：从 Arduino HID 到 Pico HID

需要说明的是，Arduino HID 属于旧式 DIY 方案的遗留组件。仓库现文档（如 docs/arduino_hid.md 顶部与 docs/flashing_hid.md）已标注 Legacy 警告：如今更推荐使用 Pico HID 作为其原位兼容替代，新方案同样支持启动阶段保持按键、满足 macOS 进入启动菜单的需求。理解 KVMD 3.8 这次 Apple 修复的来龙去脉，依然是理解 PiKVM 鼠标模式机制与 macOS 远程运维方案的最佳入口。

• 文档
• 教程