2
0
mirror of https://github.com/pikvm/pikvm synced 2024-11-08 19:10:24 +00:00
pikvm/README.md
2021-05-09 00:23:04 +03:00

31 KiB

Open and cheap DIY IP-KVM based on Raspberry Pi

Discord Reddit

A very simple and fully functional Raspberry Pi-based KVM over IP that you can make with your own hands. This device helps to manage servers or workstations remotely, regardless of the health of the operating system or whether one is installed. You can fix any problem, configure the BIOS, and even reinstall the OS using the virtual CD-ROM or Flash Drive.

The website: pikvm.org. Also join to the Discord Community Chat for news, questions and support!

Features

  • Supported Raspberry Pi 2, 3, 4 and ZeroW;
  • FullHD video using advanced HDMI-to-CSI bridge or USB dongle;
  • Extra low 100ms video latency (for CSI bridge);
  • Bootable Virtual CD-ROM and Flash Drive;
  • USB Keyboard and mouse (with leds and the wheel), PS/2 keyboard, Bluetooth HID;
  • Control the server power using ATX functions;
  • Access via Web UI or VNC;
  • Ability to use IPMI BMC, IPMI SoL, Redfish and Wake-on-LAN to control the server;
  • The ready-made OS with read-only filesystem;
  • Extensible authorization and SSL encryption;
  • Health monitoring of the Pi;
  • Control GPIO ports and USB relays;
  • It only costs between $30 and $100 for parts!
  • 100% Open Source!
Detailed about the Pi-KVM features
  • Cheaper, but better than commercial solutions
    Costs between $30 and $100 depending on the features desired. Even the most expensive configuration will be cheaper than a $500 commercial IP-KVM.
  • Easy to build
    A ready-to-use OS that can be created just by running make build and installed to an SD-card using make install. The hardware can be made in half an hour and without soldering.
  • The widest hardware support
    There are many ways to build a Pi-KVM. Video capture devices can be attached using the CSI-2 or USB interfaces. Raspberry Pi models 2, 3, 4, or ZeroW may be used. Any combination of hardware is supported, and Pi-KVM implements the maximum possible set of features.
  • Very low latency
    ~100 milliseconds of video latency. This is the smallest delay of all existing solutions.
  • Extra lightweight and fancy Web UI
    No weird proprietary clients. No ugly Java applets. Just use your favorite browser to connect to the Pi-KVM. No flash plugins either!
  • Keyboard and mouse
    Mouse usage works directly in the browser. The keyboard emulator supports displaying the state of the keyboard LEDs.
  • Mass Storage Drive
    On the Raspberry Pi 4 and ZeroW, Pi-KVM can emulate a virtual CD-ROM or Flash Drive. A live image can be uploaded to boot the attached server.
  • ATX power management
    With a very simple circuit that can be assembled on a breadboard, the power button of the attached server can be controlled using the ATX button headers on the motherboard.
  • Security
    Pi-KVM can be opened to the Internet and no one will get access without the password. SSL encryption is used to protect traffic from being intercepted by third parties.
  • Local monitoring
    Pi-KVM monitors the health of the Raspberry Pi board and will warn you if it's too hot or is not receiving enough power.
  • GPIO management You can control GPIO and USB relays via the web interface. The extensible interface allows you to make anything out of it.

Production-ready

  • Linux-based embedded OS
    The Pi-KVM OS is based on Arch Linux ARM and can be customized for any needs. Thousands of pre-built binary packages are at your service and can be updated with a single command!
  • Read-only filesystem
    By default the OS runs in read-only mode, as an embedded system should. This prevents damage to the memory card due to a sudden power outage.
  • VNC server
    The managed server and its BIOS can be accessed using a regular VNC client which supports JPEG compression.
  • IPMI BMC and Redfish
    Use ipmitool, ipmiutil or any existing network infrastructure that supports IPMI to monitor and manage the server's power. Redfish and redfishtool supported too.
  • Wake-on-LAN
    Pi-KVM can be configured to power up a managed server using WoL. This will be available in the Web menu.
  • Extensible authorization methods
    Multiple Pi-KVMs can be configured to use a common authorization service. PAM and its rich authorization mechanisms can also be used to integrate Pi-KVM into your existing authentication infrastructure.
  • Macro scripts
    If repetitive actions must be performed on the attached server (or on several different servers), a macro can be recorded with keyboard & mouse actions and can be played back multiple times.

Open Source

  • Community & support
    Pi-KVM has a large community. Join the discord chat if you have any questions.
  • Extensible
    Pi-KVM was designed as a set of microservices with a plug-in architecture. It's very easy to modify and maintain.
  • Comprehensive API
    Everything that can be done via the user interface can also be done via a powerful HTTP API.
  • Know-how
    We created our very own MJPG video server written in C with multi-threading support and GPU video encoding - the fastest streaming solution available to provide the best video quality for Pi-KVM. We also tested a lot of hardware configurations so that you can be sure devices you assemble will work reliably.
DIY Device Web UI
drawing drawing

DIY Getting Started

Required hardware

Pi-KVM supports several different hardware configurations, referred to as platforms. Now available: v2 and v0.

  • Recommended: v2 is the most modern implementation for Raspberry Pi 4 and ZeroW supporting all of the features of Pi-KVM including the Mass Storage Drive. It's also the easiest to make
  • v0 was designed to work with Raspberry Pi 2 and 3 that do not have OTG and requires a few more components for a basic implementation. It also does not support the Mass Storage Drive feature.

Hardware for v2

  • Raspberry Pi board:
    • Recommended: Raspberry Pi 4 (2 GB model is enough) for the best performance.
    • ... or Raspberry Pi ZeroW (slower alternative, no ethernet).
  • MicroSD card (min 16 GB recommended).
  • USB-A 3A charger (female socket) or power supply.
  • Video capture device:
  • Only for Raspberry Pi 4: parts for Y-splitter cable (one variant at your choice):
    • Variant #1: DIY for soldering or twist.
      • 1x USB-A to USB-C cable (male-male).
      • 1x another cable USB-A to any (male-any).
      • 1x appropriate Power Supply (USB-A or USB-C) depending on what cable you choose above.
    • Variant #2: Ready-made using USB-micro splitter.
      • 1x USB/Power Splitter Module (UK/US/CA).
      • 1x USB-A to USB-C cable (male-male) for connecting the Raspberry Pi to the splitter.
      • 1x USB-A to micro USB-B cable (male-male) for connecting the server to the splitter.
      • 1x USB-A to micro USB-B cable (male-male) to connect into a USB-A wall charger. Or you also can buy the official Raspberry Pi Power Supply with micro USB-B instead.
    • Variant #3: Ready-made using USB-C splitter.
      • 1x USB-C/Power Splitter Module (UK/US/CA).
      • 1x USB-C to USB-C cable (male-male) for connecting the Raspberry Pi to the splitter.
      • 1x USB-A to USB-C cable (male-male) for connecting the server to the splitter.
      • 1x USB-A to USB-C cable (male-male) to connect into a USB-A wall charger. Or 1x USB-C to USB-C cable to connect into a USB-C wall charger. Or you also can buy the official Raspberry Pi Power Supply with USB-C instead.
  • Only for Raspberry Pi ZeroW:
    • 2x USB A-to-micro cables (male-male, for power and keyboard & mouse emulator).
    • 1x Raspberry Pi Zero Camera Cable (if using HDMI to CSI-2 Bridge, but not compatible with Auvidea B101, check pinout).
  • For ATX control (optional):

A few words about HDMI-USB dongle

It's completely supported and Pi-KVM works great with it. But it has some disadvantages compared with recommended HDMI-CSI bridge: USB gives a lot of latency (200ms vs 100ms) and it doesn't support stream compression control (you won't be able to use Pi-KVM in a place with a poor internet connection). It also cannot automatically detect screen resolution. All this is caused by the hardware limitations of the dongle itself. In addition, 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.

Hardware for v0

  • Raspberry Pi 2 or 3.
  • MicroSD card (8 GB is enough).
  • USB-A 3A charger (female socket) or power supply.
  • For keyboard & mouse emulator (HID):
    • Arduino Pro Micro (based on an ATMega32u4).
    • Logic level shifter.
    • 1x NPN transistor (almost any NPN transistor: 2n2222 or similar).
    • 1x 390 Ohm resistor.
    • A breadboard and wires.
  • 2x USB A-to-micro cables (male-male, for power and HID).
  • HDMI capture device: see v2 description.
  • ATX control (optional): see v2 description.

Addition

  • If you want to capture VGA from your server instead of HDMI, buy the VGA-to-HDMI converter.
  • Pi-KVM can be powered using PoE, but it is not recommend to use the official PoE HAT: it is unreliable and not compatible with the HDMI bridge. Use any other PoE hat without an I2C fan controller.
  • Don't use random relay modules or random optocouplers! Some relays or optocouplers 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.
    drawing

The future v3 platform (work in progress)

drawing

We are also currently developing our own HAT for the Raspberry Pi 4. It will have all the features of the v2 platform, including:

  • HDMI capture based on the TC358743 (extra low latency and many features like compression control).
  • OTG Keyboard & mouse; Mass Storage Drive emulation.
  • Ability to simulate "removal and insertion" for USB.
  • Onboard ATX power control.
  • Onboard fan controller.
  • A real-time clock.
  • CISCO-style and USB serial console port (to manage Pi-KVM OS or to connect with the server).
  • Optional AVR-based HID (for some rare and strange motherboards whose BIOS doesn't understand the OTG emulated keyboard).
  • Optional OLED screen to display network status or other desired information.
  • No need for soldering or other assembly. It's a ready-made, reliable board which you can use yourself or provide to your clients.
  • Continued use of Pi-KVM OS - all the software will be fully open.
  • It will cost about $135 - or less, we are working to make it as cheap as possible.

YouTube Review of the v3 board: https://youtu.be/dTchVKxx7Fo

Sounds interesting? Subscribe in this form or join to Discord and we will let you know when you can purchase the board.

**Status as of April 2021: We expect to receive the first batch from the factory on April 20. Hurray! Sales are expected to start shortly afterwards. **


Setting up the hardware

Connecting the video capture

For the HDMI-CSI bridge

Click to show the instructions Insert the flexible flat cable of the HDMI 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-2 slot on the Raspberry Pi
detailed picture of the MIPI-CSI2 slot

For the HDMI-CSI bridge it 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. 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-2 bridge connected to Raspberry Pi 4
HDMI-CSI-2 bridge connected to Raspberry Pi 4

For the HDMI-USB dongle

Click to show the instructions 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
drawing drawing

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.

Setting up the v2

Click to show the instructions Here is a diagram shows that how to connect all of the pieces (click to full size).
ATX control board USB splitter cable (only for Raspberry Pi 4)
drawing drawing

Raspberry Pi 4: since one USB-C female connector is used to receive power and perform keyboard/mouse/drive emulation a special Y-cable must be made that splits the DATA and POWER lines of USB-C (see reasons). It can be made from two suitable connecting cables, or soldered together from scratch. Be sure to check the circuit diagram below, otherwise you may damage your devices. 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.

Raspberry Pi Zero W: This board has two USB micro connectors: one for power supply, the second for emulating a USB OTG device. You need to prevent backpowering as in the RPi4 case. To do this, you need to cut off the red power wire in the OTG wire, or seal the +5v pin in the USB-A connector with electrical tape like this: drawing

See video how-tos:

Setting up the v0

Click to show the instructions
ATX control board and Arduino HID (keyboard & mouse)
drawing

Installing the OS

Here the final steps. There are two ways to get the Pi-KVM OS:

  • We provide the ready-made images for Raspberry Pi 4 for platforms v2-hdmi (the CSI-2 bridge) and v2-hdmiusb (the USB dongle); and for ZeroW for v2-hdmi Follow these instructions to install the OS quickly.
  • For the other boards and platforms, you need to build the operating system manually. Don't worry, it's very simple! Just follow these instructions. You can also build the OS for RPi4 manually if you really want to :)

You're amazing!

Congratulations! Your Pi-KVM will be available via SSH (ssh root@<addr> with password root by default) and HTTPS (try to open in a browser the URL https://<addr>, the login admin and password admin by default). For HTTPS a self-signed certificate is used by default.

To change the root password use command passwd via SSH or webterm. To change Pi-KVM web password use kvmd-htpasswd set admin. As indicated on the login screen use rw to make the root filesystem writable, before issuing these commands. After making changes, make sure to run the command ro.

Access to Pi-KVM from the Internet

You can use port forwarding for port 443 on your router if it has an external IP address. In all other cases, you can use the excellent free VPN service Tailscale, which is configured on Pi-KVM with a few simple commands.

If you have any problems or questions, contact us using Discord: https://discord.gg/bpmXfz5

Subscribe to our Subreddit to follow news and releases: https://www.reddit.com/r/pikvm

Happy using of Pi-KVM :)


Limitations

  • In very rare cases, some motherboards contain a buggy BIOS that does not understand the keyboard of the v2 platform (below). The reason for this is that the BIOS doesn't fully implement the USB HID stack for composite devices correctly. Meanwhile, Mass Storage Drive can be detected. For this case, we suggest using the Arduino HID from the v0 platform with v2. Thus the Pi-KVM will be connected by two USB cables to the motherboard: one of them will be responsible for the keyboard and mouse, the other for everything else. See here.
  • A similar problem can be observed on devices with UEFI: the keyboard works fine, but the mouse does not work. This situation occurs when UEFI does not support absolute mouse mode, which prefers to use Pi-KVM. To solve this problem, you can enable relative mouse mode.
  • To use Pi-KVM with Apple UEFI, use the Arduino HID even with v2. Apple UEFI wants the most blunt keyboard possible.

Our future v3 platform will contain an optional HID module for such cases, so you won't have to build anything yourself.


Tips


FAQ & Troubleshooting

If you have any questions or run into problems, take a look at this page. We've probably already found a solution for it :)

For any help, you can contact our discord chat: https://discord.gg/bpmXfz5


Donate

This project is developed on a non-commercial basis by Open Source enthusiasts. If you find Pi-KVM useful or it has saved you a long trip to check on an unresponsive server, you can support the lead developer by donating a few dollars via Patreon or PayPal. With this money, he will be able to buy new hardware (Raspberry Pi boards and other components) to test and maintain various configurations of Pi-KVM, and generally devote significantly more time to the project. At the bottom of this page are the names of all the people who have helped this project develop with their donations. Our gratitude knows no bounds!

If you wish to use Pi-KVM in production, we accept orders to modify it for your needs or implement custom features you require. Contact us via live chat or email the lead developer at: mdevaev@gmail.com


Special thanks

These kind people donated money to the Pi-KVM project and supported work on it. We are very grateful for their help, and commemorating their names is the least we can do in return.

View all people!
  • A. Isenring
  • Aaron Heise
  • Accalia
  • Adam Goodbar
  • adipisicing
  • Adrian Basham
  • Alberto Bassi
  • Aleksei Brusianskii
  • Alessio Curri
  • Alex T
  • Alexander Pankov
  • Alexandre Jablonski
  • Alucard
  • Andreas Marufke
  • Andreas Schmid
  • Andrew Reusch
  • Andrew Ruan
  • Andrzej V
  • Anish Patel
  • Anix
  • anonymous
  • Anton Kovalenko
  • Aron Green
  • Aron Perelman
  • Arthur Woimbée
  • Ashlesh Chaudhari
  • Augusto Becciu
  • AVS Computer
  • baddog
  • Bao Tin Hoang
  • Belf Igor
  • Ben Gordon
  • Ben Scott
  • Benedikt Heine
  • Benedikt Meier
  • Benjamin Melancon
  • Benni Stauder
  • Bernhard Fitzke
  • bitjoe
  • Bits and Bytes Computers LLC
  • Blue Frog LLC
  • Bootstrapper - Programmierung erklärt
  • Bosco
  • Bradford King
  • Brainspore Networks
  • Branden Shaulis
  • Brandon Daniels
  • Brian Moses
  • Brian Vecchiarelli
  • Brian White
  • Bruno Gomes
  • Bryan Adams
  • Bryan Montgomery
  • C P ELSE
  • Cameron Tacklind
  • Carl Mercier
  • Carl-Fredrik Johansson
  • cbad536
  • Chris Burton
  • Chris Lewis
  • Chris Rizio
  • Christian Schlögl
  • Christian Svensson
  • Christoph Dette
  • Christof Maluck
  • Christoffer Lund
  • Christopher Hearn
  • Christopher Mandlbaur
  • Chucktastic
  • Clifford Coleman
  • Clinton Lee Taylor
  • Cole Imhoff
  • Colin Goodman
  • Corey Layton
  • Corey Lista
  • Crossfactor
  • ctag
  • CyB0rgg
  • DeMentor
  • Desmond Whitt
  • Damon Meledones
  • Dan Berkowitz
  • Dan Brakeley
  • David
  • David Godibadze
  • David Howell
  • David Niemann
  • David Ye
  • David York
  • Denis
  • Denis Andreev
  • Denis Yatsenko
  • Dennis Becker
  • Dennis Lomet
  • Derek Yap
  • Didrik
  • dixon wong
  • dizztrukshin
  • Dmitry Shilov
  • Egan Ford
  • Elliot Woo
  • Eric Phenix
  • ewook
  • eye-catcher.com
  • Fabiano Sidler
  • Far Pin Solutions, LLC
  • Felyx Gabryel
  • Fergus McKay
  • Finn Ebenritter
  • fo0bar
  • Foamy
  • Francisco Pavon
  • Frank
  • Frederick Czajka
  • Fredrik Idréus
  • Ge Men
  • Genkinger Andreas
  • Georgy Brodsky
  • Gernot Neuschröer
  • Giovanni Fulco
  • GK
  • Glen Dragon
  • Greg Winterstein
  • Gregory Smith
  • Gregory Treantos
  • Grey Cynic
  • Guido Bernacchi
  • Gustin Johnson
  • Heikki Tiittanen
  • Helio Leonardo Pinheiro e Mota
  • Henrik Ählström
  • Henry Hood
  • HimKo
  • HouseFPV
  • Icculus
  • iks
  • IT Lifesaver
  • Ivan Shapovalov
  • J L
  • Jaanus
  • Jackson Wyatt
  • Jacob Morgan
  • James Cadd
  • James Cobb
  • James Edwards
  • James Kocher
  • James Mayhugh
  • Jamie Murphy
  • Jan Niehusmann
  • Jari Hiltunen
  • Jason Downey
  • Jason Toland
  • Jay Davis
  • Jay Isaacs
  • Jazereel Goh
  • Jean-Philippe Guilbault
  • Jeff Bowman
  • Jeff Urlwin
  • Jennifer Herting
  • Jennifer Rowlett
  • Jerremy Holland
  • Jim Harbin
  • Jimmy Stanley
  • Joachim Bruening
  • Joe Hinteregger
  • Joe Ventura
  • Joel Jacobs
  • John Andersen
  • John Copeland
  • John F Glenn
  • John Kelley
  • John McGovern
  • Johnny Henson
  • Jonathan Vaughn
  • Josh Ricker
  • Joshua Futterer
  • Jordi Pakey-Rodriguez
  • Joris van Embden
  • Jozef Riha
  • Jörgen Fredriksson
  • Julian Forero
  • Julian Schneider
  • Justin Waters
  • Karl Dunne
  • Keith Muggleton
  • Ken Lee
  • Kenny Hui
  • Kevin Bajohr
  • Kevin Schwartz
  • Kevin Sherwood
  • Kiran Schuler
  • Koloman
  • Krzysztof Żelaśkiewicz
  • Larry Meaney
  • Lars
  • Lee Wilkinson
  • LeeNX
  • Leonard Feineis
  • Lordbob75
  • Lothar Schweikle-Droll
  • Louis Müller
  • Luca Di Diomede
  • Lucio De Carli
  • Lukas Söder
  • Malcolm Cameron
  • Marcio Zimbres
  • Marcos Wolf
  • Marius
  • Mar. Balske
  • Mark Gilbert
  • Mark Robinson
  • Markrosoft
  • Markus Halm
  • Markus Schicker
  • Markus Sobczack
  • Marshall Bjerke
  • Marten Hermans
  • Martin Gasser
  • Martin Suelmann
  • Marvin Honderboom
  • Mateusz Grabowski
  • Matthew Cameron
  • Mauricio Allende
  • Mecky
  • Mehmet Aydoğdu
  • Michael Bombe
  • Michael Collins
  • Michael Copeland
  • Michael Kovacs
  • Michael Lynch
  • Michael Pennington
  • Michael Sage
  • MichaelZ
  • Michel Bissonnette
  • Milan Múčka
  • Miles Davis
  • Moez Tharani
  • Morgan Helton
  • Nathaniel Griswold
  • Nelson Lee
  • Nicholas Jeppson
  • Nicholas Kopas
  • Nicholas Walczak
  • Nick Leffler
  • Nick Roethemeier
  • Nicolai Kragh-Hansen
  • Nihal Fernando
  • Nils Orbat
  • Nis Wechselberg
  • Nithin Philips
  • Nod Swal
  • nubbn
  • nybble
  • Oh Be
  • Oliver Schwarz
  • Oliver Zimmer
  • Omar El-Domeiri
  • Oscar
  • Patrick McDowell
  • Patrick Wagstrom
  • Paul Bishop
  • Pawel Trofimiuk
  • Peder Madsen
  • Peter Drayton
  • Peter Farrelly
  • Petri Heiskanen
  • Philip Edwards
  • Philip Merricks
  • posicat
  • pozitron03
  • Qteal
  • Quentin Peten
  • Ralph Borchers
  • Ranc1d
  • Raphael Schitz
  • Richard Bernarts
  • Richard Fancher
  • Richard Freemantle
  • Richard Michael
  • Rob Tongue
  • Robert Klauco
  • Robin Gfatter
  • Rodion DENISYUK
  • Rohit Priyadarshi
  • Rolfs 3D UG
  • Ronald LeBaron
  • rotx
  • Russell Scott
  • Samed Ozoglu
  • Sameul Davies
  • Samuel Vetsch
  • Satish Alwani
  • Scott
  • Scott Gagon
  • Scott Spicola
  • Scott Tusing
  • Sean
  • Seonwoo Lee
  • Sergey Lukjanov
  • Shichun Chen
  • Simon Evans
  • Simon Sundgaard
  • Simplistic Realities
  • srepac
  • Stefan Bautz
  • Stefan Müller
  • Stefan Stemmer
  • Stephan Schmidt
  • Steve Kerr
  • Steve Ovens
  • Steve Stringham
  • Steven Richter
  • sudo34
  • Tarlak Desaydrone
  • TechBear
  • Ted
  • Tejun Heo
  • TheTechGiant
  • Thomas Hagenmaier
  • Thomas Price
  • Thomas Søfteland
  • Tim Wilkinson
  • Timo Brinkmann
  • Timothee Besset
  • Tom Lawson
  • Tom York
  • Tomas Kuchta
  • Tomáš hrubý
  • Torsten Droste
  • Tobias Schafferhans
  • Tristan Schoening
  • Truman Kilen
  • turbochris
  • Tyler
  • Udo Schroeter
  • Uli Fahrer
  • Vasily Lazarev
  • Vicente Salvador Cubedo
  • Viktor Aschenbrenner
  • Viktor Ekmark
  • Walter_Ego
  • William Hooper
  • William Stearns
  • Yethal
  • Yevgeniy Kuksenko
  • Yogi
  • Yigal Dar
  • YURI LEE
  • Yurii Ostapchuk
  • zgen
  • Zsombor Vari