PiKVM V4 Mini & Plus quickstart guide¶

PiKVM is a feature-rich, production-grade, open-source, Raspberry Pi based KVM-over-IP device. It allows you to turn your computer on or off, restart it, configure the UEFI/BIOS, and even reinstall the OS using the Virtual CD-ROM or flash drive.

PiKVM uses your remote keyboard and mouse to simulate a local keyboard, mouse, and monitor, which are then presented in a web browser as if you were working on a remote system directly.

Datasheets:

PiKVM V4 Mini PiKVM V4 Plus

What's in the box¶

PiKVM V4 Mini or Plus device
Micro SD card with pre-imaged PiKVM software
ATX control board
ATX connection cables
ATX installation brackets
1 x Ethernet cable
1 x ATX cable
1 x USB C to USB A cable
12V 2A Power Supply (international adapters)

Interface¶

Front viewRear viewRight viewTop view

Power LED (Green)
Power Input 5.1V 3A
Activity LED (Red)
Micro SD card slot
USB 2.0 Serial console port
Serial console active LED / Beacon LED (Green)
RJ45 1Gb Ethernet port
RJ45 Serial console port (V4 Plus only)
USB 3.0 port 1 (V4 Plus only)
Power Input 12V 2A (V4 Plus only)

RJ45 ATX control port
USB 2.0 OTG connector
Beacon LED
Video source ready status LED
HDMI video input port
Video capture ready status LED
Optional antenna mounting hole (only one in V4 Mini)
HDMI video output port 2 (V4 Plus only)
HDMI video output port 1 (V4 Plus only)
USB 3.0 port 2 (V4 Plus only)
Optional antenna mounting hole (only one in V4 Mini)

Service switches
Kensington Security Slot

Display

Wiring¶

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

Network¶

Connect Ethernet (bottom right on the front side) to the network using the cable from the kit. The kit includes two Ethernet cables of different colors: one for the network, the second for ATX. Use whichever one you like best.

HDMI and USB-C¶

HDMI input (the bottom right on the rear side) and OTG port (USB emulation) should be connected to the computer.

Optionally, the ATX port can be connected to control the power. There should be no USB hub between PiKVM and the computer, as some UEFI/BIOS cannot detect them at the boot stage.

Power up¶

V4 Mini and V4 Plus have different power supplies:

The Mini comes with USB-C 5V power supply
The Plus comes with with Barrel 12V

The Plus can also work from 5V. In that case, avoid creating a significant power load on USB (external flash sticks, cameras, and so on).

Attach the appropriate connector on the front side. Do not block the ventilation holes on the sides of the device.

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. Once it's done, the PiKVM will show a greeting on the built-in display.

Connect and set up¶

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 your operating system identifies as PiKVM. Refer to your operating system's documentation on that.

Access PiKVM¶

By default, PiKVM receives a dynamic IP address via DHCP and shows it in the top row of the OLED display:

192.168.0.26
(|) iface: eth0
cpu: 1% mem: 13%

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 superuser privileges:
```
$ su -
```
When prompted for a 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 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 updating 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 the 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.
Set up an ATX connection if you need to control the power of the remote system.

Further recommendations¶

Customize the system:
- Harden the remote access by enabling 2FA.
- Configure access to PiKVM from the Internet using port forwarding or Tailscale VPN.
- Enable a microphone for two-way audio.
- Enable HDMI pass-through and USB passthrough.
- Learn how configuration files are structured.
Configure hardware:
- Install and set up the Wi-Fi antenna:
  
  Quick WiFi antenna how-to
  
  The PiKVM V4 has a robust metal case that protects your device from physical damage and electromagnetic interference. This also means that an external antenna must be used for Wi-Fi. We recommend the official Antenna Kit for Raspberry Pi.
  
  To install the antenna, fix it in the round hole in the back side of the PiKVM, and connect the wire to the connector on the Compute Module 4, as described in the instructions.
  
  Next, to activate the antenna, add line dtparam=ant2 to the /boot/config.txt file on PiKVM.
  
  Here is a video:
  
  Follow this guide to configure Wi-Fi in PiKVM OS.
- Install and set up LTE/5G modem (only for PiKVM V4 Plus).
- Set up internal USB port for USB 3.0 (only for PiKVM V4 Plus):
  Enable USB 3.0 on the internal port
  
  PiKVM V4 Plus has an internal USB port. It supports USB 3.0, but only works with USB 2.0 devices by default to minimize the power consumption. You need to flash the USB controller to enable USB 3.0. To do so, follow these steps:
  1. Open a terminal window and log into the PiKVM via SSH:
    $ ssh user@host
  2. Flash the USB controller using the built-in flashrom utility. Choose usb3 for USB 3.0 support:
    [root@pikvm ~]# flashrom-vl805 usb3
    If you need to disable USB 3.0 support at any time later, run the same command, but use default instead:
    [root@pikvm ~]# flashrom-vl805 default
  3. Perform the soft reboot:
    [root@pikvm ~]# reboot
  4. After the soft reboot, perform the reboot by power: unplug and plug again the power cable.
- Learn about DIP switches:
  DIP switches purpose
  
  The left switch [1]:
  
  When pulled down (ON state), the advanced backpower protection is used. On the default state is OFF (up), "diode protection" is used. This is required for debugging at the request of technical support. Under normal conditions, it is not necessary to change the mode.
  
  The right switch [2]:
  
  When pulled down (ON state), the Power Delivery chip is activated on the USB OTG port. The default state is OFF (up).
  
  To change the position of switches:
  1. Turn the PiKVM off.
  2. Change the position of the switched.
  3. Turn the PiKVM on.
  Warning
  
  Do not do that change the state of the DIP switched while the device is turned on. This may cause irreparable damage.
- Choose Fahrenheit over Celsius to display on the OLED:
  How to set up Fahrenheit on the OLED
  
  Create a directory for a configuration file:
```
[root@pikvm ~]# mkdir -p /etc/systemd/system/kvmd-oled.service.d
```
  Create file /etc/systemd/system/kvmd-oled.service.d/override.conf:
```
[Service]
ExecStart=
ExecStart=/usr/bin/kvmd-oled --clear-on-exit --fahrenheit
```

Known issues and limitations¶

There may be compatibility issues with certain motherboards, such as HP or DELL. If there is no image from the BIOS, you can fine-tune the HDMI settings, but it is possible that mass storage devices may not be available in the BIOS. In the latter case, USB dynamic configuration will solve the problem.
While the V4 Plus features a Mini-PCIe slot, it was only designed for LTE modems. An NVME card will not work.

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

Getting user support¶

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