From 5e225eb1258c01ccca68e9e1daa6c43aafcc500e Mon Sep 17 00:00:00 2001 From: Aleksandr Prokudin Date: Tue, 28 Oct 2025 19:27:12 +0100 Subject: [PATCH] ID and USB: add a setup replication howto and update existing content (#1600) * ID and USB: add a setup replication howto and update existing content * Quick fix for a usb config part --- docs/id.md | 24 ++++++++++-- docs/usb.md | 104 +++++++++++++++++++++++++++------------------------- 2 files changed, 76 insertions(+), 52 deletions(-) diff --git a/docs/id.md b/docs/id.md index f8c309cd..0ae03945 100644 --- a/docs/id.md +++ b/docs/id.md @@ -40,14 +40,13 @@ It works in a similar way with USB. This applies to [PiKVM V3](v3.md), [V4](v4.md) and DIY based on CSI bridge. It is impossible to change the EDID for the HDMI-USB dongle. -The EDID (Extended Display Identification Data) is responsible for preseting the display. +The EDID (Extended Display Identification Data) is responsible for presenting the display. It also provides the host with information about the resolutions that PiKVM supports. More information about this is written on [this page](edid.md), and here we will provide brief information. {!_edidconf_options.md!} -For a detailed guide on customizing EDID, please visit [this page](edid.md). -There you can also find out how to set the EDID from a real monitor, or quickly adopt your real monitor IDs with PiKVM V4 Plus. +For a detailed guide on customizing EDID, please visit [this page](edid.md). There you can also find out how to set the EDID from a real monitor, or quickly adopt your real monitor IDs with PiKVM V4 Plus. ----- @@ -162,3 +161,22 @@ After changing validate the config using `kvmd -m`. You will see the full config or a message about configuration error. If everything is fine, perform the soft reboot. + +## Replicating setups + +You can use `kvmd-edidconf` and `kvmd-otgconf` to replicate an entire host configuration for testing or other purposes. What you can do will vary depending on the PiKVM device you have: + +- V4 Plus: you can import both EDID and USB IDs. +- V4 Mini: you must manually edit `override.yaml`, as there is neither a second HDMI Out or additional USB ports on your PiKVM. +- V3: you can import USB IDs only, as there is no second HDMI output on your PiKVM. + +Assuming you have PiKVM V4 Plus, follow these steps: + +1. Connect the host's display to one of the two HDMI Out ports on the rear panel of your PiKVM. +2. Connect the host's USB keyboard and mouse to USB ports on the front and the rear panel of you PiKVM. +3. Run `rw` to switch to read-write mode. +4. Run `kvmd-edidconf --import-display-ids --apply` as root on the PiKVM. This will fetch EDID information from the connected physical display and place it into the `/etc/kvmd/override.yaml` configuration file. +5. Run `kvmd-otgconf --import-usb-ids` as root on the PiKVM. This will fetch IDs of the connected physical USB devices and place them into the `/etc/kvmd/override.yaml` configuration file. +6. Run `ro` to switch to read-only mode. +7. Run `reboot` to reboot your PiKVM and apply newly the added customization. +8. Reconnect the host's display and keyboard/mouse back to the host. \ No newline at end of file diff --git a/docs/usb.md b/docs/usb.md index a66857f7..f063dc17 100644 --- a/docs/usb.md +++ b/docs/usb.md @@ -18,7 +18,6 @@ A complete USB configuration changing (adding or removing devices) requires a reboot, but it is possible to temporarily disable and then re-enable existing emulated devices in preset. - ----- ## Basics @@ -39,31 +38,37 @@ Depending on the device, the number of required endpoints varies: * PiKVM V4 Mini/Plus also adds a relative mouse by default so it uses 5 of 9 endpoints. -You can add other devices remaining endpoints, disable existing ones at all to free some endpoints, or do this only temporarily. +You can add other devices remaining endpoints, disable existing ones +at all to free some endpoints, or do this only temporarily. -Moreover, you can configure the preset with a large number of devices (more than PiKVM allows by endpoints), -and then dynamically enable only the necessary ones. +Moreover, you can configure the preset with a large number of devices +(more than PiKVM allows by endpoints), and then dynamically enable only +the necessary ones. -If you have configured too many devices that consume more than 9 endpoints in total, -the least important of them will be inactive. You can enable them using dynamic configuration. +If you have configured too many devices that consume more than +9 endpoints in total, the least important of them will be inactive. +You can enable them using dynamic configuration. To configure additional devices, please refer to the corresponding pages: -* [USB Microphone](audio.md) - Two-way audio communication for voice applications on the target host. - Exclusive to [PiKVM V3](v3.md) and [V4 Mini/Plus](v4.md). +* [USB Microphone](audio.md) - Two-way audio communication for voice + applications on the target host. Exclusive to [PiKVM V3](v3.md) and [V4 Mini/Plus](v4.md). -* [Absolute and relative mouse](mouse.md) - The most convenient type of mouse is an absolute mouse, - but some BIOSes may not understand it. In this case, the relative one will help you. +* [Absolute and relative mouse](mouse.md) - The most convenient type + of mouse is an absolute mouse, but some BIOSes may not understand it. + In this case, the relative one will help you. -* [USB Ethernet](usb_ethernet.md) - A FTP or Samba server on PiKVM can be configured, and the target host - will see this over the network. It is also possible that PiKVM can work as a router to connect a host to a big network. +* [USB Ethernet](usb_ethernet.md) - An FTP or Samba server on PiKVM + can be configured, and the target host will see this over the network. + It is also possible that PiKVM can work as a router to connect a host + to a big network. -* [USB Serial Port](usb_serial.md) - It can be used for terminal access from the target host to the PiKVM, - or for any other purpose that requires a serial connection. +* [USB Serial Port](usb_serial.md) - It can be used for terminal access + from the target host to the PiKVM, or for any other purpose that + requires a serial connection. For information on how emulated devices are represented on the target host and how to change it, read [here](id.md). - ----- ## Default preset @@ -90,10 +95,8 @@ otg: The `start` parameter is also available for all USB devices, see `kvmd -m` for the entire configuration tree. - ## Dynamic configuration - ### Command-line utility The `kvmd-otgconf` utility allows you to view and modify the USB configuration on the fly. @@ -102,59 +105,61 @@ It will also inform you about the number of endpoints used. Changing requires root permissions. -View the config. Each line represents an emulated device. -Plus or minus sign means the state (enabled or not), next it displays the device name, -the number of required endpoints and its description. +Let's take a look at the configuration: ```console -[root@pikvm ~]# kvmd-otgconf -# Endpoints used: 7 of 9 -# Endpoints free: 2 -- acm.usb0 # [3] Serial Port -+ hid.usb0 # [1] Keyboard -+ hid.usb1 # [1] Absolute Mouse -+ hid.usb2 # [1] Relative Mouse -+ mass_storage.usb0 # [2] Mass Storage Drive -+ uac2.usb0 # [2] Microphone +[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 ``` -Sometimes it happens that it is impossible to get into the UEFI/BIOS due to their bugs in USB support, -and you need to boot from the PiKVM mass storage. +Each line represents an emulated device, left to right: -In this case you can disable all devices except keyboard and relative mouse, and enter the BIOS: +* Plus or minus sign: the state (enabled or not). +* The device name (e.g., `hid.usb0`). +* The number of required endpoints (e.g., `[2]`). +* The description (e.g., `Absolute mouse`). +* Path to the relevant configuration parameter (e.g., `otg/devices/hid/mouse/start`) you can use to boot or not boot a service when `kvmd` launches. + +Sometimes it's impossible to get into the UEFI/BIOS due to their bugs +in USB support, and you need to boot from the PiKVM mass storage. + +In this case, you can disable all devices except keyboard and relative +mouse, and enter the BIOS: ```console [root@pikvm ~]# kvmd-otgconf -d mass_storage.usb0 uac2.usb0 hid.usb1 # Endpoints used: 2 of 9 # Endpoints free: 7 -- acm.usb0 # [3] Serial Port -+ hid.usb0 # [1] Keyboard -- hid.usb1 # [1] Absolute Mouse -+ hid.usb2 # [1] Relative Mouse -- mass_storage.usb0 # [2] Mass Storage Drive -- uac2.usb0 # [2] Microphone ++ 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 ``` -Then change the boot order in the BIOS by setting the USB sticks as first priority. +Then change the boot order in the BIOS by setting the USB sticks +as first priority. -Exit the BIOS, and turn on mass storage again. Use it as usual to boot the image from PiKVM mass storage: +Exit the BIOS, and turn on mass storage again. Use it as usual to boot +the image from PiKVM mass storage: ```console [root@pikvm ~]# kvmd-otgconf -e mass_storage.usb0 # Endpoints used: 4 of 9 # Endpoints free: 5 -- acm.usb0 # [3] Serial Port -+ hid.usb0 # [1] Keyboard -- hid.usb1 # [1] Absolute Mouse -+ hid.usb2 # [1] Relative Mouse -+ mass_storage.usb0 # [2] Mass Storage Drive -- uac2.usb0 # [2] Microphone ++ 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 ``` You can also enable `uac2.usb0` and `hid.usb1` again. - -### Web UI Menu +### Web UI menu Using the pseudo-GPIO driver, you can USB control devices via the menu in the web interface. Read about GPIO basics [here](gpio.md). @@ -199,4 +204,5 @@ with your existing one in `/etc/kvmd/override.yaml` in a usual way. - ["#Mass Storage Drive", "#mass_storage.usb0", mass_storage.usb0] ``` -Please note that this menu is not dynamically generated, you need to update the configuration if you added or deleted devices. +Please note that this menu is not dynamically generated, you need +to update the configuration if you added or deleted devices.