You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
pikvm/docs/usb_dynamic.md

3.4 KiB

Dynamic USB configuration

PiKVM emulates a number of USB devices to ensure normal operation: keyboards, mouse and mass storage drive. Also an additional relative mouse may be present (like on PiKVM V4 by default), or a user configured USB Ethernet or Serial port.

In rare cases, the host BIOS/UEFI may not understand such a large number of emulated devices on single USB port, so some of them may need to be disabled. USB reconfiguration usually requires a reboot, but it is possible to temporarily disable already configured existing emulated devices.

!!! warning This feature is experimental. Due to the imperfections of the kernel modules, rarely a dynamic configuration change can lead to a kernel panic and reboot.

For PiKVM V3 and V4 this is considered more secure because they have two independent watchdog systems
that can bring devices back to life after a timeout of a few minutes.

Command-line utility

The kvmd-otgconf utility allows you to view and modify the USB configuration on the fly. It requires root permission and can be used for example from a web terminal.

View the config:

# kvmd-otgconf
+ hid.usb0  # Keyboard
+ hid.usb1  # Absolute Mouse
+ hid.usb2  # Relative Mouse
+ mass_storage.usb0  # Mass Storage Drive

Each line represents a device (function). First comes plus or minus sign (the device on or off), then the name of the device and its description.

Disabling the device:

[root@pikvm ~]# kvmd-otgconf --disable-function mass_storage.usb0
+ hid.usb0  # Keyboard
+ hid.usb1  # Absolute Mouse
+ hid.usb2  # Relative Mouse
- mass_storage.usb0  # Mass Storage Drive

Enabling the device:

[root@pikvm ~]# kvmd-otgconf --enable-function mass_storage.usb0
+ hid.usb0  # Keyboard
+ hid.usb1  # Absolute Mouse
+ hid.usb2  # Relative Mouse
+ mass_storage.usb0  # Mass Storage Drive

Web UI menu

Using the pseudo-GPIO driver, you can also control devices via the menu in the web interface. Read about GPIO basics here.

To setup the menu, use kvmd-otgconf to generate the configuration, and combine it with your existing one in /etc/kvmd/override.yaml in a usual way.

# kvmd-otgconf --make-gpio-config
kvmd:
    gpio:
        drivers:
            otgconf:
                type: otgconf
        scheme:
            hid.usb0:
                driver: otgconf
                mode: output
                pin: hid.usb0
                pulse:
                    delay: 0
            hid.usb1:
                driver: otgconf
                mode: output
                pin: hid.usb1
                pulse:
                    delay: 0
            hid.usb2:
                driver: otgconf
                mode: output
                pin: hid.usb2
                pulse:
                    delay: 0
            mass_storage.usb0:
                driver: otgconf
                mode: output
                pin: mass_storage.usb0
                pulse:
                    delay: 0
        view:
            table:
            -   - '#Keyboard'
                - '#hid.usb0'
                - hid.usb0
            -   - '#Absolute Mouse'
                - '#hid.usb1'
                - hid.usb1
            -   - '#Relative Mouse'
                - '#hid.usb2'
                - hid.usb2
            -   - '#Mass Storage Drive'
                - '#mass_storage.usb0'
                - mass_storage.usb0