企业官网建设流程全解析

• 文档
• 教程

本文是 PiKVM 开源 IP-KVM 项目中 DIY 硬件的接线示例详解，覆盖 HDMI-CSI 桥接板、USB 视频采集卡、直连目标机诊断以及 EZCOO 多路 KVM 交换机等五种典型布线拓扑。阅读本文后，你将能够依据自己的树莓派型号与手头物料，正确规划 PiKVM 的采集链路与供电/数据回路，并掌握排线插接、端口绑定与基本故障排查的完整要领。

接线方案总览

PiKVM 的硬件核心在于"把目标机的画面采进来、把键鼠信号送出去"。围绕视频采集路径，官方文档 wiring_examples.md 给出了五类经实测的布线范例：

下文逐一对每种方案展开说明，并补充来自仓库配套文档与源码的实操细节。

HDMI-CSI：树莓派 CSI 接口 + 桥接板方案

物料清单

官方示例图csi_wiring.jpg展示了一套完整的 HDMI-CSI 采集链路。需要准备的物料如下（注意：文中所附商品链接仅用于说明形态，可能随时失效，请自行搜索同类产品）：

• USB-A 公头转 USB-A 公头数据线（用于目标机到树莓派之间的 USB 数据传输，即键鼠回传链路）
• USB 电源隔离器（PortaPow USB Power Blocker 之类）：在 USB 数据线中阻断电源线，防止目标机的 USB 供电反向灌入树莓派，避免两边供电冲突
• USB-C OTG 分线器（如 USB C OTG Splitter）：将树莓派 4 的 USB-C 口拆分为"数据 + 供电"两条通路，数据线走 OTG 至目标机，供电线接 PiKVM 电源
• 普通 HDMI 线：连接目标机显卡输出到桥接板
• DisplayPort 转 HDMI 短线（DP to HDMI pigtail）：当目标机仅有 DisplayPort 输出时使用（官方提醒示例图片中的接法显示有误，请以实物接口方向为准）
• TARGET：即你要控制的任何目标主机

接线拓扑

整体链路为：

目标机 HDMI ──HDMI线──> HDMI-CSI 桥接板 ──排线──> 树莓派 CSI 接口 目标机 USB <────────── USB-A 数据线 ──────────> 树莓派 OTG（经分线器/电源隔离）

即视频走 CSI 通道进入树莓派，键鼠 HID 走 USB OTG 通道反向输出到目标机，两条链路互不干扰，这正是 PiKVM 延迟表现最好的采集形态。

排线插接细节（易错点）

CSI 排线的插接是 DIY 过程中最容易出错、也最容易损坏硬件的一步。仓库配套文档 docs/_diy_setup_video_csi.md 给出了明确的操作要领：

1. 找到正确接口：将 HDMI-CSI 桥接板的柔性排线插入树莓派上标有CAMERA的窄白色连接器（靠近大 USB 接口的那个）。
2. 正确打开锁扣：树莓派一侧可轻轻向上并略微侧向抬起黑色压条打开锁扣；HDMI-CSI 桥接板一侧则取决于你购买的版本，可能是向上轻拉，也可能是侧向推压。
3. 确认插入方向与深度：确保排线从正确的一面插入并顶到底，然后推回黑色压条锁紧。
4. 严禁暴力：排线与 PCB 的焊点是相当脆弱的，插入时避免用力过猛。
5. 绝对禁止热插拔：永远不要在设备带电时插拔排线！这是非即插即用设备，带电插拔可能直接损坏桥接板或树莓派。
6. 使用原装排线：只使用随设备附带的排线，若使用第三方排线务必确认其引脚定义正确。

上电后的验证与故障排查

接线完成后，若画面未出现，仓库的 docs/_basic_troubleshooting.md 给出了两个诊断命令：

[root@pikvm ~]# dmesg | egrep 'tc35|1-1.4|uvc' [root@pikvm ~]# systemctl status kvmd-tc358743

• kvmd-tc358743是 PiKVM 平台软件中负责驱动 TC358743 HDMI-CSI 桥接芯片的系统服务（该服务名来自 kvmd-platform 平台包）。
• 若输出中显示服务失败，首先要检查 CSI 排线的方向并尝试重新插接。
• 再次强调：CSI 不是热插拔设备，重新插拔排线前必须先断开设备电源。

使用 PCB 分线器的 CSI 方案

部分用户的树莓派除了接 HDMI-CSI 桥接板，还需要同时使用 CSI 摄像头等其他外设。此时可以使用 PCB 分线器扩展 CSI 通道，官方示例图csi_wiring_w_pcb_splitter.jpg展示了这一拓扑。

这种方案的接线方法与标准 HDMI-CSI 完全一致，只是将桥接板排线先接入分线器，再由分线器连接到树莓派的 CSI 接口。它的实用价值在于：避免在"接摄像头"与"接采集卡"之间反复插拔排线，一次接线即可同时保留多种 CSI 外设的接入能力。插拔注意事项与上一节完全通用。

HDMI-USB：USB 视频采集卡方案

如果你的树莓派没有可用的 CSI 接口（例如某些老旧型号），或希望免去插拔脆弱排线的步骤，可以选择 USB HDMI 视频采集卡方案，示例图见usb_capture_wiring.jpg。

端口绑定：必须插在指定 USB 口

仓库配套文档 docs/_diy_setup_video_usb.md 明确指出：

必须将 USB 采集卡连接到指定的 USB 端口。该端口在软件中已被绑定，这样操作系统就不会把视频设备与其他设备混淆。

• 在树莓派 2、3 和 5 上，绑定到特定端口；在树莓派 4 上绑定到对应 USB 口（各板型的正确端口位置见usbcap_rpi2.jpg与usbcap_rpi4.jpg示意）。
• 如果绑定失败（例如遇到未测试过的树莓派板型修订），设备将退化为对所有端口可用，功能上仍能正常工作。
• 潜在副作用：如果系统上同时接有普通 USB 摄像头，Linux 可能把它误认成采集卡设备，此时需联系 PiKVM 支持修复绑定。

与 CSI 方案的差异

从 PiKVM 软件层面看，两种采集方式对应不同的平台驱动与服务（CSI 方案对应kvmd-tc358743，USB 方案对应 UVC 设备路径），但 Web UI 中的使用方式一致。USB 采集卡方案胜在接线简单、对板型宽容度高，代价是延迟通常略高于原生 CSI 通道。

直连目标机：最小化排障与线缆诊断

当 PiKVM 出现"无画面"或"键鼠无响应"时，官方给出了一种极简的直连方案，见direct_connect_to_target.jpg。

连接方式

将树莓派的 USB-C 口通过 USB-A 数据线直接接到目标机的 USB-A 口，此时：

• 键鼠 HID 数据经由这根线传输到目标机；
• 目标机的 USB 口同时为树莓派供电，即"一线双用"。

三个典型使用场景

官方文档明确列出了此方案的三类用途：

1. 判断数据线是否为真正的数据线：很多廉价 USB 线只有电源芯线、没有数据芯线（俗称"充电线"），直连后若 PiKVM 端键鼠设备未出现在目标机上，即可断定线缆无数据传输能力。
2. 测试分线器或线缆是否损坏：绕过 OTG 分线器、电源隔离器等中间环节，直连目标机，若恢复正常则问题出在中间器件上。
3. 基本故障排查：用最小硬件链路定位问题层级，再逐级恢复完整接线。

这一方案同时说明了一个核心硬件常识：PiKVM 的键鼠 HID 与供电是可以共线的，而电源隔离器的存在价值在于阻止"目标机供电"与"PiKVM 独立供电"两套电源同时存在时产生冲突或回流。

EZCOO 多路 KVM 交换机接线

EZCOO 是有管理端口（串口可控）的商用 HDMI KVM 交换机。将它放在 PiKVM 与多台主机之间，即可让单台 PiKVM 控制并切换多台服务器，官方接线示例见ezcoo_wiring.jpg，完整配置指南见 docs/ezcoo.md。

兼容性前提

仓库配套文档 docs/_multiport_usb.md 明确：此类交换机需要一个 USB 主机端口来输出控制信号，因此：

• 兼容：PiKVM V3、V4 Plus，以及基于树莓派 2/3/4 的 DIY 设备；
• 不兼容：PiKVM V4 Mini（无 USB 主机口，属单主机设备）、基于树莓派 Zero 2 W 的 DIY 设备（同样无 USB 主机口）。

接线步骤（来自 ezcoo.md）

1. 将树莓派 OTG 口的 USB-C 线（经自定义分线器/设备）连接到ezCoo 交换机前面板的 USB 3 口或背面的 USB 1 口。注意：如果接到交换机的键盘口（USB 2），则目标机将看不到鼠标。
2. 将 ezCoo 交换机的 HDMI 输出接到树莓派的 CSI-2 到 HDMI 输入（即 HDMI-CSI 桥接板）；也有用户反馈 USB HDMI 编码器采集卡同样可用。
3. 用一根USB-A 转 Micro USB 线将树莓派连接到 ezCoo 交换机侧面的管理口（Micro USB，即 F/W CTL 管理端口），该口在树莓派上表现为/dev/ttyUSB0。
4. 按交换机说明书，把各主机的 USB 与 HDMI 线接入交换机。
5. SSH 登录 PiKVM，执行ls -la /dev/ttyUSB0确认交换机已被识别。

让 Web UI 能切换主机（GPIO 配置）

接线完成后，可通过 GPIO 驱动 在 PiKVM Web 界面加入 4 路输入切换按钮。核心配置写入/etc/kvmd/override.yaml（以交换机在/dev/ttyUSB0为例）：

kvmd: gpio: drivers: ez: type: ezcoo protocol: 2 device: /dev/ttyUSB0 scheme: ch0_led: driver: ez pin: 0 mode: input ch1_led: driver: ez pin: 1 mode: input ch2_led: driver: ez pin: 2 mode: input ch3_led: driver: ez pin: 3 mode: input ch0_button: driver: ez pin: 0 mode: output switch: false ch1_button: driver: ez pin: 1 mode: output switch: false ch2_button: driver: ez pin: 2 mode: output switch: false ch3_button: driver: ez pin: 3 mode: output switch: false view: table: - ["#Input 1", ch0_led, ch0_button] - ["#Input 2", ch1_led, ch1_button] - ["#Input 3", ch2_led, ch2_button] - ["#Input 4", ch3_led, ch3_button]

配置要点：

• 配置前先执行rw切换到可写模式，改完执行ro恢复只读，再systemctl restart kvmd重启服务；
• YAML 缩进必须使用空格（每级 4 个空格），不能使用 Tab；
• 老版本 USB 2.0 的 ezCoo 交换机（已停产的旧版）需要去掉protocol: 2这一行；
• 若切换后键鼠无输出，用ls -la /dev/tty* | grep USB检查设备是否仍在——很多线缆只是电源线，会造成设备消失；
• 保存后在 KVM 页面点击GPIO菜单即可看到 4 路输入按钮，绿色圆点指示当前选中通道。

EZCOO 方案的已知限制

• 官方警告：ezCoo 属第三方硬件，可能需要反复试验才能达到预期效果（尤其是 U3P 热键版本，可能无法按预期工作）；
• 交换机音频未测试，假定不可用；
• 与直接插 CSI 采集器一样，存在"目标机已上电并接着显示器时接入 CSI2-HDMI 采集器可能不出画面"的底层限制。解决方法是先让所有目标机保持关机，直接连到交换机后再上电。

接线后的软件层校验

无论采用哪种接线方案，都可以从软件层面验证链路是否完整：

视频链路

• CSI 方案：systemctl status kvmd-tc358743，确认服务 active；
• USB 方案：dmesg | grep uvc，确认 UVC 采集设备被识别；
• 确认当前使用的是匹配板型的 OS 镜像：pacman -Q | grep kvmd-platform。

USB OTG 链路

PiKVM 通过 OTG 模拟键盘、鼠标与虚拟光驱（MSD）等设备，每个模拟设备都会消耗 USB端点（endpoints）资源。仓库文档 docs/usb.md 说明 PiKVM 共提供 9 个端点：

用kvmd-otgconf可实时查看与调整：

[root@pikvm ~]# kvmd-otgconf # Endpoints used: 5 of 9 # Endpoints free: 4 + hid.usb0 # [1] Keyboard # otg/devices/hid/keyboard/start + hid.usb1 # [1] Absolute Mouse # otg/devices/hid/mouse/start + hid.usb2 # [1] Relative Mouse # otg/devices/hid/mouse_alt/start + mass_storage.usb0 # [2] Mass Storage Drive # otg/devices/msd/start

若目标机 BIOS/UEFI 对大量模拟设备不兼容，可临时禁用部分设备再进入 BIOS：

[root@pikvm ~]# kvmd-otgconf -d mass_storage.usb0 uac2.usb0 hid.usb1

接线通用注意事项汇总

1. 线缆选择：务必确认 USB 线支持数据传输（而非仅供电），直连测试法是验证数据线最有效的手段。
2. 供电隔离：PiKVM 与目标机各自供电时，USB 数据线应串入电源隔离器（如 PortaPow USB Power Blocker），阻断回流与电位冲突。
3. CSI 排线：认准CAMERA接口、正确方向、插入到底、锁紧压条；带电禁插拔，插拔前断电。
4. 多路交换机：确认设备有 USB 主机口（V3/V4 Plus/树莓派 2/3/4 DIY 可用；V4 Mini 与 Zero 2 W 不可用），管理口接入后检查/dev/ttyUSB0。
5. 出现故障时的排查顺序：先直连目标机做最小链路验证 → 再逐级恢复分线器、隔离器 → 检查服务状态与 dmesg 日志 → 检查排线方向。

通过上述五种接线方案与配套验证手段，你可以根据手头树莓派型号与预算，搭建出稳定可靠的 DIY PiKVM，并具备独立诊断硬件链路故障的能力。

• 文档
• 教程