@ -32,7 +32,7 @@ The website: [pikvm.org](https://pikvm.org). Also join to the [Discord Community
* 100% Open Source!
<details>
<summary><b>More indepth details about the Pi-KVM features</b></summary>
<summary><b>More indepth details about the PiKVM features</b></summary>
## Fully-featured and modern IP-KVM
* **Cheaper, but better than commercial solutions**
@ -40,27 +40,27 @@ The website: [pikvm.org](https://pikvm.org). Also join to the [Discord Community
* **Easy to build - For the v0 variant**
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.
There are many ways to build a PiKVM. 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 PiKVM 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!
No weird proprietary clients. No ugly Java applets. Just use your favorite browser to connect to the PiKVM. 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.
On the Raspberry Pi 4 and ZeroW, PiKVM 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 is used to protect traffic from being intercepted by third parties.
PiKVM can be opened to the Internet and no one will get access without the password. SSL 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.
PiKVM 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](https://archlinuxarm.org) 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!
The PiKVM OS is based on [Arch Linux ARM](https://archlinuxarm.org) 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**
@ -68,30 +68,30 @@ The website: [pikvm.org](https://pikvm.org). Also join to the [Discord Community
* **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.
PiKVM 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](https://github.com/pikvm/kvmd-auth-server). PAM and its rich authorization mechanisms can also be used to integrate Pi-KVM into your existing authentication infrastructure.
Multiple PiKVMs can be configured to use a [common authorization service](https://github.com/pikvm/kvmd-auth-server). PAM and its rich authorization mechanisms can also be used to integrate PiKVM 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](https://discord.gg/bpmXfz5) if you have any questions.
PiKVM has a large community. Join the [discord chat](https://discord.gg/bpmXfz5) 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.
PiKVM 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](https://github.com/pikvm/ustreamer) 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.
We created [our very own MJPG video server](https://github.com/pikvm/ustreamer) written in C with multi-threading support and GPU video encoding - the fastest streaming solution available to provide the best video quality for PiKVM. We also tested a lot of hardware configurations so that you can be sure devices you assemble will work reliably.
</details>
-----
# 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**. **For Raspberry Pi 4 (not for Zero), there is support for H.264 video.**. **It's also the easiest to make**.
PiKVM 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 PiKVM including the **Mass Storage Drive**. **For Raspberry Pi 4 (not for Zero), there is support for H.264 video.**. **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
@ -148,7 +148,7 @@ Pi-KVM supports several different hardware configurations, referred to as **plat
- A breadboard and wires.
#### A few words about HDMI-USB dongle (H.264 is NOT officially supported at this time)
The dongle is completely supported and Pi-KVM works great with it. But it has some disadvantages compared with recommended [HDMI-CSI bridge](https://aliexpress.com/item/4000102166176.html): USB gives a lot of latency (200ms vs 100ms for MJPEG) 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). There is no H.264 support at the moment. 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.
The dongle is completely supported and PiKVM works great with it. But it has some disadvantages compared with recommended [HDMI-CSI bridge](https://aliexpress.com/item/4000102166176.html): USB gives a lot of latency (200ms vs 100ms for MJPEG) and it doesn't support stream compression control (you won't be able to use PiKVM in a place with a poor internet connection). There is no H.264 support at the moment. 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.
@ -166,18 +166,18 @@ The dongle is completely supported and Pi-KVM works great with it. But it has so
#### Addition
* If you want to capture VGA from your server instead of HDMI, buy the [VGA-to-HDMI converter](https://aliexpress.com/item/4000553298530.html).
* 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](https://github.com/pikvm/pikvm/issues/6). Use any other PoE hat without an I2C fan controller.
* PiKVM 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](https://github.com/pikvm/pikvm/issues/6). 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](https://github.com/pikvm/pikvm/issues/13).
# How to set up the device can be seen from [here](https://github.com/pikvm/pikvm/blob/master/pages/Wiring%20Examples.md)
# Pi-KVM v3 HAT Features
# PiKVM v3 HAT Features
<imgsrc="img/v3_kit.jpg"alt="drawing"height=200>
**[>>> Pi-KVM v3 HAT on Kickstarter! <<<](https://www.kickstarter.com/projects/mdevaev/pikvm-v3-hat)**
**[>>> PiKVM v3 HAT on Kickstarter! <<<](https://www.kickstarter.com/projects/mdevaev/pikvm-v3-hat)**
We have developed our own HAT for the Raspberry Pi 4. It will have all the features of the v2 platform, including:
@ -190,7 +190,7 @@ We have developed our own HAT for the Raspberry Pi 4. It will have all the featu
* **Onboard ATX controller** to manage the server's power.
* **PWM fan controller**.
* **A real-time clock** for accurate logging.
* CISCO-style and USB **serial console port** (to manage Pi-KVM OS or to connect the server).
* CISCO-style and USB **serial console port** (to manage PiKVM OS or to connect the server).
* Ability to use **IPMI BMC**, **IPMI SoL**, **Redfish** and **Wake-on-LAN** to control the server.
* **Extensible authorization** and **SSL encryption** out of the box.
* **Health monitoring** of the Raspberry Pi.
@ -200,11 +200,11 @@ We have developed our own HAT for the Raspberry Pi 4. It will have all the featu
* **No need for soldering or breadboarding**. It's a ready-made, reliable board which you can use yourself or provide to your clients.
Watch the video:
* [Pi-KVM v3 Review by **Novaspirit Tech**](https://youtu.be/dTchVKxx7Fo)
* [PiKVM v3 Review by **Novaspirit Tech**](https://youtu.be/dTchVKxx7Fo)
* [Another review by **Level1Techs**](https://www.youtube.com/watch?v=LwsznhIBPMc)
* [Review by **The Geek Freaks** (DE)](https://www.youtube.com/watch?v=fnd6wojrw3c)
**[>>> Pi-KVM v3 HAT on Kickstarter! <<<](https://www.kickstarter.com/projects/mdevaev/pikvm-v3-hat)**
**[>>> PiKVM v3 HAT on Kickstarter! <<<](https://www.kickstarter.com/projects/mdevaev/pikvm-v3-hat)**
-----
@ -272,27 +272,27 @@ See video how-tos:
-----
# Installing the OS
Here the final steps. There are two ways to get the Pi-KVM OS:
Here the final steps. There are two ways to get the PiKVM OS:
* We provide the ready-made images for **Raspberry Pi 4** for platforms v3, **v2-hdmi** (the CSI-2 bridge) and **v2-hdmiusb** (the USB dongle); for **ZeroW****v2-hdmi** [Follow these instructions](pages/flashing_os.md) 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](pages/building_os.md). You can also build the OS for RPi4 manually if you really want to :)
# You're amazing!
- ❗NOTE❗ After performing any update of pikvm, clear web browser cache or use incognito/private browsing mode.
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.
Congratulations! Your PiKVM 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`.
To change the root password use command `passwd` via SSH or webterm. To change PiKVM 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
# Access to PiKVM from the Internet
- ❗NOTE❗ Please take proper security precaustions when exposing this to the internet. The use of tailscale is HIGHLY suggested.
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](pages/tailscale.md), which is configured on Pi-KVM with a [few simple commands](pages/tailscale.md).
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](pages/tailscale.md), which is configured on PiKVM with a [few simple commands](pages/tailscale.md).
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 :)
Happy using of PiKVM :)
-----
@ -302,11 +302,11 @@ Happy using of Pi-KVM :)
-----
# What's next?
* The Pi-KVM file system is always mounted in read-only mode. This prevents it from being damaged by a sudden power outage. To change the configuration you must first switch the filesystem to write mode using the command `rw` from root. After the changes, be sure to run the command `ro` to switch it back to read-only.
* The PiKVM file system is always mounted in read-only mode. This prevents it from being damaged by a sudden power outage. To change the configuration you must first switch the filesystem to write mode using the command `rw` from root. After the changes, be sure to run the command `ro` to switch it back to read-only.
* **NEVER** edit `/etc/kvmd/main.yaml`. Use `/etc/kvmd/override.yaml` to redefine the system parameters. All other files that are also not recommended for editing have read-only permissions. If you edit any of these files, you will need to manually make changes to them when you upgrade your system. You can view the current configuration and all available KVMD parameters using the command `kvmd -m`.
* Almost all KVMD (the main daemon controlling Pi-KVM) configuration files use [YAML](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html) syntax. Information on the format's syntax can be found at the link provided.
* Almost all KVMD (the main daemon controlling PiKVM) configuration files use [YAML](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html) syntax. Information on the format's syntax can be found at the link provided.
@ -365,14 +365,14 @@ 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](https://www.patreon.com/pikvm) or [PayPal](https://www.paypal.me/mdevaev). 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!
This project is developed on a non-commercial basis by Open Source enthusiasts. If you find PiKVM 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](https://www.patreon.com/pikvm) or [PayPal](https://www.paypal.me/mdevaev). With this money, he will be able to buy new hardware (Raspberry Pi boards and other components) to test and maintain various configurations of PiKVM, 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](https://discord.gg/bpmXfz5) or email the lead developer at: mdevaev@gmail.com
If you wish to use PiKVM in production, we accept orders to modify it for your needs or implement custom features you require. Contact us via [live chat](https://discord.gg/bpmXfz5) 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.
These kind people donated money to the PiKVM 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.
| https://www.thingiverse.com/thing:4799094 | Case for the [USB-C/PWR Splitter without Barrel jack](https://www.tindie.com/products/8086net/usb-cpwr-splitter/) |
| https://www.thingiverse.com/thing:4931970 | Case for the [USB-C/PWR Splitter without Barrel jack](https://www.tindie.com/products/8086net/usb-cpwr-splitter/) |
| https://www.thingiverse.com/thing:4862304 | Case for Pi-KVM (LCD + ATX) |
| https://www.thingiverse.com/thing:4862304 | Case for PiKVM (LCD + ATX) |
| https://www.thingiverse.com/thing:4868258 | R4C3R - Low Profile PCIe bracket for PiKVM based on Raspberry Pi Zero + Lusya + ATX controls |
| https://www.thingiverse.com/thing:4866005 | R4C3R - Full Profile PCIe bracket for PiKVM based on Raspberry Pi Zero + Lusya + ATX controls |
| https://www.thingiverse.com/thing:4832248 | Case for the [USB-C/PWR Splitter without Barrel jack](https://www.tindie.com/products/8086net/usb-cpwr-splitter/) and HDMI-CSI bridge |
| https://www.thingiverse.com/thing:4916230 | A very compact case without internal power splitter |
| https://www.thingiverse.com/thing:4915627 | ZeroW + CSI case |
| https://www.thingiverse.com/thing:4950281 | Pi-KVM RETRO Case for CSI-2 C779 Bridge w/ OLED Display Screen |
| https://www.thingiverse.com/thing:4950281 | PiKVM RETRO Case for CSI-2 C779 Bridge w/ OLED Display Screen |
| https://www.thingiverse.com/thing:4950280 | USB Power Blocker Case |
- [Can this do 4K?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#can-this-do-4k)
- [Does PIKVM support sound](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#does-pikvm-support-sound)
- [Why so much latency between the screen and target?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#why-so-much-latency-between-the-screen-and-target)
- [Is Pi-KVM an OS or its own Distro?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#is-pi-kvm-an-os-or-its-own-distro)
- [Is PiKVM an OS or its own Distro?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#is-pikvm-an-os-or-its-own-distro)
- [Why are you using Arch Linux?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#why-are-you-using-arch-linux)
- [Can I power the Pi via POE?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#can-i-power-the-pi-via-poe)
- [Do I need a power splitter? Why do I need one?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#do-i-need-a-power-splitter-why-do-i-need-one)
- [I can't get the KVM KB to work on my ZeroW!](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#i-cant-get-the-kvm-kb-to-work-on-my-zerow)
- [Can I use a KB on my ZeroW?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#can-i-use-a-kb-on-my-zerow)
- [Can you have the pi-kvm(RPi4) connected along with a monitor?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#can-you-have-the-pi-kvmrpi4-connected-along-with-a-monitor)
- [Wouldn't it be good to have different hostnames for your multitude of pi-kvms?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#wouldnt-it-be-good-to-have-different-hostnames-for-your-multitude-of-pi-kvms)
- [I want to do something not related to Pi-KVM](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#i-want-to-do-something-not-related-to-pi-kvm)
- [Can you have the pikvm(RPi4) connected along with a monitor?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#can-you-have-the-pikvmrpi4-connected-along-with-a-monitor)
- [Wouldn't it be good to have different hostnames for your multitude of pikvms?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#wouldnt-it-be-good-to-have-different-hostnames-for-your-multitude-of-pikvms)
- [I want to do something not related to PiKVM](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#i-want-to-do-something-not-related-to-pikvm)
- [Can this be used in any other distro’s like Rasbian? Run this in a Docker?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#can-this-be-used-in-any-other-distros-like-rasbian-run-this-in-a-docker)
- [Can you switch from USB to CSI or from CSI to USB?](#can-you-switch-from-usb-to-csi-or-from-csi-to-usb)
- [My Pi keeps disconnecting from my wireless! What do I do?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#my-pi-keeps-disconnecting-from-my-wireless-what-do-i-do)
@ -31,9 +31,9 @@
- [How do I emulate various USB devices on the target machine?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#how-do-i-emulate-various-usb-devices-on-the-target-machine)
- [Things to do after initial install](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#things-to-do-after-initial-install)
- [Can I have a RW FS all of the time?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#can-i-have-a-rw-fs-all-of-the-time)
- [Can you run a desktop on pi-kvm?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#can-you-run-a-desktop-on-pi-kvm)
- [Can you run a desktop on pikvm?](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#can-you-run-a-desktop-on-pikvm)
[Back to the Top](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#Index)
### Is Pi-KVM an OS or its own Distro?
### Is PiKVM an OS or its own Distro?
- Yes and No, Other than the some repacking and patches, its heavly based off an existing [Arch Linux ARM](https://archlinuxarm.org/).
[Back to the Top](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#Index)
@ -116,11 +116,11 @@ Ensure that you have the cable(Needs to support both power/data) plugged into th
[Back to the Top](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#Index)
### Can you have the pi-kvm(RPi4) connected along with a monitor?
### Can you have the pikvm(RPi4) connected along with a monitor?
- **A community member has had success with the following: https://www.amazon.com/gp/product/B08DQWLXF1**
- Some Alternitives
- If you have two outputs, you may be able to use screen mirroring from the OS but not BIOS
- If you have one output or need access from both a local monitor or Pi-KVM at boot time, one of the following options may work:
- If you have one output or need access from both a local monitor or PiKVM at boot time, one of the following options may work:
- Passthrough HDMI capture devices (sometimes referred to as a loop capture device). The Elgato devices DO NOT WORK! Look for Linux OS support when choosing a device, the expected price range is about $35-$70 US.
- Depending on your capture device, an HDMI splitter may work but will need what is called an EDID (Extended Device ID) generator, the monitor and capture device both generate EDID so the splitter must produce its own separate EDID for the host.
- Look for HDMI splitters - although there have been reports that these are not stable
@ -129,7 +129,7 @@ Ensure that you have the cable(Needs to support both power/data) plugged into th
[Back to the Top](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#Index)
### Wouldn't it be good to have different hostnames for your multitude of pi-kvms?
### Wouldn't it be good to have different hostnames for your multitude of pikvms?
Yes! And it's easy to do! Using a SSH session or the web terminal:
- Make sure you're `root`, if you're not root use the `su` command to become root
- Enter read write mode of the PiKVM by executing the `rw` command
@ -139,7 +139,7 @@ Yes! And it's easy to do! Using a SSH session or the web terminal:
[Back to the Top](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#Index)
### I want to do something not related to Pi-KVM
### I want to do something not related to PiKVM
- It's recommended that you review Arch documents related to what you want to do, while there are several folks in discord who can help, there is no obligation...they do it for the feels. So if you don't get an answer within the time frame you are looking for, it's advised you start google searching for what you want.
[Back to the Top](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#Index)
@ -273,7 +273,7 @@ set tabstospaces
### Can I use RealVNC/Guacamole to connect to PiKVM?
- No, RealVNC is not a real vnc so will not work
- No, Guacamole supports a minimum of VNC capabilities and is fundamentally incompatible with Pi-KVM (for example, it does not support JPEG for video compression).
- No, Guacamole supports a minimum of VNC capabilities and is fundamentally incompatible with PiKVM (for example, it does not support JPEG for video compression).
[Back to the Top](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#Index)
[Back to the Top](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#Index)
### Can you run a desktop on pi-kvm?
### Can you run a desktop on pikvm?
- Yes BUT, its not recommended OR supported as this OS should be used in RO and it will need RW enabled all of the time. Instructions [here](https://www.linuxfordevices.com/tutorials/linux/how-to-install-gui-on-arch-linux)
[Back to the Top](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#Index)
[Back to the Top](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#Index)
### Common Commands for troubleshooting Pi-KVM
### Common Commands for troubleshooting PiKVM
- `journalctl -u kvmd`
- `journalctl -u kvmd-vnc`
@ -518,14 +518,14 @@ iw wlan0 info
### Misc stuff
- Fully working [example](https://docs.google.com/document/d/1wgBZHxwpbJWkJBD3I8ZkZxSDxt0DdNDDYRNtVoL_vK4) of a Pi4 USB-HDMI KVM attached to AIMOS 4-port HDMI KVM switch (8 port is on AliExpress), with keyboard hotkey switching between inputs, and mass storage media emulation on a Pi Zero W
- Pi-KVM that mitigates HDMI backpower and requires no splitter board [here](https://docs.google.com/document/d/1M9xUgNE_-P8GydKr_3qIgXUR9YzqApHNPhetRv3pcsE/edit)
- Useful scripts that enhance the Pi-KVM's functionality ```https://pastebin.com/u/srepac```
- PiKVM that mitigates HDMI backpower and requires no splitter board [here](https://docs.google.com/document/d/1M9xUgNE_-P8GydKr_3qIgXUR9YzqApHNPhetRv3pcsE/edit)
- Useful scripts that enhance the PiKVM's functionality ```https://pastebin.com/u/srepac```
[Back to the Top](https://github.com/pikvm/pikvm/blob/master/pages/Community_FAQ.md#Index)
### Useful links
- https://www.tomshardware.com/how-to/kvm-over-ip-raspberry-pi - Very good article on PI-KVM setup
- Current 3D cases that support the various Pi-KVM hardware configurations:
- https://www.tomshardware.com/how-to/kvm-over-ip-raspberry-pi - Very good article on PIKVM setup
- Current 3D cases that support the various PiKVM hardware configurations:
This document describes the Pi-KVM API. Since the system consists of microservices, here is a common API with a common entry point provided by Nginx. The examples above use `curl` and [`websocat`](https://github.com/vi/websocat) with the `-k` parameter to disable SSL certificate verification, since the self-signed certificateis used in the default installation.
This document describes the PiKVM API. Since the system consists of microservices, here is a common API with a common entry point provided by Nginx. The examples above use `curl` and [`websocat`](https://github.com/vi/websocat) with the `-k` parameter to disable SSL certificate verification, since the self-signed certificateis used in the default installation.
## Authorization: `/api/auth`
All APIs are restricted to authorization. To make requests, you either need to authorize each request individually,
@ -81,7 +81,7 @@ ws.close()
```
## System info: `/api/info`
On `GET` this handle will return general information about the Pi-KVM device. If you specify the `fields` query parameter, only the requested category will be selected, like `fields=system,hw`. By default all categories will be displayed:
On `GET` this handle will return general information about the PiKVM device. If you specify the `fields` query parameter, only the requested category will be selected, like `fields=system,hw`. By default all categories will be displayed:
Pi-KVM is able to emulate a Bluetooth keyboard & mouse.
This is not the main case of using Pi-KVM since you still need it to pair with a remote host, but can be used for something like mobile KVM.
PiKVM is able to emulate a Bluetooth keyboard & mouse.
This is not the main case of using PiKVM since you still need it to pair with a remote host, but can be used for something like mobile KVM.
:exclamation: Using Bluetooth HID requires additional configuration of the operating system. For v2, this means losing the UART port,
since it will be used by Bluetooth. Also, Bluetooth operation was tested only on RPi4 and v2 platform. Other boards may require different system service settings.
@ -54,6 +54,6 @@ since it will be used by Bluetooth. Also, Bluetooth operation was tested only on
8. To reverse, uncomment lines from Step 2 and remove lines in Step 6, ```reboot```
# Using Bluetooth HID
* After a reboot, the Pi-KVM will be ready for detection and pairing with no auth. You will see the `Pi-KVM HID` device.
* Once the server is connected, Pi-KVM will no longer be discoverable and pairable to other clients until you unpair the server.
* If something went wrong, use the web menu `System -> Reset keyboard & mouse`. This will cause unpair the device and switch the Pi-KVM to public mode before the first client is connected.
* After a reboot, the PiKVM will be ready for detection and pairing with no auth. You will see the `PiKVM HID` device.
* Once the server is connected, PiKVM will no longer be discoverable and pairable to other clients until you unpair the server.
* If something went wrong, use the web menu `System -> Reset keyboard & mouse`. This will cause unpair the device and switch the PiKVM to public mode before the first client is connected.
The Pi-KVM OS is based on Arch Linux ARM and contains all the required packages and configs for it to work.
The PiKVM OS is based on Arch Linux ARM and contains all the required packages and configs for it to work.
To build the OS you will need x86_64 Linux machine with:
* kernel >= 5.8
@ -32,7 +32,7 @@ Latest Arch Linux is working.
- `PLATFORM=v0-hdmi` for RPi 2 or 3 with HDMI-CSI bridge and Arduino HID.
- `PLATFORM=v2-hdmiusb` for RPi4 with HDMI-USB dongle.
- `PLATFORM=v0-hdmiusb` for RPi 2 or 3 with HDMI-USB dongle and Arduino HID.
- Other options are for legacy or specialized Pi-KVM boards (WIP).
- Other options are for legacy or specialized PiKVM boards (WIP).
3. Create the config file `config.mk` for the target system. You must specify the path to the SD card on your local computer (this will be used to format and install the system) and the version of your Raspberry Pi and platform. You can change other parameters as you wish. Please note: if your password contains the # character, you must escape it using a backslash like `ROOT_PASSWD = pass\#word`.
```Makefile
@ -96,11 +96,11 @@ Latest Arch Linux is working.
8. **Only for v0**: [Flash the Arduino HID](flashing_hid.md).
9. 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.
9. Congratulations! Your PiKVM 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.
*The latest versions of Chrome do not allow access to the page with a self signed certificate. You can proceed by typing ```thisisunsafe``` and Chrome will then load the page*
10. 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`.
10. To change the root password use command `passwd` via SSH or webterm. To change PiKVM 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`.
11. Important **note for HDMI-USB dongle** users only. Because of this, many 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:
@ -120,7 +120,7 @@ Latest Arch Linux is working.
# systemctl restart kvmd
```
12. **27.08.2020 note about systemd**: the latest version of Arch Linux has a slightly broken systemd. The problem is that SSH to the Pi-KVM host may not work the first time, but the second or third. The Pi-KVM build environment contains a workaround for this problem: in the file `/etc/pam.d/system-login` line `-session optional pam_systemd.so` is commented. This does not have any negative impact on the PI-KVM functionality, but if you want to, after fixing the systemd (in a couple of months with the next update), you can uncomment this line.
12. **27.08.2020 note about systemd**: the latest version of Arch Linux has a slightly broken systemd. The problem is that SSH to the PiKVM host may not work the first time, but the second or third. The PiKVM build environment contains a workaround for this problem: in the file `/etc/pam.d/system-login` line `-session optional pam_systemd.so` is commented. This does not have any negative impact on the PiKVM functionality, but if you want to, after fixing the systemd (in a couple of months with the next update), you can uncomment this line.
## Further Help
If you have any problems or questions, contact us using Discord: https://discord.gg/bpmXfz5
This page contains derivative projects from our community that can be very useful.
This includes additional software, additional software, unofficial ports to other platforms and alternative firmware
and even PCB and case designs for Pi-KVM.
and even PCB and case designs for PiKVM.
# Software
* [Pi-KVM port to x86 using docker](https://github.com/purplepalmdash/pikvmx86) - BEWARE: This project has been abandoned - Left here for historical value
* [PiKVM port to x86 using docker](https://github.com/purplepalmdash/pikvmx86) - BEWARE: This project has been abandoned - Left here for historical value
* [Serial HID using STM32 (work in progress)](https://github.com/jannic/pikvm-hid-stm32)
Specifically to v2. This can be used for terminal access from the managed server to the Pi-KVM, or for any other purpose that requires a serial connection. In the last case, you only need to perform step 1 and reboot.
Specifically to v2. This can be used for terminal access from the managed server to the PiKVM, or for any other purpose that requires a serial connection. In the last case, you only need to perform step 1 and reboot.
1. Edit `/etc/kvmd/override.yaml` (remove `{}` if this your first configuration entry) and add these lines:
``` yaml
@ -65,7 +65,7 @@ Specifically to v2. This can be used for terminal access from the managed server
# systemctl enable getty@ttyGS0.service
# reboot
```
5. Once Pi-KVM is rebooted you will have access to a virtual serial port on the server that the USB is connected to. Use mingetty, screen, putty, or something like this to access the kvm from the server. The port is called `/dev/ttyAMA0`.
5. Once PiKVM is rebooted you will have access to a virtual serial port on the server that the USB is connected to. Use mingetty, screen, putty, or something like this to access the kvm from the server. The port is called `/dev/ttyAMA0`.
The ezCoo managed switch can be controlled by Pi-KVM to allow it to connect to multiple hosts. A typical scenario is a single Pi-KVM device which can control and switch between multiple hosts or servers using the ezCoo switch. UI elements can be added to the [GPIO dropdown](gpio.md) to allow switching between hosts from the Pi-KVM webpage. The instructions here were tested with the ~~[ezCoo SW41HA HDMI 4x1 switch](https://www.easycoolav.com/products/hdmi20-switch-4x1-with-usb20-kvm-4-port-usbsupport-4k60hz-444-and-hdr-audio-breakout)~~ [ezCoo EZ-SW41HA-KVMU3L 4x1 switch](https://www.easycoolav.com/products/hdmi20-switch-4x1-with-usb30-kvm-3-port-usbsupport-4k60hz-444-and-hdr-audio-breakout-36). Both older USB2.0 and newer USB3.0 variants are supported. The following was testing on a Raspberry Pi 4 but should also work on the Pi 2 and 3. This document was createdy using the contributions from multiple users on the [Pi-KVM Discord](https://discord.gg/bpmXfz5) and the author appreciates their efforts.
The ezCoo managed switch can be controlled by PiKVM to allow it to connect to multiple hosts. A typical scenario is a single PiKVM device which can control and switch between multiple hosts or servers using the ezCoo switch. UI elements can be added to the [GPIO dropdown](gpio.md) to allow switching between hosts from the PiKVM webpage. The instructions here were tested with the ~~[ezCoo SW41HA HDMI 4x1 switch](https://www.easycoolav.com/products/hdmi20-switch-4x1-with-usb20-kvm-4-port-usbsupport-4k60hz-444-and-hdr-audio-breakout)~~ [ezCoo EZ-SW41HA-KVMU3L 4x1 switch](https://www.easycoolav.com/products/hdmi20-switch-4x1-with-usb30-kvm-3-port-usbsupport-4k60hz-444-and-hdr-audio-breakout-36). Both older USB2.0 and newer USB3.0 variants are supported. The following was testing on a Raspberry Pi 4 but should also work on the Pi 2 and 3. This document was createdy using the contributions from multiple users on the [PiKVM Discord](https://discord.gg/bpmXfz5) and the author appreciates their efforts.
:exclamation: While most images of the switch do not show the sides, there is a Micro USB port on the side of the ezCoo switch. This is the management port, which is controlled via COM port on the ezCoo KVM. When plugged into the Raspberry Pi, it appears as `/dev/ttyUSB0`.
@ -13,14 +13,14 @@ From a high level, the ezCoo switch uses standard connections to the host machin
2. Connect the HDMI out from the ezCoo switch to the Raspberry Pi CSI-2 to HMDI input. Other users have reported HMDI encoder USB dongles as working.
3. Connect a USB-A to Micro USB cable from the Raspberry Pi to the management port on the side of the ezCoo switch.
4. Connect host USB and HDMI cables from the ezCoo switch to the machines to be managed per the switch instructions.
5. At this point the KVM switch should be present as a device on the Pi-KVM. SSH into Pi-KVM and ensure a device like `/dev/ttyUSB0` is present. The following instructions assume this is the KVM switch.
5. At this point the KVM switch should be present as a device on the PiKVM. SSH into PiKVM and ensure a device like `/dev/ttyUSB0` is present. The following instructions assume this is the KVM switch.
:exclamation: There is a limitation in the underlying Pi-KVM software related to plugging video cables from a host which is already powered and connected to a monitor to a Raspberry Pi CSI2-HDMI encoder. These limitations apply equally when using the ezCoo KVM switch. If video is not present in Pi-KVM, try keeping all host machines off and connecting them directly to the ezCoo switch before powering the hosts on.
:exclamation: There is a limitation in the underlying PiKVM software related to plugging video cables from a host which is already powered and connected to a monitor to a Raspberry Pi CSI2-HDMI encoder. These limitations apply equally when using the ezCoo KVM switch. If video is not present in PiKVM, try keeping all host machines off and connecting them directly to the ezCoo switch before powering the hosts on.
## Adding UI elements to control the KVM switch
The UI can be updated to add buttons to switch between KVM inputs and indicators for which input is currently selected. The instructions below will make these available in the Pi-KVM UI after clicking the "GPIO" menu button in the KVM view.
The UI can be updated to add buttons to switch between KVM inputs and indicators for which input is currently selected. The instructions below will make these available in the PiKVM UI after clicking the "GPIO" menu button in the KVM view.
1. SSH into Pi-KVM
1. SSH into PiKVM
2. Enable read-write mode on the sd card via `rw`
3. Edit the `/etc/kvmd/override.yaml` file and include the following. Note the assumption that the KVM switch is present on `/dev/ttyUSB0`:
As a first step, we recommend carefully reading our documentation on [GitHub](https://github.com/pikvm/pikvm). Most steps to successfully set up your Pi-KVM are already described there. If you run into any issues you can check this page which will list common errors. If that still doesn't help you you're welcome to raise an [issue ticket](https://github.com/pikvm/pikvm/issues) or [join our Discord](https://discord.gg/bpmXfz5) for further help.
As a first step, we recommend carefully reading our documentation on [GitHub](https://github.com/pikvm/pikvm). Most steps to successfully set up your PiKVM are already described there. If you run into any issues you can check this page which will list common errors. If that still doesn't help you you're welcome to raise an [issue ticket](https://github.com/pikvm/pikvm/issues) or [join our Discord](https://discord.gg/bpmXfz5) for further help.
Note: if you can't find an answer to your question here, try the [Community FAQ](Community_FAQ.md). It will be merged with this page in the future
@ -15,25 +15,25 @@ Note: if you can't find an answer to your question here, try the [Community FAQ]
-----
# Common questions
### Can I connect multiple servers to a single Pi-KVM?
### Can I connect multiple servers to a single PiKVM?
<details>
<summary>Click to view</summary>
* Yes, but it will require additional work to set up. See [this page](multiport.md).
</details>
### How can I get the access to Pi-KVM in my local network over Internet?
### How can I get the access to PiKVM in my local network over Internet?
<details>
<summary>Click to view</summary>
* 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](tailscale.md), which is configured on Pi-KVM with a [few simple commands](tailscale.md).
* 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](tailscale.md), which is configured on PiKVM with a [few simple commands](tailscale.md).
</details>
### Can I use Pi-KVM with non-Raspberry boards (Orange, Nano, etc)?
### Can I use PiKVM with non-Raspberry boards (Orange, Nano, etc)?
<details>
<summary>Click to view</summary>
* Yes, but you will have to prepare the operating system yourself. As for the Pi-KVM software, you will need to replace some config files (such as UDEV rules). If you are a developer or an experienced system administrator, you will not have any problems with this. In addition, we are open to patches. If you need help with this, please contact us via [Discord](https://discord.gg/bpmXfz5).
* Yes, but you will have to prepare the operating system yourself. As for the PiKVM software, you will need to replace some config files (such as UDEV rules). If you are a developer or an experienced system administrator, you will not have any problems with this. In addition, we are open to patches. If you need help with this, please contact us via [Discord](https://discord.gg/bpmXfz5).
</details>
-----
@ -43,7 +43,7 @@ Note: if you can't find an answer to your question here, try the [Community FAQ]
<details>
<summary>Click to view</summary>
* There are two types of accounts: OS and Pi-KVM (web interface) accounts. The system account `root` can be used for SSH/UART access and has the password `root`. The web interface account is called `admin` and has the password `admin`. The Pi-KVM account cannot be used for SSH access and vice versa.
* There are two types of accounts: OS and PiKVM (web interface) accounts. The system account `root` can be used for SSH/UART access and has the password `root`. The web interface account is called `admin` and has the password `admin`. The PiKVM account cannot be used for SSH access and vice versa.
To change passwords, use the following commands (under root):
```bash
@ -62,27 +62,27 @@ Note: if you can't find an answer to your question here, try the [Community FAQ]
* The web terminal works with the account `kvmd-webterm`. This is a regular user with no administrator privileges and. In addition, `sudo` and login are disabled for this user for security reasons. To get `root` access, you need to use the `su -` command (minus is important) and **enter the root password**.
</details>
### Where is the Pi-KVM configuration located?
### Where is the PiKVM configuration located?
<details>
<summary>Click to view</summary>
* Almost all KVMD (the main daemon controlling Pi-KVM) configuration files located in `/etc/kvmd`. You can also find nginx configs and SSL certificates there. KVMD configs use [YAML](config.md) syntax. The specific platform parameters can be found in the file `/etc/kvmd/main.yaml` and **you should never edit it**. Use `/etc/kvmd/override.yaml` to redefine the system parameters.
* Almost all KVMD (the main daemon controlling PiKVM) configuration files located in `/etc/kvmd`. You can also find nginx configs and SSL certificates there. KVMD configs use [YAML](config.md) syntax. The specific platform parameters can be found in the file `/etc/kvmd/main.yaml` and **you should never edit it**. Use `/etc/kvmd/override.yaml` to redefine the system parameters.
Another files that are also not recommended for editing have read-only permissions. If you edit any of these files, you will need to manually make changes to them when you upgrade your system. You can view the current configuration and all available KVMD parameters using the command `kvmd -m`.
</details>
### I can't edit any file on Pi-KVM. Why is the system in read-only mode?
### I can't edit any file on PiKVM. Why is the system in read-only mode?
<details>
<summary>Click to view</summary>
* The Pi-KVM file system is always mounted in read-only mode. This measure prevents it from being damaged by a sudden power outage. To change the configuration you must first switch the filesystem to write mode using the command `rw` from root. After the changes, be sure to run the command `ro` to switch it back to read-only. If you get a message that the file system is busy, then the easiest way is to perform a `reboot`.
* The PiKVM file system is always mounted in read-only mode. This measure prevents it from being damaged by a sudden power outage. To change the configuration you must first switch the filesystem to write mode using the command `rw` from root. After the changes, be sure to run the command `ro` to switch it back to read-only. If you get a message that the file system is busy, then the easiest way is to perform a `reboot`.
</details>
### How do I update Pi-KVM with the latest software?
### How do I update PiKVM with the latest software?
<details>
<summary>Click to view</summary>
* Pi-KVM OS is based on Arch Linux ARM and is fully updated from the repository by a regular package manager. Connect to your Pi-KVM via ssh and run:
* PiKVM OS is based on Arch Linux ARM and is fully updated from the repository by a regular package manager. Connect to your PiKVM via ssh and run:
```
rw
pacman -Syu
@ -102,7 +102,7 @@ Note: if you can't find an answer to your question here, try the [Community FAQ]
* WebRTC is an alternative mode for the default MJPEG and it's only supported on v2+ platforms with the CSI video capture device. See [this](webrtc.md) page to solve any problems with WebRTC.
</details>
### Pi-KVM does not show the video from the computer at all
### PiKVM does not show the video from the computer at all
<details>
<summary>Click to view</summary>
@ -147,7 +147,7 @@ Note: if you can't find an answer to your question here, try the [Community FAQ]
* The story is [here](https://github.com/raspberrypi/firmware/issues/1562). Very-very rarely, Raspberry boards can have a hardware defect that causes some of the chip blocks to be unstable under normal power. The solution is to slightly increase the power supply, as in overclocking. Add `over_voltage=1` (or `over_voltage=2` if previous doesn't help) to `/boot/config.txt` and perform `reboot`.
To make sure that you are facing this particular problem, first perform a diagnostic:
- Boot the Pi-KVM without the specified options.
- Boot the PiKVM without the specified options.
- Open Web-UI and wait for freezing.
- Click **System -> Reset Stream**.
- Click **System -> Open log** and make sure that the log contains messages like `H264: Can't wait for the VCOS semaphore`.
@ -158,13 +158,13 @@ Note: if you can't find an answer to your question here, try the [Community FAQ]
<details>
<summary>Click to view</summary>
* Sometimes Awesome WM on Linux can't recognize a video output change on a cable. That is, if the cable was first inserted into the monitor, and then you reconnected it to Pi-KVM - it may happen that you will not see the image. It seems that the problem is Awesome WM, since for example with KDE, it is not reproducable. If you turn on your workstation with Pi-KVM already connected, everything will work fine.
* Sometimes Awesome WM on Linux can't recognize a video output change on a cable. That is, if the cable was first inserted into the monitor, and then you reconnected it to PiKVM - it may happen that you will not see the image. It seems that the problem is Awesome WM, since for example with KDE, it is not reproducable. If you turn on your workstation with PiKVM already connected, everything will work fine.
</details>
-----
# USB problems (keyboard, mouse, mass storage, etc)
### My computer does not recognize USB of Pi-KVM v2+ at all
### My computer does not recognize USB of PiKVM v2+ at all
<details>
<summary>Click to view</summary>
@ -183,7 +183,7 @@ Note: if you can't find an answer to your question here, try the [Community FAQ]
<details>
<summary>Click to view</summary>
* The BIOS does not support absolute mouse mode, which is preferred by Pi-KVM. In this case, [you can enable relative or dual positioning mode](mouse.md).
* The BIOS does not support absolute mouse mode, which is preferred by PiKVM. In this case, [you can enable relative or dual positioning mode](mouse.md).
</details>
### I can't wake up suspended computer on v2+
@ -197,7 +197,7 @@ Note: if you can't find an answer to your question here, try the [Community FAQ]
```
</details>
### Mass storage drive working (I can boot an image from Pi-KVM v2+), but keyboard/mouse does not
### Mass storage drive working (I can boot an image from PiKVM v2+), but keyboard/mouse does not
<details>
<summary>Click to view</summary>
@ -217,7 +217,7 @@ Note: if you can't find an answer to your question here, try the [Community FAQ]
<details>
<summary>Click to view</summary>
* Unusual case: RPi4 is used as a Pi-KVM to control RPi3. In this case, the mouse delay may be several seconds. To fix it, just add line `usbhid.mousepoll=0` to `/boot/config.txt` to the server (i.e. RPI3 in our case) and reboot it.
* Unusual case: RPi4 is used as a PiKVM to control RPi3. In this case, the mouse delay may be several seconds. To fix it, just add line `usbhid.mousepoll=0` to `/boot/config.txt` to the server (i.e. RPI3 in our case) and reboot it.
</details>
-----
@ -227,7 +227,7 @@ Note: if you can't find an answer to your question here, try the [Community FAQ]
<details>
<summary>Click to view</summary>
* The latest versions of Chrome do not allow access to the page with a self signed certificate, so if you see the following screen when loading the pi-kvm website:
* The latest versions of Chrome do not allow access to the page with a self signed certificate, so if you see the following screen when loading the PiKVM website:
@ -245,8 +245,8 @@ Note: if you can't find an answer to your question here, try the [Community FAQ]
<details>
<summary>Click to view</summary>
* Safari on iOS contains an old bug that prevents a web application from connecting over a web socket if you use a self-signed certificate on the server (the default for Pi-KVM). There are two solutions:
- Install a valid SSL certificate for Pi-KVM host to `/etc/kvmd/nginx/ssl`.
* Safari on iOS contains an old bug that prevents a web application from connecting over a web socket if you use a self-signed certificate on the server (the default for PiKVM). There are two solutions:
- Install a valid SSL certificate for PiKVM host to `/etc/kvmd/nginx/ssl`.
- Disable HTTPS at all in `/etc/kvmd/nginx/nginx.conf`. To do this, comment some lines [like in this file](https://github.com/pikvm/kvmd/blob/master/configs/nginx/nginx.conf#L39) and restart web server: `systemctl restart kvmd-nginx`.
:exclamation: Don't do this for insecure networks or the Internet. Your passwords and what you type on the keyboard will be transmitted in unencrypted form.
@ -263,10 +263,10 @@ Note: if you can't find an answer to your question here, try the [Community FAQ]
<details>
<summary>Click to view</summary>
* If problems occur when uploading even a small disk image it may be due to unstable network operation or antivirus software. It is well known that Kaspersky antivirus cuts off Pi-KVM connections during uploading, so you should add the Pi-KVM website to Kaspersky's list of exceptions or not filter web requests with the antivirus. Antivirus programs can also affect the performance of certain interface elements, for example the quality slider. For Kaspersky, the steps to add the network address of Pi-KVM's website to the exclusion list is: **Protection -> Private browsing -> Categories and exclusions -> Exclusions**.
* If problems occur when uploading even a small disk image it may be due to unstable network operation or antivirus software. It is well known that Kaspersky antivirus cuts off PiKVM connections during uploading, so you should add the PiKVM website to Kaspersky's list of exceptions or not filter web requests with the antivirus. Antivirus programs can also affect the performance of certain interface elements, for example the quality slider. For Kaspersky, the steps to add the network address of PiKVM's website to the exclusion list is: **Protection -> Private browsing -> Categories and exclusions -> Exclusions**.
</details>
### I can't copy clipboard contents from the server (the machine controlled via Pi-KVM) to the client
### I can't copy clipboard contents from the server (the machine controlled via PiKVM) to the client
@ -56,15 +56,15 @@ Decompress and flash image and follow to the [final steps](#the-final-steps). Be
2. When the process is complete, pull out the memory card and insert it into the Raspberry Pi. Connect the Raspberry Pi to the power supply. Your device will obtain the IP address via DHCP automatically. <br>:exclamation:Windows users: balenaEtcher will automatically safely remove the memory card. If you are using a Windows version prior to Windows 10 1809 and a different flashing software, you should do the safe remove manually.
3. After power-up, Pi-KVM OS generates unique SSH keys and certificates. Do not turn off the Raspberry Pi until it's fully booted. If you set up Wi-Fi in step 1, it won't be able to connect to the network on the first boot. You need to wait 10 minutes for all the OS preparations to complete, then just restart the device. On the second boot, the Raspberry will connect to the network without any problems.
3. After power-up, PiKVM OS generates unique SSH keys and certificates. Do not turn off the Raspberry Pi until it's fully booted. If you set up Wi-Fi in step 1, it won't be able to connect to the network on the first boot. You need to wait 10 minutes for all the OS preparations to complete, then just restart the device. On the second boot, the Raspberry will connect to the network without any problems.
3a. Please scan for your pikvm either using Angry IP scanner for PC or Fing for mobile before proceeding to the next step, if not found please restart step 1.
4. Congratulations! Your Pi-KVM will be available via SSH (`ssh root@<ip-address>` with the password `root` by default) and HTTPS. In most networks you should be able to reach Pi-KVM via any browser with the URL `https://pikvm/`. If that doesn't work you'll need to find the IP address manually in your router and try it via `https://<ip-address>`. The default login username is `admin` with `admin` as the password). For HTTPS a self-signed certificate is used by default. Your browser will give you a warning about an invalid SSL certificate which you can safely ignore.
4. Congratulations! Your PiKVM will be available via SSH (`ssh root@<ip-address>` with the password `root` by default) and HTTPS. In most networks you should be able to reach PiKVM via any browser with the URL `https://pikvm/`. If that doesn't work you'll need to find the IP address manually in your router and try it via `https://<ip-address>`. The default login username is `admin` with `admin` as the password). For HTTPS a self-signed certificate is used by default. Your browser will give you a warning about an invalid SSL certificate which you can safely ignore.
Please see this page for additional functionality https://github.com/pikvm/pikvm/tree/master/pages
5. 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, you need to use `rw` to make the root filesystem writable before issuing these commands. After making changes, make sure to run the command `ro` to switch the filesystem back to read-only. If you are using a web terminal, use the `su -` command to get root access (enter the root password).
5. To change the root password use command `passwd` via SSH or webterm. To change PiKVM web password use `kvmd-htpasswd set admin`. As indicated on the login screen, you need to use `rw` to make the root filesystem writable before issuing these commands. After making changes, make sure to run the command `ro` to switch the filesystem back to read-only. If you are using a web terminal, use the `su -` command to get root access (enter the root password).
6. After installation, we recommend you to update your operating system:
[GPIO (general-purpose input/output)](https://en.wikipedia.org/wiki/General-purpose_input/output) is a series of digital interfaces that can be used to connect relays, LEDs, sensors, and other components.
:exclamation: Note: Using GPIO on a Pi-KVM was designed as a feature for advanced users, so please familiarize yourself with the topic to make sure you understand how to use use it before setting it up. Otherwise you might damage your Raspberry Pi or components.
:exclamation: Note: Using GPIO on a PiKVM was designed as a feature for advanced users, so please familiarize yourself with the topic to make sure you understand how to use use it before setting it up. Otherwise you might damage your Raspberry Pi or components.
When talking about Pi-KVM and GPIO it refers not solely to the [physical interface of the Raspberry Pi](https://www.raspberrypi.org/documentation/usage/gpio), but also to various plugins (for example, for [USB relays](http://vusb.wikidot.com/project:driver-less-usb-relays-hid-interface)) that can also be used transparently by emulating an abstract GPIO API.
When talking about PiKVM and GPIO it refers not solely to the [physical interface of the Raspberry Pi](https://www.raspberrypi.org/documentation/usage/gpio), but also to various plugins (for example, for [USB relays](http://vusb.wikidot.com/project:driver-less-usb-relays-hid-interface)) that can also be used transparently by emulating an abstract GPIO API.
# Configuration
Setting up GPIO is considerably complex. The interface is divided into several layers for flexibility. Any configuration is performed using a file `/etc/kvmd/override.yaml` which uses the [YAML syntax](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html). We will look at each part of the configuration individually with an example for each. Sections should be combined under shared keys.
@ -28,7 +28,7 @@ kvmd:
### Drivers
The first part of the configuration refers to the hardware layer, which defines which IO channels are used (standard GPIO pins of the Raspberry Pi, an USB relay, and so on). If you just want to use GPIO with the default settings you can skip to the next section [Scheme](#Scheme).
Each hardware input/output requires a individual driver configuration entry. Each driver has a type (which refers to the plugin that handles the communication between Pi-KVM and the hardware) and a unique name. This allows you to either can add multiple drivers of the same type with different settings or connect multiple USB HID relays.
Each hardware input/output requires a individual driver configuration entry. Each driver has a type (which refers to the plugin that handles the communication between PiKVM and the hardware) and a unique name. This allows you to either can add multiple drivers of the same type with different settings or connect multiple USB HID relays.
:exclamation: Each driver requires a unique name. Names surrounded by double underscore are system reserved and should not be used.
@ -46,7 +46,7 @@ kvmd:
my_gpio:
type: gpio # Refers to the plugin name handling the communication
# Example for a USB HID relay connected to Pi-KVM
# Example for a USB HID relay connected to PiKVM
relay:
type: hidrelay # Eefers to the plugin name handling the communication
device: /dev/hidraw0 # The path to the linux device
@ -57,7 +57,7 @@ The second part defines how the various driver channels are configured. Each cha
:exclamation: Names that starts and ends with two underscores (like `__magic__`) are reserved.
Two interaction modes are available for outputs: `pulse` and `switch`. In pulse mode, the output quickly switches its state to logical 1 and back (just like pressing a button). In switch mode, it saves (toggles) the state that the user set. When Pi-KVM is started/rebooted (any time the KVMD daemon is started or stopped) all output channels are reset to 0. This can be changed using the `initial` parameter. For example, `initial=true` for logic 1 on startup.
Two interaction modes are available for outputs: `pulse` and `switch`. In pulse mode, the output quickly switches its state to logical 1 and back (just like pressing a button). In switch mode, it saves (toggles) the state that the user set. When PiKVM is started/rebooted (any time the KVMD daemon is started or stopped) all output channels are reset to 0. This can be changed using the `initial` parameter. For example, `initial=true` for logic 1 on startup.
If you don't specify a driver for the channel in the scheme the default driver, `__gpio__` will be used.
@ -82,7 +82,7 @@ __Example configuration__
kvmd:
gpio:
scheme:
# A certain device sends signals to the RPi and we want the Pi-KVM to display this as an led
# A certain device sends signals to the RPi and we want the PiKVM to display this as an led
led1:
pin: 19 # GPIO pin number on the RPi
mode: input
@ -179,7 +179,7 @@ Channels should not use duplicate physical numbers. The driver supports saving s
<details>
<summary>:exclamation:Click to view:exclamation:</summary>
You can use GPIO to control KVM port switching. This usually requires the use of relays and buttons, but for the [ezCoo switch](https://github.com/pikvm/pikvm/blob/master/pages/ezcoo.md) there is a special `ezcoo` driver that simulates GPIO by sending commands to the switch via serial port. So you can make a menu in Pi-KVM to control the multiport switch.
You can use GPIO to control KVM port switching. This usually requires the use of relays and buttons, but for the [ezCoo switch](https://github.com/pikvm/pikvm/blob/master/pages/ezcoo.md) there is a special `ezcoo` driver that simulates GPIO by sending commands to the switch via serial port. So you can make a menu in PiKVM to control the multiport switch.
IPMI is an [old protocol](https://en.wikipedia.org/wiki/Intelligent_Platform_Management_Interface) for remote server management.
It can be useful for managing a large number of machines with Pi-KVM. Its advantage is that it is supported by many enterprise systems.
It can be useful for managing a large number of machines with PiKVM. Its advantage is that it is supported by many enterprise systems.
:exclamation: Although Pi-KVM supports the IPMI protocol, we strongly recommend that you DO NOT USE IT
:exclamation: Although PiKVM supports the IPMI protocol, we strongly recommend that you DO NOT USE IT
outside of trusted networks due to the protocol's [insecurity](https://github.com/NitescuLucian/nliplace.com.blog.drafts). Use Redfish or [KVMD API](api.md) instead of it.
To enable ipmi IPMI BMC follow these steps:
@ -27,9 +27,9 @@ To enable ipmi IPMI BMC follow these steps:
# IPMI SoL
IPMI supports the ability to get console access to the server using Serial-over-LAN. Pi-KVM can act as a proxy for your server's COM port.
IPMI supports the ability to get console access to the server using Serial-over-LAN. PiKVM can act as a proxy for your server's COM port.
To use this feature, you will need a USB-COM adapter that you need to connect to the Pi-KVM. The COM port of the adapter need to be connected to the server. As with IPMI BMC, you need to configure `kvmd-vnc` and add the following configuration to `/etc/kvmd/override.yaml`:
To use this feature, you will need a USB-COM adapter that you need to connect to the PiKVM. The COM port of the adapter need to be connected to the server. As with IPMI BMC, you need to configure `kvmd-vnc` and add the following configuration to `/etc/kvmd/override.yaml`:
@ -6,17 +6,17 @@ In absolute mode, the input device transmits the exact coordinates (X,Y) where t
In relative mode, only the relative offset (dX,dY) to the current position is transmitted, which is unknown to the input device itself. This is a regular mouse.
By default, Pi-KVM uses absolute positioning mode as the most convenient for the user and software.
By default, PiKVM uses absolute positioning mode as the most convenient for the user and software.
However, this is not always supported by the BIOS/UEFI.
For such cases, support is provided for the relative mode of operation, which can be enabled in the config.
When using relative mode, the browser will exclusively capture your mouse when you click on the stream window in Pi-KVM once.
When using relative mode, the browser will exclusively capture your mouse when you click on the stream window in PiKVM once.
When you press `Esc`, the browser releases the mouse.
# Important notes
The relative mouse generates a huge number of events that can be poorly transmitted over the network or very slowly perceived by the BIOS/UEFI driver. To solve this problem, mouse events are optimized using a vector sum. This mode is enabled by default and is available in the web menu `System -> Squash mouse moves`. You can try disabling this if you have problems with mouse acceleration. This is the best and most reasonable compromise right now.
Also currently the relative mouse mode is not supported by [Pi-KVM VNC server](vnc.md) yet. The reason is that none of the recommended clients support the [QEMU Pointer Motion Change](https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#qemu-pointer-motion-change-pseudo-encoding) extension.
Also currently the relative mouse mode is not supported by [PiKVM VNC server](vnc.md) yet. The reason is that none of the recommended clients support the [QEMU Pointer Motion Change](https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#qemu-pointer-motion-change-pseudo-encoding) extension.
We expect to implement this in [TigerVNC](https://github.com/TigerVNC/tigervnc/issues/619). The relative mode is also not supported by mobile browsers.
# Enabling the relative mouse on the v2 platform (OTG HID)
This is a feature available on Pi-KVM v2+ that allows you to emulate a CD-ROM or Flash Drive.
This is a feature available on PiKVM v2+ that allows you to emulate a CD-ROM or Flash Drive.
There are some subtleties that you should know:
* **The size of the CD-ROM image is limited to 2.2 GB**. This is a limitation of the Linux kernel, which currently cannot emulate a DVD.
@ -23,7 +23,7 @@ To disable mass storage emulation altogether, you can place the following piece
# kvmd-helper-otgmsd-remount rw
```
2. Upload the .ISO image(s) to `/var/lib/kvmd/msd/images` via scp or similar.
3. Create an empty file in `/var/lib/kvmd/msd/meta/` with the exact name (case sensitive!) of the uploaded image. This will indicate Pi-KVM that the uploaded image is okay and can be used. For example:
3. Create an empty file in `/var/lib/kvmd/msd/meta/` with the exact name (case sensitive!) of the uploaded image. This will indicate PiKVM that the uploaded image is okay and can be used. For example:
There are many ways to do this, but the best and most documented one right now is to use the [ezCoo KVM switch](ezcoo.md).
Also, Pi-KVM can be connected to a multi-port HDMI/USB switch and the switch's buttons can be connected via optocouplers to [the Pi's GPIO to switch channels](gpio.md).
Also, PiKVM can be connected to a multi-port HDMI/USB switch and the switch's buttons can be connected via optocouplers to [the Pi's GPIO to switch channels](gpio.md).
If your KVM switches channels using keyboard shortcuts, there is a chance that it will not be able to work with OTG (v2 platform, see below), since it does not fully implement the USB stack. In this case, you will have to [use an Arduino board](arduino_hid.md) to emulate the keyboard & mouse (Pi-KVM supports this configuration).
If your KVM switches channels using keyboard shortcuts, there is a chance that it will not be able to work with OTG (v2 platform, see below), since it does not fully implement the USB stack. In this case, you will have to [use an Arduino board](arduino_hid.md) to emulate the keyboard & mouse (PiKVM supports this configuration).
❗WARNING:exclamation: - If you choose AiMOS, be aware that it has a back powering issue that you need to use work arounds for. Limitations are are listed below. Also please be aware that Arudino's will not work with the AIMOS KVM's.
@ -16,7 +16,7 @@ Here the status is:
| Model | Status | Notes |
|:------|:-------|:------|
| [ezCoo EZ-SW41HA-KVMU3L 4x1 switch](https://www.easycoolav.com/products/hdmi20-switch-4x1-with-usb30-kvm-3-port-usbsupport-4k60hz-444-and-hdr-audio-breakout-36) ~~[ezCoo SW41HA HDMI 4x1 switch](https://www.easycoolav.com/products/hdmi20-switch-4x1-with-usb20-kvm-4-port-usbsupport-4k60hz-444-and-hdr-audio-breakout)~~ (legacy) | ✔ | [Using with Pi-KVM](ezcoo.md) - 4 Port is the ONLY supported KVM, 2 Port does not work the same and is not supported |
| [ezCoo EZ-SW41HA-KVMU3L 4x1 switch](https://www.easycoolav.com/products/hdmi20-switch-4x1-with-usb30-kvm-3-port-usbsupport-4k60hz-444-and-hdr-audio-breakout-36) ~~[ezCoo SW41HA HDMI 4x1 switch](https://www.easycoolav.com/products/hdmi20-switch-4x1-with-usb20-kvm-4-port-usbsupport-4k60hz-444-and-hdr-audio-breakout)~~ (legacy) | ✔ | [Using with PiKVM](ezcoo.md) - 4 Port is the ONLY supported KVM, 2 Port does not work the same and is not supported |
| [Ali's noname](https://a.aliexpress.com/_BSpS8t) | ✔ | Limitations are are listed below |
| [Aimos 8-port HDMI USB-C KVM Switch](https://www.amazon.de/AIMOS-Umschalter-Tastatur-unterst%C3%BCtzen-verbunden/dp/B08FR5K111/) | ✔ | Similar to Ali's noname model, available in 4/8port editions, has same HDMI bridge boot problem/solution using a Marmitek 312 UHD HDMI splitter. Limitations are are listed below |
| [TESmart 8 PORT - HDMI KVM SWITCH](https://buytesmart.com/collections/8-ports) | ✔ | Use OTG with USB 2.0 Hub only, no hotkey support. Switching available with serial or IP-to-serial interface using fixed IP (/31 peer-to-peer addressing supported). Can be managed [via WebUI](tesmart.md) or [CLI tool](https://github.com/bbeaudoin/bash/tree/master/tesmart) |
[Prometheus](https://prometheus.io) is one of the popular monitoring systems.
It pulls service's endpoint to get metrics in a [simple text format](https://prometheus.io/docs/instrumenting/exposition_formats).
Pi-KVM has the ability to export some information to this system such as the server's ATX state, Pi's temperature, [GPIO](gpio.md) state and some other things.
PiKVM has the ability to export some information to this system such as the server's ATX state, Pi's temperature, [GPIO](gpio.md) state and some other things.
# Configure Prometheus
To enable Prometheus getting metrics from pikvm following [config](https://prometheus.io/docs/prometheus/latest/configuration/configuration) could be used:
@ -19,7 +19,7 @@ scrape_configs:
```
# Output example
This example includes the [GPIO](gpio.md) from the PI-KVM's [test config](https://github.com/pikvm/kvmd/blob/905bcf555f00d191654982cca80e294363efecc1/testenv/v2-hdmi-rpi4.override.yaml#L40).
This example includes the [GPIO](gpio.md) from the PiKVM's [test config](https://github.com/pikvm/kvmd/blob/905bcf555f00d191654982cca80e294363efecc1/testenv/v2-hdmi-rpi4.override.yaml#L40).
You can use [Tailscale](https://tailscale.com/) to access Pi-KVM on the internal network. This is a convenient and free (for private use) tool for organizing a small VPN network.
You can use [Tailscale](https://tailscale.com/) to access PiKVM on the internal network. This is a convenient and free (for private use) tool for organizing a small VPN network.
# Installation
## On the Pi-KVM side
## On the PiKVM side
1. Use these commands:
```
# rw
@ -18,4 +18,4 @@ You can use [Tailscale](https://tailscale.com/) to access Pi-KVM on the internal
## On the workstation side
* Download and install tailscale for your OS: https://tailscale.com/download
* Check the page https://login.tailscale.com/admin/machines to view your VPN network.
* Follow the URL in the web browser: `https://<tailscale_kvm_ip>` and you will see Pi-KVM web interface.
* Follow the URL in the web browser: `https://<tailscale_kvm_ip>` and you will see PiKVM web interface.
The TESMART managed switch can be controlled by Pi-KVM to allow it to connect to multiple hosts. A typical scenario is a single Pi-KVM device which can control and switch between multiple hosts or servers using the TESMART switch. UI elements can be added to the [GPIO dropdown](gpio.md) to allow switching between hosts from the Pi-KVM webpage. The instructions here were tested with the [TESMART HKS1601A10 HDMI 16x1 switch](https://www.amazon.com/TESmart-Enterprise-Control-Rackmount-Keyboard/dp/B07258PWTW/). This should work with any of the other TESMART variants which have a LAN port - there is both a 8x1 and 4x1 variant. This was tested with an RPI4, but as this is executed over a network protocol, this should with almost anything.
The TESMART managed switch can be controlled by PiKVM to allow it to connect to multiple hosts. A typical scenario is a single PiKVM device which can control and switch between multiple hosts or servers using the TESMART switch. UI elements can be added to the [GPIO dropdown](gpio.md) to allow switching between hosts from the PiKVM webpage. The instructions here were tested with the [TESMART HKS1601A10 HDMI 16x1 switch](https://www.amazon.com/TESmart-Enterprise-Control-Rackmount-Keyboard/dp/B07258PWTW/). This should work with any of the other TESMART variants which have a LAN port - there is both a 8x1 and 4x1 variant. This was tested with an RPI4, but as this is executed over a network protocol, this should with almost anything.
## Connections
From a high level, the TESMART switch uses standard connections to the host machines (USB-A to USB-B and HDMI). The Raspberry Pi OTG connector (the one coming from the USB-C port on a Pi 4 via the custom splitter cable or device) should be connected to one of the USB 2 output ports on the TESMART switch (not the keyboard/mouse port). Based on your specific devices, and to get boot images to mount, you may need to connect this through a USB 2 hub.
@ -10,7 +10,7 @@ From a high level, the TESMART switch uses standard connections to the host mach
3. Connect the LAN port on the front of the switch using standard ethernet cable into one of your network switches.
4. Connect host USB and HDMI cables from the TESMART switch to the machines to be managed per the switch instructions.
:exclamation: There is a limitation in the underlying Pi-KVM software related to plugging video cables from a host which is already powered and connected to a monitor to a Raspberry Pi CSI2-HDMI encoder. These limitations apply equally when using the TESMART KVM switch. If video is not present in Pi-KVM, try keeping all host machines off and connecting them directly to the TESMART switch before powering the hosts on.
:exclamation: There is a limitation in the underlying PiKVM software related to plugging video cables from a host which is already powered and connected to a monitor to a Raspberry Pi CSI2-HDMI encoder. These limitations apply equally when using the TESMART KVM switch. If video is not present in PiKVM, try keeping all host machines off and connecting them directly to the TESMART switch before powering the hosts on.
## Setting the IP Address of the TESMART switch
@ -29,9 +29,9 @@ On this screen, change to your desired IP address, gateway, mask, and port. Then
There may be alternatives other than changing the IP address in this manner if you don't have access to a Windows machine or if this address doesn't work for you. See this [README](https://github.com/bbeaudoin/bash/blob/master/tesmart/README.md) for other options (Images and concepts from the bash file were borrowed for creation of this plugin). This also contains a summary of the protocol, which is also available on the TESMART downloads page.
## Adding UI elements to control the KVM switch
The UI can be updated to add buttons to switch between KVM inputs and indicators for which input is currently selected. The instructions below will make these available in the Pi-KVM UI after clicking the "Switches" menu button in the KVM view.
The UI can be updated to add buttons to switch between KVM inputs and indicators for which input is currently selected. The instructions below will make these available in the PiKVM UI after clicking the "Switches" menu button in the KVM view.
1. SSH into Pi-KVM
1. SSH into PiKVM
2. Enable read-write mode on the sd card via `rw`
3. Edit the `/etc/kvmd/override.yaml` file and include the following:
Specifically to v2. When combined with configuring a DNS server, FTP, or SMB (for example), this is a powerful way to extend the capabilities of Pi-KVM.
Specifically to v2. When combined with configuring a DNS server, FTP, or SMB (for example), this is a powerful way to extend the capabilities of PiKVM.
:exclamation: The USB-Ethernet features are experimental, so some of the default settings may be changed in future releases.
@ -14,8 +14,8 @@ Specifically to v2. When combined with configuring a DNS server, FTP, or SMB (fo
host_mac: 48:6f:73:74:50:43
kvm_mac: 42:61:64:55:53:42
```
The `host_mac` address will be used on the server's network interface. The `kvm_mac` means the address that will be assigned to the local interface on the Pi-KVM. The KVM interface will be called `usb0`network interface. If the `host_mac` or `kvm_mac` is not specified, a random value will be used. The `driver` parameter means the protocol that will be used for the USB network. The default value is `ecm` so it can be passed it this example. Other possible values are `eem`, `ncm` and `rndis`.
2. To automatically configure the USB network on the server recommended using the service `kvmd-otgnet`. It configures the firewall, assigns an address to the local Pi-KVM interface `usb0` and starts DHCP so the managed server can get the IPv4 address. By default, the address `169.254.0.1/28` to interface `usb0` will be assigned. One of the other addresses from the network `169.254.0.0./28` will be assigned to the server when it requests it via DHCP. For security reasons, all incoming connections from the server to the Pi-KVM side are blocked (except for ICMP and UDP port 67 which is used for DHCP). If you want to allow access from the server to the Pi-KVM interface, then you need to add ports 80 and 443 to the whitelist using `/etc/kvmd/override.yaml` file like this:
The `host_mac` address will be used on the server's network interface. The `kvm_mac` means the address that will be assigned to the local interface on the PiKVM. The KVM interface will be called `usb0`network interface. If the `host_mac` or `kvm_mac` is not specified, a random value will be used. The `driver` parameter means the protocol that will be used for the USB network. The default value is `ecm` so it can be passed it this example. Other possible values are `eem`, `ncm` and `rndis`.
2. To automatically configure the USB network on the server recommended using the service `kvmd-otgnet`. It configures the firewall, assigns an address to the local PiKVM interface `usb0` and starts DHCP so the managed server can get the IPv4 address. By default, the address `169.254.0.1/28` to interface `usb0` will be assigned. One of the other addresses from the network `169.254.0.0./28` will be assigned to the server when it requests it via DHCP. For security reasons, all incoming connections from the server to the PiKVM side are blocked (except for ICMP and UDP port 67 which is used for DHCP). If you want to allow access from the server to the PiKVM interface, then you need to add ports 80 and 443 to the whitelist using `/etc/kvmd/override.yaml` file like this:
```yaml
otgnet:
firewall:
@ -25,9 +25,9 @@ Specifically to v2. When combined with configuring a DNS server, FTP, or SMB (fo
3. To enable the service, use the command `systemctl enable kvmd-otgnet`.
4. Perform `reboot`.
## Routing via Pi-KVM
## Routing via PiKVM
By default, `kvmd-otgnet` will configure network connection between Pi-KVM and the server host only. The server host will not be able to reach other hosts beyond Pi-KVM. If the full network access is required from the server host through the USB-Ethernet feature (access all hosts Pi-KVM can access), additional settings are needed in `/etc/kvmd/override.yaml`.
By default, `kvmd-otgnet` will configure network connection between PiKVM and the server host only. The server host will not be able to reach other hosts beyond PiKVM. If the full network access is required from the server host through the USB-Ethernet feature (access all hosts PiKVM can access), additional settings are needed in `/etc/kvmd/override.yaml`.
1. Run `echo "net.ipv4.ip_forward = 1" > /etc/sysctl.d/99-kvmd-extra.conf`.
2. Add network interface to forward requests to (default gateway) by adding a line `forward_iface: <interface name>` under `firewall:`. Typically it would be `eth0` if the built-in ethernet port is used::
The **Pi-KVM v3 HAT Board** is designed to work with the **Raspberry Pi 4** and provides the following features:
The **PiKVM v3 HAT Board** is designed to work with the **Raspberry Pi 4** and provides the following features:
* **HDMI capture** device with max resolution 1080p 50Hz and audio support
* **Keyboard**&**mouse** emulation
* **Mass storage emulation** (i.e., virtual flash drive or CD drive provided by image file saved on PiKVM)
@ -12,7 +12,7 @@ The **Pi-KVM v3 HAT Board** is designed to work with the **Raspberry Pi 4** and
* USB & RJ-45 **serial console**
## Requirements
To use Pi-KVM v3, you will need the following things, which are NOT included in the base kit:
To use PiKVM v3, you will need the following things, which are NOT included in the base kit:
* **Raspberry Pi 4** (a model with any amount of memory is suitable)
* **5.1v 3A** official Raspberry power supply with USB-C
* A regular **HDMI cable**
@ -23,7 +23,7 @@ To use Pi-KVM v3, you will need the following things, which are NOT included in
# Known issues & limitations
* The actual frame rate of the image received via HDMI will depend on the network bandwidth, resolution and the load on the Raspberry Pi. This is usually ~20-24 FPS for 1080p over LAN.
* **AIMOS** KVM switch not trully compatible with v3.2, but works great with v3.3 (Kickstarter edition)
* There may be **compatibility** issues with some motherboards (such as **HP** or **DELL**) which are the same as those that exist with Pi-KVM v2. Not everything is perfect, but if you have already used Pi-KVM v2 - our new v3 will work perfectly and please you. If there is no image from the BIOS, you can fine-tune the HDMI settings, but it is possible that the Mass Storage devices will not be available in the BIOS.
* There may be **compatibility** issues with some motherboards (such as **HP** or **DELL**) which are the same as those that exist with PiKVM v2. Not everything is perfect, but if you have already used PiKVM v2 - our new v3 will work perfectly and please you. If there is no image from the BIOS, you can fine-tune the HDMI settings, but it is possible that the Mass Storage devices will not be available in the BIOS.
# Installation
0. Print a plastic case if you want it ([v3.3](../stl/v3.3/README.md) for the Kickstarter model, [v3.2](../stl/v3.2/README.md) for the pre-release).
@ -57,13 +57,13 @@ To use Pi-KVM v3, you will need the following things, which are NOT included in
4. **USB serial console status LED**
The console has independent power from the USB connected host, so you can reboot the Pi and not lose the connection to the console. The LED indicates the presence of power via USB.
5. **COM serial console**
For connection, the so-called CISCO-style serial cable is used (on the one hand, RJ45, on the other, COM port). You can buy any suitable cable or [make your own](https://wiki.mikrotik.com/wiki/Manual:System/Serial_Console). If you do not need console access to the Pi-KVM, this port can be used to access the server.
For connection, the so-called CISCO-style serial cable is used (on the one hand, RJ45, on the other, COM port). You can buy any suitable cable or [make your own](https://wiki.mikrotik.com/wiki/Manual:System/Serial_Console). If you do not need console access to the PiKVM, this port can be used to access the server.
6. **PoE pins**
Pi-KVM is compatible with PoE hats. These pins are used for power supply.
PiKVM is compatible with PoE hats. These pins are used for power supply.
7. **UART jumpers**
The two jumpers installed here provide communication between the console ports (3, 5) and the UART of Raspberry. By removing them, you will get access to the UART.
8. **Audio capture jumpers**
The Pi-KVM can capture audio. Although this is not yet implemented in the software, the hardware capability is already present and you can use the `arecord` command to record audio. These pins are used for this purpose. If you need additional GPIO pins, you can remove these jumpers, comment line `dtoverlay=tc358743-audio` in `/boot/config.txt`, and use the [GPIO 19, 20 and 21](https://pinout.xyz/pinout/pin35_gpio19) as you see fit.
The PiKVM can capture audio. Although this is not yet implemented in the software, the hardware capability is already present and you can use the `arecord` command to record audio. These pins are used for this purpose. If you need additional GPIO pins, you can remove these jumpers, comment line `dtoverlay=tc358743-audio` in `/boot/config.txt`, and use the [GPIO 19, 20 and 21](https://pinout.xyz/pinout/pin35_gpio19) as you see fit.
9. **HDMI reset jumper**
Currently unused. In the future, it will be used for hardware resetting of the video capture chip. If you remove it, you will be able to use the [GPIO 17](
https://pinout.xyz/pinout/pin11_gpio17)
@ -76,7 +76,7 @@ To use Pi-KVM v3, you will need the following things, which are NOT included in
13. **OTG USB**
The port to connect to the server. Here, the keyboard, mouse, disk, and so on are emulated.
14. **OTG USB AUX**
For fans of soldering. You can use these pins to connect OTG if you have installed Pi-KVM inside the server case.
For fans of soldering. You can use these pins to connect OTG if you have installed PiKVM inside the server case.
15. **HDMI input**
From 640x480 to 1920x1080 50Hz (max).
16. **Service USB**
@ -90,7 +90,7 @@ To use Pi-KVM v3, you will need the following things, which are NOT included in
21. **5v fan connector**
Connector for controlling a 5v fan with PWM support.
22. **5v power pins**
To receive or alternatively supply power to the Pi-KVM.
To receive or alternatively supply power to the PiKVM.
@ -3,8 +3,8 @@ As an alternative to the web interface, you can use VNC with various desktop cli
:exclamation: **Please note: we strongly advise against using VNC without X.509 or TLS encryption on untrusted networks!** Otherwise your password will be transmitted over the network in plain text. Unfortunately, this is the reality of the VNC protocol.
# Enabling VNC on the Pi-KVM side
1. Switch Pi-KVM filesystem to read-write mode using command `rw`.
# Enabling VNC on the PiKVM side
1. Switch PiKVM filesystem to read-write mode using command `rw`.
2. _Optional:_ Change client's keyboard layout if you're using an non-US keyboard. To do this edit file `/etc/kvmd/override.yaml`
:exclamation: **(remove `{}` before adding lines)**:
@ -20,9 +20,9 @@ In contrast, WebRTC is a completely different way of transmitting video.
It uses a P2P connection and UDP. This reduces network load, but makes it difficult to configure -
the server needs to know your network configuration in order to use it correctly.
To implement this, the Pi-KVM checks which of the network interfaces is used for the default gateway,
To implement this, the PiKVM checks which of the network interfaces is used for the default gateway,
and also tries to find out your external address using the Google [STUN](https://en.wikipedia.org/wiki/STUN) server.
This is necessary when using [Tailscale](tailscale.md) or so that you can connect to your Pi-KVM from the external Internet,
This is necessary when using [Tailscale](tailscale.md) or so that you can connect to your PiKVM from the external Internet,
since simply forwarding ports 80 and 443 for WebRTC is not enough - it requires a direct connection.
If you don't like using Google (it was chosen as the default for reliability reasons) for this purpose,
@ -39,7 +39,7 @@ And restart `systemctl restart kvmd-janus`.
# Custom Janus config
[Janus](https://janus.conf.meetecho.com) is a WebRTC gateway that is used to transmit the [uStreamer](https://github.com/pikvm/ustreamer) video.
KVMD-Janus is a wrapper around it, configuring and monitoring changes in the network configuration. This is suitable for most users.
However, if your Pi-KVM is not connected to the Internet and/or you want to use a custom Janus configuration,
However, if your PiKVM is not connected to the Internet and/or you want to use a custom Janus configuration,
then you should use the `kvmd-janus-static` service instead. You should first change the Janus configuration yourself.
You can find it in `/etc/kvmd/janus/janus.jcfg`.
@ -51,8 +51,8 @@ You can find it in `/etc/kvmd/janus/janus.jcfg`.
# Troubleshooting
In rare cases, WebRTC may not work. The most common reasons are:
* Tricky IPv6 configuration on the network. IPv6 support for WebRTC in Pi-KVM is still in its infancy, so if your network has IPv4, it will be easiest to disable IPv6 on Pi-KVM. To do this, switch the file system to write mode using `rw` command, add option `ipv6.disable_ipv6=1` to `/boot/cmdline.txt` and perform `reboot`. Also see [here](https://wiki.archlinux.org/title/IPv6#Disable_IPv6).
* A paranoid firewall when you try to connect to the Pi-KVM by forwarding port 443 to the Internet from the internal network. WebRTC is not enough of this, it uses UDP on ports 10000-20000 for a P2P connection. Make sure that the Firewall does not block them.
* Tricky IPv6 configuration on the network. IPv6 support for WebRTC in PiKVM is still in its infancy, so if your network has IPv4, it will be easiest to disable IPv6 on PiKVM. To do this, switch the file system to write mode using `rw` command, add option `ipv6.disable_ipv6=1` to `/boot/cmdline.txt` and perform `reboot`. Also see [here](https://wiki.archlinux.org/title/IPv6#Disable_IPv6).
* A paranoid firewall when you try to connect to the PiKVM by forwarding port 443 to the Internet from the internal network. WebRTC is not enough of this, it uses UDP on ports 10000-20000 for a P2P connection. Make sure that the Firewall does not block them.
* If nothing helps, open the browser's JS console and look at the log, and contact our community via [Discord](https://discord.gg/bpmXfz5). Developers and/or experienced users will definitely help you.
* Another option to try is if you have both wifi and eth connected, disable wifi `rfkill list wifi` then `rfkill block X` X=the number that shows in the output. Reason: Arch linux will choose to route all outgoing packets out wifi by default.
* There are some linux distro's that require more work to be able to use H.264 (WEBRTC MODE), this may include any RedHat variant.
Maxim Devaev
3 years ago