DIY PiKVM V1 quick start guide¶

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 8Gb class 10.
Official USB-Micro Power Supply.
Raspberry Pi board:
- ✮ ✮ ✮ Raspberry Pi 3.
- ... or Raspberry Pi 2.
  Does not support H.264 even with HDMI-CSI bridge.
- ... or Raspberry Pi Zero 2 W.
  Compact and cheap, but not so reliable solution because of lack of the wired Ethernet. Note that the better way to use Pi Zero is making PiKVM V2 - it supports more USB features.
Video capture device:
- ✮ ✮ ✮ HDMI-CSI bridge based on TC358743 chip.
  Supports H.264 video encoding on Raspberry Pi 3, automatic resolution selection and the lowest possible latency.
- ... or HDMI-USB dongle.
  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.
The Pico HID Keyboard & mouse emulator:
- x1 Raspberry Pi Pico board with soldered pins. Pico 2 is not supported right now.
- 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.
Board-specific parts:

✮ ✮ ✮ "Nothing special for Raspberry Pi 2 or 3
Raspberry Pi Zero 2 W
✮ ✮ ✮ HDMI-CSI bridge
- x1 Raspberry Pi Zero Camera Cable. Not compatible with Auvidea B101.
... or HDMI-USB dongle
- x1 USB-A socket to USB-Micro adapter (female-male).
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 optocouplers TLP241BF(F or PC817X2NSZ9F (the input polarity must be observed) or 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. 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.
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 of the Pico HID manual.

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.

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

Raspberry Pi 2 & 3

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.

Raspberry Pi Zero 2 W

Connect the USB dongle to USB-to-Micro adapter, and connect it to the USB port marked as USB (not PWR) on the Pi Zero board:
The Pico HID and ATX controller:

Connect all the parts according to this scheme:

✮ ✮ ✮ With ATX controller

Simple wiring diagram

Electrical schematic diagram for advanced users

... or without ATX controller

Simple wiring diagram

Electrical schematic diagram for advanced users
Flash firmware to the Pico HID.
Flash the memory card with PiKVM OS and insert it to Raspberry Pi.

Wiring¶

Warning

Double check that the circuit is assembled correctly to avoid any damage of the hardware.

PiKVM V1 requires several items available separately:

Ethernet cable (Raspberry Pi 2 and 3 only)
HDMI cable

Let's connect all the wires before you power up the device.

Connect the HDMI video capture device to the video output port on the target host.
Connect the Pico HID to the USB port on the target host.
Raspberry Pi 2/3: connect Ethernet to the network, e.g., to the Wi-Fi router.
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.

Power up¶

If everything is assembled correctly, attach the power supply to the Raspberry Pi.

After turning on the power, PiKVM OS generates unique SSH keys and certificates and performs all necessary operations on the memory card. It takes a few minutes.

Do not turn off the device until it's fully booted for the first time.

Configure the display¶

The operating system on your remote computer will treat PiKVM as an additional display and use it in the Extend mode by default. That's why you will see an empty desktop when you first connect.

To avoid that, go to the display settings in your remote computer's operating system and enable the mirror mode for the external screen that you operating system identifies as PiKVM. Refer to your operating system's documentation on that.

Access PiKVM¶

You need to know PiKVM's IP address in the network to be able to access it. Unlike PiKVM V3 and V4, PiKVM V1 doesn't have an OLED to display the IP address it receives automatically. You need to discover it manually. There are several ways to do that.

Common way: Open the web interface of your router and find the list of issued IP addresses there.
Linux-only: Use the arp-scan --localnet command.
Linux, MacOS, Windows: Download and run Angry IP Scanner.
Windows PowerShell: Use the arp -a command.

Let's assume that PiKVM has received the address 192.168.0.26 and has also been assigned a hostname pikvm.

Type the URL in the browser's address bar and press Enter: https://192.168.0.26/ or https://pikvm/.

Submit the default credentials and click Login:

Username: admin
Password: admin
2FA Code: disabled by default, skip this field

You will see the initial dashboard screen of the PiKVM where you can access the remote host, connect to the PiKVM command line, or log out:

Change the default passwords¶

For security's sake, it's best to change the default passwords immediately after running PiKVM for the first time.

Passwords are important!

Please ensure that you change both passwords: for Web UI access and for the Linux superuser (root).

To do that:

On the initial dashboard screen, click the Terminal button to open the web terminal. You will see this command line interface:
Gain Linux superuser privileges:
```
$ su -
```
When prompted for password, use root.
Run rw to change the access to the SD card to the write mode:
```
[root@pikvm ~]# rw
```
Change the password for the Linux superuser:
```
[root@pikvm ~]# passwd root
```
Submit the new password, retype it the second time to confirm, press Enter, and you should see this:
```
passwd: password updated successfully
```
Change the password for web access:
```
[root@pikvm ~]# kvmd-htpasswd set admin
```
Submit the new password, retype it the second time to confirm, and press Enter.
Run ro to change the access to the SD card back to the read-only mode:
```
[root@pikvm ~]# ro
```
Press Ctrl+D or type "exit" and press Enter to drop the root privileges.
Go back one page in the browser. You should be back to the initial dashboard screen.

Access the remote system¶

On the initial dashboard screen, click the KVM button to access the remote host.
You should now see the host system's display and interact with it remotely using a keyboard and a mouse.

Important next steps¶

We strongly recommend to update the PiKVM OS after the first launch:
Updating PiKVM OS

To update, run following commands under the root user:
```
[root@pikvm ~]# pikvm-update
```
If you encounter an error like:
```
[root@pikvm ~]# pikvm-update
bash: pikvm-update: command not found
```
It's most likely you have an old OS release. You can update the OS as follows:
```
[root@pikvm ~]# rw
[root@pikvm ~]# pacman -Syy
[root@pikvm ~]# pacman -S pikvm-os-updater
[root@pikvm ~]# pikvm-update
```
Next time you will be able to use the usual method with pikvm-update.
Learn about basics of PiKVM OS Configuration: where to find configs, how to edit the, etc.
Configuring PiKVM OS

Most of the PiKVM configuration files are located in the /etc/kvmd directory.

The /etc/kvmd/main.yaml file defines the platform config and you should never edit it. To redefine system parameters use the file /etc/kvmd/override.yaml. All other files that are also not recommended for editing have read-only permissions.

In the /etc/kvmd/meta.yaml file you can specify some information regarding the host that this PiKVM manages.

Tip

A complete list of all parameters can be viewed using the kvmd -m command.

Files with the suffix *.yaml uses the YAML syntax and describes a parameter tree with key-value pairs of different types. To define the parameters within one section, an indent of 4 spaces is used. Comments starts with the # symbol.

Only 4 spaces should be used for indentation

Be careful when editing YAML and follow this rule. Invalid indentation or tabs instead of spaces will cause an error when starting the services.

Sections under the same keys should be merged:
- Wrong:
```
kvmd:
    gpio:
        drivers: ...
kvmd:
    gpio:
        scheme: ...
```
- Correct:
```
kvmd:
    gpio:
        drivers: ...
        scheme: ...
```
Get to know PiKVM Web UI: read this help section to better understand all the possibilities of the web user interface.
Tune the HDMI dongle capture device if you're using it:
Persistent HDMI cable connection with 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.

Further recommendations¶

Harden the remote access by enabling 2FA and setting session expiration time.
Configure access to PiKVM from the Internet using port forwarding or Tailscale VPN.
Learn how configuration files are structured.

Known issues and limitations¶

Max resolution.
PiKVM V1 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.

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.

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

Getting user support¶

If something doesn't work, check out our FAQ. Otherwise, head straight to our Discord chat.