From f2308d5402c4b0a11db7ddd56e9a5560c9af02bc Mon Sep 17 00:00:00 2001 From: Aleksandr Prokudin Date: Sun, 25 May 2025 10:32:13 +0200 Subject: [PATCH] Add USB passthrough documentation --- docs/usb-passthrough.md | 60 +++++++++++++++++++++++ docs/usb-passthrough/usb-passthrough.png | Bin 0 -> 12752 bytes mkdocs.yml | 1 + 3 files changed, 61 insertions(+) create mode 100644 docs/usb-passthrough.md create mode 100644 docs/usb-passthrough/usb-passthrough.png diff --git a/docs/usb-passthrough.md b/docs/usb-passthrough.md new file mode 100644 index 00000000..0437dec2 --- /dev/null +++ b/docs/usb-passthrough.md @@ -0,0 +1,60 @@ +--- +title: USB Passthrough +description: "How to set up USB Passthrough on PiKVM" +--- + +# USB Passthrough + +For USB keyboards and mice connected to PiKVM directly, USB passthrough allows forwarding their input to the host system. This feature is available for all versions of PiKVM except the DIY version based on Pi Zero. + +Let's consider this setup: + +- [PiKVM V4 Plus](v4.md) connected to [PiKVM switch](switch.md); +- A keyboard and a mouse connected to USB A ports on the PiKVM; +- An external display connected to the PiKVM directly using HDMI out. + +![Example setup](usb-passthrough.png){ width="400" } + +With both HDMI passthrough and USB passthrough enabled, you would be able to do this: + +- Switch between Computer 1 and Computer 2 connected to PiKVM Switch; +- Control them directly from this single keyboard/mouse pair (in addition to remote control); +- See the video output from the selected host on the local display. + +## Enabling USB passthrough + +Follow these steps to enable USB passthrough on your PiKVM: + +1. [Log into your PiKVM](cheatsheet.md) as `root`, either via SSH, web console, or USB serial connection. + +2. You need KVMD 4.74+ to be able to use this feature. Update the PiKVM OS as `root`: + + ``` + [root@pikvm ~]# pikvm-update + ``` + +3. PiKVM will reboot, log in as `root` again. + +4. Run the following command to change acces to read-write, enable USB passthrough, and change acces to read-only again: + + ``` + [root@pikvm ~]# rw; systemctl enable --now kvmd-localhid; ro + ``` + +Once you've done that, you should be able to use your USB keyboard and mouse connected directly to your PiKVM to control the host. + +## Toggling USB passthrough + +Every once in a while you may want using keyboard/mouse to control your PiKVM instead of controlling a host. Once USB passthrough is enabled in the system, you can switch it on and off with shortcuts: + +- `LeftAlt, LeftAlt, K` (mnemonic **K**VM) disables keyboard/mouse grabbing and allows using the input devices with PiKVM locally, for example, for the console operating. + +- `LeftAlt, LeftAlt, H` (mnemonic **H**ost) switches back to the passthrough mode and passes keyboard-mouse events to the host. + +Press these keys **immediately** one after another: `LeftAlt`, then `LeftAlt` again, then the mnemonic key. + +## Switching the PiKVM Switch channels + +If you have one or two PiKVM Switches, you can use `LeftAlt, LeftAlt, 1` (1-8) to switch between up to 8 channels. + +For three or more PiKVM Switches, you need to use double numbers, e.g., `LeftAlt, LeftAlt, 3, 2` (unit 3, channel 2). \ No newline at end of file diff --git a/docs/usb-passthrough/usb-passthrough.png b/docs/usb-passthrough/usb-passthrough.png new file mode 100644 index 0000000000000000000000000000000000000000..fe467acfe841d7df6b455a5072412a05ab6de000 GIT binary patch literal 12752 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