From d224a69616d7db06111ea4397b3d66ffbc606373 Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Sun, 1 Jun 2025 21:23:31 +0300 Subject: [PATCH] id guide --- docs/_edidconf_options.md | 43 +++++ docs/{override.md => config.md} | 0 docs/{override => config}/kvmd-hid-keymap.png | Bin docs/{override => config}/nano-start.png | Bin docs/{override => config}/save-exit.png | Bin docs/edid.md | 151 ++++++++++++------ docs/id.md | 145 +++++++++++++++++ docs/v1.md | 1 + docs/v2.md | 1 + docs/v3.md | 1 + docs/v4.md | 1 + mkdocs.yml | 1 + 12 files changed, 293 insertions(+), 51 deletions(-) create mode 100644 docs/_edidconf_options.md rename docs/{override.md => config.md} (100%) rename docs/{override => config}/kvmd-hid-keymap.png (100%) rename docs/{override => config}/nano-start.png (100%) rename docs/{override => config}/save-exit.png (100%) create mode 100644 docs/id.md diff --git a/docs/_edidconf_options.md b/docs/_edidconf_options.md new file mode 100644 index 00000000..c18ceb19 --- /dev/null +++ b/docs/_edidconf_options.md @@ -0,0 +1,43 @@ +--- +search: + exclude: true +--- + +!!! tip "Quick IDs changing on PiKVM V4 Plus" + + PiKVM V4 Plus has a simple way read and adopt display identifiers like model and serial number + from your physical display. See [here](edid.md#adopt-real-display-indentifiers-on-v4-plus) for details. + +Run `kvmd-edidconf` on PiKVM: + +```console +[root@pikvm ~]# kvmd-edidconf +Manufacturer ID: LNX +Product ID: 0x7773 (30579) +Serial number: 0x01010101 (16843009) +Monitor name: PiKVM V4 Plus +Monitor serial: CAFEBABE +Audio: yes +``` + +The fields have obvious names and purposes. Note the two similar fields `Serial number` and `Monitor serial`. +The first has a numeric value, and the second is ASCII. If you are using a custom EDID from some real display, some fields may be missing. + +To change the values of the EDID fields, use the `kvmd-edidconf` with options, a complete list is available in `kvmd-edidconfi --help`. + +Here the small example of changing all available fields from the previous listing: + +``` +[root@pikvm ~]# rw +[root@pikvm ~]# kvmd-edidconf --set-mfc-id=TTP --set-product-id=0x5B81 --set-serial=0x8DE11B79 --set-monitor-name=TOSHIBA --set-monitor-serial=ABCD1234 --apply +Manufacturer ID: TTP +Product ID: 0x5B81 (23425) +Serial number: 0x8DE11B79 (2380340089) +Monitor name: TOSHIBA +Monitor serial: ABCD1234 +Audio: yes +... +[root@pikvm ~]# ro +``` + +The full list of manufacturer IDs is available [here](https://uefi.org/pnp_id_list). diff --git a/docs/override.md b/docs/config.md similarity index 100% rename from docs/override.md rename to docs/config.md diff --git a/docs/override/kvmd-hid-keymap.png b/docs/config/kvmd-hid-keymap.png similarity index 100% rename from docs/override/kvmd-hid-keymap.png rename to docs/config/kvmd-hid-keymap.png diff --git a/docs/override/nano-start.png b/docs/config/nano-start.png similarity index 100% rename from docs/override/nano-start.png rename to docs/config/nano-start.png diff --git a/docs/override/save-exit.png b/docs/config/save-exit.png similarity index 100% rename from docs/override/save-exit.png rename to docs/config/save-exit.png diff --git a/docs/edid.md b/docs/edid.md index 7b0a1884..9dd76009 100644 --- a/docs/edid.md +++ b/docs/edid.md @@ -1,25 +1,42 @@ # EDID +!!! info + + 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. + + +The EDID provides an information about the video modes supported by the video capture device. +In the case of PiKVM, this is an HDMI CSI bridge. +Usually, you don't need to change this, since the default configuration is quite flexible, +but sometimes, for example for strange UEFIs/BIOSes, this may be necessary +([a story](https://github.com/pikvm/pikvm/issues/78)). + + +----- +## Basics + +The EDID is stored on the PiKVM in the file `/etc/kvmd/tc358743-edid.hex` in HEX format. +When booting PiKVM OS, it is used by `kvmd-tc358743.service` and loaded into the video capture chip. + +If you replace the EDID in this file, the EDID can be applied manually without rebooting +using the command `kvmd-edidconf --apply`. + +If you just want to change the monitor's identification, we don't recommend that you change the entire EDID. +Just use `kvmd-edidconf` and its built-in EDID changing options. + !!! note - This will only apply to the CSI models include V3+, USB capture is not compatable. - Modifing the EDID may or may not work in some instances where a "no signal" might be a result of outside factors. + Windows caches drivers and registry settings so changing the monitor name is not enough, + you will also need to change the product ID and/or the serial number along with the monitor name: -EDID is information about the video modes supported by the video capture device. -In the case of PiKVM, this is an HDMI CSI bridge. Usually, you don't need to change this, since the default configuration is quite flexible, -but sometimes, for example for strange UEFIs/BIOSes, this may be necessary (the [story](https://github.com/pikvm/pikvm/issues/78)). + ```console + [root@pikvm ~]# kvmd-edidconf --set-monitor-name=TOSHIBA --set-mfc-id=TTP --set-product-id=34953 --set-serial=2290649089 --apply + ``` -The EDID is stored on the PiKVM in the file `/etc/kvmd/tc358743-edid.hex`. If you write new data there, it will be applied after rebooting -or using the command `kvmd-edidconf --apply`. +{!_edidconf_options.md!} -You can also apply the new EDID without rebooting to make sure it works: - -* Switch filesystem to RW-mode: `rw`. -* Create the new EDID file `/root/edid.hex` (examples of file contents are shown below). -* Apply EDID using the command `kvmd-edidconf --edid=/root/edid.hex --apply`. -* DO NOT REBOOT the PiKVM. Just your PC. Check the UEFI/BIOS or the OS. -* If everything is working, you can make this config permanent: `kvmd-edidconf --import=/root/edid.hex`. This command will write the EDID to `/etc/kvmd/tc358743-edid.hex` in a pretty format. -* Switch filesystem to RO-mode: `ro`. +Typical examples of working with EDID and the full cycle of using custom EDID will be shown below. ----- @@ -37,7 +54,7 @@ To adopt display identifiers, connect the display to `OUT2` port and run these c [root@pikvm ~]# ro ``` -The display can be unplugged. PiKVM will remember the new settings. +Now the display can be unplugged. PiKVM will remember the new settings. ----- @@ -73,7 +90,7 @@ so you can force 1080p resolution by default: ----- ## Disable 1920x1200 on PiKVM V4 -PiKVM V4 supports the advanced capture mode of 1920x1200. If it bothers you +PiKVM V4 supports the advanced capture mode with 1920x1200. If it bothers you (for example, if you use a physical monitor 1920x1080 with [video passthrough](pass.md)), you can easily disable it and use only 1920x1080: @@ -85,9 +102,24 @@ you can easily disable it and use only 1920x1080: ----- -## Other EDID examples for PiKVM V4 +## Applying a custom EDID -PiKVM V4 can mimic many physical monitors. You can find the appropriate EDID in [this database](https://github.com/linuxhw/EDID) and import its HEX code to PiKVM. Choose something with a maximum resolution of 1920x1080 or 1920x1200. +PiKVM is able to emulate a physical display with a specific EDID. +You can find EDID examples in the [community database](https://github.com/linuxhw/EDID) +and then use it on PiKVM. + +At the same time, you should pay attention to the hardware capabilities of PiKVM +and the EDID capabilities that you use. For example, if EDID reports 8K support, +then this obviously won't work: your host will try to send an 8K signal, +while PiKVM can process no more than 1080p. + +* PiKVM V1-V3: The maximum resolution is 1920x1080 at 50Hz. +* PiKVM V4: The maximum is 1920x1200 at 60Hz. + +In the case of the [PiKVM V4](v4.md), almost any EDID for 1080p monitors will work. +All EDIDs that are suitable for [PiKVM V3](v3.md) will work too. + +### Example EDIDs for PiKVM V4 ??? example "Acer B246WL, 1920x1200, with audio" Taken [here](https://github.com/linuxhw/EDID/blob/master/Digital/Acer/ACR0565/CCF78B30FE61), as described above. @@ -131,7 +163,6 @@ PiKVM V4 can mimic many physical monitors. You can find the appropriate EDID in 001800000000000000000000000000DC ``` - ??? example "DELL D2721H to avoid black screen on some HDMI splitters, 1920x1080, no audio" Taken [here](https://github.com/linuxhw/EDID/blob/master/Digital/Dell/DEL2013/EEE824E681BF), as described above. ``` @@ -153,11 +184,7 @@ PiKVM V4 can mimic many physical monitors. You can find the appropriate EDID in 0000000000000000000000000000004F ``` - ------ -## EDID examples for PiKVM V2+ - -Copy the contents into a file, for example `/root/edid.hex`, then follow the same steps as above. +### Example EDIDs for PiKVM V1-V3 ??? example "1280x1024 as preferred. Useful for Gigabyte GA-H77-DS3H" ``` @@ -219,6 +246,40 @@ Copy the contents into a file, for example `/root/edid.hex`, then follow the sam 00000000000000000000000000000045 ``` +### Applying a choosen custom EDID + +To apply the selected EDID, follow these steps: + +1. Switch filesystem to RW-mode: + + ```console + [root@pikvm ~]# rw + ``` + +2. Open the file `/etc/kvmd/tc358743-edid.hex` with any text editor, for example, with Nano: + + ```console + [root@pikvm ~]# nano /etc/kvmd/tc358743-edid.hex + ``` + +3. Replace the HEX data with the new, save and close the editor. + +4. Apply the EDID: + + ```console + [root@pikvm ~]# kvmd-edidconf --apply + ``` + +5. Sometimes it may be necessary to reboot the target host. Check the OS on the host, UEFI/BIOS. + If everything works, then your goal has been achieved and proceed to the last step. + If something went wrong, you can always undo these changes and [restore the default EDID](#restore-default-edid). + +6. Don't forget to switch filesystem to the RO-mode: + + ```console + [root@pikvm ~]# ro + ``` + ----- ## Editing EDID @@ -230,46 +291,34 @@ to PiKVM using the `kvmd-edidconf` utility. So, to tune EDID on PiKVM, use the following steps: -1. Switch filesystem to RW-mode: `rw`. +1. Switch filesystem to RW-mode: -2. Export the system edid to the binary file `myedid.bin`: + ```console + [root@pikvm ~]# rw + ``` + +2. Export the system EDID to the binary file `myedid.bin`: ```console # kvmd-edidconf --export-bin=/root/myedid.bin ``` -3. Copy this file to your PC with the editor. Use SCP, Putty or something like that. Open this binary file in the editor and change the necessary parameters. Edit, save and copy it back to PiKVM. +3. Copy this file to your PC using SCP, Putty or something like that. + Open this binary file in the EDID editor and change the necessary parameters. + Save your changes and copy the binary file back to PiKVM. 4. Convert the binary file to the HEX and test it: - ```console - [root@pikvm ~]# kvmd-edidconf --import=/root/myedid.bin --edid=/root/myedid.hex --apply - ``` - -5. If everything works fine, install the new EDID file into the system: - - ```console - [root@pikvm ~]# cp /root/myedid.hex /etc/kvmd/tc358743-edid.hex - ``` - -6. Alternative to step (4) and (5): if you are confident in your abilities, you can immediately install the new `myedit.bin` into the system and apply it instantly, without the need to use the temporary `myedid.hex`: - ```console [root@pikvm ~]# kvmd-edidconf --import=/root/myedid.bin --apply ``` -7. Switch filesystem to RO-mode: `ro`. +5. Sometimes it may be necessary to reboot the target host. Check the OS on the host, UEFI/BIOS. + If everything works, then your goal has been achieved and proceed to the last step. + If something went wrong, you can always undo these changes and [restore the default EDID](#restore-default-edid). -The `kvmd-edidconfig` utility has the ability to change some simple parameters without using an external editor. For example you can change the vendor, model name and enable [HDMI audio](audio.md) on the PiKVM virtual display: - -```console -[root@pikvm ~]# kvmd-edidconf --set-mfc-id=LNX --set-monitor-name=PiKVM --set-audio=1 --apply -``` - -!!! note - - Windows cache's drivers and registry settings so changing the monitor name is not enough, you will also need to change the product ID and/or the serial number along with the monitor name: +6. Don't forget to switch filesystem to the RO-mode: ```console - [root@pikvm ~]# kvmd-edidconf --set-monitor-name=TOSHIBA --set-mfc-id=TTP --set-product-id=34953 --set-serial=2290649089 --apply + [root@pikvm ~]# ro ``` diff --git a/docs/id.md b/docs/id.md new file mode 100644 index 00000000..f3aa73e4 --- /dev/null +++ b/docs/id.md @@ -0,0 +1,145 @@ +# Identifying PiKVM on the target host + +This page explains how PiKVM is presented to the target host's operating system, and how this can be changed. +This is useful for developers, testers and system administrators who need PiKVM to emulate a specific USB device or monitor. + +!!! info + + Before exploring this page, we recommend to read the [PiKVM configuration guide](config.md) + so that you understand the terminology and how exactly the parameters described below change. + + +----- +## Basics + +PiKVM is a combined emulator of several devices for user interaction. +Simply put, your host sees the connected PiKVM not just as a single device, but as a set of multiple devices. + +In the most default case out of the box, these are the following: + +- HDMI video display; +- USB keyboard; +- USB mouse (two mice for [PiKVM V4](v4.md)); +- USB mass storage drive (ejectable); + +Thus, PiKVM emulates two types of devices: HDMI and USB. Each of them has a specific set of identifiers. +For example, if you go to monitor settings on the host, you will see something like `PiKVM V4 Plus`. +It works in a similar way with USB. + + +----- +## HDMI Identifiers + +!!! info + + 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. + +The EDID (Extended Display Identification Data) is responsible for preseting the display. +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. + +{!_edidconf_options.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. + + +----- +## USB Identifiers + +USB is a much more complex subsystem and another part of PiKVM is responsible for it. +Be careful when changing the settings here, it may cause the USB to fail. + +As you may have found out from the [PiKVM configuration guide](config.md) (if you haven't read it yet, now is the time), +you can get the list of all configuration parameters using the `kvmd -m` command. + +Below is a listing of all the parameters, from which the unrelated and those USB parameters +that should not be changed have been removed. In the context of identifiers, we are interested in the following: + +```yaml +[root@pikvm ~]# kvmd -m +otg: + vendor_id: 7531 + product_id: 260 + manufacturer: PiKVM + product: PiKVM Composite Device + serial: CAFEBABE + device_version: -1 + max_power: 250 + + devices: + drives: + default: + inquiry_string: + cdrom: + vendor: PiKVM + product: Optical Drive + revision: '1.00' + + flash: + vendor: PiKVM + product: Flash Drive + revision: '1.00' + + msd: + default: + inquiry_string: + cdrom: + vendor: PiKVM + product: Optical Drive + revision: '1.00' + + flash: + vendor: PiKVM + product: Flash Drive + revision: '1.00' +``` + +Pay attention to the nesting levels. The parameters are always located in certain sections. +All numeric values are displayed in decimal form, but in the config you can use a hex form. +The generally accepted names from the USB specifications are shown in parentheses. + +* `vendor_id` (`idVendor`) - Unique [vendor ID](https://usb.org/sites/default/files/vendor_ids051920_0.pdf) assigned by USB.org. +* `product_id` (`idProduct`) - Just an ID for the product assigned by this vendor. +* `manufacturer` (`iManufacturer` to 0x409) - ASCII name of the vendor. +* `product` (`iProduct` to 0x409) - ASCII name of the product. +* `serial` (`iSerialNumber` to 0x409) - ASCII serial number of the product. +* `device_version` (`bcdDevice`) - Kinda the revision of the device. Assigned automatically. It can be changed to 256, 257, 258 or something like this. + +The strings under `otg/drives` and `otg/msd` sections deserve a special description. +They relate to virtual media emulation and are separate parts of the SCSI inquiry string, the drive identifier used by the OS driver. +All three parameters `vendor`, `product`, and `revision` are short ASCII strings responsible for CD/DVD or Flash representation. + +The `msd` refers to a virtual drive accessible from the Web UI, +and the `drives` describes all additional drives if you have configured them (disabled by default). + +To change the parameters, use the `/etc/kvmd/override.yaml`, for example, like this: + +```yaml +otg: + vendor_id: 0x6940 + product_id: 0x6973 + manufacturer: Corsair + product: Gaming RGB + serial: 1000 + + devices: + msd: + default: + inquiry_string: + cdrom: + vendor: Corsair + product: DVD + revision: '1.00' + + flash: + vendor: Corsair + product: STICK + revision: '1.00' +``` + +After changing validate the config using `kvmd -m`. You will see the full config list with changed and default values, +or a message about configuration error. + +If everything is fine, perform the soft reboot. diff --git a/docs/v1.md b/docs/v1.md index fbf6ac34..a87b994a 100644 --- a/docs/v1.md +++ b/docs/v1.md @@ -300,6 +300,7 @@ To do that: - [Harden the remote access](auth.md) by enabling 2FA and setting session expiration time. - Configure access to PiKVM from the Internet using [port forwarding](port_forwarding.md) or [Tailscale VPN](tailscale.md). - [Learn](config.md) how configuration files are structured. +- Read how PiKVM is [identified](id.md) on the target host. ----- diff --git a/docs/v2.md b/docs/v2.md index 6e7b7f66..098b27ad 100644 --- a/docs/v2.md +++ b/docs/v2.md @@ -331,6 +331,7 @@ To do that: - [Harden the remote access](auth.md) by enabling 2FA. - Configure access to PiKVM from the Internet using [port forwarding](port_forwarding.md) or [Tailscale VPN](tailscale.md). - [Learn](config.md) how configuration files are structured. +- Read how PiKVM is [identified](id.md) on the target host. ----- diff --git a/docs/v3.md b/docs/v3.md index 6b84263a..79f60921 100644 --- a/docs/v3.md +++ b/docs/v3.md @@ -257,6 +257,7 @@ To do that: - Configure access to PiKVM from the Internet using [port forwarding](port_forwarding.md) or [Tailscale VPN](tailscale.md). - Enable a microphone for [two-way audio](audio.md). - [Learn](config.md) how configuration files are structured. + - Read how PiKVM is [identified](id.md) on the target host. 2. **Configure hardware**: diff --git a/docs/v4.md b/docs/v4.md index ca1c9017..ee73b7a0 100644 --- a/docs/v4.md +++ b/docs/v4.md @@ -242,6 +242,7 @@ To do that: - Enable a microphone for [two-way audio](audio.md). - Enable [HDMI pass-through](pass.md) and [USB passthrough](usb_pass.md). - [Learn](config.md) how configuration files are structured. + - Read how PiKVM is [identified](id.md) on the target host. 2. **Configure hardware**: diff --git a/mkdocs.yml b/mkdocs.yml index e58d140b..5baf1dbb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -77,6 +77,7 @@ plugins: "webrtc.md": "video.md" "first_steps.md": "cheatsheet.md" "cheat_sheet.md": "cheatsheet.md" + "override.md": "config.md" - glightbox: touchNavigation: false loop: false