public_git
/
pikvm
mirror of https://github.com/pikvm/pikvm.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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
This commit is contained in:
Aleksandr Prokudin 2025-10-28 19:27:12 +01:00 committed by GitHub
parent 85bdff32d7
commit 5e225eb125
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 76 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
docs/id.md
View File

@ -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. 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. 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. 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. More information about this is written on [this page](edid.md), and here we will provide brief information.
{!_edidconf_options.md!} {!_edidconf_options.md!}
For a detailed guide on customizing EDID, please visit [this page](edid.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.
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. or a message about configuration error.
If everything is fine, perform the soft reboot. 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.

102
docs/usb.md
View File

@ -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 requires a reboot, but it is possible to temporarily disable and then
re-enable existing emulated devices in preset. re-enable existing emulated devices in preset.
----- -----
## Basics ## 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. * 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), Moreover, you can configure the preset with a large number of devices
and then dynamically enable only the necessary ones. (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, If you have configured too many devices that consume more than
the least important of them will be inactive. You can enable them using dynamic configuration. 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: 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. * [USB Microphone](audio.md) - Two-way audio communication for voice
Exclusive to [PiKVM V3](v3.md) and [V4 Mini/Plus](v4.md). 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, * [Absolute and relative mouse](mouse.md) - The most convenient type
but some BIOSes may not understand it. In this case, the relative one will help you. 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 * [USB Ethernet](usb_ethernet.md) - An FTP or Samba server on PiKVM
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. 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, * [USB Serial Port](usb_serial.md) - It can be used for terminal access
or for any other purpose that requires a serial connection. 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). For information on how emulated devices are represented on the target host and how to change it, read [here](id.md).
----- -----
## Default preset ## 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. The `start` parameter is also available for all USB devices, see `kvmd -m` for the entire configuration tree.
## Dynamic configuration ## Dynamic configuration
### Command-line utility ### Command-line utility
The `kvmd-otgconf` utility allows you to view and modify the USB configuration on the fly. 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. Changing requires root permissions.
View the config. Each line represents an emulated device. Let's take a look at the configuration:
Plus or minus sign means the state (enabled or not), next it displays the device name,
the number of required endpoints and its description.
```console ```console
[root@pikvm ~]# kvmd-otgconf [root@pikvm ~]# kvmd-otgconf
# Endpoints used: 7 of 9 # Endpoints used: 5 of 9
# Endpoints free: 2 # Endpoints free: 4
- acm.usb0 # [3] Serial Port + hid.usb0 # [1] Keyboard # otg/devices/hid/keyboard/start
+ hid.usb0 # [1] Keyboard + hid.usb1 # [1] Absolute Mouse # otg/devices/hid/mouse/start
+ hid.usb1 # [1] Absolute Mouse + hid.usb2 # [1] Relative Mouse # otg/devices/hid/mouse_alt/start
+ hid.usb2 # [1] Relative Mouse + mass_storage.usb0 # [2] Mass Storage Drive # otg/devices/msd/start
+ mass_storage.usb0 # [2] Mass Storage Drive
+ uac2.usb0 # [2] Microphone
``` ```
Sometimes it happens that it is impossible to get into the UEFI/BIOS due to their bugs in USB support, Each line represents an emulated device, left to right:
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: * 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 ```console
[root@pikvm ~]# kvmd-otgconf -d mass_storage.usb0 uac2.usb0 hid.usb1 [root@pikvm ~]# kvmd-otgconf -d mass_storage.usb0 uac2.usb0 hid.usb1
# Endpoints used: 2 of 9 # Endpoints used: 2 of 9
# Endpoints free: 7 # Endpoints free: 7
- acm.usb0 # [3] Serial Port + hid.usb0 # [1] Keyboard # otg/devices/hid/keyboard/start
+ hid.usb0 # [1] Keyboard - hid.usb1 # [1] Absolute Mouse # otg/devices/hid/mouse/start
- hid.usb1 # [1] Absolute Mouse + hid.usb2 # [1] Relative Mouse # otg/devices/hid/mouse_alt/start
+ hid.usb2 # [1] Relative Mouse - mass_storage.usb0 # [2] Mass Storage Drive # otg/devices/msd/start
- mass_storage.usb0 # [2] Mass Storage Drive
- uac2.usb0 # [2] Microphone
``` ```
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 ```console
[root@pikvm ~]# kvmd-otgconf -e mass_storage.usb0 [root@pikvm ~]# kvmd-otgconf -e mass_storage.usb0
# Endpoints used: 4 of 9 # Endpoints used: 4 of 9
# Endpoints free: 5 # Endpoints free: 5
- acm.usb0 # [3] Serial Port + hid.usb0 # [1] Keyboard # otg/devices/hid/keyboard/start
+ hid.usb0 # [1] Keyboard - hid.usb1 # [1] Absolute Mouse # otg/devices/hid/mouse/start
- hid.usb1 # [1] Absolute Mouse + hid.usb2 # [1] Relative Mouse # otg/devices/hid/mouse_alt/start
+ hid.usb2 # [1] Relative Mouse + mass_storage.usb0 # [2] Mass Storage Drive # otg/devices/msd/start
+ mass_storage.usb0 # [2] Mass Storage Drive
- uac2.usb0 # [2] Microphone
``` ```
You can also enable `uac2.usb0` and `hid.usb1` again. 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. Using the pseudo-GPIO driver, you can USB control devices via the menu in the web interface.
Read about GPIO basics [here](gpio.md). 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] - ["#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.