How to Guide: Set Up a PiKVM

PiKVM is an incredibly powerful open-source KVM-over-IP solution that turns a Raspberry Pi into a remote management tool for your servers and computers. This comprehensive guide will walk you through every step of setting up your PiKVM, from unboxing to full operation, including troubleshooting common issues like the OLED display not turning on.

What is PiKVM?

PiKVM (Pi Keyboard Video Mouse) is a DIY or pre-assembled device that provides remote access to computers at the BIOS level. Unlike traditional remote desktop solutions, PiKVM works independently of the operating system, allowing you to troubleshoot boot problems, access BIOS settings, and even reinstall operating systems remotely.

Hardware Requirements

Before you begin, ensure you have the following components:

• Raspberry Pi 4 (2GB RAM minimum, 4GB recommended) or Raspberry Pi Zero 2 W
• MicroSD card (16GB minimum, Class 10 or better)
• HDMI capture device (recommended: USB HDMI capture dongle or official PiKVM HAT)
• USB cable for keyboard/mouse emulation (USB-A to USB-A or appropriate adapter)
• Power supply (official Raspberry Pi power supply recommended)
• OLED display (optional, typically included with pre-assembled units)
• Network cable for Ethernet connection (recommended over WiFi)
• Case (optional but recommended for protection)

Step 1: Download the PiKVM Image

First, you need to download the appropriate PiKVM operating system image for your hardware:

1. Visit the official PiKVM website at pikvm.org
2. Navigate to the Downloads section
3. Select the image that matches your hardware configuration:
   • V2-HDMI for DIY builds with USB HDMI capture
   • V3-HAT for official PiKVM HAT
   • V4-Mini or V4-Plus for pre-assembled units
4. Download the latest stable release (file will be in .img.xz format)

Step 2: Flash the Image to Your MicroSD Card

Use a reliable flashing tool to write the image to your MicroSD card:

1. Download and install one of these flashing tools:
   • Raspberry Pi Imager (Recommended - official tool from Raspberry Pi)
   • balenaEtcher (Popular alternative, works on Windows, Mac, and Linux)
2. Insert your MicroSD card into your computer
3. Open the flashing software
4. Select the downloaded PiKVM image file
5. Select your MicroSD card as the target
6. Click "Flash" or "Write" and wait for the process to complete
7. Safely eject the MicroSD card

Important: This process will erase all data on the MicroSD card.

Step 3: Hardware Assembly

Now it's time to physically assemble your PiKVM:

1. Insert the MicroSD card into your Raspberry Pi
2. Connect the HDMI capture device to one of the USB 3.0 ports (blue ports on Pi 4)
3. Connect the HDMI cable from your target computer's video output to the HDMI input on your capture device
4. Connect the USB cable from the Raspberry Pi's USB-C port (for Pi 4) or OTG port to your target computer's USB port for keyboard/mouse emulation
5. Connect the OLED display (if included) to the GPIO pins:
   • VCC to Pin 1 (3.3V)
   • GND to Pin 6 (Ground)
   • SCL to Pin 5 (GPIO 3, SCL)
   • SDA to Pin 3 (GPIO 2, SDA)
6. Connect the Ethernet cable to your network
7. Connect the power supply last

Step 4: Initial Boot and Network Configuration

When you power on your PiKVM for the first time:

1. The Raspberry Pi will boot (you'll see activity LEDs flashing)
2. Wait 2-3 minutes for the initial boot to complete
3. The device will obtain an IP address via DHCP
4. Check your router's admin panel or use a network scanner tool to find the PiKVM's IP address (hostname is usually pikvm)

Alternative method to find IP: If you have access to your router, look for a device named "pikvm" in the connected devices list.

Step 5: Access the Web Interface and Terminal

Once you have the IP address, you can access your PiKVM through the web interface and optionally through SSH.

Accessing the Web Interface

1. Open a web browser on a computer connected to the same network
2. Navigate to https://<pikvm-ip-address> (for example: https://192.168.1.100)
3. You'll see a security warning about a self-signed certificate – this is normal, proceed anyway
4. Log in with the default credentials:
   • Username: admin
   • Password: admin

Important: You will change this password in the next step!

Two Ways to Access the Terminal

You'll need terminal access to configure your PiKVM and change passwords. Choose the method that works best for you:

Option A: Using the Web Terminal (Recommended for Beginners)

The easiest way to access the PiKVM terminal is directly through the web interface - no SSH client required!

1. After logging into the PiKVM web interface
2. Click the menu icon (three horizontal lines) in the top-left corner
3. Select "Terminal" from the menu
4. A terminal window will open right in your browser
5. Log in with:
   • Username: root
   • Password: root

Advantages of the web terminal:

• No need to install an SSH client
• Works from any device with a web browser
• Same window as your KVM interface - convenient for multitasking
• Copy and paste works seamlessly
• Perfect for quick configuration changes

Option B: Using SSH (Traditional Method)

If you prefer using a dedicated SSH client:

1. Open a terminal or SSH client (PuTTY on Windows, Terminal on Mac/Linux)
2. Connect: ssh root@<pikvm-ip-address>📋
3. Default SSH password for root is root

Note: Throughout this guide, whenever you see instructions to "access the terminal" or "SSH into your PiKVM," you can use either method - both work exactly the same way!

Step 6: Update Your PiKVM to the Latest Version

Before changing passwords and proceeding with configuration, it's highly recommended to update your PiKVM to the latest version to ensure you have all the newest features, bug fixes, and security patches.

Using the pikvm-update Command

The pikvm-update📋 command is the official and recommended method for updating PiKVM. It handles all PiKVM-specific updates properly and includes safety checks.

1. Access the terminal (web terminal or SSH as described in Step 5)
2. Make sure you're root (run su -📋 if needed)
3. Switch to read-write mode: rw📋
4. Run the update command: pikvm-update📋
5. Follow the on-screen prompts
6. Wait for the update to complete (this may take several minutes)
7. Switch back to read-only mode: ro📋
8. Reboot when prompted: reboot📋

Verifying the Update

After rebooting, you can verify your PiKVM version:

1. Log back into the web interface
2. Open the menu and go to "System"
3. Look for the version information at the top of the system page

Best Practice: Check for updates monthly or whenever you notice issues. Updates often include important security fixes and performance improvements.

Step 7: Change Default Passwords (CRITICAL FOR SECURITY)

For security, you must change all default passwords immediately. Use either the web terminal or SSH from Step 5 above.

Important: Switch to Root User First

If you're not already logged in as root, you need to switch to the root user before making any changes. Run this command first:

Enter the root password (root by default) when prompted.

Step-by-Step Password Change Process

Step 1: Switch the filesystem to read-write mode

Step 2: Change the web interface admin password

Enter your new password when prompted (you'll need to type it twice for confirmation).

Step 3: Change the root SSH/terminal password

Enter your new root password when prompted (type it twice).

Step 4: Change the kvmd OS user password

Enter your new kvmd password when prompted (type it twice).

Step 5: Switch back to read-only mode

Step 8: Basic Configuration

Configure your PiKVM settings through the web interface:

1. Click the menu icon (three horizontal lines) in the top-left corner
2. Navigate to System settings
3. Configure options such as:
   • Hostname
   • Video streaming quality
   • Keyboard layout
   • ATX power control (if available)
4. Apply changes and reboot if necessary

Step 9: Enable and Configure OLED Display

If your PiKVM has an OLED display, you'll need to enable it in the configuration:

Important: Make sure you're logged in as root. If you're using the web terminal or SSH and not already root, run su -📋 first.

1. Access the terminal (web terminal or SSH as described in Step 5)
2. Switch to read-write mode: rw📋
3. Edit the override configuration file: nano /etc/kvmd/override.yaml📋
4. Add the following configuration (adjust based on your display type):
   Copy

   kvmd:
       info:
           meta:
               server:
                   host: pikvm
       
   kvmd-vnc:
       enabled: true
   
   kvmd-ipmi:
       enabled: true
   
   otg:
       devices:
           keyboard:
               enabled: true
           mouse:
               enabled: true
   
   leds:
       enabled: true
       
   kvmd-oled:
       enabled: true

5. Save the file (Ctrl+X, then Y, then Enter)
6. Restart the PiKVM services: systemctl restart kvmd kvmd-oled📋
7. Switch back to read-only mode: ro📋

Troubleshooting: OLED Display Not Turning On

If your OLED display remains blank after enabling it, try these troubleshooting steps:

Note: For all troubleshooting steps below, you can use either SSH or the web terminal (accessed via the menu in the web interface). The web terminal is often more convenient as you can see both the terminal and your PiKVM interface simultaneously.

1. Verify Hardware Connections

Double-check that the OLED is properly connected to the GPIO pins:

• VCC → Pin 1 (3.3V Power)
• GND → Pin 6 (Ground)
• SCL → Pin 5 (GPIO 3, I2C Clock)
• SDA → Pin 3 (GPIO 2, I2C Data)

Ensure the connections are firm and the display is properly seated.

2. Enable I2C Kernel Module

The I2C interface needs to be properly enabled at the kernel level.

Important: Make sure you're logged in as root. If not, run su -📋 first.

Step 1: Switch to read-write mode

Step 2: Enable the I2C kernel module

Step 3: Switch back to read-only mode

Step 4: Reboot your PiKVM

3. Enable I2C in Boot Configuration

Check if I2C is enabled in the boot configuration:

If you don't see dtparam=i2c_arm=on in the output, you need to add it:

Step 1: Switch to read-write mode

Step 2: Add I2C parameter to boot configuration

Step 3: Switch back to read-only mode

Step 4: Reboot to apply changes

After rebooting, verify I2C is working.

4. Check I2C Detection

SSH into your PiKVM and run:

You should see a device address (commonly 0x3C or 0x3D). If nothing appears, there's a hardware connection issue or the I2C interface isn't properly enabled.

5. Verify OLED Service Status

Check if the OLED service is running:

If it's not active, enable and start it:

Step 1: Switch to read-write mode

Step 2: Enable and start the OLED service

The --now flag both enables the service at boot and starts it immediately.

Step 3: Switch back to read-only mode

6. Configure OLED Network Display

To ensure the OLED properly displays network information, add the following to your override configuration:

Step 1: Switch to read-write mode

Step 2: Open the configuration file

Add or update the kvmd section with OLED network configuration:

kvmd-oled:
    enabled: true

kvmd:
    oled:
        net:
            iface: eth0
            ipv6: false

This configuration tells the OLED to display information for the eth0 interface and disable IPv6 display (which can help if you're only using IPv4).

Save the file (Ctrl+X, then Y, then Enter).

Step 3: Restart the OLED service

Step 4: Switch back to read-only mode

7. Check Configuration File Syntax

Ensure your /etc/kvmd/override.yaml file has correct YAML syntax (proper indentation is crucial):

Step 1: Switch to read-write mode

Step 2: Validate the configuration

This command validates your configuration. Fix any errors it reports.

Step 3: Switch back to read-only mode

8. Try Different Display Addresses

Some OLED displays use different I2C addresses. Edit the override file:

Step 1: Switch to read-write mode

Step 2: Open the configuration file

Try specifying the address explicitly:

kvmd-oled:
    enabled: true
    bus: 1
    address: 0x3C  # Try 0x3D if this doesn't work

Save the file (Ctrl+X, then Y, then Enter).

Step 3: Switch back to read-only mode

9. Check Logs for Errors

Review the OLED service logs for specific error messages:

Look for I2C communication errors or initialization failures.

Additional Troubleshooting Tips

Video Not Appearing

• Check HDMI connections: Ensure both ends of the HDMI cable are secure
• Try a different HDMI port: Some computers have multiple outputs
• Check capture device: Verify it's connected to a USB 3.0 port
• Adjust resolution: Some capture devices don't support all resolutions
• Check source computer: Ensure it's powered on and outputting video

Keyboard/Mouse Not Working

• Verify USB-OTG connection: Check the USB cable from Pi to target computer
• Check target computer: Ensure it recognizes the USB device
• Enable OTG in config: Verify OTG is enabled in /etc/kvmd/override.yaml
• Try different USB ports: Some ports may not support HID devices

Cannot Access Web Interface

• Check network connection: Verify the Ethernet cable is connected
• Verify IP address: Use ping pikvm.local or check your router
• Firewall issues: Ensure your firewall isn't blocking the connection
• Certificate warnings: Accept the self-signed certificate in your browser
• Try different browser: Some browsers handle self-signed certificates better

Slow Performance or Lag

• Use Ethernet: WiFi can cause lag; wired connections are more stable
• Adjust streaming quality: Lower the video quality in settings
• Reduce resolution: Lower resolutions use less bandwidth
• Check network load: Other devices may be consuming bandwidth
• Disable VPN: VPNs can add latency

MSD (Mass Storage Drive) Not Working

• Check configuration: Ensure MSD is enabled in your override file
• Format properly: Use the web interface to create/format images
• Target computer settings: Some BIOS/UEFI settings may block USB storage
• Reboot target: Sometimes the target computer needs a reboot to recognize MSD

Advanced Configuration

Setting Up ATX Power Control

If you have ATX power control wiring, you can remotely power on/off your computer:

1. Connect GPIO pins to your motherboard's power/reset headers
2. Edit /etc/kvmd/override.yaml to enable ATX controls
3. Test using the power button in the web interface

Enabling VNC Access

VNC provides an alternative way to access your remote system:

kvmd-vnc:
    enabled: true
    port: 5900
    auth:
        vncauth:
            enabled: true

Setting Up IPMI

IPMI compatibility allows PiKVM to work with tools like ipmitool:

kvmd-ipmi:
    enabled: true
    port: 623

Security Best Practices

• Change all default passwords immediately
• Use strong passwords with mixed case, numbers, and symbols
• Enable two-factor authentication if available in your version
• Keep PiKVM updated with latest security patches
• Use VPN access when accessing over the internet
• Disable SSH if you don't need it: systemctl disable sshd📋
• Use HTTPS only – never disable certificate checking
• Restrict network access using firewall rules
• Regular backups of your configuration files

Maintenance Tips

• Regular updates: Run pikvm-update📋 monthly to keep system updated
• Monitor SD card health: SD cards can fail; keep backups
• Check logs periodically: Review for any unusual activity
• Clean connections: Dust can cause connectivity issues
• Proper ventilation: Ensure adequate airflow to prevent overheating

Useful Commands Reference

# Switch to read-write mode
rw

# Switch to read-only mode
ro

# Restart PiKVM services
systemctl restart kvmd

# Check service status
systemctl status kvmd

# View real-time logs
journalctl -u kvmd -f

# Update system
pikvm-update

# Validate configuration
kvmd -m

# Reboot PiKVM
reboot

# Check I2C devices
i2cdetect -y 1

# Test OLED manually
systemctl restart kvmd-oled

Practical Use Cases for PiKVM

Now that your PiKVM is set up, here are some powerful ways to use it:

1. Remote Server Management

Scenario: Managing servers in a data center, colocation facility, or remote office.

• Access BIOS/UEFI settings without physical presence
• Troubleshoot boot failures and kernel panics
• Perform firmware updates that require BIOS access
• Reconfigure RAID controllers at boot level
• Access servers that have network configuration issues

Real-world example: Your server won't boot due to a kernel panic. With PiKVM, you can see the exact error message, boot into single-user mode, and fix the issue - all from home.

2. Operating System Installation and Recovery

Scenario: Installing or reinstalling operating systems on remote machines.

• Mount ISO images using PiKVM's Mass Storage Device (MSD) feature
• Install Windows, Linux, or ESXi without physical USB drives
• Access recovery environments when systems won't boot
• Perform bare-metal restores from backup images
• Test different operating systems without burning physical media

Real-world example: Need to install Ubuntu Server on a remote machine? Upload the ISO through the web interface, mount it as a virtual USB drive, reboot the system, and complete the installation as if you were sitting in front of it.

3. Homelab and Testing Environment

Scenario: Managing multiple test systems and learning environments.

• Manage multiple VMs or physical machines from one interface
• Test BIOS settings changes without leaving your desk
• Troubleshoot hypervisor installations (Proxmox, ESXi)
• Practice disaster recovery procedures
• Learn networking and system administration safely

Real-world example: Testing a new Proxmox cluster setup? Use PiKVM to configure multiple nodes, access their BIOS for boot order changes, and troubleshoot any boot issues without constantly running between machines.

4. Gaming PC Remote Management

Scenario: Managing high-performance gaming or workstation PCs.

• Access BIOS to overclock or adjust fan curves
• Troubleshoot startup issues with RGB software or drivers
• Power cycle frozen systems remotely (with ATX power control)
• Monitor POST codes and boot sequences
• Enter safe mode for Windows troubleshooting

Real-world example: Your gaming PC freezes while you're away from home. Use PiKVM to force a hard reboot, watch it boot up, and boot into safe mode to disable the problematic driver.

5. Small Business IT Support

Scenario: Providing IT support for small offices or clients.

• Support clients without on-site visits
• Fix boot problems before business hours
• Access machines that can't connect to remote desktop
• Perform after-hours maintenance without disturbing users
• Reduce IT support costs with remote BIOS-level access

Real-world example: A client's computer won't start Windows. Instead of driving to their office, use PiKVM to diagnose the boot issue, access Windows recovery, and repair the boot configuration remotely.

6. Network Equipment Configuration

Scenario: Managing routers, firewalls, and network appliances.

• Access serial consoles on network equipment
• Recover from bad configurations that lock you out
• Perform firmware updates on critical infrastructure
• Configure pfSense, OPNsense, or other router OSes
• Set up VLANs and routing without physical access

Real-world example: You accidentally misconfigure your pfSense firewall and lose network access. PiKVM lets you see the console output, boot into single-user mode, and restore the previous configuration.

7. Cryptocurrency Mining Rig Management

Scenario: Managing mining rigs that need frequent BIOS tuning.

• Adjust BIOS settings for optimal mining performance
• Troubleshoot boot issues with multiple GPUs
• Monitor POST sequences to identify hardware issues
• Reboot frozen rigs remotely
• Update motherboard firmware without downtime

8. Development and Testing

Scenario: Developers working with embedded systems or bootloaders.

• Test bootloader modifications safely
• Debug early boot processes
• Develop custom BIOS/UEFI applications
• Test hardware compatibility for drivers
• Capture boot logs for debugging

9. Disaster Recovery and Business Continuity

Scenario: Enterprise disaster recovery planning.

• Access critical systems during network outages
• Perform emergency recovery procedures remotely
• Test failover procedures without physical presence
• Document and practice disaster recovery runbooks
• Reduce mean time to recovery (MTTR) for critical incidents

10. Educational and Training Purposes

Scenario: Teaching system administration or IT courses.

• Demonstrate BIOS configuration to students remotely
• Show operating system installation procedures
• Practice troubleshooting without physical lab access
• Create recorded tutorials of low-level system operations
• Provide students with real hardware experience remotely

Tips for Maximizing Your PiKVM

• Document everything: Keep notes on your BIOS settings and configurations
• Set up ATX control: Remote power cycling is incredibly valuable
• Use good cables: Quality HDMI and USB cables prevent frustrating issues
• Keep ISOs ready: Maintain a library of useful recovery and installation ISOs
• Secure it properly: Use VPN access when exposing to the internet
• Test regularly: Periodically verify your PiKVM is working correctly
• Have a backup plan: Keep a spare SD card with PiKVM image as backup

Conclusion

Setting up a PiKVM opens up powerful remote management capabilities for your servers and computers. While the initial setup requires some technical knowledge, following these steps carefully will result in a reliable KVM-over-IP solution. Remember to prioritize security by changing default passwords and keeping your system updated.

If you encounter issues not covered in this guide, the PiKVM community is active and helpful on their Discord server and GitHub discussions. Don't hesitate to reach out for support.

Happy remote managing!

Have questions or additional troubleshooting tips? Leave a comment below and help fellow PiKVM users!