| 1 | + | ??? warning "USB limitations" |
| 2 | + | **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.** |
| 3 | + | |
| 4 | + | There is a hardware limit on the number of devices that can be emulated at the same time. |
| 5 | + | Each USB device uses so-called endpoints to communicate with the host. |
| 6 | + | Depending on the type, the device consumes a different number of endpoints, |
| 7 | + | while their total number is limited by the capabilities of the chip, **for Raspberry Pi it is 8**. |
| 8 | + | |
| 9 | + | It is quite difficult to calculate the number of endpoints used, but in the case of PiKVM, |
| 10 | + | you can focus on the following numbers: |
| 11 | + | |
| 12 | + | | Device | Endpoints | |
| 13 | + | |--------|-----------| |
| 14 | + | | Keyboard, mouse | 1 for each | |
| 15 | + | | Mass Storage Drive | 2 for each | |
| 16 | + | | USB Ethernet, USB Serial | 3 for each | |
| 17 | + | |
| 18 | + | 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. |
| 19 | + | |
| 20 | + | Creating an axtra Mass Storage Drive consumes additional endpoints, as well as USB Serial and USB Ethernet, |
| 21 | + | so only a limited number of devices can be selected for the final configuration, for example, one USB Ethernet. |
| 22 | + | |
| 23 | + | If you need something more non-standard, you can [disable the regular Mass Storage Drive](msd.md#disable-msd) |
| 24 | + | and the additional mouse (on V4) to free up some extra endpoints. |
| 25 | + | |
| 26 | + | The `kvmd-otg` service is responsible for setting up USB emulation. If the endpoint limit is exceeded, |
| 27 | + | the service will not be able to start and no emulated USB device will work. |
| 28 | + | |
| 29 | + | In the log it looks something like this: |
| 30 | + | |
| 31 | + | ``` |
| 32 | + | # journalctl -u kvmd-otg |
| 33 | + | ... |
| 34 | + | kvmd-otg[382]: kvmd.apps.otg INFO --- ===== Preparing complete ===== |
| 35 | + | kvmd-otg[382]: kvmd.apps.otg INFO --- Enabling the gadget ... |
| 36 | + | kvmd-otg[382]: kvmd.apps.otg INFO --- WRITE --- /sys/kernel/config/usb_gadget/kvmd/UDC |
| 37 | + | kvmd-otg[382]: OSError: [Errno 524] Unknown error 524 |
| 38 | + | kvmd-otg[382]: During handling of the above exception, another exception occurred: |
| 39 | + | kvmd-otg[382]: Traceback (most recent call last): |
| 40 | + | kvmd-otg[382]: File "/usr/bin/kvmd-otg", line 9, in <module> |
| 41 | + | kvmd-otg[382]: main() |
| 42 | + | kvmd-otg[382]: File "/usr/lib/python3.10/site-packages/kvmd/apps/otg/__init__.py", line 348, in main |
| 43 | + | kvmd-otg[382]: options.cmd(config) |
| 44 | + | kvmd-otg[382]: File "/usr/lib/python3.10/site-packages/kvmd/apps/otg/__init__.py", line 278, in _cmd_start |
| 45 | + | kvmd-otg[382]: _write(join(gadget_path, "UDC"), udc) |
| 46 | + | kvmd-otg[382]: File "/usr/lib/python3.10/site-packages/kvmd/apps/otg/__init__.py", line 83, in _write |
| 47 | + | kvmd-otg[382]: with open(path, "w") as file: |
| 48 | + | kvmd-otg[382]: OSError: [Errno 524] Unknown error 524 |
| 49 | + | systemd[1]: kvmd-otg.service: Main process exited, code=exited, status=1/FAILURE |
| 50 | + | systemd[1]: kvmd-otg.service: Failed with result 'exit-code'. |
| 51 | + | systemd[1]: Failed to start PiKVM - OTG setup. |
| 52 | + | ``` |
| 53 | + | |
| 54 | + | In this case, you need to disable some of the previously enabled devices and restart PiKVM. |
| 55 | + | |