DIY PiKVM V2 Instructions¶

So many choices!

There are many different options with sub-items, so you can choose what will suit you.
However, we marked the recommended way by sign ✮ ✮ ✮

Required parts¶

MicroSD card minimum 16Gb class 10.
Raspberry Pi board:
- ✮ ✮ ✮ Raspberry Pi 4 2Gb.
  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.
  Compact and cheap, but not so reliable solution because of lack of the wired Ethernet.
- ... Raspberry Pi 5 is not supported right now. It doesn't have GPU video encoders, therefore, there is no point in using it for PiKVM, it will not give any performance boost for this case. The Pi 5 is a great device, just not suitable for PiKVM.
Video capture device:
- ✮ ✮ ✮ HDMI-CSI bridge based on TC358743 chip.
  Supports H.264 video encoding, automatic resolution selection and the lowest possible latency.
- ... or HDMI-USB dongle (not available for Pi Zero 2).
  Only heavy MJPEG video, no resolution detection, big latency compared to HDMI-CSI. Some users report hardware problems: the dongle may not work in the BIOS or simply stop working after a while. It's a black box, and no one knows what's inside it. If you have problems with it, it will not be possible to fix them.
Board-specific: Power supply, USB connectivity, etc.
✮ ✮ ✮ Raspberry Pi 4

On a Raspberry Pi 4 only the USB-C port that receives power is capable of acting as a USB Device. The other USB ports are capable only of acting as USB Hosts. Therefore a special cable must be used on the USB power port that it can simultanously act as USB Device for the target host and receive external power from an power supply.
✮ ✮ ✮ Variant #1: Power supply + ready-made Y-splitter module
- x1 USB-C/Power Splitter Module (US/UK/CA).
- x1 USB-C to USB-C cable (male-male) for connecting the Raspberry Pi to the splitter.
- x1 USB-A to USB-C cable (male-male) for connecting the target host to the splitter.
- x1 Official USB-C Power Supply.
... or Variant #2: Power supply + Y-splitter based on power blocker
- x1 USB-A to USB-C cable (male-male).
- x1 USB splitter.
- x1 USB Power Blocker - Will go into the USB-A end towards the target host.
- x1 Raspberry Pi Official USB-C Power Supply.
... or Variant #3: Power supply + DIY Y-splitter for soldering
- x1 USB-A to USB-C cable (male-male).
- x1 Another cable USB-A to any (male-any).
- x1 Any 5V 3A power supply with USB-A socket.
... or Raspberry Pi Zero 2 W
- x1 USB-A to USB-Micro cable (male-male).
- x1 Raspberry Pi Zero Camera Cable. Not compatible with Auvidea B101.
- x1 Raspberry Pi Official USB-Micro Power Supply.
Optional features:
✮ ✮ ✮ ATX controller to manage the target host's power

With this part, you will be able to remotely turn on, turn off and restart your computer!
- x4 MOSFET relays OMRON G3VM-61A1 or OMRON G3VM-61AY1.
  Don't use random relay modules or random optocouplers! Some of these may not be sensitive enough for the Raspberry Pi, some others may be low-level controlled. Either use relays that are activated by a high logic level, or follow the design provided and buy an OMRON. See details here.
- x4 390 Ohm resistors (see here for alternatives).
- 2x 4.7 kOhm resistors.
- x10+ dupont wires male-male.
- x1 a breadboard.
- various wires for the breadboard.
This can be partially replaced by using Wake-on-LAN in the software, but it will not allow to reboot a hung system, and it is not as reliable as an ATX controller. Sometimes the Wake-on-LAN on the host just stops working, for its own or network reasons.
VGA video capture

If you want to capture VGA from your server instead of HDMI, buy the VGA-to-HDMI converter. Some converters have issues with not supporting all resolutions and refresh rates.

Kit parts suitable for assembly are also on sale in Poland.

Setting up the hardware¶

Video capture device:

✮ ✮ ✮ HDMI-CSI bridge

Insert the flexible flat cable of the HDMI-CSI bridge into the narrow white connector on the Raspberry Pi (the closest one to big USB sockets). It is labeled CAMERA. To insert you need to open the connector first. On the Raspberry Pi side you can gently lift the black part up and a little bit sideways:

Opening the MIPI CSI slot on the Raspberry Pi

For the HDMI-CSI bridge this operation depends on the version you bought. Either pull it gently up as on the Raspberry or push it sideways. Make sure that the cable is inserted on the correct side and until it stops, and then push the black latch back. Avoid using force when pushing the cable in, as the slots bond to the PCB is quite fragile. Never connect or disconnect the flat cable from a powered device. This is not Plug-and-Play, and you can damage it. Also use only the cable that was included with the device package, or make sure that the third-party cable has the correct pinout.

HDMI-CSI bridge connected to Raspberry Pi 4

HDMI-CSI bridge connected to Raspberry Pi 2 W (using the adapter cable)

... or HDMI-USB dongle

Connect USB dongle to exactly this port. It is bound in the software so the OS does not confuse the video device with something else.

Raspberry Pi 2 and 3 Raspberry Pi 4

There are many revisions of the Raspberry Pi boards and you may come across one that we haven't tested. If the binding fails, the device will be available for all ports. Everything will work, but if you use a webcam and Linux mistakes it for a dongle, write to us and we will fix it.
USB cable and power supply

✮ ✮ ✮ Raspberry Pi 4

✮ ✮ ✮ Variant #1: Power supply + ready-made Y-splitter module

... or Variant #2: Power supply + Y-splitter based on power blocker

... or Variant #3: Power supply + DIY Y-splitter for soldering

It is assumed that if you have followed this path, you know how to handle a soldering iron and a multimeter.

The Y-splitter can be soldered from two suitable USB cables. Check the attached diagram. The appropriate USB pinout(s) can easily be found on Google.

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

... or Raspberry Pi Zero 2 W

This board has two USB micro connectors: one for power supply (marked as PWR) and the second for emulating a USB gadget (marked as USB). Both connectors have a common power line, so to prevent Raspberry power from entering the USB port of the target host, it is required to make a special USB A-to-Micro cable without power line.

One way is to physically cut the power wire inside the USB cable.

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. The magic cable will be used to connect the device to the target host.
✮ ✮ ✮ Optional feature: ATX controller

Connect all the parts according to this scheme:

Simple wiring diagram

Electrical schematic diagram for advanced users
Double check that the circuit is assembled correctly to avoid any damage of the hardware.

Wiring with the target host¶

Connect the HDMI video capture device to the video output port on the target host.
Using the Y-cable, connect the PiKVM to the USB on the target host.
Connect the ATX controller if you built it

To control the power, two display LEDs (power and HDD activity) and two buttons (power and reset) are provided on the front panel of the computer case. They are connected by wires to pins on the motherboard.

All you have to do is connect the PiKVM ATX controller to their wires by making a parallel connection. Please note that the pinout differs on different motherboards, so before you continue, check the documentation on your motherboard for correct pinout.

The following illustration shows how the connection between the power LED and the power button should be performed:

On the left are the wires from the PiKVM ATX controller, the pad in the middle indicates the pins on the motherboard, and on the right are the LED and button of the target host. The implementation of this scheme is left to your discretion and can be performed, for example, by cutting wires and performing twisting, followed by insulation with duct tape.

Be careful and respect the polarity of the LEDs. The polarity of the button does not matter (they have no polarity at all). The connection of HDD LED and reset switch is performed in the same way.

Video modes¶

PiKVM V2 with CSI bridge can only handle the maximum resolution 1920x1080@50Hz, 60Hz is not supported due hardware limitation. You can use any other resolution less than the specified one, for example 1280x720@60Hz.

If you have any problems with video on CSI bridge, follow this guide.

First launch and usage¶

Double-check the correct assembly of the device, and make sure that you have connected all the necessary cables to the host: USB, HDMI and ATX.
Flash the memory card with PiKVM OS and insert it to Raspberry Pi.
Carefully read and follow the First Steps Guide.
It describes how to perform the first power-on, how to find PiKVM on the network, login, change passwords, and so on.
Follow the steps described there and come back to this page.
Just reminding again:
✮ ✮ ✮ CHANGE THE PASSWORDS! ✮ ✮ ✮

PiKVM comes with the following default passwords:
- Linux admin (SSH, console, etc.): user root, password root.
- PiKVM Web Interface (API, VNC...): user admin, password admin, no 2FA code.
These are two separate entities with independent accounts.

To change passwords, you will need to use the console access via SSH or the Web Terminal. If you are using the Web Terminal, enter the su - command to get the root access (enter the root user password).
```
[root@pikvm ~]# rw
[root@pikvm ~]# passwd root
[root@pikvm ~]# kvmd-htpasswd set admin
[root@pikvm ~]# ro
```
If you require additional user for the Web UI access, use the following:
```
[root@pikvm ~]# kvmd-htpasswd set <user> # Set a new user with password or change of an existing one
[root@pikvm ~]# kvmd-htpasswd del <user> # Remove/delete a user
```
Optionally you can enable the two-factor authentication for more security.

Changing the VNCAuth passkey and IPMI password at the first start of PiKVM is not required, since these services are disabled by default. But it is here just so that you remember their existence.
Try to manage the computer using PiKVM with the Web Interface.
Make sure that you get an image and both keyboard and mouse are working. If something doesn't work, check out our FAQ (it's really useful). If nothing helped, you can get support in our Discord chat.
Note for the HDMI-USB dongle

Many USB video capture devices tell the server's video card that the HDMI cable is supposedly disconnected. This may lead to the fact that if you boot the server without an active stream, the server will not detect your capture card. This is easy to fix:
- Switch filesystem to RW-mode:
```
[root@pikvm ~]# rw
```
- Edit file /etc/kvmd/override.yaml and add these lines:
```
kvmd:
    streamer:
        forever: true
        cmd_append: [--slowdown]
```
- Finish:
```
[root@pikvm ~]# ro
[root@pikvm ~]# systemctl restart kvmd
```
- Check that everything is working.
Configure access to PiKVM from the Internet using port forwarding or Tailscale VPN, if you need it.
Explore the features of PiKVM using the site's table of contents and have fun!

Basic troubleshooting¶

Ensure that you are using the right OS image for your platform by running the following command: pacman -Q | grep kvmd-platform.
If you are not getting a display, run the two following commands:
- dmesg | egrep 'tc35|1-1.4|uvc'
- systemctl status kvmd-tc358743
If you see a failed message on that output, be sure verify the orientation of the CSI cable or try reseating it.

Not that this is not a hotplug device and you must first turn off the power.