public_git/pikvm
1
0
Fork 0
mirror of https://github.com/pikvm/pikvm.git synced 2026-10-21 00:27:11 +02:00
Code Issues Projects Releases Wiki Activity

ID and USB: add a setup replication howto and update existing content (#1600)

Browse Source 
* 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 20:27:12 +02:00
committed by GitHub
parent 85bdff32d7
commit 5e225eb125
2 changed files with 76 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/usb.md
+55 -49
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
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.