企业官网建设流程全解析

• 文档
• 教程

导读

2020 年 12 月 20 日，PiKVM 项目发布了关于第三代硬件（V3）原型机的最新进展。这篇来自官方博客的公告（docs/blog/posts/2020/2020-12-20/index.md）虽然篇幅不长，却浓缩了 V3 区别于此前 DIY 版本（V1/V2）的四大关键特性：HDMI 音频采集、内置 PWM 风扇控制器、同时支持 USB 与 PS/2 的 Arduino HID，以及全 USB-C 接口标准化。本文将以此公告为骨架，结合当前仓库中的 V3 使用指南、音频配置、Arduino HID 文档 及后续版本发布记录，逐项解析这些特性的技术背景、最终落地形态与配置方法，帮助读者理解 V3 在 KVM-over-IP 产品化道路上的关键设计取舍。

一、公告背景：从 DIY 走向产品化的 V3

公告首先确认了两件事：V3 原型机"几乎准备就绪"，且自上次公布以来加入了若干新变更与附加特性。当时的 PiKVM 生态正处于从 V1/V2 纯 DIY 方案向"即插即用整机"过渡的阶段——这一点在今天的 README 中仍能看到清晰的定位划分：V1/V2 面向动手组装，V3 则是"plug-and-play、fully assembled、industrial grade"的整机产品。

需要强调的是，这篇公告描述的是当时尚未发货的试产原型，其中部分特性（如 HDMI 音频的软件支持、PS/2 鼠标）在公告中明确标注为"稍后完成"。而今天的仓库文档已经完整记录了这些特性在量产 V3 上的最终形态，本文将以"公告承诺 → 最终实现"的对照方式展开。

二、HDMI 音频采集：突破 CSI 桥接芯片的硬件缺陷

2.1 公告中的问题陈述

公告指出了当时 DIY 视频采集方案的一个普遍痛点：除了昂贵的 Auvidea B101 之外，市面上所有 CSI 桥接芯片都存在硬件电路错误，无法采集 HDMI 中的音频信号。V3 在设计上解决了这一缺陷，音频采集在硬件层面已经实现，软件支持随后跟进，并计划与 H.264 视频压缩一起提供给用户。

这一承诺在后续产品中完整落地。根据 README 的功能对照表，HDMI 音频采集与麦克风双向音频正是 V3/V4 整机与 DIY 版本的关键分水岭——DIY V1/V2 在音频能力一栏均为 ❌。

2.2 硬件实现：I2S 音频跳线与 tc358743-audio

从 V3 使用指南 中可以看到 V3 的音频采集在硬件层面的具体形态。V3 的 HDMI 采集基于 TC358743 芯片，板上有一组音频采集跳线（jumper #4），用于将 I2S 引脚（GPIO 18/19/20/21）连接到 HDMI 采集芯片：

• I2S HDMI sound-GPIO 18, 19, 20, 21. Can be used for custom purposes if thetc358743-audiooverlay in/boot/config.txtis disabledANDjumpers [4] are removed.

也就是说，这组跳线与/boot/config.txt中的dtoverlay=tc358743-audio设备树覆盖协同工作：跳线接通且 overlay 启用时，HDMI 输入的音频通过 I2S 总线送入系统；只有两者同时被移除/禁用时，这些 GPIO 才能挪作他用。这从侧面印证了公告中所说的"硬件电路错误"是可以通过正确布线规避的——V3 正是通过将 I2S 正确连接到 TC358743 来根治问题的。

2.3 软件支持：EDID 音频块与 WebRTC 多媒体

公告称"软件将稍后准备就绪"，如今 音频配置文档 已经给出了完整方案。值得注意的是，V3 上的音频在量产机型中出于兼容性历史原因默认关闭（避免破坏老用户的 EDID 配置），需要按以下步骤开启：

1. 确认 V3 HAT 板上的音频跳线（jumper #4）未拆除，且/boot/config.txt中的dtoverlay=tc358743-audio未被注释；
2. 更新系统并重启；
3. 在 EDID 中启用 Basic Audio 支持并再次重启：

[root@pikvm ~]# rw [root@pikvm ~]# kvmd-edidconf --set-audio=yes [root@pikvm ~]# reboot

kvmd-edidconf --set-audio的作用是向 PiKVM 对外暴露的 EDID 中写入音频数据块（Audio Data Block），让被控主机认为 HDMI 显示设备具备音频输出能力——这正是被控主机"决定是否通过 HDMI 输出音频"的依据。仓库中 2024-02-15 的发布记录 也提到，kvmd-edidconf --set-audio=1可以自动为某些"特别挑剔的 OS"添加音频块。

配置完成后，在 Web UI 的System菜单中把视频模式切换为WebRTC，打开Multimedia开关并将音量调到非零值，视频流会重启并开始播放被控主机的音频。音频规格上，V3 支持标准位深与采样率的立体声，如 32/44.1/48 kHz 配合 16/24 bit。

2.4 后续演进：从单向往双向音频

公告中"h264 视频压缩 + 音频"的设想，最终演化为完整的双向音频能力：除了从 HDMI 采集被控主机的声音（扬声器方向），V3 还能通过 OTG 模拟一个 USB 麦克风，把浏览器端的语音送入被控主机（麦克风方向）。根据 音频配置文档，启用 USB 麦克风需要在/etc/kvmd/override.yaml中添加：

otg: devices: audio: enabled: true

也可以使用kvmd-override命令完成同样的配置（见 _config.md 配置指南）：

[root@pikvm ~]# kvmd-override --set otg/devices/audio/enabled=true

同时在 Web UI 中允许浏览器访问麦克风并打开Microphone开关即可。需要注意的是，双向音频仅在 WebRTC 模式下可用，VNC 不支持音频；且 DIY 设备（无论 CSI 还是 USB 采集棒）都不具备该能力。

三、内置风扇控制器：解决 Raspberry Pi 的散热问题

3.1 公告中的动机

公告指出，由于 Raspberry Pi 存在散热问题，V3 内置了风扇控制器。这在 V3 的整机形态下是合理的：金属外壳 + 主动散热，才能保证 7×24 小时 KVM 场景下的长期稳定运行。

3.2 实现与落地：kvmd-fan 服务

从仓库文档看，V3 的风扇控制器最终以独立系统服务kvmd-fan的形式落地。2022-01-08 的 KVMD 3.53 发布记录 明确写道：

The next new feature iskvmd-fan. This new utility implements automatic fan speed control depending on temperature.

即kvmd-fan实现依据温度自动调节风扇转速。在 V3 硬件上，风扇通过PWM 控制器驱动，占用 GPIO 12。根据 V3 使用指南 的 GPIO 说明：

• PWM fan controller-GPIO 12. Can be used for custom purposes if the fan disconnected andkvmd-fanservice is stopped.

这意味着 GPIO 12 是 PWM 风扇专用引脚：只有拔掉风扇并且停止kvmd-fan服务后，才能将它用于其他自定义用途。而 GPIO 引脚清单还警告，在 V3/V4 Plus 上，某些 GPIO 扩展模块会与kvmd-fan冲突（见 GPIO 文档 中的硬件限制说明）。

3.3 启用方式

对于老版本的 V3 HAT 镜像，OLED 与风扇默认并未启用，需要手动开启（新版出厂镜像默认已启用）：

[root@pikvm ~]# rw [root@pikvm ~]# systemctl enable --now kvmd-oled kvmd-oled-reboot kvmd-oled-shutdown [root@pikvm ~]# systemctl enable --now kvmd-fan [root@pikvm ~]# ro

kvmd-fan与kvmd-oled一起构成了 V3 整机的本地状态呈现与散热管理闭环——OLED 屏显示温度、CPU 与内存占用，风扇则依据温度自动调速，这正对应公告中"解决 RPi 散热问题"的设计目标。

四、Arduino HID：USB 与 PS/2 键盘鼠标的统一方案

4.1 公告中的定位

公告宣布 V3 的 Arduino HID 同时支持USB 和 PS/2 键盘鼠标，并强调"这一方案对 Apple UEFI 是必需的"（this thing is necessary to work with Apple UEFI）。公告同时坦白 PS/2 鼠标的软件支持"稍后完成，硬件已就绪"。

这条背景需要放在当时的时间线理解：就在公告发布前一周（2020-12-11），KVMD 2.6 发布记录 刚刚宣布"完全重写 Arduino HID 子系统"，其中一项关键成果正是Arduino HID 兼容 Mac UEFI，能够在启动时访问其菜单，并注明"如果需要完整的 Mac UEFI 支持，请使用 Arduino HID，这是推荐方法"。V3 公告实际上是这条开发路线的硬件延续。

4.2 固件形态：多模式编译开关

Arduino HID 的软件形态是一套基于 PlatformIO 的 AVR 固件（源码位于/usr/share/kvmd/hid/arduino，刷写方法见 刷写 Arduino HID）。根据 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 HID 并支持动态模式切换；通过注释/取消注释对应宏，可以组合出"纯 PS/2 键盘""PS/2 键盘 + USB 绝对鼠标""PS/2 键盘 + USB 相对鼠标"等多种形态。公告中"USB 和 PS/2 键盘鼠标"的承诺，正对应这套可配置的多模式固件体系。

4.3 PS/2 接线与已知限制

使用 PS/2 键盘时，将 Arduino 引脚连接到主板的紫色 PS/2 接口（若只有一个通用接口，绿紫双色亦可）：Arduino pin 7 ↔ PS/2 CLOCK，Arduino pin 5 ↔ PS/2 DATA，GND ↔ GND。文档同时提醒，纯 PS/2 设备需要把 Arduino 的 VIN 接到树莓派的 5V 引脚，而 USB 连接时 Arduino 会自行取电、无需外接。

公告发布时 PS/2 鼠标尚未完成，Arduino HID 文档 也记录了当时的限制：使用 PS/2 固件时无法使用可切换的 USB HID，且 PS/2 鼠标暂不支持——文档注明"这两个问题都将在近期解决，两个不同版本的固件将合并为一个通用版本"。此后 KVMD 3.8（2021-07-10）的 Epic Apple fix 发布记录 证实了这条路线对 Mac 的价值：Intel 版 Mac 可借助 Arduino HID 进入 Option / Cmd+R 等启动菜单，在引导管理器中相对鼠标可用，恢复模式下相对/绝对鼠标均可用。

4.4 后续定位：被 Pico HID 取代

需要提醒的是，Arduino HID 如今已被官方标记为Legacy（旧版）方案。Arduino HID 文档 开篇即警告：该方案仅用于旧版 DIY 组装，更现代且更好的替代品是 Pico HID（基于 Raspberry Pi Pico 的 HID 桥接方案）。因此，本文对 Arduino HID 的讨论定位在"V3 原型机阶段的历史技术路线"这一语境下，新项目应优先考虑 Pico HID。

五、接口标准化：全 USB-C 与官方电源兼容

公告还宣布 V3 板只使用 USB-C 接口，以实现标准化，并与官方 Raspberry Pi 电源完全兼容——后者将被推荐作为 V3 的供电方案。

这一设计在 V3 使用指南 中得到了印证。V3 前面板提供USB-C 电源输入（5.1V 3A），后面板则是USB-C OTG 接口（承担键盘/鼠标、虚拟 CD-ROM/U 盘、USB 以太网、USB 串口等全部 USB 设备模拟功能），此外还有独立的USB-C 串口控制台接口。也就是说，USB-C 在 V3 上同时承担了"供电 + OTG 设备模拟 + 控制台"三重角色，充分体现了公告所说的"标准化"意图。

配套地，V3 对供电也给出了明确建议：使用 5V USB 电源适配器，勿遮挡侧面的散热孔；首次上电时系统会生成 SSH 密钥与证书，耗时数分钟，期间不应断电。

六、试产计划与产品化时间线（历史背景）

公告末尾公布了当时的发售计划，作为产品化历程的一部分记录如下：

• 首批限量 30 套，面向商业客户与部分感兴趣的用户，手工组装试产，单套$200–250；
• 套件包含：V3 主板、Arduino HID 板、适配板、小风扇，以及（可能的）3D 打印外壳；不包含Raspberry Pi 与电源；
• 计划在 2021 年 1 月开始销售量产型号，价格大幅降低（约 $100）。

从后续发布记录可以还原这条时间线的真实走向：2021-07-04 的 KVMD 3.7 发布记录 提到首批 v3 在俄罗斯海关延误，第二批（9 月，中国代工）计划随后推进。今天仓库中的 V3 使用指南、3D 打印外壳图纸 与 V3.3 图纸（后者即"Kickstarter/Store 型号"），都证明 V3 最终以 HAT 组装套件与整机两种形态量产交付。公告中"原型机几乎准备就绪"的表述，与最终产品的一致性，为本文"特性对照"式的解读提供了依据。

七、总结

2020 年 12 月的这篇 V3 公告虽然只有寥寥数段，却精准预告了 PiKVM 产品化阶段的技术重心：

对于研究 PiKVM 硬件演进的读者，这篇公告是理解 V3 设计取舍的起点；对于实际使用者，仓库中对应的功能配置文档、V3 完整指南 与 GPIO 说明 则提供了从特性到可操作配置的完整路径。V3 作为 PiKVM 从 DIY 走向整机产品的承上启下之作，其"音频 + 散热 + HID 兼容性"三大方向，也一直延续到了后续的 V4 系列。

附注：本篇文章所述特性均以当前仓库文档为准。音频、风扇与 HID 的具体配置命令以 PiKVM OS 配置指南 中描述的/etc/kvmd/override.yaml与kvmd-override工具为基础，实际使用请以安装的 KVMD 版本为准。

• 文档
• 教程