pikvm/pikvm#260: usb limits

docs/_usb_limits.md

@@ -0,0 +1,54 @@
+??? warning "USB limitations"
+    **TL;DR: By default, you can add only one additional device to choose from, such as USB Ethernet, or USB Serial, or an extra Mass Storage Drive.**
+
+    There is a hardware limit on the number of devices that can be emulated at the same time.
+    Each USB device uses so-called endpoints to communicate with the host.
+    Depending on the type, the device consumes a different number of endpoints,
+    while their total number is limited by the capabilities of the chip, **for Raspberry Pi it is 8**.
+
+    It is quite difficult to calculate the number of endpoints used, but in the case of PiKVM,
+    you can focus on the following numbers:
+
+    | Device | Endpoints |
+    |--------|-----------|
+    | Keyboard, mouse | 1 for each |
+    | Mass Storage Drive | 2 for each |
+    | USB Ethernet, USB Serial | 3 for each |
+
+    V2 and V3 emulates one mouse by default, V4 emulates two mouses. Thus, V2 and V3 use 4 endpoints, and V4 uses 5 by default.
+
+    Creating an axtra Mass Storage Drive consumes additional endpoints, as well as USB Serial and USB Ethernet,
+    so only a limited number of devices can be selected for the final configuration, for example, one USB Ethernet.
+
+    If you need something more non-standard, you can [disable the regular Mass Storage Drive](msd.md#disable-msd)
+    and the additional mouse (on V4) to free up some extra endpoints.
+
+    The `kvmd-otg` service is responsible for setting up USB emulation. If the endpoint limit is exceeded,
+    the service will not be able to start and no emulated USB device will work.
+
+    In the log it looks something like this:
+
+    ```
+    # journalctl -u kvmd-otg
+    ...
+    kvmd-otg[382]: kvmd.apps.otg                     INFO --- ===== Preparing complete =====
+    kvmd-otg[382]: kvmd.apps.otg                     INFO --- Enabling the gadget ...
+    kvmd-otg[382]: kvmd.apps.otg                     INFO --- WRITE --- /sys/kernel/config/usb_gadget/kvmd/UDC
+    kvmd-otg[382]: OSError: [Errno 524] Unknown error 524
+    kvmd-otg[382]: During handling of the above exception, another exception occurred:
+    kvmd-otg[382]: Traceback (most recent call last):
+    kvmd-otg[382]:   File "/usr/bin/kvmd-otg", line 9, in <module>
+    kvmd-otg[382]:     main()
+    kvmd-otg[382]:   File "/usr/lib/python3.10/site-packages/kvmd/apps/otg/__init__.py", line 348, in main
+    kvmd-otg[382]:     options.cmd(config)
+    kvmd-otg[382]:   File "/usr/lib/python3.10/site-packages/kvmd/apps/otg/__init__.py", line 278, in _cmd_start
+    kvmd-otg[382]:     _write(join(gadget_path, "UDC"), udc)
+    kvmd-otg[382]:   File "/usr/lib/python3.10/site-packages/kvmd/apps/otg/__init__.py", line 83, in _write
+    kvmd-otg[382]:     with open(path, "w") as file:
+    kvmd-otg[382]: OSError: [Errno 524] Unknown error 524
+    systemd[1]: kvmd-otg.service: Main process exited, code=exited, status=1/FAILURE
+    systemd[1]: kvmd-otg.service: Failed with result 'exit-code'.
+    systemd[1]: Failed to start PiKVM - OTG setup.
+    ```
+
+    In this case, you need to disable some of the previously enabled devices and restart PiKVM.

docs/msd.md

@@ -94,6 +94,8 @@ to the server and download some files from to PiKVM from it.
 !!! info
     The presence of an additional Mass Storage Drive should not interfere with the boot, but for reasons of compatibility paranoia, this is disabled by default. We recommend setting up the drives in advance, making sure that booting from the ISO CD is still working, and then using the drives as needed.
 
+{!_usb_limits.md!}
+
 
 ### How to enable extra drives
 

docs/usb_ethernet.md

@@ -2,7 +2,9 @@
 
 ## Basic configuration
 
-Specifically to v2+. When combined with configuring a DNS server, FTP, or SMB (for example), this is a powerful way to extend the capabilities of PiKVM.
+Specifically to V2+. When combined with configuring a DNS server, FTP, or SMB (for example), this is a powerful way to extend the capabilities of PiKVM.
+
+{!_usb_limits.md!}
 
 1. Edit `/etc/kvmd/override.yaml` and add these lines:
 

docs/usb_serial.md

@@ -1,6 +1,8 @@
 # Serial-over-USB connection
 
-Specifically to v2+. This can be used for terminal access from the managed server to the PiKVM, or for any other purpose that requires a serial connection. In the last case, you only need to perform step 1 and reboot.
+Specifically to V2+. This can be used for terminal access from the managed server to the PiKVM, or for any other purpose that requires a serial connection. In the last case, you only need to perform step 1 and reboot.
+
+{!_usb_limits.md!}
 
 1. Edit `/etc/kvmd/override.yaml` and add these lines: