diff --git a/docs/_diy_parts_pico_hid.md b/docs/_diy_parts_pico_hid.md index 8800cf0..5ea44d1 100644 --- a/docs/_diy_parts_pico_hid.md +++ b/docs/_diy_parts_pico_hid.md @@ -1,4 +1,15 @@ * *x1* [Raspberry Pi Pico board](https://www.raspberrypi.com/products/raspberry-pi-pico/) with soldered pins. + * *x1* USB-A to Micro-USB cable. + * *x10* dupont wires female-female. + * *x1* 1N5819 diode. It's optional but strongly recommended. Any similar one will do. + + !!! warning + The diode is needed to provide power to the Pico HID regardless of the target host state, + which prevents the backpowering problem. It will allow you to keep the keyboard buttons pressed + during the target host power cycle, which is, for example, important for MacOS to get into the boot menu. + + Do not connect the red wire (the `VSYS (Pico) -> 5V (Pi)` line) without a diode. + If you can't find a diode, don't connect this wire at all. diff --git a/docs/first_steps.md b/docs/first_steps.md index 03b3cb3..53b14be 100644 --- a/docs/first_steps.md +++ b/docs/first_steps.md @@ -13,11 +13,11 @@ 1. Optional: [setting up Wi-Fi](on_boot_config.md) before booting.
*There is nothing more reliable than wired Ethernet, so it's better to use a cable.* -2. Power up the device. +2. **Power up the device.** -3. Do not turn off the device until it's fully booted for the first time.
+3. **Do not turn off the device until it's fully booted for the first time.**
*After turning on the power, PiKVM OS will generate unique SSH keys and certificates - and perform all necessary operations on the memory card.* + and perform all necessary operations on the memory card. It takes a few minutes.* ----- @@ -52,14 +52,23 @@ For future examples, let's assume that your PiKVM has received the address **192 **The default `root` password is `root`.** -??? example "OPTIONAL: Update PiKVM software" - This part is not nessessary for a working OOB experience and should only be performed if you are physically at the PiKVM to recover it, you however, may benefit from performing the below actions. These are the instructions: +PiKVM OS often receives software updates. After installation, it makes sense to update the OS. +It's best to do this now, when you have physical access to the device, because if something goes wrong +(for example, the power goes out during the update), you will need to [reflash the memory card](flashing_os.md). - ``` - rw - pacman -Syu - reboot - ``` +!!! tip "Obtaining root access" + * If you have logged in via SSH, then most likely you are already `root`. + * To get `root` in the Web Terminal, use command `su -` and enter the root password. + +To update, run these commands under the `root` user: + +```console +[root@pikvm]# rw +[root@pikvm]# pacman -Syu +[root@pikvm]# reboot +``` + +**And then, after all...** {!_passwd.md!} @@ -67,11 +76,7 @@ For future examples, let's assume that your PiKVM has received the address **192 ----- ## Configuring PiKVM -Most of the PiKVM settings are done through configuration files. All configuration changes must be made from under the `root` user (= the administrator). - -!!! tip "Obtaining root access" - * If you have logged in via SSH, then most likely you are already `root`. - * To get `root` in the Web Terminal, use command `su -` and enter the root password. +Most of the PiKVM settings are done through configuration files. All configuration changes must be made from under the `root` user (i.e. the administrator). The PiKVM memory card is mounted in read-only mode. It protects the filesystem from damage in case of sudden power outage. To edit any files and make changes, it is necessary to remount the file system to the read-write mode. @@ -83,11 +88,13 @@ The PiKVM memory card is mounted in read-only mode. It protects the filesystem f In this handbook, you will often find instructions for editing configuration files. The simplest and most beginner-friendly text editor is `nano`, but you can also use `vim`. ??? example "Editing files in the Web Terminal" - ``` - $ su - - # rw - # nano /etc/kvmd/override.yaml - # ro + ```console + [kvmd-webterm@pikvm ~]$ su - + [root@pikvm ~]# rw + [root@pikvm ~]# nano /etc/kvmd/override.yaml + [root@pikvm ~]# ro + [root@pikvm ~]# exit + [kvmd-webterm@pikvm ~]$ ``` ----- diff --git a/docs/pico_hid.md b/docs/pico_hid.md index 48750d6..a137f2b 100644 --- a/docs/pico_hid.md +++ b/docs/pico_hid.md @@ -25,29 +25,24 @@ This page explains how to build, connect and use all the features of the Pico HI ----- ## Making the Pico HID -If you are building the [PiKVM V1](v1.md), then all the necessary components should already be at your fingertips. -If you are making the Pico HID for [V2](v2.md) or [V3](v3.md), then here is all that you will need: +If you are building [PiKVM V1](v1.md), then the hardware should already be assembled. Skip this step unless you need PS/2 support. -{!_diy_parts_pico_hid.md!} +But if you are making the Pico HID for [V2](v2.md) or [V3](v3.md), then follow this guide: -!!! tip "Tip for soldering gurus" - If you know how to solder, you can buy the Pico without pins and just solder everything without needig the dupond wires. +??? example "The Pico HID from scratch" -!!! warning - The diode is needed to provide power to the Pico HID regardless of the host state, - which prevents the backpowering problem. It will allow you to keep the keyboard buttons pressed - during the host power cycle, which is, for example, important for MacOS to get into the boot menu. + Parts list: + + {!_diy_parts_pico_hid.md!} - Do not connect the red wire (the `VSYS (Pico) -> 5V (Pi)` line) without a diode. - If you can't find a diode, don't connect this wire at all. + Connect all the parts according to this scheme: -Connect all the parts according to this scheme: + ??? example "Simple wiring diagram" + -??? example "Simple wiring diagram" - + ??? example "Electrical schematic diagram for advanced users" + -??? example "Electrical schematic diagram for advanced users" - ### PS/2 Keyboard & Mouse @@ -129,7 +124,7 @@ To upload the firmware to Pico HID, you can use any computer with a USB port. 2. Press and hold the white button on the Pico board. 3. While still holding the button, plug it in the computer using a USB cable. 4. Release the button. -5. The Pico board appears as a flash drive on the host computer. +5. The Pico board appears as a flash drive on your computer. 6. Copy the `pico-hid.uf2` file to this flash drive. 7. Safely eject the USB device. @@ -137,7 +132,7 @@ To upload the firmware to Pico HID, you can use any computer with a USB port. ----- ## The final steps -Connect the Pico HID to the host computer using the USB cable. +Connect the Pico HID to a computer using the USB cable. If you are building PiKVM [V1](v1.md), no further action with the Pico HID is required. diff --git a/docs/v1.md b/docs/v1.md index c232b8a..096ec8c 100644 --- a/docs/v1.md +++ b/docs/v1.md @@ -8,14 +8,14 @@ ----- ## Required parts -1. **Raspberry Pi board**: +1. **Raspberry Pi board** * **✮ ✮ ✮ [Raspberry Pi 3](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/)**.
* ... or [Raspberry Pi 2](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/).
*Does not support H.264 even with HDMI-CSI bridge.* -2. **MicroSD card minimum 8Gb class 10**. +2. **MicroSD card minimum 8Gb class 10** -3. **Video capture device**: +3. **Video capture device** * **✮ ✮ ✮ [HDMI-CSI bridge based on TC358743 chip](https://www.amazon.de/Waveshare-Raspberry-Supports-Backward-Compatible/dp/B092HVP926/)**.
*Supports H.264 video encoding on Raspberry Pi 3, automatic resolution selection and the lowest possible latency.* * ... or [HDMI-USB dongle](https://www.amazon.com/Capture-Streaming-Broadcasting-Conference-Teaching/dp/B09FLN63B3).
@@ -25,24 +25,32 @@ 4. **[Official USB-Micro Power Supply](https://www.amazon.com/Capture-Streaming-Broadcasting-Conference-Teaching/dp/B09FLN63B3)**. -5. **The Pico HID Keyboard & mouse emulator**: +5. **The Pico HID Keyboard & mouse emulator** {!_diy_parts_pico_hid.md!} -6. **Optional feature: ATX controller** +6. **Optional features** - {!_diy_parts_atx.md!} + ??? success "✮ ✮ ✮ ATX controller to manage the target host's power" -7. **Optional feature: VGA video capture** + {!_diy_parts_atx.md!} - If you want to capture VGA from your server instead of HDMI, buy the [VGA-to-HDMI converter](https://aliexpress.com/item/3256801728005613.html). - Some converters have issues with not supporting all resolutions and refresh rates. + ??? note "PS/2 Keyboard & mouse" + + The use of PS/2 is intended for advanced users. Check out the additional list of details in advance + in the [corresponding paragraph](pico_hid.md#ps2-keyboard-mouse) of the Pico HID manual. + + ??? note "VGA video capture" + + If you want to capture VGA from your server instead of HDMI, + buy the [VGA-to-HDMI converter](https://aliexpress.com/item/3256801728005613.html). + Some converters have issues with not supporting all resolutions and refresh rates. ----- ## Setting up the hardware -1. **Video capture device**: +1. **Video capture device** ??? success "✮ ✮ ✮ HDMI-CSI bridge" @@ -52,10 +60,33 @@ {!_diy_setup_video_usb.md!} -2. **[Build the Pico HID Keyboard & Mouse emulator](pico_hid.md)**. +2. **The Pico HID and ATX controller** + + Connect all the parts according to this scheme: + + ??? success "✮ ✮ ✮ With ATX controller" + + ??? example "Simple wiring diagram" + + + ??? example "Electrical schematic diagram for advanced users" + + ??? note "... or without ATX controller" + + ??? example "Simple wiring diagram" + + + ??? example "Electrical schematic diagram for advanced users" + + +3. **[Flash firmware to the Pico HID](pico_hid.md)** + + +----- +## Wiring with the target host -!!! warning "WORK IN PROGRESS" +!!! warning "Under construction" ----- diff --git a/docs/v1/v1_breadboard.png b/docs/v1/v1_breadboard.png new file mode 100644 index 0000000..b4cbaee Binary files /dev/null and b/docs/v1/v1_breadboard.png differ diff --git a/docs/v1/v1_scheme.png b/docs/v1/v1_scheme.png new file mode 100644 index 0000000..6da9130 Binary files /dev/null and b/docs/v1/v1_scheme.png differ diff --git a/docs/v2.md b/docs/v2.md index 3ee3bde..9f6aa23 100644 --- a/docs/v2.md +++ b/docs/v2.md @@ -8,15 +8,15 @@ ----- ## Required parts -1. **Raspberry Pi board**: +1. **Raspberry Pi board** * **✮ ✮ ✮ [Raspberry Pi 4 2Gb](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/)**.
*It makes no sense to buy a Pi 4 with more memory than 2Gb, since PiKVM software uses very few resources.* * ... or [Raspberry Pi Zero 2 W](https://www.raspberrypi.com/products/raspberry-pi-zero-2-w/).
*Compact and cheap, but not so reliable solution because of lack of the wired Ethernet.* -2. **MicroSD card minimum 16Gb class 10**. +2. **MicroSD card minimum 16Gb class 10** -3. **Video capture device**: +3. **Video capture device** * **✮ ✮ ✮ [HDMI-CSI bridge based on TC358743 chip](https://www.amazon.de/Waveshare-Raspberry-Supports-Backward-Compatible/dp/B092HVP926/)**.
*Supports H.264 video encoding, automatic resolution selection and the lowest possible latency.* * ... or [HDMI-USB dongle](https://www.amazon.com/Capture-Streaming-Broadcasting-Conference-Teaching/dp/B09FLN63B3).
@@ -59,15 +59,17 @@ * *x1* [Raspberry Pi Zero Camera Cable](https://www.amazon.com/Arducam-Raspberry-Camera-Ribbon-Extension/dp/B085RW9K13). *Not compatible with Auvidea B101*. * *x1* [Official USB-Micro Power Supply](https://www.amazon.com/Capture-Streaming-Broadcasting-Conference-Teaching/dp/B09FLN63B3). -5. **Optional feature: ATX controller** +5. **Optional features** - {!_diy_parts_atx.md!} + ??? success "✮ ✮ ✮ ATX controller to manage the target host's power" -6. **Optional feature: VGA video capture** + {!_diy_parts_atx.md!} - If you want to capture VGA from your server instead of HDMI, buy the [VGA-to-HDMI converter](https://aliexpress.com/item/3256801728005613.html). - Some converters have issues with not supporting all resolutions and refresh rates. + ??? note "VGA video capture" + If you want to capture VGA from your server instead of HDMI, + buy the [VGA-to-HDMI converter](https://aliexpress.com/item/3256801728005613.html). + Some converters have issues with not supporting all resolutions and refresh rates. *Kit parts suitable for assembly are also on [sale in Poland](https://3mdeb.com/shop/open-source-hardware/pikvm/).* @@ -75,7 +77,7 @@ ----- ## Setting up the hardware -1. **Video capture device**: +1. **Video capture device** ??? success "✮ ✮ ✮ HDMI-CSI bridge" @@ -85,17 +87,17 @@ {!_diy_setup_video_usb.md!} -2. **USB cable and power supply**: +2. **USB cable and power supply** ??? success "✮ ✮ ✮ Raspberry Pi 4" ??? success "✮ ✮ ✮ Variant #1: Power supply + ready-made Y-splitter module" - + ??? note "... or Variant #2: Power supply + Y-splitter based on power blocker" - + ??? note "... or Variant #3: Power supply + DIY Y-splitter for soldering" @@ -107,7 +109,7 @@ Please note that if you make a Y-cable from two no-name cables, the colors of the wires may not match those shown. Use a multimeter to make sure the connections are correct. - + **Video How-To: [Making a USB Y-splitter cable](https://www.youtube.com/watch?v=uLuBuQUF61o)** @@ -121,14 +123,26 @@ An easier way is to stick a piece of duct tape, as shown in this picture: - + - Connect the power supply to the `PWR`, and your magic cable to the `USB`. Use the USB-A of the magic cable + Connect the power supply to the `PWR`, and your magic cable to the `USB`. The magic cable will be used to connect the device to the target host. -3. **Optional feature: ATX control**: +3. **✮ ✮ ✮ Optional feature: ATX controller** - !!! warning "WORK IN PROGRESS" + Connect all the parts according to this scheme: + + ??? example "Simple wiring diagram" + + + ??? example "Electrical schematic diagram for advanced users" + + + +----- +## Wiring with the target host + +!!! warning "Under construction" ----- diff --git a/docs/v2/v2_atx_breadboard.png b/docs/v2/v2_atx_breadboard.png new file mode 100644 index 0000000..9c75725 Binary files /dev/null and b/docs/v2/v2_atx_breadboard.png differ diff --git a/docs/v2/v2_atx_scheme.png b/docs/v2/v2_atx_scheme.png new file mode 100644 index 0000000..f323498 Binary files /dev/null and b/docs/v2/v2_atx_scheme.png differ diff --git a/docs/_diy/v2_splitter_cable.jpg b/docs/v2/v2_splitter_cable.jpg similarity index 100% rename from docs/_diy/v2_splitter_cable.jpg rename to docs/v2/v2_splitter_cable.jpg diff --git a/docs/_diy/v2_splitter_module.jpg b/docs/v2/v2_splitter_module.jpg similarity index 100% rename from docs/_diy/v2_splitter_module.jpg rename to docs/v2/v2_splitter_module.jpg diff --git a/docs/_diy/v2_splitter_soldering.png b/docs/v2/v2_splitter_soldering.png similarity index 100% rename from docs/_diy/v2_splitter_soldering.png rename to docs/v2/v2_splitter_soldering.png diff --git a/docs/_diy/v2_tape_off.jpg b/docs/v2/v2_tape_off.jpg similarity index 100% rename from docs/_diy/v2_tape_off.jpg rename to docs/v2/v2_tape_off.jpg