public_git/pikvm
1
0
Fork 0
mirror of https://github.com/pikvm/pikvm.git synced 2026-10-20 21:30:52 +02:00
Code Issues Projects Releases Wiki Activity

docs.pikvm.org

Browse Source
This commit is contained in:
Maxim Devaev
2021-10-12 21:45:00 +03:00
parent 888f128a6a
commit ddd1baf604
114 changed files with 3461 additions and 3132 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/3d_printing.md
+21
View File
@@ -0,0 +1,21 @@
# Cases for 3D printing
## PiKVM V3 HAT cases
* [**v3.3 model (Kickstarter, Store)**](stl/v3.3/index.md)
* [v3.2 model (Pre-release)](stl/v3.2/index.md)
## DIY cases
| Model | Notes |
|-------|-------|
| 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 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 | PiKVM RETRO Case for CSI-2 C779 Bridge w/ OLED Display Screen |
| https://www.thingiverse.com/thing:4950280 | USB Power Blocker Case |
docs/_assets/favicon.ico
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

docs/_assets/logo.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.0 KiB

docs/_assets/user.css
+80
View File
@@ -0,0 +1,80 @@
/*.md-header__button.md-logo img {
width: unset;
}*/
.md-main__inner {
margin-top: unset;
}
.md-nav__title {
display: none;
}
/*.md-header,*/ .md-footer {
background-color: #333333;
}
.md-footer__inner.md-grid {
display: none;
}
.md-sidebar {
padding-top: 0px;
}
/*.md-sidebar.md-sidebar--primary {
position: unset;
}*/
.md-sidebar.md-sidebar--secondary {
padding-top: 10px;
}
.md-sidebar.md-sidebar--primary .md-sidebar__scrollwrap {
/*overflow-y: unset;*/
padding-right: 1px;
border-right: 1px solid #adadad;
}
.md-sidebar.md-sidebar--primary .md-sidebar__inner {
/*border-right: 1px solid #adadad;*/
padding-bottom: 30px;
}
.md-sidebar.md-sidebar--secondary .md-sidebar__inner {
border-left: 1px solid #adadad;
}
.md-nav__item .md-nav__list {
padding-left: 10px;
}
.md-content {
margin-top: 25px;
/*border-left: 1px solid #adadad;
border-right: 1px solid #adadad;*/
}
.md-top {
display: none;
}
.md-typeset hr {
border-bottom: 1px solid #adadad;
}
.md-typeset h1,
.md-typeset h2,
.md-typeset h3,
.md-typeset h4,
.md-typeset h5 {
font-weight: bold;
}
.md-typeset table:not([class]) td:not(:last-child),
.md-typeset table:not([class]) th:not(:last-child) {
border-right: .05rem solid var(--md-typeset-table-color);
}
ol li::marker {
font-weight: bold;
}
docs/api.md
+430
View File
@@ -0,0 +1,430 @@
# API
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` option to disable SSL certificate verification, since the self-signed certificateis used in the default installation.
-----
## Authorization
All APIs are restricted to authorization. To make requests, you either need to authorize each request individually,
or get a token and pass it as a cookie with each request.
### Single request auth
There are two options here:
* **Using X-headers.** Just pass `X-KVMD-User` and `X-KVMD-Passwd` with the request:
```
$ curl -k -H X-KVMD-User:admin -H X-KVMD-Passwd:admin https://<pikvm-ip>/api/auth/check
```
* **Using HTTP Basic Auth.** Please note: contrary to the standard, this method DOES NOT use the `WWW-Authenticate` header. HTTP Basic Auth in this implementation is intended only for compatibility with other systems, such as [Prometheus](prometheus.md).
```
$ curl -k -u admin:admin https://<pikvm-ip>/api/auth/check
```
### Session-based cookie auth
1. Authorize and get token for the user using `POST /api/auth/login`:
```
$ curl -k -v -X POST --data user=admin --data passwd=admin https://pikvm/api/auth/login
...
< Set-Cookie: auth_token=796cb83b11de4fcb749bc1bad14a91fb06dede84672b2f847fef1e988e6900de; Path=/
...
```
On success the cookie `auth_token` will be received with `200 OK`. On invalid user or password you will get `403 Forbidden`.
2. The handle `GET /api/auth/check` can be used for check the auth status. Return of `200 OK` will signal that user is authenticated. If the token or any of the single-request auth methods are missing, `401 Unauthorized` will be returned. In case of incorrect credentials or token, `403 Forbidden` will be returned.
3. The handle `POST /api/auth/logout` can be used to invalidate session token. The response codes will be similar to the previous handle.
-----
## WebSocket events
Most of the data during the user's work with pikvm is transmitted over WebSocket. This includes mouse events, keyboard input, change the state of the various subsystems (such as ATX and Mass Storage Drive). Each event type will be described in the corresponding paragraph for its component. When connecting via WebSocket, the client receives current states as separate events. Then, as the states change, it will receive new events.
In a normal situation, opening a socket session triggers the video streamer to start. The streamer works as long as there is at least one client connected via WebSocket. After the last connection is closed and the client timeout expires, the streamer will also be terminated.
It is possible create a session that will not start the streamer and will not be counted when counting clients to stop the streamer. To do this, use the URL parameter `stream=0`:
```
$ websocat -k wss://<pikvm-ip>/api/ws?stream=0 -H X-KVMD-User:admin -H X-KVMD-Passwd:admin
```
??? example "Output with initial events"
```js
{"event_type": "gpio_model_state", "event": {"scheme": {"inputs": {"led1": {"hw": {"driver": "__gpio__", "pin": 19}}, "led2": {"hw": {"driver": "__gpio__", "pin": 16}}}, "outputs": {"button1": {"switch": false, "pulse": {"delay": 0.1, "min_delay": 0.1, "max_delay": 0.1}, "hw": {"driver": "__gpio__", "pin": 26}}, "button2": {"switch": false, "pulse": {"delay": 0.1, "min_delay": 0.1, "max_delay": 0.1}, "hw": {"driver": "__gpio__", "pin": 20}}, "relay1": {"switch": true, "pulse": {"delay": 0.1, "min_delay": 0.1, "max_delay": 0.1}, "hw": {"driver": "relay", "pin": 0}}, "relay2": {"switch": true, "pulse": {"delay": 2.0, "min_delay": 0.1, "max_delay": 5.0}, "hw": {"driver": "relay", "pin": 1}}}}, "view": {"header": {"title": "Switches"}, "table": [[{"type": "label", "text": "Generic GPIO leds"}], null, [{"type": "label", "text": "Test 1:"}, {"type": "input", "channel": "led1", "color": "green"}, {"type": "output", "channel": "button1", "text": "Click"}], [{"type": "label", "text": "Test 2:"}, {"type": "input", "channel": "led2", "color": "green"}, {"type": "output", "channel": "button2", "text": "Click"}], null, [{"type": "label", "text": "HID Relays /dev/hidraw0"}], null, [{"type": "label", "text": "Relay #1:"}, {"type": "output", "channel": "relay1", "text": "Boop 0.1"}], [{"type": "label", "text": "Relay #2:"}, {"type": "output", "channel": "relay2", "text": "Boop 2.0"}]]}}}
{"event_type": "info_extras_state", "event": {"vnc": {"name": "VNC", "description": "Show VNC information", "icon": "share/svg/vnc.svg", "path": "vnc", "keyboard_cap": false, "daemon": "kvmd-vnc", "port": 5900, "place": 20, "enabled": true}, "ipmi": {"name": "IPMI", "description": "Show IPMI information", "icon": "share/svg/ipmi.svg", "path": "ipmi", "keyboard_cap": false, "daemon": "kvmd-ipmi", "port": 623, "place": 21, "enabled": true}}}
{"event_type": "info_hw_state", "event": {"platform": {"type": "rpi", "base": "Virtual Raspberry Pi"}, "health": {"temp": {"cpu": 36.511, "gpu": 35.0}, "throttling": {"raw_flags": 0, "parsed_flags": {"undervoltage": {"now": false, "past": false}, "freq_capped": {"now": false, "past": false}, "throttled": {"now": false, "past": false}}}}}}
{"event_type": "info_meta_state", "event": {"server": {"host": "localhost.localdomain"}, "kvm": {}}}
{"event_type": "info_system_state", "event": {"kvmd": {"version": "1.102"}, "streamer": {"app": "ustreamer", "version": "1.25", "features": {"WITH_OMX": false, "WITH_GPIO": false, "WITH_PTHREAD_NP": true, "WITH_SETPROCTITLE": true, "HAS_PDEATHSIG": true}}, "kernel": {"system": "Linux", "release": "5.8.10-arch1-1", "version": "#1 SMP PREEMPT Thu, 17 Sep 2020 18:01:06 +0000", "machine": "x86_64"}}}
{"event_type": "wol_state", "event": {"enabled": false, "target": {"ip": "255.255.255.255", "port": 9, "mac": ""}}}
{"event_type": "gpio_state", "event": {"inputs": {"led1": {"online": true, "state": false}, "led2": {"online": true, "state": false}}, "outputs": {"button1": {"online": true, "state": false, "busy": false}, "button2": {"online": true, "state": false, "busy": false}, "relay1": {"online": false, "state": false, "busy": false}, "relay2": {"online": false, "state": false, "busy": false}}}}
{"event_type": "hid_state", "event": {"online": true, "keyboard": {"online": true, "leds": {"caps": false, "scroll": false, "num": false}}, "mouse": {"online": true}}}
{"event_type": "atx_state", "event": {"enabled": true, "busy": false, "leds": {"power": false, "hdd": false}}}
{"event_type": "msd_state", "event": {"enabled": true, "online": true, "busy": false, "storage": {"size": 234950152192, "free": 23514271744, "images": {}, "uploading": false}, "drive": {"image": null, "connected": false, "cdrom": true}, "features": {"multi": true, "cdrom": true}}}
{"event_type": "streamer_state", "event": {"limits": {"max_fps": 40}, "params": {"desired_fps": 30, "quality": 80}, "snapshot": {"saved": null}, "streamer": null, "features": {"quality": true, "resolution": false}}}
{"event_type": "loop", "event": {}}
```
After connecting the client receives a bundle of states of all KVMD subsystems. After the batch is completed, it sends a `loop` event, which means that the websocket has entered event loop mode. Now it will send new states and respond to client's requests.
Another type of event is `ping`, which can be sent by the client: `{"event_type": "ping", "event": {}}`. If the server is running, it will respond with pong: `{"event_type": "pong", "event": {}}`.
??? example "Sending key events using Python"
For keypresses, set `event_type` to `key` and fill in the `event` structure with `key` and `state`, where `key` is the key from mapping and `state` is boolean that determines if the key is pressed or released:
```python
# python, install websocket-client
import websocket
uri = "wss://10.0.0.7/api/ws?stream=0"
headers = {"X-KVMD-User": "admin", "X-KVMD-Passwd": "admin"}
ws = websocket.WebSocket(sslopt={"cert_reqs": ssl.CERT_NONE})
ws.connect(uri, header=headers)
ws.send('{"event_type": "key", "event": {"key": "Enter", "state": true}}')
time.sleep(0.05)
ws.send('{"event_type": "key", "event": {"key": "Enter", "state": false}}')
ws.close()
```
-----
## System functions
### Get system info
The `GET /api/info` handle returns the general information about the PiKVM device.
Parameters:
* `fields=...` *(optional)* - Only specified categories will be returned, for example `fields=system,hw`. By default all categories will be displayed.
```
$ curl -k -u admin:admin https://<pikvm-ip>/api/info
```
??? note "Click to expand"
```js
{
"ok": true,
"result": {
"extras": { // Installed applications; null on internal error
"ipmi": {
"daemon": "kvmd-ipmi",
"description": "Show IPMI information",
"enabled": true,
"icon": "share/svg/ipmi.svg",
"keyboard_cap": false,
"name": "IPMI",
"path": "ipmi",
"place": 21,
"port": 623
},
"vnc": {
"daemon": "kvmd-vnc",
"description": "Show VNC information",
"enabled": true,
"icon": "share/svg/vnc.svg",
"keyboard_cap": false,
"name": "VNC",
"path": "vnc",
"place": 20,
"port": 5900
}
},
"hw": { // Hardware info
"health": {
"temp": {
"cpu": 36.511, // /sys/class/thermal/thermal_zone0/temp / 1000; null on error
"gpu": 35.0 // vcgencmd measure_temp; null on error
},
"throttling": { // vcgencmd get_throttled; null on error
"parsed_flags": {
"freq_capped": {
"now": false,
"past": false
},
"throttled": {
"now": false,
"past": false
},
"undervoltage": {
"now": false,
"past": false
}
},
"raw_flags": 0
}
},
"platform": {
"base": "Raspberry Pi 4 Model B Rev 1.1", // /proc/device-tree/model; null on error
"type": "rpi"
}
},
"meta": { // /etc/kvmd/meta.yaml; null on error
"kvm": {},
"server": {
"host": "localhost.localdomain"
}
},
"system": {
"kernel": {
"machine": "x86_64",
"release": "5.8.14-arch1-1",
"system": "Linux",
"version": "#1 SMP PREEMPT Wed, 07 Oct 2020 23:59:46 +0000"
},
"kvmd": {
"version": "2.1"
},
"streamer": {
"app": "ustreamer",
"features": { // {} on error
"HAS_PDEATHSIG": true,
"WITH_GPIO": false,
"WITH_OMX": false,
"WITH_PTHREAD_NP": true,
"WITH_SETPROCTITLE": true
},
"version": "2.1" // "" on error
}
}
}
}
```
Each category is represented by its own event in the websocket (`info_hw_state`, `info_system_state`, etc). The event content has the same format as the category content in API.
### Get system log
The `GET /api/log` handle displays logs from all KVMD services as plain text.
Parameters:
* `follow=1` *(optional)* - Turns the request into long-polling mode and follow log messages in real time.
* `seek=N` *(optional)* - Runs the log for the specified time in seconds, for example `seek=3600` will show the log for the last hour.
```
$ curl -k -u admin:admin https://<pikvm-ip>/api/log
```
-----
## ATX power management
### Get ATX state
The `GET /api/atx` handle shows the current ATX state.
```
$ curl -k -u admin:admin https://<pikvm-ip>/api/atx
```
??? note "Click to expand"
```js
{
"ok": true,
"result": {
"busy": false, // True if ATX is busy performing an operation and does not accept commands
"enabled": true,
"leds": {
"hdd": false,
"power": false
}
}
}
```
### Set ATX power
The `POST /api/atx/power` handle changes ATX power state to desired.
Parameters:
* `action=...` - Describes desired state:
* `on` - Turn on (do nothing in case PSU is already on).
* `off` - Turn off (aka soft-off), emulates click on the power button.
* `off_hard` - Perform long press on the power button (5+ seconds).
* `reset_hard` - Emulates pressing reset button (hardware hot reset).
* `wait=1` *(optional)* - Says if call should return immediately or just after finishing operation.
```
$ curl -X POST -k -u admin:admin https://<pikvm-ip>/api/atx/power?action=on
```
### Click ATX button
The `POST /api/atx/click` handle sends the ATX button press event.
Parameters:
* `button=...` - Specifies the desired PC case button:
* `power` - Short click on the power button.
* `power_long` - Long press on the power button (5+ seconds).
* `reset` - Short click on the reset button.
* `wait=1` *(Optional)* - Says if call should return immediately or just after finishing operation.
```
$ curl -X POST -k -u admin:admin https://<pikvm-ip>/api/atx/click?button=power
```
-----
## Mass Storage Drive
### Get MSD state
The `GET /api/msd` handle shows the current MSD state.
```
$ curl -k -u admin:admin https://<pikvm-ip>/api/msd
```
### Upload MSD image
The `POST /api/msd/write` uploads an image to MSD.
Parameters:
* `image=...` - Specifies the name of the image.
* Binary data should be passed to the POST body.
```
$ # create a test image
$ dd if=/dev/zero of=test.iso bs=1M count=1
$ # upload it to pikvm
$ curl -v -X POST --data-binary @test.iso -k -u admin:admin https://<pikvm-ip>/api/msd/write?image=test.iso
```
### Upload MSD image by URL
The `POST /api/msd/write_remote` handle downloads an image from HTTP(S) URL to the MSD.
Parameters:
* `url=...` - Image URL.
* `image=...` *(optional)* - Image name.
* `timeout=N` *(optional)* - Remote request timeout, 10 seconds by default.
!!! note
This is a long-polling request. Do not interrupt the request until the download is complete, otherwise the download will stop.
```
$ # create test image
$ dd if=/dev/zero of=test.iso bs=1M count=1
$ # upload it to pikvm
$ curl -v -X POST -k -u admin:admin https://<pikvm-ip>/api/msd/write_remote?url=http://example.com/test.iso
```
### Set MSD parameters
The `POST /api/msd/set_params` handle changes the current image and/or set drive parameters
Parameters:
* `image=...` *(optional)* - Change the current image.
* `cdrom=1|0` *(optional)* - Change the media type to the CD-ROM on `1`, otherwise to the Flash.
```
$ curl -X POST -k -u admin:admin "https://<pikvm-ip>/api/msd/set_params?image=test.iso&cdrom=1"
```
### Control MSD
The `POST /api/msd/set_connected` connects or disconnect the MSD to the host.
Parameters:
* `connected=1|0` - Change the state.
```
$ curl -X POST -k -u admin:admin https://<pikvm-ip>/api/msd/set_connected?connected=1
```
### Remove MSD image
The `POST /api/msd/remove` handle removes the specified image.
Parameters:
* `image=...` - The image name.
```
$ curl -X POST -k -u admin:admin https://<pikvm-ip>/api/msd/remove?image=test.iso
```
### Reset MSD
The `POST /api/msd/reset` handle resets the drive.
```
$ curl -X POST -k -u admin:admin https://<pikvm-ip>/api/msd/reset
```
-----
## GPIO
### Get GPIO state
The `GET /api/gpio` handle shows the current GPIO state.
```
$ curl -k -u admin:admin https://<pikvm-ip>/api/gpio
```
### Switch GPIO channel
The `POST /api/gpio/switch` handle interacts with selected GPIO driver channel in `switch` mode.
Parameters:
* `channel=...` - The GPIO driver channel.
* `state=1|0` - The new switch state.
* `wait=1` *(optional)* - Says if call should return immediately or just after finishing operation.
### Pulse GPIO channel
The `POST /api/gpio/pulse` handle interacts with selected GPIO driver channel in `pulse` mode.
Parameters:
* `channel=...` - The GPIO driver channel.
* `delay=N.N` *(optional)* - The pulse time in seconds (float), `0` for default delay.
* `wait=1` *(optional)* - Says if call should return immediately or just after finishing operation.
----
## Misc
### Get Prometheus metrics
The `GET /api/export/prometheus/metrics` handle returns the Prometheus metrics. Also see [here](prometheus.md) for details.
```
$ curl -k -u admin:admin https://<pikvm-ip>/api/export/prometheus/metrics
```
-----
# To be continued ===>
You can find all existing APIs in the [KVMD source tree](https://github.com/pikvm/kvmd/tree/master/kvmd/apps/kvmd/api). We would appreciate your help with documentation.
docs/arduino_hid.md
+222
View File
@@ -0,0 +1,222 @@
# Using Arduino HID on non-v0 platform
This is useful if you need a simple and primitive keyboard/mouse emulator device. For example when used with a hardware KVM switch which [does not recognize composite HID](https://github.com/pikvm/pikvm/issues/7). You can also use the Arduino HID to emulate the PS/2 keyboard.
-----
## Serial HID
!!! warning "PiKVM v3 HAT note"
Don't use it, use [SPI HID](#spi-hid) for v3. Otherwise, you won't be able to use the Serial console.
### USB keyboard and mouse
1. ??? example "Get some parts"
* Arduino Pro Micro (based on an ATMega32u4).
* [Logic level shifter](https://www.sparkfun.com/products/12009).
* 1x NPN transistor (almost any NPN transistor: 2n2222 or similar).
* 1x 390 Ohm resistor.
* A breadboard and wires.
2. ??? example "Build the Arduino HID according to the scheme"
<img src="arduino_serial_hid.jpg" />
3. Power up PiKVM and switch it to RW-mode using command `rw`.
4. Add these lines to `/etc/kvmd/override.yaml`:
```yaml
kvmd:
hid:
type: serial
reset_pin: 4
device: /dev/kvmd-hid
```
5. Create file `/etc/udev/rules.d/99-kvmd-extra.rules`:
```udev
KERNEL=="ttyAMA0", SYMLINK+="kvmd-hid"
```
6. Run `systemctl disable getty@ttyAMA0.service`.
7. Remove `console=ttyAMA0,115200`or `console=serial0,115200` and `kgdboc=ttyAMA0,115200` or `kgdboc=serial0,115200` from `/boot/cmdline.txt`.
8. [Flash the Arduino HID](flashing_hid.md).
9. Perform `reboot`.
### PS/2 keyboard
Using the PS/2 firmware currently have some limitations:
* The possibility of using the switchable USB HID is excluded.
* PS/2 mouse is not supported right now (but it will).
Both of these problems will be solved in the nearest future and the two different firmware versions will be combined into one universal one.
To select the PS/2 firmware, follow the instructions for the [USB](#usb-keyboard-and-mouse), but with one exception:
??? note "Before `make` you will need to edit file `platformio.ini`"
Open the file and find these lines:
```ini
[_common]
build_flags =
-DHID_PS2_KBD_CLOCK_PIN=7
-DHID_PS2_KBD_DATA_PIN=5
-DHID_USB_CHECK_ENDPOINT
# ----- The default config with dynamic switching -----
-DHID_DYNAMIC
-DHID_WITH_USB
-DHID_SET_USB_KBD
-DHID_SET_USB_MOUSE_ABS
# ----- PS2 keyboard only -----
# -DHID_WITH_PS2
# -DHID_SET_PS2_KBD
# ----- PS2 keyboard + USB absolute mouse -----
# -DHID_WITH_USB
# -DHID_WITH_PS2
# -DHID_SET_PS2_KBD
# -DHID_SET_USB_MOUSE_ABS
# ----- PS2 keyboard + USB relative mouse -----
# -DHID_WITH_USB
# -DHID_WITH_PS2
# -DHID_SET_PS2_KBD
# -DHID_SET_USB_MOUSE_REL
```
By default, the firmware works with USB HID and supports dynamic mode switching. You can choose one of the other modes by commenting some lines and uncommenting others. This example to use a USB mouse and PS/2 keyboard:
```ini
...
# ----- The default config with dynamic switching -----
# -DHID_DYNAMIC
# -DHID_WITH_USB
# -DHID_SET_USB_KBD
# -DHID_SET_USB_MOUSE_ABS
# ----- PS2 keyboard only -----
...
# ----- PS2 keyboard + USB absolute mouse -----
-DHID_WITH_USB
-DHID_WITH_PS2
-DHID_SET_PS2_KBD
-DHID_SET_USB_MOUSE_ABS
# ----- PS2 keyboard + USB relative mouse -----
...
```
Next, connect Arduino pins to the female PS/2 port of your motherboard. Choose the purple port. If your motherboard only have one port, it's probably universal and can be used either for the keyboard or for the mouse. Most likely, it is painted in two colors: green and purple. You can use it either.
??? example "Follow the diagram"
| Female PS/2 port (front view) | Pinout |
|-------------------------------|--------|
| <img src="ps2_kbd.png" alt="drawing" width="200"/> | Arduino pin 7 <-> PS/2 CLOCK<br>Arduino pin 5 <-> PS/2 DATA<br>Arduino GND pin <-> PS/2 GND |
!!! warning
Connect VIN pin of Arduino to [any Raspberry's 5v pin](https://pinout.xyz/pinout/5v_power) for PS/2 only device. But you don't need to connect the Arduino VIN pin if you connected USB (Arduino will get power through it).
-----
## SPI HID
Using an SPI connection, an Arduino Micro (not Pro) or compatible can be flashed from the Pi and used as an HID keyboard and mouse. Unlike UART, SPI does not share pins with Bluetooth on the Raspberry Pi so the Bluetooth radio does not need to be disabled.
<img src="arduino_spi_hid.png" alt="Diagram of the Arduino SPI wiring for HID keyboard and mouse." width="654"/>
Before powering either device, double-check the connections. The following should be wired from the Pi to either the level shifter or the Arduino. While the Arduino tolerates 3.3V logic input, 5V outputs from the Arduino can damage or destroy the Raspberry Pi and must not be connected directly to 3.3V GPIO pins directly.
### Parts list
There are very few parts needed besides the Raspberry Pi to build the solution. Some parts may be purchased with or without headers, if headers are not pre-soldered, it may be necessary to order some breakaway header strips and solder them to the boards prior to assembly unless the wires will be soldered directly to the boards.
* Raspberry Pi Zero W or Pi 4 are the most popular boards for this solution, pre-soldered headers recommended
* Arduino Micro (or compatible) microcontroller board with pre-soldered headers recommended
* Logic Level Converter. This may be RX/TX, Bidirectional, or Single Supply
* Dupont wires (female to male pin) recommended for breadboard or other suitable means of making the connections
* *Optional:* Breakaway headers for the logic level converter
* *Optional:* Breadboard large enough to accomodate the parts
* *Optional:* Header pins for connection to a breadboard
!!! note
A smaller "Pro Micro" board is available in a 3.3V model but the SS connection (RX_LED) is not available as a separate pin or solderable hole. If using this board, a jumper wire can be soldered to the resistor for the RX_LED but there is risk of burning the resistor, the LED, the board, or other components in the process. Advantages of this board include not requiring a logic level converter and reduced breadboard or board space for building the solution.
### List of connections to be made
For the primary functionality, most connections are made using a 4-channel bidirectional level shifter
* Pi 3v3 to LV on the level shifter
* Pi Ground to LV GND
* Arduino GND to HV GND
* GPIO10 (MOSI) via the level shifter to MOSI on the Arduino
* GPIO9 (MISO) via the level shifter to MISO on the Arduino
* GPIO11 (SPIO_SCLK) via the level shifter to SCK on the Arduino
* GPIO7 (SPIO_CE1_N) via the level shifter to SS (or RX_LED) on the Arduino
An additional circuit is used with a transistor to reset the HID for mode changes and for SPI programming as follows:
* GPIO25 to PNP base on transistor
* PNP emitter to ground
* PNP collector to RST on the Arduino
Pictures of this setup are also available in full resolution for download to assist for both the Raspberry Pi and the Arduino board. A smaller version of the images has been included on this page and can be downloaded.
| Raspberry Pi Closeup | Breadboard with Arduino |
|------------|--------|
| <img src="arduino_spi_hid_rpi.jpg" alt="A closeup of the Raspberry Pi wired to the breadboard." width="300" /> | <img src="arduino_spi_hid_bb.jpg" alt="Arduino on a breadboard fully wired to the Pi." width="300" /> |
Programming assumes the Arduino is powered via USB, either from the connected host or the Pi itself. If the USB is not connected, 5 V may be provided by the Raspberry Pi GPIO but should be disconnected prior to connecting USB to the Arduino's USB port. The Raspberry Pi does not have backcurrent protection, a circuit using one or more Schottky diodes can be built to OR power from multiple sources but it's easier and more cost effective to avoid conflict and voltage differences between power supplies by leaving the 5 V wire disconnected.
### Preparing the installation for SPI devices and programming
As of the latest package release, the kdmd service supports SPI. It should be sufficient to ensure the packages are up-to-date with the latest release, the programmer is installed, and the SPI device overlay is loaded at boot.
* Switch the filesystem to read-write mode with `rw`
* Update the system with `pacman -Syu` for the latest packages
* Install the avrdude programmer with `pacman -S avrdude-svn`
* Add `dtoverlay=spi0-1cs` to `/boot/config.txt`
* Reboot with `reboot` or `systemctl reboot`
### Flashing the Arduino
Instructions on flashing the Arduino can be found on the page [Flash the Arduino HID](flashing_hid.md).
If programming fails, ensure the Arduino is powered and check the wiring again. If there is a misconfiguration, power off the Pi and the Arduino, correct the wiring, and try again. Note it is not recommended or required to supply 5V power from the Raspberry Pi if the Arduino is USB powered, if the issue appears to be power related it may be removed from the solution and replaced with a powered USB connection if it will aid in troubleshooting but check all other wires first to ensure there are no shorts.
Wiring problems are a common issue but there could be other reasons for programming not to complete. While it is not possible to list every possible problem and solution here, there is an active user community in our [Discord](https://discord.gg/bpmXfz5) with others familiar with the solution and willing to help.
### Enable the SPI configuration and restart kvmd
Once the installation has completed, all that should remain is to add the following configuration to `/etc/kvmd/override.yaml` and restart the kvmd service. If the first line exists due to existing overrides, omit that line and either add or update the hid section as appropriate.
```yaml
kvmd:
hid:
type: spi
chip: 0
bus: 0
sw_cs_pin: 7
reset_pin: 25
reset_inverted: true
```
After saving the changes to `/etc/kvmd/override.yaml`, restart `kvmd` and clear your browser cache. The command to restart `kvmd` is
```
# systemctl restart kvmd
```
If your device is still in read-write mode, `ro` will put the SD back in read-only mode.
-----
## Fixing the USB absolute mouse on Windows 98
Due to an ancient buggy driver, the USB absolute mouse on Windows 98 moves only within the upper-left quarter of the screen. To fix this, just recompile the firmware with uncommented flag `-DHID_WITH_USB_WIN98` in `platformio.ini`.
docs/arduino_hid/arduino_serial_hid.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 273 KiB

docs/arduino_hid/arduino_spi_hid.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 266 KiB

docs/arduino_hid/arduino_spi_hid_bb.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 MiB

docs/arduino_hid/arduino_spi_hid_rpi.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 MiB

docs/arduino_hid/ps2_kbd.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 91 KiB

docs/bluetooth_hid.md
+80
View File
@@ -0,0 +1,80 @@
# Bluetooth HID
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.
!!! warning
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.
!!! note
Bluetooth mouse can work only in [relative mode](mouse.md). The reason is that many Bluetooth host drivers do not correctly implement HID descriptors. Horizontal scrolling is not supported for the same reason.
## Configuring the OS
1. Switch filesystem to RW-mode, perform update and install some packages:
```
# rw
# pacman -Syu
# pacman -S bluez bluez-utils raspberrypi-bluetooth
```
2. Edit `/boot/config.txt` and comment these lines:
```
#enable_uart=1
#dtoverlay=disable-bt
```
3. Create an empty directory `/var/lib/bluetooth` and add mountpoint to `/etc/fstab`:
```
# mkdir /var/lib/bluetooth
# echo 'tmpfs /var/lib/bluetooth tmpfs nodev,nosuid,mode=0755 0 0' >> /etc/fstab
```
4. Override and enable the services:
```
# mkdir /etc/systemd/system/bluetooth.service.d
# cat << EOF > /etc/systemd/system/bluetooth.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/lib/bluetooth/bluetoothd --noplugin=*
EOF
# systemctl enable bluetooth
# systemctl enable raspberrypi-btuart
```
5. Override `kvmd` service:
```
# mkdir /etc/systemd/system/kvmd.service.d
# cat << EOF > /etc/systemd/system/kvmd.service.d/override.conf
[Service]
AmbientCapabilities=CAP_NET_RAW CAP_NET_BIND_SERVICE CAP_SYS_ADMIN CAP_SETUID CAP_SETGID CAP_CHOWN
CapabilityBoundingSet=CAP_NET_RAW CAP_NET_BIND_SERVICE CAP_SYS_ADMIN CAP_SETUID CAP_SETGID CAP_CHOWN
EOF
```
6. Add following lines to `/etc/kvmd/override.yaml`:
```yaml
kvmd:
hid:
type: bt
```
7. Perform `reboot`.
8. To reverse, uncomment lines from Step 2 and remove lines in Step 6, and `reboot`.
## Using Bluetooth HID
* 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.
docs/building_os.md
+106
View File
@@ -0,0 +1,106 @@
# Building the OS
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
* glibc >= 2.33
* docker >= 19.03.13
Docker must be enabled in privileged mode.
1. When starting with a clean OS you need to install and configure docker (after adding your user to the docker group you must log out and log back in), as well as git and make. An example for Ubuntu:
```shell
[user@localhost ~]$ sudo apt-get install git make curl binutils -y
[user@localhost ~]$ curl -fsSL https://get.docker.com -o get-docker.sh
[user@localhost ~]$ sudo sh get-docker.sh
[user@localhost ~]$ sudo usermod -aG docker $USER
```
Re-login to apply the changes.
2. Git checkout the build toolchain:
```shell
[user@localhost ~]$ git clone --depth=1 https://github.com/pikvm/os
[user@localhost ~]$ cd os
```
3. Determine the target hardware configuration (platform):
* Choose the board: `BOARD=rpi4` for Raspberry Pi 4 or `BOARD=zerow`, `BOARD=rpi2`, `BOARD=rpi3` for other options.
* Choose the platform:
* `PLATFORM=v3-hdmi` for RPi4 and PiKVM v3 HAT.
* `PLATFORM=v2-hdmi` for RPi4 or ZeroW with HDMI-CSI bridge.
* `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 PiKVM boards (WIP).
4. 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
[user@localhost os]$ cat config.mk
# rpi3 for Raspberry Pi 3; rpi2 for the version 2, zerow for ZeroW
BOARD = rpi4
# Hardware configuration
PLATFORM = v2-hdmi
# Target hostname
HOSTNAME = pikvm
# ru_RU, etc. UTF-8 only
LOCALE = en_US
# See /usr/share/zoneinfo
TIMEZONE = Europe/Moscow
# For SSH root user
ROOT_PASSWD = root
# Web UI credentials: user=admin, password=<this>
WEBUI_ADMIN_PASSWD = admin
# IPMI credentials: user=admin, password=<this>
IPMI_ADMIN_PASSWD = admin
# SD card device
CARD = /dev/mmcblk0
```
If you want to configure wifi (for ZeroW board for example) you must add these lines to `config.mk`:
```Makefile
WIFI_ESSID = "my-network"
WIFI_PASSWD = "P@$$word"
```
4. Build the OS. It may take about one hour depending on your Internet connection:
```shell
[user@localhost os]$ make os
```
5. One of two actions:
* Put SD card into card reader and install OS (**you should disable automounting beforehand**: `systemctl stop udisk2` or something like that):
```shell
[user@localhost os]$ make install
```
* Make the image to copy elsewhere and burn on to SD card:
```shell
[user@localhost os]$ make image
```
Image is then available as a bziped file in `images/`.
6. After installation remove the SD card and insert it into your RPi. Turn on the power. The RPi will try to get an IP address using DHCP on your LAN. It will then be available via SSH.
7. If you can't find the device's address, try using the following command:
```shell
[user@localhost os]$ make scan
```
docs/community_faq.md
+349
View File
@@ -0,0 +1,349 @@
### Can I power the Pi via POE?
- Yes! But you will still need to ensure you isolate the 5v connection between the Raspberry Pi and host PC to prevent backpower issues that can cause instability or damage to either the host PC or the Pi. Power/Data cable + usb power blocker would work. Please see Variant #1 in the main getting started page for details.
### Do I need a power splitter? Why do I need one?
- Yes for RPi4, Yes and No for ZeroW - Yes if you want dedicated power, otherwise No
- Yes, otherwise you could back power the pi and or the target
- You can get a Y cable from amazon and mod one of the leads - Please see getting started guide - or see [non modding of Y cable](https://github.com/pikvm/pikvm#hardware-for-v2)
- You can also get a power splitter board from Tindi or PiShop [(Links provided under variants #3 & #4)](https://github.com/pikvm/pikvm#hardware-for-v2)
- If you have the v3 HAT - This is built in
### I can't get the KVM KB to work on my ZeroW!
Make sure that you did NOT modify your config.txt file, this is the default:
```
# See /boot/overlays/README for all available options
initramfs initramfs-linux.img followkernel
hdmi_force_hotplug=1
gpu_mem=64
enable_uart=1
dtoverlay=tc358743,i2c_pins_28_29=1
dtoverlay=disable-bt
dtoverlay=dwc2,dr_mode=peripheral
```
Ensure that you have the cable(Needs to support both power/data) plugged into the right port, the one closest to the mini HDMI is the correct port
### Can I use a KB on my ZeroW?
- Yes but kb/mouse passthrough will not work. Its one or the other - This is especially true if you use an addon that requires the below to change.
- edit ```/boot/config.txt```
- Host mode - Comment out dtoverlay=dwc2
- Passthrough mode - Uncomment out dtoverlay=dwc2
### 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 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
- Please use the search function in Discord, some users have had sucess in getting this to work but your mileage may vary
- The better solution is to capture the stream in a dir and then use VLC to stream to that capture on another computer. This will result in fps loss.
### 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
- Execute: `hostnamectl set-hostname yournewhostname.domain`
- Optional: Edit `/etc/kvmd/meta.yaml` to alter the displayed hostname in the web UI
- Reboot the pikvm
### 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.
### Can this be used in any other distro’s like Rasbian? Run this in a Docker?
- Officially, no. Unofficially yes and totally #unsupported. Please DM @srepac on discord for the directions.
- Docker image is available, search the docker hub but this is #unsupported and #unofficial and not updated.
### Can you switch from USB to CSI or from CSI to USB?
- Officially, no. You would be advised to make 2 seperate SD cards and swap them when needed. Unofficially yes and totally NOT supported. Please DM @srepac on discord for the script and directions.
### My Pi keeps disconnecting from my wireless! What do I do?
- You can try the following: Edit "/etc/conf.d/wireless-regdom" and look for your region and uncomment it. Example: WIRELESS_REGDOM="US"
### I want a static IP!!
- You can configure systemd-networkd for a static address for ethernet NIC. Config file is /etc/systemd/network/eth0.network
- For wireless adapter, config file is /etc/netctl/wlan0-<wifiname>
- See [this page](wifi.md) for details on how to get basic wireless config with DHCP going. Afterwards, you’ll need to edit the /etc/netctl/wlan0-<wifiname> file changing the IP=dhcp line with the following lines updated to reflect your network:
```
For /etc/systemd/network/eth0.network
[Match]
Name=eth0
[Network]
Address=192.168.X.XXX/24
Gateway=192.168.X.X
DNS=192.168.X.X
DNS=192.168.X.X
For /etc/netctl/wlan0-<wifiname>
IP=static
Address=('192.168.X.XXX/24')
Gateway=('192.168.X.X')
DNS=("192.168.X.X 1.0.0.1 1.1.1.1")
```
- You can also reserve the IP in your dhcp server (Quicker)
### Why do I keep getting a different IP?
- You can do 2 of the following actions:
- Add to, /etc/systemd/network/eth0.network
```
[DHCP]
ClientIdentifier=mac
```
- OR reserve the DHCP ip in your server/router
### HELP!! I can't find the IP on the ZeroW/RPi4
- Open a browser and type: pikvm, still doesnt work?
- Use the FING mobile app to scan your network, its free
- Install Angry IP scanner, tools/preferences/Display results in the results list/Select Alive hosts, modify IP range, hit start
- Using FF, navigate to https://pikvm (Depends on your network if this actually works, in most case's it "should" work))
- The below commands will verify that your Pi on on your network
```
Linux: arp -a | grep below is a list of MAC's for Raspberry Pi
B8:27:EB:xx:xx:xx B8-27-EB-xx-xx-xx B827.EBxx.xxxx
DC:A6:32:xx:xx:xx DC-A6-32-xx-xx-xx DCA6.32xx.xxxx
E4:5F:01:xx:xx:xx E4-5F-01-xx-xx-xx E45F.01xx.xxxx
Windows Power shell: arp -a | findstr 'b8-27-eb' (Replace with the above, all lower case)
```
- For older flashed images you can do the following on the RPI4, ZeroW edit it when you edit WiFi info
- Open web terminal and go to root, ```rw``` then ```nano /etc/issue```
- add ```IP: \4```
- Once you reboot, you will now see the IP in the upper left
### Help! I ran out of space aka room! What now?
(This ONLY applies to the older flashed images and is no longer nessessary as the newer images had the main partition increased, as a result, the MSD partition was shrunk)
- You’ve cached package updates you no longer need.
- Enter read/write mode by executing rw as root
- Execute the following as root to clear the package cache
```
rm -rf /var/cache/pacman/pkg/*
```
- Exit read/write mode by executing ro as root
- You can also use gparted to resize partitions without "losing data", although there is a chance this may delete all of your data
### Can you connect a camera to this and still make pikvm functional?
- Yes, any cheapo webcam can be used in place of the usb dongle, please use the usb image
- A PiCam will NOT work
### HELP!! Something isn't working!!
- What was the last thing or most recent thing you did? Did you undo it?
- Did you change a file? Did you back it up before changing it?
- Did you hook this to anything else? If not why not?
- Did you try different cables?
### HELP! I am getting a 500/503 error when I try and access the main KVM page!
- This is due to a bad line in your yaml file, here are some steps you can make to help in the future.
- Run ```kvmd -m```, this will display ALL kvmd settings, you can compare to your own. Make sure you are not doubling up on child/sub-child entries.
- Remember you need 4 space per child and 4 additional for each sub-child
- Make a .nanorc file and populate it with the following:
*set linenumbers* is optional
```
set linenumbers
set tabsize 4
set tabstospaces
```
- Now re-edit your override.yaml file and just use tab to get the right spacing, you might need to delete the current leading "spaces" to ensure proper formatting
### Can you use an iPad on PiKVM?
- Yes, with the correct hardware you can control an iPad
- Yes, activate VNC and use JUMP app(Full featured but more expensive), or bVNC(Not recommended, lack luster features but cheap). RealVNC does NOT work
### How do I add my own SSL cert?
- If you have a certificate(:exclamation:**Making a cert falls outside the scope of PIKVM - Please reference Linux documentation**:exclamation:), replace the public key in /etc/kvmd/nginx/ssl/server.crt and private key in /etc/kvmd/nginx/ssl/server.key and restart the kvmd-nginx service.
- It should look like the following:
```
cd /etc/kvmd/nginx
cat ssl.conf (Expection of what's inside the file)
ssl_protocols TLSv1.3 TLSv1.2 TLSv1.1 TLSv1;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
ssl_certificate /etc/kvmd/nginx/ssl/server.crt;
ssl_certificate_key /etc/kvmd/nginx/ssl/server.key;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
```
### How do I emulate various USB devices on the target machine?
By default this is what is set:
```
otg:
manufacturer: PiKVM
max_power: 250
product: Composite KVM Device
product_id: 260
serial: CAFEBABE
udc: ''
user: kvmd
vendor_id: 7531
```
You can change how this is displayed with the following example:
```nano /etc/kvmd/override.yaml```
```
otg:
manufacturer: Corsair
product: Corsair Gaming RGB
serial:
vendor_id: 6940
product_id: 6973
```
Use the following USB Data Base to get the desired devices: ```https://the-sz.com/products/usbid/``` or ```https://devicehunt.com```
❗NOTE❗ You may need to include ```0x0``` in the id string's for it to work properly.
- Example:
- ```vendor_id: 0x06940```
### Things to do after initial install:
- Fix date: 'timedatectl list-timezones' then 'timedatectl set-timezone America/Los_Angeles' (Change to your location)
- Update PiKVM, follow #news on Discord for instructions
- Setup a NFS share to give read/write storage on the read only pikvm
- Note: this does assume you already have an NFS server on your network and accessible to pikvm
- Source https://linuxhint.com/install_configure_nfs/
```
pacman -S nfs-utils
showmount -e 192.168.1.XXX
mount -t nfs 192.168.1.XXX:/volume1/Data /mnt/Data
nano /etc/fstab
```
Add To the bottom of the file
```
192.168.1.XXX:/volume1/Data /mnt/Data nfs auto,rw,soft 0 0
```
### 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)
### Troubleshooting
- :exclamation:**It is expected that you are aware of basic networking while working on this project and that you have read up on the project prior to going to Discord**:exclamation:
- Do you know the IP?
- Can you ping the IP?
- Did you swap cables?
- Did you swap the eth port to a known working eth port?
- Do you have access to another router or switch?
- Did you change ports on the router/switch?
- RPi4 - Did you hook up a monitor? Once logged in, can you ping to your gateway? Other IP's on the same network?
- Did you connect a monitor to the target? Does it work?
- Did you connect the PIKVM to the target directly? Does it work?
- Reboot target
- Try default image, do not update and test
-copy/paste into a file, call it pi-info.sh, chmod +x pi-info.sh, ./pi-info.sh **Same script is located [here](https://pastebin.com/u/srepac)**
```
#!/bin/bash
uptime
TMPFILE="/tmp/pacmanquery"; /bin/rm -f $TMPFILE
pacman -Q | awk '{print $2, $1}' > $TMPFILE
chmod go+w $TMPFILE
pistat && echo
printf "%-18s\t%s\n" "Version" "Package-Name" "----------------------" "-----------------------------"
PACKAGES="firmware bootloader kvmd ustreamer nginx wpa wireless"
for PKG in $( echo $PACKAGES ); do
printf "%-18s\t%s\n" $(grep $PKG $TMPFILE | sed 's/-[1-9]//g')
done
```
```dmesg | grep tc35``` - CSI
<br/><br/>
```dmesg | egrep '1-1.[245]|uvc'``` - USB
```systemctl status kvmd```
```systemctl status kvmd-otg```
- **hint:** look at kvmd-platform line of the output... make sure it matches the image they expect for the capture device and platform
- Keyboard/Mouse icons orange? Try a different cable (ALLOT are power only), try a different usb port
- Should see the following if everything is in place
`ls -l /dev/kvmd`
```
lrwxrwxrwx 1 root root 5 Apr 5 21:33 /dev/kvmd-hid-keyboard -> hidg0
lrwxrwxrwx 1 root root 5 Apr 5 21:33 /dev/kvmd-hid-mouse -> hidg1
lrwxrwxrwx 1 root root 6 Mar 15 09:07 /dev/kvmd-video -> video0
```
### Common Commands for troubleshooting PiKVM
- `journalctl -u kvmd`
- `journalctl -u kvmd-vnc`
- `journalctl -u kvmd-ipmi`
### Bootup/power issues
- PiKVM won’t boot past “rainbow” screen
- Are you plugged into the right HDMI port? Needs to be the one next to the power for RPI4
- Have you reflashed your SD card?
### PiKVM Complains about low power warnings
- Are you using a `proper` power supply? Not one you hacked together?
- Some USB power bricks advertise 5V @ 2.1A or higher, but can’t deliver consistent 5V. Best to use rpi foundation recommended power supplies
### USB Video Capture Issues
- Make sure this is a capture card and not an adapter (HDMI->USB)
### HDMI-CSI Capture issues
- Have you reset the Target PC?
- Are you sure it's a bridge and not an extender? There is a difference
- Did you make sure it's plugged into the right port? It needs to say Camera NOT Display
- Did you try another ribbon cable?
- Did you reseat the ribbon cable?
- Is the ribbon cable facing the right way? Needs to be towards the PCB (Green or Black)
- If you are getting snow looking screen, you need to make sure you select 50hz OR select anything below 1080p, like 720p60
- If you are getting an Indian looking screen, please clear the browser cache or use private/incog window
### 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
- PiKVM that mitigates HDMI backpower and requires no splitter board [here](https://docs.google.com/document/d/1M9xUgNE_-P8GydKr_3qIgXUR9YzqApHNPhetRv3pcsE/edit)
- VERY useful scripts that enhance the PiKVM's functionality - Please DM @srepac on discord to gain access
### Useful links
- https://www.tomshardware.com/how-to/kvm-over-ip-raspberry-pi - Very good article on PIKVM setup
As of March 2021, Below are frequently out of Stock or hard to get items, all have exceptionally LONG shipping dates
```
Ezcoo KVM - Goes out of stock frequently
CSI2-HDMI bridge w/ TC358743XBG chip - Goes out of stock freqently
Alternative names for the same devices:
Tiamu Sling Yazan Ningwang Essenc Geekworm
Fauge Haudang AKAT Docoop Katigan Lyusa (recommended by mdevaev)
LNIMI cherrypop Lopbinte Uang Tuneway Mustwell
Facibom Binchil Cobeky Ctzrzyt Davitu
```
- Community recommended USB capture [card](https://www.amazon.com/gp/product/B08FG54QPH)
- Community recommended Loop device that allows [Monitor+PiKVM](https://www.amazon.com/gp/product/B08DQWLXF1)
docs/edid.md
+92
View File
@@ -0,0 +1,92 @@
# EDID
EDID is information about the video modes supported by the video capture device.
In the case of PiKVM, this is an HDMI CSI bridge. Usually, you don't need to change this, since the default configuration is quite flexible,
but sometimes, for example for strange UEFIs/BIOSes, this may be necessary (the [story](https://github.com/pikvm/pikvm/issues/78)).
The EDID is stored on the PiKVM in the file `/etc/kvmd/tc358743-edid.hex`. If you write new data there, it will be applied on the PiKVM reboot.
You can also apply the new EDID without rebooting to make sure it works:
* Switch filesystem to RW-mode: `rw`.
* Create file with EDID `/root/edid.hex` (examples of file contents are shown below).
* Apply EDID using the command `v4l2-ctl --device=/dev/kvmd-video --set-edid=file=/root/edid.hex --fix-edid-checksums`.
* DO NOT REBOOT the PiKVM. Just your PC. Check the UEFI/BIOS.
* If everything works, you can write the same data to `/etc/kvmd/tc358743-edid.hex`.
* Switch filesystem to RO-mode: `ro`.
The examples below are tested on these devices, but they are also suitable for others. To edit or create EDID you can use [AW EDID Editor](https://www.analogway.com/emea/products/software-tools/aw-edid-editor).
## Custom EDIDs
??? example "1280x1024 as preferred. Useful for Gigabyte GA-H77-DS3H"
```
00FFFFFFFFFFFF005262888800888888
1C150103800000780AEE91A3544C9926
0F505425400001000100010001000100
010001010101D51B0050500019400820
B80080001000001EEC2C80A070381A40
3020350040442100001E000000FC0050
492D4B564D20566964656F0A000000FD
00323D0F2E0F0000000000000000014D
02030400DE0D20A03058122030203400
F0B400000018E01500A0400016303020
3400000000000018B41400A050D01120
3020350080D810000018AB22A0A05084
1A3030203600B00E1100001800000000
00000000000000000000000000000000
00000000000000000000000000000000
00000000000000000000000000000045
```
??? example "1920x1080 as preferred. Useful for Gigabyte GA-H77-DS3H or Intel NUC"
```
00FFFFFFFFFFFF005262888800888888
1C150103800000780AEE91A3544C9926
0F505425400001000100010001000100
010001010101D32C80A070381A403020
350040442100001E7E1D00A050001940
3020370080001000001E000000FC0050
492D4B564D20566964656F0A000000FD
00323D0F2E0F000000000000000001C4
02030400DE0D20A03058122030203400
F0B400000018E01500A0400016303020
3400000000000018B41400A050D01120
3020350080D810000018AB22A0A05084
1A3030203600B00E1100001800000000
00000000000000000000000000000000
00000000000000000000000000000000
00000000000000000000000000000045
```
??? example "1280x1024 as preferred, disabled 1080p at all. This may be necessary in extremely rare cases if the BIOS is completely buggy. In the future, we will provide a way to dynamically switch EDID"
```
00FFFFFFFFFFFF005262888800888888
1C150103800000780AEE91A3544C9926
0F50542FCF0001000100010001000100
0100010101018C2300A050001E403020
370080001000001E000000FC0050492D
4B564D20566964656F0A000000FD0032
3D0F2E0F000000000000000000000010
0000000000000000000000000000016B
02030400DE0D20A03058122030203400
F0B400000018E01500A0400016303020
3400000000000018B41400A050D01120
3020350080D810000018AB22A0A05084
1A3030203600B00E1100001800000000
00000000000000000000000000000000
00000000000000000000000000000000
00000000000000000000000000000045
```
## Default EDID
If for some reason you need to go back to the default EDID (changing attached device etc), you can find it locally on the Pi at `/usr/share/kvmd/configs.default/kvmd/tc358743-edid.hex`:
```
# cp /usr/share/kvmd/configs.default/kvmd/tc358743-edid.hex /etc/kvmd/tc358743-edid.hex
```
... or in the [kvmd repo](https://github.com/pikvm/kvmd/blob/master/configs/kvmd/tc358743-edid.hex).
docs/ezcoo.md
+124
View File
@@ -0,0 +1,124 @@
# ezCoo managed multiport KVM switch
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 in our [Discord](https://discord.gg/bpmXfz5) and the author appreciates their efforts.
!!! info
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`.
!!! info
Audio was not tested, it is assumed to be non-functional.
## Connections
From a high level, the ezCoo 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 the USB 3 port on the ezCoo switch. There is an additional USB cable connected to the managed port on the switch.
1. Connect the USB-A cable from the Raspberry Pi OTG port to ezCoo switch USB 3 port on the front of the switch. **Note**: If this cable is connected to the keyboard port of the ezCoo switch the mouse will not be present.
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 PiKVM. SSH into PiKVM and ensure a device like `/dev/ttyUSB0` is present. The following instructions assume this is the KVM switch.
!!! info
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 PiKVM UI after clicking the "GPIO" menu button in the KVM view.
1. Enable read-write mode on the SD card via `rw`
2. Edit the file: `nano /etc/kvmd/override.yaml` and include the following. Note the assumption that the KVM switch is present on `/dev/ttyUSB0`:
```yaml
kvmd:
gpio:
drivers:
ez:
type: ezcoo
device: /dev/ttyUSB0
scheme:
ch0_led:
driver: ez
pin: 0
mode: input
ch1_led:
driver: ez
pin: 1
mode: input
ch2_led:
driver: ez
pin: 2
mode: input
ch3_led:
driver: ez
pin: 3
mode: input
ch0_button:
driver: ez
pin: 0
mode: output
switch: false
ch1_button:
driver: ez
pin: 1
mode: output
switch: false
ch2_button:
driver: ez
pin: 2
mode: output
switch: false
ch3_button:
driver: ez
pin: 3
mode: output
switch: false
view:
table:
- ["#Input 1", ch0_led, ch0_button]
- ["#Input 2", ch1_led, ch1_button]
- ["#Input 3", ch2_led, ch2_button]
- ["#Input 4", ch3_led, ch3_button]
```
Make sure to notate the spacing for each line, needs to be a total of 4 spaces:
```
For example:
parent: 0 spaces (kvmd:)
child: 4 spaces (gpio:)
sub-child: 8 spaces (drivers:)
sub-sub-child: 16 spaces (ez:)
```
3. Return to read-only mode for the sd card via `ro`.
4. Restart the kvmd service: `systemctl restart kvmd`.
5. If you are still not getting KB output, issue a `ls -la /dev/tty* | grep USB` , if no output change cables (Alot of cables are power only)
## Switching between hosts in the UI
To switch between hosts, enter the KVM UI and click the "GPIO" menu. You should see 4 inputs, one of which will have a green circle indicating it is currently selected. Click the other inputs to change the selected host.
## Additional step for the USB 3.0 version
Please add `protocol: 2` to the override.yaml under the `type: ezcoo` at the same level:
```yaml
kvmd:
gpio:
drivers:
ez:
type: ezcoo
protocol: 2
device: /dev/ttyUSB0
```
docs/faq.md
+304
View File
@@ -0,0 +1,304 @@
# FAQ & Troubleshooting
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.
!!! tip
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.
## Common questions
??? question "Can I connect multiple servers to a single PiKVM?"
Yes, but it will require additional work to set up. See [this page](multiport.md).
??? question "How can I get the access to PiKVM in my local network over Internet?"
You can use port forwarding for port 443 on your router if it has an external IP address. In all other cases, you can use the excellent free VPN service [Tailscale](tailscale.md), which is configured on PiKVM with a [few simple commands](tailscale.md).
??? question "Can I use PiKVM for gaming?"
No, because:
* For HDMI-CSI bridge, bus bandwidth is not enough to transmit more than 1080p50.
* For HDMI-USB dongle, high latency and low video quality.
* General hardware video capture differs from software streaming and introduces additional latency.
* PiKVM can't transmit audio at this time. It will be available on PiKVM v3 HAT at some point in the future (implemented in the hardware, but doesn't have software support).
??? question "Can PiKVM do 4K video?"
* For HDMI-CSI bridge, no. There is not enough bandwidth in the CSI bus for that much data. 1080p50 will max out the bandwidth.
* For the USB capture devices: technically yes, they will downsample to something smaller to meet the USB 2.0 bandwidth limitations, so the source may be 4k, but the stream will not.
* The 4K real-time video will not fit through the network anyway.
??? question "Where does the video latency come from?"
Here is the chain of transferring an image to your browser or VNC client.
`Capture device -> Compression -> Network -> Decompression -> Rendering`
100-200ms is very, very fast for this. But we are working to speed things up even more.
??? question "Does PiKVM support sound?"
At this time sound is not supported on any platform however, once sound is implimented, it will only be available for PiKVM v3 HAT. Due to a hardware bug in HDMI-CSI bridges, sound may or may not work.
??? question "Can I use PiKVM with non-Raspberry boards (Orange, Nano, etc)?"
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).
??? question "Is PiKVM OS its own custom distro?"
No. PiKVM OS is an [Arch Linux ARM](https://archlinuxarm.org) with our own repository for KVM-related packages. We distribute OS images (that is, our Arch Linux ARM build) to simplify installation, since PiKVM requires some tuning of the OS and special partitioning of the memory card.
??? question "Why is PiKVM OS based on Arch Linux ARM and not Raspbian / Raspberry Pi OS?"
There are several reasons:
* Several years ago, when PiKVM was just starting out, Raspbian didn't have a minimalistic buiimage and the transition to systemd was in full swing, which is why the distribution was not too stable.
* Raspbian did not have all the necessary packages in the repositories to satisfy most software dependencies.
* PiKVM was born as a pet project, and the founder likes Arch the most.
However, we plan to provide an alternative OS image based on Raspbian in the future - now it is quite stable.
## First steps
??? question "What is the default password? How do I change it?"
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
su - # If you're in the webterm
rw # Switch filesystem to read-write mode
passwd root # Change OS root password
kvmd-htpasswd set admin # Change web ui admin password
ro # Back to read-only
```
??? question "How do I get root access in the web terminal?"
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**.
??? question "Where is the PiKVM configuration located?"
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](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html) 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`.
??? question "I can't edit any file on PiKVM. Why is the system in read-only mode?"
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`.
??? question "I want to get read-write filesystem all of the time"
!!! danger "DON'T DO THIS"
!!! danger "DON'T DO THIS"
!!! danger "DON'T DO THIS"
**Seriously, DON'T**. Read-only mode increases the life of the memory card and protects the filesystem from power loss failures. See the question above ^ ^ ^
You can turn it off, but don't say you weren't warned.
??? danger "DON'T OPEN THIS SPOILER AND DON'T DO THIS"
Okay, fine.
* Edit `/boot/cmdline.txt` and change option `ro` to `rw`.
* Do the same in `/etc/fstab` for the `/boot` partition.
* Comment `tmpfs` lines in `/etc/fstab` for `/var/lib` and `/var/log`.
!!! danger "But again: DON'T DO THIS"
??? question "How to install or remove any packages in PiKVM OS?"
PiKVM OS is based on Arch Linux ARM and uses the [pacman](https://wiki.archlinux.org/title/Pacman) package manager.
* Switch filesystem to RW-mode: `rw`.
* Update the package cache: `pacman -Syy`.
* Find some packages (`emacs` for example): `pacman -Ss emacs`.
* Install it: `pacman -S emacs`.
* Remove it: `pacman -R emacs`.
* Switch filesystem to RO-mode: `ro`.
??? question "How do I update PiKVM with the latest software?"
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
# reboot
```
Pacman saves all installed packages in a compressed format so that you can roll back to the old version if something goes wrong. After you've updated and made sure everything works, it makes sense to clear the package cache so that it doesn't take up space on the SD card: `rw; rm -rf /var/cache/pacman/pkg; ro`.
??? question "I don't need ATX functions. How do I disable this in the Web UI?"
If you don't need ATX power control you can disable the relevant Web UI menu in `/etc/kvmd/override.yaml`:
```yaml
kvmd:
atx:
type: disabled
```
... then restart `kvmd`:
```
# systemctl restart kvmd
```
??? question "How to disable the web terminal?"
```
# systemctl disable --now kvmd-webterm
```
??? question "How to completely disable authorization in PiKVM?"
Edit the file `/etc/kvmd/override.yaml`:
```yaml
kvmd:
auth:
enabled: false
```
... then restart `kvmd`:
```
[root@pikvm ~]# systemctl restart kvmd
```
## Video problems
??? question "I can see the video but I can't see the WebRTC switch"
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.
??? question "PiKVM does not show the video from the computer at all"
* Double-check that the video capture device is connected correctly. For the [CSI bridge](/README.md#for-the-hdmi-csi-bridge), this should be exactly the camera port, for the [USB dongle](/README.md#for-the-hdmi-usb-dongle), strictly the port indicated in the picture.
* Some laptops do not output any signal until you switched the output (usually via the FN + and an F5 key on the keyboard).
* Your computer may have turned on sleep mode for the monitor. Move the mouse and turn it off.
??? question "The video works in the booted OS, but not in the BIOS/UEFI"
The problem appears on Intel NUC, GA-H77-DS3H, and some other devices with using CSI bridge. All you need to do is [change the EDID data](edid.md). This is the information about supported resolutions that the CSI bridge reports to your computer.
??? question "Glitchy or wrong BIOS/UEFI resolution"
On some motherboards, the BIOS may be displayed at a lower resolution, or with some rendering issues/glitches, specially on newer ASUS ones. Like this:
<img src="bios_glitch.png" alt="ASUS BIOS glitch" width="400"/>
This can be solved by enabling the **Compatibility Support Module (CSM)** in your BIOS, usually under the **Boot** options.
If you can't or don't want to enable the CSM, you can try connecting a DisplayPort monitor, or a [dummy plug](http://amazon.com/s?k=displayport+dummy+plug). If you remove the DP cable/adapter the bug will reappear.
If none of this works, try connecting the DP cable first, boot into the BIOS, disable the CSM and shutdown (do not restart) your PC. Then, boot into the BIOS and enable the CSM before shutting down your PC. Then connect the HDMI and turn your PC on again.
??? question "CSI bridge does not work with official Raspberry Pi PoE HAT"
Details [here](https://github.com/pikvm/pikvm/issues/6). The reason is that the [official HAT](https://www.raspberrypi.org/products/poe-hat) has a built-in fan controller that conflicts with the TC358743 chip of the bridge. The solution is to disable the fan control and connect it to the power line so that it works continuously. To turn off the controller you need to add the line `disable_poe_fan=1` to `/boot/config.txt`.
??? question "The video freezes a few seconds after the start, restarting the Web UI or VNC does not help"
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 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`.
* Make sure that the last message from ustreamer was `H264: Configuring MMAL encoder` (not counting messages about connecting and disconnecting stream clients).
??? question "No image from computer with Linux + Awesome WM"
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.
## USB problems (keyboard, mouse, mass storage, etc)
??? question "My computer does not recognize USB of PiKVM v2+ at all"
* Make sure that you have used the correct USB cable with DATA lines to connect the OTG port for the Raspberry to the computer. You may have decided to use a USB hub instead of a Y-cable and **it won't work**. Use good cables and follow the instructions :)
* In rare cases, some very buggy BIOSes does not like HID and Mass Storage in one USB device. You can either [disable Mass Storage](msd.md#disable-msd), or use [Arduino HID](arduino_hid.md) to physically separate them.
??? question "BIOS/UEFI does not recognize USB of v2+, but computer does"
If you are using a USB hub or USB PCI controller, this may not be handled by your BIOS. Try to use another USB port. Some ports may have a built-in hub on the motherboard and a buggy BIOS that can't handle it.
??? question "The keyboard works in BIOS/UEFI, but the mouse does not"
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).
??? question "I can't wake up suspended computer on v2+"
This feature is experimental and requires manual activation. Perform a full system update, edit `/etc/kvmd/override.yaml`, and reboot. After that, you can use remote wakeup by pressing any keyboard key or mouse button.
```yaml
otg:
remote_wakeup: true
```
??? question "Mass storage drive working (I can boot an image from PiKVM v2+), but keyboard/mouse does not"
In rare cases, some very buggy BIOSes does not like HID and Mass Storage in one USB device. You can either [disable Mass Storage](msd.md#disable-msd), or use [Arduino HID](arduino_hid.md) to physically separate them.
??? question "Buggy absolute mouse on Windows 98 as managed server"
How to fix:
* [v2+/OTG](mouse.md#fixing-the-absolute-mouse-on-windows-98).
* [Arduino HID](arduino_hid.md#fixing-the-usb-absolute-mouse-on-windows-98).
??? question "Big mouse latency on another Raspberry as managed server"
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.
## Web UI problems
??? question "Chrome Certificate Issue"
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:
<img src="chrome.png" alt="Chrome Blocking" width="400"/>
You can proceed by typing `thisisunsafe` and Chrome will then load the page.
??? question "Pressing ESC in full screen mode causes this to close"
Your browser does not support [keyboard lock](https://caniuse.com/mdn-api_keyboard_lock). Right now, only Chrome implements this.
??? question "I can't use this on iOS: the Web UI network indicator flashes yellow"
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`.
!!! danger
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.
??? question "The Web UI doesn't work properly in Firefox while it works fine in Chrome"
This might be related to your specific hardware combination or browser hardware acceleration. Try [disabling hardware acceleration in Firefox](https://support.mozilla.org/en-US/kb/hardware-acceleration-and-windowblinds-crash) or updating your GPU and chipset drivers.
??? question "Unexpected interruption while loading the image for Mass storage drive"
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`.
??? question "I can't copy clipboard contents from the server (the machine controlled via PiKVM) to the client"
The clipboard only works from the client to the server not vice versa. There is currently no way to do it.
## Hardware problems (Wi-Fi, ATX, etc)
??? question "No Wi-Fi on Raspberry Pi Zero W"
* If your device is unable to connect to the Wi-Fi network that you have setup check the 2.4 GHz Wi-Fi channel used by your Wi-Fi access point.
If channels 12 to 14 are used (some countries have banned these channels) try to use a channel between 1 and 11.
* Some Zeros contain a defective Wi-Fi chip. You can either return the device to the store, or try the [software workaround](https://github.com/pikvm/pikvm/issues/137).
??? question "LEDs/Switches does not work in ATX control"
Double check your wiring as per [the documentation](/README.md#setting-up-the-v2). Make sure you placed the relays (G3VM-61A1) in the correct orientation. The relays for switches (Power, Reset) have a different orientation than the ones for LEDs.
docs/faq/bios_glitch.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 921 KiB

docs/faq/chrome.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 315 KiB

docs/first_steps.md
+128
View File
@@ -0,0 +1,128 @@
# First steps
## Getting access to PiKVM
By default, PiKVM receives a dynamic IP address via DHCP.
??? example "Finding PiKVM in the network"
To determine the IP address of your PiKVM, use one of the following methods:
* **Common way:** Open the web interface of your router and find the list of issued IP addresses there. It depends on the router model.
* **Linux-only:** Use the command `arp-scan --localnet`.
* **Linux, MacOS, Windows:** Download and run [Angry IP Scanner](https://angryip.org).
For future examples, let's assume that your PiKVM has received the address **192.168.0.100**, which you have successfully detected using the instructions above. Then your device was assigned a hostname: **pikvm**.
??? example "Access to PiKVM Web Interface"
In most networks you should be able to reach PiKVM via any browser with the URL `https://192.168.0.100/` or `https://pikvm/`. Google Chrome (Chromium), Firefox and Safari work best. Microsoft Edge and Internet Explorer are not supported.
**The default user is `admin` and the password is also `admin`.** After logging in, you will get access to the menu with the main functions. Using the Web terminal, you can change system settings and passwords.
The latest versions of Chrome do not allow access to the page with a self signed certificate, which is used in PiKVM by default. You can proceed by typing `thisisunsafe` and Chrome will then load the page.
??? example "Access to PiKVM via SSH"
SSH is the most common remote access method in the Linux world. PiKVM is accessible via SSH. This method is used to manage the device:
* **Linux, MacOS:** Open any terminal application and run: `ssh root@192.168.0.100` or `ssh root@pikvm`.
* **Windows:** Use [PuTTY](https://www.putty.org/) for this.
**The default `root` password is `root`.**
??? danger "✮ ✮ ✮ CHANGE THE PASSWORDS! ✮ ✮ ✮"
PiKVM comes with the following default passwords:
* **Linux admin** (SSH, etc.): user `root`, password `root`.
* **PiKVM Web Interface**: user `admin`, password `admin`.
**These are two separate entities with independent accounts.** To change passwords, you will need to use the terminal (read below) access via SSH or Web Terminal. If you are using the Web Terminal, use the `su -` command to get root access (enter the root user password).
```
# rw
# passwd root
# kvmd-htpasswd set admin
# ro
```
## Configuring PiKVM
Most of the PiKVM settings are done through configuration files. All configuration changes must be made from under the `root` user (that is, the administrator).
!!! tip "Obtaining root access"
* If you have logged in via SSH, then most likely you are already `root`.
* To get `root` in the Web Terminal, use command `su -` and enter the root password.
The PiKVM memory card is mounted in read-only mode. It protects the filesystem from damage in case of sudden power outage. To edit any files and make changes, it is necessary to remount the file system to the read-write mode.
!!! tip "Enabling write mode"
* To enable write-mode, run command `rw` (under `root`).
* To disable it, run command `ro`.
* If you receive the message "Device is busy", perform `reboot`.
In this handbook, you will often find instructions for editing configuration files. The simplest and most beginner-friendly text editor is `nano`, but you can also use `vim`.
??? example "Editing files in the Web Terminal"
```
$ su -
# rw
# nano /etc/kvmd/override.yaml
# ro
```
-----
## Structure of configuration files
Most of the PiKVM configuration files are located in the `/etc/kvmd` directory.
The `/etc/kvmd/main.yaml` file defines the platform config and **you should never edit it**. To redefine system parameters use the file `/etc/kvmd/override.yaml`. All other files that are also not recommended for editing have read-only permissions.
In the `/etc/kvmd/meta.yaml` file you can specify some information regarding the host that this PiKVM manages.
!!! tip
A complete list of all parameters can be viewed using the `kvmd -m` command.
Files with the suffix `*.yaml` uses the [YAML syntax](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html)
and describes a parameter tree with key-value pairs of different types.
To define the parameters within one section, an indent of 4 spaces is used.
Comments starts with the `#` symbol.
!!! warning "Only 4 spaces should be used for indentation"
Be careful when editing YAML and follow this rule.
Invalid indentation or tabs instead of spaces will cause an error when starting the services.
??? example "Sections under the same keys should be merged"
* **Wrong:**
```yaml
kvmd:
gpio:
drivers: ...
kvmd:
gpio:
scheme: ...
```
* **Correct:**
```yaml
kvmd:
gpio:
drivers: ...
scheme: ...
```
-----
## What's next?
* Set up Internet access using [port forwarding](port_forwarding.md) or [Tailscale VPN](tailscale.md).
* Explore PiKVM features using the table of contents on the left.
* Join our [Discord](https://discord.gg/bpmXfz5) to contact the community and developers.
* Check out the [GitHub](https://github.com/pikvm) - PiKVM is a fully Open Source project!
-----
## FAQ and Troubleshooting
If you have any questions or run into problems, take a look at the [FAQ](faq.md).
Seriously, it's really useful! We've probably already found a solution for it :)
For any other help and support, you can contact us via the [Discord chat](https://discord.gg/bpmXfz5).
docs/flashing_hid.md
+364
View File
@@ -0,0 +1,364 @@
# Flashing the Arduino HID
## TTL Firmware (the default option)
This operation can be done using your RPi (except Pi Zero W). Here the common steps:
1. Disconnect the RESET wire from the Arduino board.
2. Connect the Arduino and RPi with a suitable USB cable.
3. Log in to the Raspberry Pi using SSH (`ssh root@<addr>` with password `root` by default) or using keyboard and monitor. The Raspberry Pi obtains the network address over DHCP.
4. Execute `rw`, add line `dtoverlay=spi0-1cs` to `/boot/config.txt` and perform `reboot`.
5. Upload the firmware (USB keyboard & mouse is used by default, on this step [you can choose PS/2 keyboard](arduino_hid.md#ps2-keyboard)):
```shell
[root@pikvm ~]# rw
[root@pikvm ~]# systemctl stop kvmd
[root@pikvm ~]# cp -r /usr/share/kvmd/hid ~
[root@pikvm ~]# cd ~/hid
[root@pikvm hid]# make
[root@pikvm hid]# make install
[root@pikvm hid]# reboot
```
6. Connect the RESET wire, disconnect the USB cable, and reboot the RPi.
With a Pi Zero W, you may consider building the firmware on a faster system and programming using USB or booting from another SD card and following the build steps using a clone of the [KVMD repo](https://github.com/pikvm/kvmd).
## SPI Firmware
This operation can be done using your Raspberry Pi without disconnecting any wires:
1. Connect the Arduino and RPi with a suitable USB cable.
2. Log in to the Raspberry Pi using SSH (`ssh root@<addr>` with password `root` by default) or using keyboard and monitor. The Raspberry Pi obtains the network address over DHCP.
3. Build and upload the firmware (USB keyboard & mouse is used by default)
```shell
[root@pikvm ~]# rw
[root@pikvm ~]# systemctl stop kvmd
[root@pikvm ~]# cp -r /usr/share/kvmd/hid ~
[root@pikvm ~]# cd ~/hid
[root@pikvm hid]# make spi
[root@pikvm hid]# make install
[root@pikvm hid]# reboot
```
## Common Errors
### Circuit Issues
#### Common - Reset Wire
Different pins are used for the reset wire but serve a similar function. For programming the TTL firmware over USB, the reset wire should be disconnected. When programming using SPI, the reset wire needs to be connected through a transistor circuit and connected to GPIO25 (pin 22 on the GPIO header)
#### SPI-specific Wiring
The 3v3, ground, Reset (GPIO25), MISO, MOSI, SCLK, and CS1 need to be connected appropriately. SPIO_CS0 and SPIO_CS1 can both be used but the default configuration uses SPIO_CS1 for the Arduino Microcontroller (CS0 is used for another device on the v3). These generally follow a block as follows:
```
Pin 0 2 4
2 0 0
.........GR.C.......
Row # 12345678901234567890
........3MMS........
Pin 0 1 3
1 7 9
```
The most common error is an "off-by-one" error where pins are shifted by a row. Some cases have non-standard GPIO layouts so please be careful when following these instructions using a case that has a modified pinout.
### Library Compatibility
On `make install` you may encounter the following error:
```
/root/.platformio/packages/tool-avrdude/avrdude: error while loading shared libraries: libtinfo.so.5: cannot open shared object file: No such file or directory
```
Create a symlink for this library:
```
# ln -s /usr/lib/libtinfo.so.6 /usr/lib/libtinfo.so.5
```
... and run `make install` again.
If you have any problems or questions, contact us using [Discord](https://discord.gg/bpmXfz5).
## Example SPI build + Flash
??? note "Here's an end-to-end build and flash of the SPI HID firmware using the default options as described above"
```
[root@pikvm ~]# rw
[root@pikvm ~]# systemctl stop kvmd
[root@pikvm ~]# cp -r /usr/share/kvmd/hid ~
[root@pikvm ~]# cd ~/hid
[root@pikvm hid]# make spi
make _build E=spi
make[1]: Entering directory '/root/hid'
rm -f .current
platformio run --environment spi
************************************************************************************************************************************
If you like PlatformIO, please:
- follow us on Twitter to stay up-to-date on the latest project news > https://twitter.com/PlatformIO_Org
- star it on GitHub > https://github.com/platformio/platformio
- try PlatformIO IDE for embedded development > https://platformio.org/platformio-ide
************************************************************************************************************************************
Processing spi (platform: atmelavr; board: micro; framework: arduino)
------------------------------------------------------------------------------------------------------------------------------------
Platform Manager: Installing atmelavr
Unpacking [####################################] 100%
Platform Manager: atmelavr @ 3.1.0 has been installed!
The platform 'atmelavr' has been successfully installed!
The rest of the packages will be installed later depending on your build environment.
Tool Manager: Installing platformio/toolchain-atmelavr @ ~1.50400.0
Downloading [####################################] 100%
Unpacking [####################################] 100%
Tool Manager: toolchain-atmelavr @ 1.50400.190710 has been installed!
Tool Manager: Installing platformio/framework-arduino-avr @ ~5.1.0
Downloading [####################################] 100%
Unpacking [####################################] 100%
Tool Manager: framework-arduino-avr @ 5.1.0 has been installed!
Tool Manager: Installing platformio/tool-avrdude @ *
Tool Manager: tool-avrdude @ 1.60300.200527 has been installed!
Tool Manager: Installing platformio/tool-scons @ ~4.40001.0
Unpacking [####################################] 100%
Tool Manager: tool-scons @ 4.40001.0 has been installed!
Verbose mode can be enabled via `-v, --verbose` option
patch([], [])
patch([], [])
CONFIGURATION: https://docs.platformio.org/page/boards/atmelavr/micro.html
PLATFORM: Atmel AVR (3.1.0) > Arduino Micro
HARDWARE: ATMEGA32U4 16MHz, 2.50KB RAM, 28KB Flash
DEBUG: Current (simavr) On-board (simavr)
PACKAGES:
- framework-arduino-avr 5.1.0
- tool-avrdude 1.60300.200527 (6.3.0)
- toolchain-atmelavr 1.50400.190710 (5.4.0)
LDF: Library Dependency Finder -> http://bit.ly/configure-pio-ldf
LDF Modes: Finder ~ chain, Compatibility ~ soft
Library Manager: Installing HID-Project @ 2.6.1
Library Manager: HID-Project @ 2.6.1 has been installed!
Library Manager: Installing git+https://github.com/Harvie/ps2dev#v0.0.3
git version 2.30.0
Cloning into '/root/hid/.platformio/.cache/tmp/pkg-installing-84arveu0'...
Note: switching to 'a043002178450772d72a58b0c42752a506fd4dea'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:
git switch -c <new-branch-name>
Or undo this operation with:
git switch -
Turn off this advice by setting config variable advice.detachedHead to false
Library Manager: ps2dev @ 0.0.3+sha.a043002 has been installed!
Library Manager: Installing digitalWriteFast @ 1.0.0
Library Manager: digitalWriteFast @ 1.0.0 has been installed!
Found 8 compatible libraries
Scanning dependencies...
Dependency Graph
|-- <HID-Project> 2.6.1
| |-- <HID> 1.0
|-- <ps2dev> 0.0.3+sha.a043002
|-- <digitalWriteFast> 1.0.0
|-- <SPI> 1.0
Building in release mode
patch -p1 -d /root/hid/.platformio/packages/framework-arduino-avr < patches/no-main.patch
patching file cores/arduino/main.cpp
<lambda>([], [])
patch -p1 -d /root/hid/.platformio/packages/framework-arduino-avr < patches/optional-usb-serial.patch
patching file cores/arduino/PluggableUSB.cpp
patching file cores/arduino/USBCore.cpp
<lambda>([], [])
patch -p1 -d /root/hid/.platformio/packages/framework-arduino-avr < patches/get-plugged-endpoint.patch
patching file cores/arduino/PluggableUSB.h
<lambda>([], [])
patch -p1 -d /root/hid/.pio/libdeps/spi/HID-Project < patches/shut-up.patch
patching file src/KeyboardLayouts/ImprovedKeylayouts.h
<lambda>([], [])
patch -p1 -d /root/hid/.pio/libdeps/spi/HID-Project < patches/no-hid-singletones.patch
patching file src/SingleReport/BootKeyboard.cpp
patching file src/SingleReport/BootKeyboard.h
patching file src/SingleReport/BootMouse.cpp
patching file src/SingleReport/BootMouse.h
patching file src/SingleReport/SingleAbsoluteMouse.cpp
patching file src/SingleReport/SingleAbsoluteMouse.h
<lambda>([], [])
patch -p1 -d /root/hid/.pio/libdeps/spi/HID-Project < patches/absmouse-win-fix.patch
patching file src/SingleReport/SingleAbsoluteMouse.cpp
<lambda>([], [])
Compiling .pio/build/spi/src/main.cpp.o
Compiling .pio/build/spi/src/spi.cpp.o
Compiling .pio/build/spi/lib2d3/HID/HID.cpp.o
Compiling .pio/build/spi/libd81/HID-Project/MultiReport/AbsoluteMouse.cpp.o
Compiling .pio/build/spi/libd81/HID-Project/MultiReport/Consumer.cpp.o
Archiving .pio/build/spi/lib2d3/libHID.a
Indexing .pio/build/spi/lib2d3/libHID.a
Compiling .pio/build/spi/libd81/HID-Project/MultiReport/Gamepad.cpp.o
Compiling .pio/build/spi/libd81/HID-Project/MultiReport/ImprovedKeyboard.cpp.o
Compiling .pio/build/spi/libd81/HID-Project/MultiReport/ImprovedMouse.cpp.o
Compiling .pio/build/spi/libd81/HID-Project/MultiReport/NKROKeyboard.cpp.o
Compiling .pio/build/spi/libd81/HID-Project/MultiReport/SurfaceDial.cpp.o
Compiling .pio/build/spi/libd81/HID-Project/MultiReport/System.cpp.o
Compiling .pio/build/spi/libd81/HID-Project/SingleReport/BootKeyboard.cpp.o
Compiling .pio/build/spi/libd81/HID-Project/SingleReport/BootMouse.cpp.o
Compiling .pio/build/spi/libd81/HID-Project/SingleReport/RawHID.cpp.o
Compiling .pio/build/spi/libd81/HID-Project/SingleReport/SingleAbsoluteMouse.cpp.o
Compiling .pio/build/spi/libd81/HID-Project/SingleReport/SingleConsumer.cpp.o
Compiling .pio/build/spi/libd81/HID-Project/SingleReport/SingleGamepad.cpp.o
Compiling .pio/build/spi/libd81/HID-Project/SingleReport/SingleNKROKeyboard.cpp.o
Compiling .pio/build/spi/libd81/HID-Project/SingleReport/SingleSystem.cpp.o
Compiling .pio/build/spi/libd81/HID-Project/port/samd.cpp.o
Compiling .pio/build/spi/libeaf/ps2dev/ps2dev.cpp.o
Archiving .pio/build/spi/lib822/libdigitalWriteFast.a
Indexing .pio/build/spi/lib822/libdigitalWriteFast.a
Compiling .pio/build/spi/lib519/SPI/SPI.cpp.o
.pio/libdeps/spi/ps2dev/src/ps2dev.cpp: In member function 'int PS2dev::keyboard_reply(unsigned char, unsigned char*)':
.pio/libdeps/spi/ps2dev/src/ps2dev.cpp:243:17: warning: variable 'enabled' set but not used [-Wunused-but-set-variable]
unsigned char enabled;
^
Archiving .pio/build/spi/libd81/libHID-Project.a
Archiving .pio/build/spi/libFrameworkArduinoVariant.a
Indexing .pio/build/spi/libFrameworkArduinoVariant.a
Indexing .pio/build/spi/libd81/libHID-Project.a
Compiling .pio/build/spi/FrameworkArduino/CDC.cpp.o
Archiving .pio/build/spi/lib519/libSPI.a
Archiving .pio/build/spi/libeaf/libps2dev.a
Indexing .pio/build/spi/lib519/libSPI.a
Indexing .pio/build/spi/libeaf/libps2dev.a
Compiling .pio/build/spi/FrameworkArduino/HardwareSerial.cpp.o
Compiling .pio/build/spi/FrameworkArduino/HardwareSerial0.cpp.o
Compiling .pio/build/spi/FrameworkArduino/HardwareSerial1.cpp.o
Compiling .pio/build/spi/FrameworkArduino/HardwareSerial2.cpp.o
Compiling .pio/build/spi/FrameworkArduino/HardwareSerial3.cpp.o
Compiling .pio/build/spi/FrameworkArduino/IPAddress.cpp.o
Compiling .pio/build/spi/FrameworkArduino/PluggableUSB.cpp.o
Compiling .pio/build/spi/FrameworkArduino/Print.cpp.o
Compiling .pio/build/spi/FrameworkArduino/Stream.cpp.o
Compiling .pio/build/spi/FrameworkArduino/Tone.cpp.o
Compiling .pio/build/spi/FrameworkArduino/USBCore.cpp.o
Compiling .pio/build/spi/FrameworkArduino/WInterrupts.c.o
Compiling .pio/build/spi/FrameworkArduino/WMath.cpp.o
.platformio/packages/framework-arduino-avr/cores/arduino/USBCore.cpp: In function 'bool ClassInterfaceRequest(USBSetup&)':
.platformio/packages/framework-arduino-avr/cores/arduino/USBCore.cpp:378:5: warning: unused variable 'i' [-Wunused-variable]
u8 i = setup.wIndex;
^
Compiling .pio/build/spi/FrameworkArduino/WString.cpp.o
Compiling .pio/build/spi/FrameworkArduino/abi.cpp.o
Compiling .pio/build/spi/FrameworkArduino/hooks.c.o
Compiling .pio/build/spi/FrameworkArduino/main.cpp.o
Compiling .pio/build/spi/FrameworkArduino/new.cpp.o
Compiling .pio/build/spi/FrameworkArduino/wiring.c.o
Compiling .pio/build/spi/FrameworkArduino/wiring_analog.c.o
Compiling .pio/build/spi/FrameworkArduino/wiring_digital.c.o
Compiling .pio/build/spi/FrameworkArduino/wiring_pulse.S.o
Compiling .pio/build/spi/FrameworkArduino/wiring_pulse.c.o
Compiling .pio/build/spi/FrameworkArduino/wiring_shift.c.o
Archiving .pio/build/spi/libFrameworkArduino.a
Indexing .pio/build/spi/libFrameworkArduino.a
Linking .pio/build/spi/firmware.elf
Building .pio/build/spi/firmware.hex
Checking size .pio/build/spi/firmware.elf
Advanced Memory Usage is available via "PlatformIO Home > Project Inspect"
RAM: [= ] 9.9% (used 253 bytes from 2560 bytes)
Flash: [=== ] 34.7% (used 9952 bytes from 28672 bytes)
=================================================== [SUCCESS] Took 56.86 seconds ===================================================
Environment Status Duration
------------- -------- ------------
spi SUCCESS 00:00:56.861
=================================================== 1 succeeded in 00:00:56.861 ===================================================
************************************************************************************************************************************
There is a new version 5.1.0 of PlatformIO available.
Please upgrade it via `platformio upgrade` or `pip install -U platformio` command.
Changes: https://docs.platformio.org/en/latest/history.html
************************************************************************************************************************************
echo -n spi > .current
make[1]: Leaving directory '/root/hid'
[root@pikvm hid]# make install
platformio run --environment spi --target upload
Processing spi (platform: atmelavr; board: micro; framework: arduino)
------------------------------------------------------------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
CONFIGURATION: https://docs.platformio.org/page/boards/atmelavr/micro.html
PLATFORM: Atmel AVR (3.1.0) > Arduino Micro
HARDWARE: ATMEGA32U4 16MHz, 2.50KB RAM, 28KB Flash
DEBUG: Current (simavr) On-board (simavr)
PACKAGES:
- framework-arduino-avr 5.1.0
- tool-avrdude 1.60300.200527 (6.3.0)
- toolchain-atmelavr 1.50400.190710 (5.4.0)
LDF: Library Dependency Finder -> http://bit.ly/configure-pio-ldf
LDF Modes: Finder ~ chain, Compatibility ~ soft
Found 8 compatible libraries
Scanning dependencies...
Dependency Graph
|-- <HID-Project> 2.6.1
| |-- <HID> 1.0
|-- <ps2dev> 0.0.3+sha.a043002
|-- <digitalWriteFast> 1.0.0
|-- <SPI> 1.0
Building in release mode
Checking size .pio/build/spi/firmware.elf
Advanced Memory Usage is available via "PlatformIO Home > Project Inspect"
RAM: [= ] 9.9% (used 253 bytes from 2560 bytes)
Flash: [=== ] 34.7% (used 9952 bytes from 28672 bytes)
Configuring upload protocol...
AVAILABLE: custom
CURRENT: upload_protocol = custom
Uploading .pio/build/spi/firmware.hex
avrdude: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.00s
avrdude: Device signature = 0x1e9587 (probably m32u4)
avrdude: NOTE: "flash" memory has been specified, an erase cycle will be performed
To disable this feature, specify the -D option.
avrdude: erasing chip
avrdude: reading input file ".pio/build/spi/firmware.hex"
avrdude: writing flash (9952 bytes):
Writing | ################################################## | 100% 2.78s
avrdude: 9952 bytes of flash written
avrdude: verifying flash memory against .pio/build/spi/firmware.hex:
avrdude: load data flash data from input file .pio/build/spi/firmware.hex:
avrdude: input file .pio/build/spi/firmware.hex contains 9952 bytes
avrdude: reading on-chip flash data:
Reading | ################################################## | 100% 2.33s
avrdude: verifying ...
avrdude: 9952 bytes of flash verified
avrdude: safemode: Fuses OK (E:CB, H:D8, L:FF)
avrdude done. Thank you.
=================================================== [SUCCESS] Took 7.54 seconds ===================================================
Environment Status Duration
------------- -------- ------------
spi SUCCESS 00:00:07.536
=================================================== 1 succeeded in 00:00:07.536 ===================================================
[root@pikvm hid]# reboot
```
docs/flashing_os.md
+63
View File
@@ -0,0 +1,63 @@
# Flashing the OS image
!!! warning "Micro-SD Card Requirements"
* Minimum **16 Gb**
* **Class 10** is strongly recommended
## Download the image
Download the appropriate SD card image. Select it based on the board, platform, and the video capture device you are using:
* [**PiKVM v3 HAT (Raspberry Pi 4)**](https://pikvm.org/images/v3-hdmi-rpi4.img.bz2) <sub>- [*sha1*](https://pikvm.org/images/v3-hdmi-rpi4.img.bz2.sha1)</sub>
* **DIY - Raspberry Pi 4, v2 platform:**
* [For HDMI-CSI bridge](https://pikvm.org/images/v2-hdmi-rpi4.img.bz2) <sub>- [*sha1*](https://pikvm.org/images/v2-hdmi-rpi4.img.bz2.sha1)</sub>
* [For HDMI-USB dongle](https://pikvm.org/images/v2-hdmiusb-rpi4.img.bz2) <sub>- [*sha1*](https://pikvm.org/images/v2-hdmiusb-rpi4.img.bz2.sha1)</sub>
* **DIY - Raspberry Pi ZeroW, v2 platform:**
* [For HDMI-CSI bridge](https://pikvm.org/images/v2-hdmi-zerow.img.bz2) <sub>- [*sha1*](https://pikvm.org/images/v2-hdmi-zerow.img.bz2.sha1)</sub>
Pre-compiled images are only available for the Raspberry Pi 4 and ZeroW. For all other cases, you will need to build the operating system yourself. But don't worry, it's [very simple](building_os.md).
## Flash the image
!!! tip
Choose the most suitable method for you
### Using Linux CLI
Decompress and flash the image. Be careful when choosing your device path:
```
# bzip2 -d v2-hdmi-rpi4.img.bz2
# dd if=v2-hdmi-rpi4.img of=/dev/mmcblkX
```
### Using balenaEtcher (Linux, MacOS and Windows)
1. Download and install [balenaEtcher](https://www.balena.io/etcher).
2. Decompress the image file using your favorite archive software. If you don't have one that supports `.bz2` files (on Windows for example) - [7-Zip](https://www.7-zip.org) is a great and free tool. *Do not try to flash a compressed image: either it will not work, or it will take a very long time.*
3. Run balenaEtcher:
<img src="balena-1.png" alt="drawing" height="250" />
4. Press **Flash from file** and select a **decompressed** image (a file with `.img` suffix):
<img src="balena-2.png" alt="drawing" height="250" />
5. Insert the memory card into the card reader. Press **Select target** and choose your memory card:
<img src="balena-3.png" alt="drawing" height="250" />
6. Press **Flash!** button.
<img src="balena-4.png" alt="drawing" height="250" />
7. Wait for the process to finish. Get yourself a coffee or do some stretching :) If an error occurs during flashing, repeat the process:
<img src="balena-5.png" alt="drawing" height="250" />
!!! tip
If balenaEtcher does not work for you and you continue to get failed bootup's, download the [Raspberry Pi Imager](https://www.raspberrypi.com/software) and use that instead. The general algorithm of actions is exactly the same: use a decompressed image, run Imager, select a device and flash the image there.
docs/flashing_os/balena-1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

docs/flashing_os/balena-2.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

docs/flashing_os/balena-3.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

docs/flashing_os/balena-4.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

docs/flashing_os/balena-5.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 63 KiB

docs/gpio.md
+445
View File
@@ -0,0 +1,445 @@
# GPIO
[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.
!!! warning
* Before using GPIO on **PiKVM v3 HAT**, carefully study [the purpose of its ports](v3.md#io-ports-and-jumpers).
* 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.
* **Careless usage of GPIO can damage your Raspberry Pi or components.**
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.
-----
## Basics
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.
* **Wrong:**
```yaml
kvmd:
gpio:
drivers: ...
kvmd:
gpio:
scheme: ...
```
* **Correct:**
```yaml
kvmd:
gpio:
drivers: ...
scheme: ...
```
-----
## 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 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.
!!! note
Each driver requires a unique name. Names surrounded by double underscore are system reserved and should not be used.
The only exception to this is the default GPIO driver with the name `__gpio__`, representing the physical GPIO interface of the Raspberry Pi. The configuration section for `__gpio__` is only required in your `/etc/kvmd/override.yaml` if you want to change the default settings. It can be omitted if you are fine with the defaults.
```yaml
kvmd:
gpio:
drivers:
# This example shows how the default __gpio__ driver settings can be changed. It can be omitted if you are fine with the defaults.
__gpio__: # Names surrounded by double underscore are system reserved
type: gpio # Refers to the plugin name handling the communication
# You can define another gpio driver for some reason
my_gpio:
type: gpio
# Example for a USB HID relay connected to PiKVM
relay:
type: hidrelay
device: /dev/hidraw0 # The path to the linux device
```
-----
## Scheme
The second part defines how the various driver channels are configured. Each channel has a unique name, a mode (`input` or `output`), a pin number, and a reference to the driver configured in the previous part.
!!! note
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 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.
| Parameter | Type | Allowed values | Default | Description |
|-----------------------------------|-----------|--------------------------|---------|-----------------------|
| `led1`, `button1`, `relay1`, etc. | `string` | `a-Z`, numbers, `_`, `-` | | A section for the named channel |
| `pin` | `integer` | `X >= 0` | | Refers to a GPIO pin or driver's pin/port |
| `mode` | `enum` | `input` or `output` | | Defines if a channel is used for input or output, may be limited by driver plugin |
| **Input only** | | | | |
| `debounce` | `float` | `x >= 0` | `0.1` | [Debounce](https://www.arduino.cc/en/Tutorial/Debounce) time in seconds. `0` for disable debounce |
| **Output only** | | | | |
| `switch` | `bool` | `true` or `false` | `true` | Enables or disables the switch mode on the channel (enabled by default). |
| `initial` | `nullable bool` | `true`, `false` or `null` | `false` | Defines the initial state of the switch upon boot, `null` for don't make changes (the last one does not supported by generic GPIO) |
| `inverted` | `bool` | `true` or `false` | `false` | Inverts the active logical level |
| `pulse` | | | | A section header to define switch pulse configuration |
| `delay` | `float` | `X >= 0` | `0.1` | Defines the pulse time in seconds, `0` for disable pulsing |
| `min_delay` | `float` | `X >= 0.1` | `0.1` |
| `max_delay` | `float` | `X >= 0.1` | `0.1` |
```yaml
kvmd:
gpio:
scheme:
# 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
led2:
pin: 16
mode: input
# Two outputs of RPi's GPIO
button1:
pin: 26 # GPIO pin number on the RPi
mode: output
switch: false # Disable switching, only pulse available
button2:
pin: 20
mode: output
switch: false
relay1: # Channel 1 of the relay /dev/hidraw0
pin: 0 # Numerating starts from 0
mode: output # Relays can't be inputs
initial: null # Don't reset the state to 0 when initializing and terminating KVMD
relay2: # Channel 2
pin: 1
mode: output
initial: null
pulse:
delay: 2 # Default pulse value
max_delay: 2 # The pulse interval can be between min_delay=0.1 (by default) and max_delay=2
```
-----
## View
This is the last part of the required configuration. It defines how the previous driver and channel configuration is rendered on the Web interface. Here's an example for the example configuration above:
```yaml
kvmd:
gpio:
view:
header:
title: Switches # The menu title
table: # The menu items are rendered in the form of a table of text labels and controls
- ["#Generic GPIO leds"] # Text starting with the sharp symbol will be a label
- [] # creates a horizontal separator and starts a new table
- ["#Test 1:", led1, button1] # Text label, one input, one button with text "Click"
- ["#Test 2:", led2, button2]
- []
- ["#HID Relays /dev/hidraw0"]
- []
- ["#Relay #1:", "relay1|Boop 0.1"] # Text label and button with alternative text
- ["#Relay #2:", "relay2|Boop 2.0"]
```
This will be rendered as:
<img src="gpio_menu.png" alt="drawing" />
Some rules and customization options:
* Text starting with the `#` symbol will be a label.
* To place a channel in a cell, use the name you defined in the scheme.
* Inputs are displayed as round LEDs.
* Outputs are displayed as a switch AND a button.
* If the switch mode is disabled, only a button will be displayed. If pulse is disabled, only a switch will be shown.
* To change the LED's color specify it after the channel name like `"led1|red"`. Available: `green`, `yellow` and `red`.
* To change title of the button, write some its name like `"relay1|My cool relay"`.
* Buttons and switches can request confirmation on acting. To do this write its name like `"relay1|confirm|My cool relay"`. The third argument with a title is required in this case.
-----
## Hardware modules and pseudo-drivers
### Raspberry's GPIO
??? note "Click to view"
The driver `gpio` provides access to regular GPIO pins with input and output modes. It uses `/dev/gpiochip0` and the libgpiod library to communicate with the hardware. Does not support saving state between KVMD restarts (meaning `initial=null`).
You can use the [interactive scheme](https://pinout.xyz/) when selecting the pins to use. Please note that when selecting a pin for a channel, you need to use a logical number instead of a physical number. That is, if you want to use a physical pin with the number 40, the channel must have the number 21 corresponding to the logical GPIO21.
Channels should not use duplicate pins. You can also not use already used pins. To see which pins are currently used, run the command `gpioinfo`.
### USB HID Relay
??? note "Click to view"
The driver `hidrelay` provides access to cheap managed [USB HID relays](http://vusb.wikidot.com/project:driver-less-usb-relays-hid-interface) that can be found on AliExpress. This driver does not support input mode, only output. To use it, you need to specify the path to the device file (like `/dev/hidraw0`) using the `device` parameter.
Additionally, we recommend to configure access rights and static device name using [UDEV rules](https://wiki.archlinux.org/index.php/udev). For example, create `/etc/udev/rules.d/99-kvmd-extra.rules`:
```
KERNEL=="hidraw[0-9]*", SUBSYSTEMS=="usb", ATTRS{idVendor}=="16c0", ATTRS{idProduct}=="05df", GROUP="kvmd"
```
Channels should not use duplicate physical numbers. The driver supports saving state between KVMD restarts (meaning `initial=null`).
### ezCoo KVM switch
??? note "Click to view"
You can use GPIO to control KVM port switching. This usually requires the use of relays and buttons, but for the [ezCoo switch](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
??? note "Click to view"
The driver `ipmi` provides the ability to send IPMI commands (on, off, reset) and show the power status of the remote host. In fact, this is not a hardware driver, but something like a pseudo-GPIO. Each "pin" is actually responsible for a specific IPMI operation of `ipmitool`:
| Pin | Type | Command |
|-----|----------|---------|
| `0` | `input` | `ipmitool ... power status`, can be used to draw the LED in the menu |
| `1` | `output` | `ipmitool ... power on`, sends the `on` command (and only this), so like all other outputs it should be a button |
| `2` | `output` | `ipmitool ... power off` |
| `3` | `output` | `ipmitool ... power cycle` |
| `4` | `output` | `ipmitool ... power reset` |
| `5` | `output` | `ipmitool ... power diag` |
| `6` | `output` | `ipmitool ... power soft` |
You are supposed to define one driver per host:
```yaml
kvmd:
gpio:
drivers:
my_server:
type: ipmi
host: myserver.local
user: admin
passwd: admin
scheme:
my_server_status:
driver: my_server
pin: 0
mode: input
my_server_on:
driver: my_server
pin: 1
mode: output
switch: false
my_server_off:
driver: my_server
pin: 2
mode: output
switch: false
view:
table:
- [my_server_status, "my_server_on|On", "my_server_off|Off"]
```
### Wake-on-LAN
??? note "Click to view"
The driver `wol` provides a simple generator of Wake-on-LAN packages. One driver and one output are generated for one host if a [simplified configuration method](wol.md) is used. However, you can define multiple drivers if you want to manage different hosts. One driver controls one host, and can only be used as an output. Pin numbers are ignored.
```yaml
kvmd:
gpio:
drivers:
wol_server1:
type: wol
mac: ff:ff:ff:ff:ff:f1
wol_server2:
type: wol
mac: ff:ff:ff:ff:ff:f2
ip: 192.168.0.100
port: 9
scheme:
wol_server1:
driver: wol_server1
pin: 0
mode: output
switch: false
wol_server2:
driver: wol_server2
pin: 0
mode: output
switch: false
view:
table:
- ["#Server 1", "wol_server1|Send Wake-on-LAN"]
- ["#Server 2", "wol_server2|Send Wake-on-LAN"]
```
### PWM
??? note "Click to view"
The `pwm` driver allows you to use [some GPIO pins](https://pinout.xyz/pinout/pwm) on the Raspberry Pi for PWM.
Here the small example with servo control:
1. Add to `/boot/config.txt`:
```
dtoverlay=pwm
```
2. Create `/etc/udev/rules.d/99-kvmd-pwm.rules`:
```
SUBSYSTEM=="pwm*", ACTION=="add", RUN+="/bin/chgrp -R kvmd /sys%p", RUN+="/bin/chmod -R g=u /sys%p"
SUBSYSTEM=="pwm*", ACTION=="change", ENV{TRIGGER}!="none", RUN+="/bin/chgrp -R kvmd /sys%p", RUN+="/bin/chmod -R g=u /sys%p"
```
3. Connect Servo motor like SG90 PWM connection to RPi GPIO18, +5V and GND to a 5V and GND pin on header:
4. Add to /etc/kvmd/override.yaml
```yaml
kvmd:
gpio:
drivers:
servo1:
type: pwm
chip: 0 # PWM Chip Number
period: 20000000 # Servo Motor SG90 Period in nano-seconds
duty_cycle_push: 1500000 # Servo Motor SG90 duty_cycle for pushing button
duty_cycle_release: 1000000 # Servo Motor SG90 duty_cycle for releasing button
scheme:
short_press:
driver: servo1
pin: 0 # Pin number is the PWM channel number on the PWM Chip
mode: output
switch: false
pulse:
delay: 0.5
max_delay: 2
long_press:
driver: servo1
pin: 0
mode: output
switch: false
pulse:
delay: 2
max_delay: 2
extra_long_press:
driver: servo1
pin: 0
mode: output
switch: false
pulse:
delay: 10
max_delay: 20
view:
header:
title: Controls
table:
- ["#Servo - Short Press", "short_press|Press"]
- ["#Servo - Long Press", "long_press|Press"]
- ["#Servo - Extra Long Press", "extra_long_press|Press"]
```
### Servo
??? note "Click to view"
The `servo` module is built on top of the `pwm` module and allows user to define angles instead of `duty_cyles` to control a PWM enabled servo motor like SG90. When the button is pressed the servo motor moves to an angle defined by `angle_push` and when button is released it moves back to `angle_release`. In the example configuration for a [cheap 5V SG90 Servo](https://www.ebay.co.uk/itm/184555802744), the motor moves to an angle of 45 degrees when button is pressed and moves back to 20 degress when released.
To use Servo motors in PiKVM you need to follow steps 1-3 for [PWM Module](#pwm) and then use the following configuration.
Add to `/etc/kvmd/override.yaml`:
```yaml
kvmd:
gpio:
drivers:
servo1:
type: servo
chip: 0 # PWM Chip Number
period: 20000000 # Servo Motor SG90 Period in nano-seconds
duty_cycle_min: 350000 # Servo Motor SG90 duty_cycle for -90 degrees
duty_cycle_max: 2350000 # Servo Motor SG90 duty_cycle for +90 degrees
angle_max: 90 # Servo Motor SG90 angle at duty_cycle_max
angle_min: -90 # Servo Motor SG90 angle at duty_cycle_min
angle_push: 45 # Servo Motor SG90 angle to push button
angle_release: 20 # Servo Motor SG90 angle to release button
scheme:
short_press:
driver: servo1
pin: 0 # Pin number is the PWM channel number on the PWM Chip
mode: output
switch: false
pulse:
delay: 0.5
max_delay: 2
long_press:
driver: servo1
pin: 0
mode: output
switch: false
pulse:
delay: 2
max_delay: 2
extra_long_press:
driver: servo1
pin: 0
mode: output
switch: false
pulse:
delay: 10
max_delay: 20
view:
header:
title: Controls
table:
- ["#Servo - Short Press", "short_press|Press"]
- ["#Servo - Long Press", "long_press|Press"]
- ["#Servo - Extra Long Press", "extra_long_press|Press"]
```
### Philips Hue
??? note "Click to view"
The `hue` module can control [smartplugs](https://shop.ledvance.com/en/products/smart-plug-eu) and lamps over Philips Hue Bridge API. In general the plugin can switch any device on/off which is connected to the bridge. To use it you will need API token aka username:
1. Open `http://bridge/debug/clip.html`.
2. In the URL: Field type `/api/`.
3. In the Message Body: Field type: `{"devicetype": "pikvm"}`.
4. Hit the Get Button.
5. As the Response you become the Username: `{"success": {"username": "apiusername"}`.
Example:
```yaml
kvmd:
gpio:
drivers:
hue:
type: hue
url: http://bridge
token: YG-xxxxxxxxxxxx
scheme:
plug_button:
driver: hue
pin: 32
mode: output
initial: null
switch: true
pulse:
delay: 0
plug_led:
driver: hue
pin: 32
mode: input
view:
table:
- ["plug_led", "plug_button"]
```
docs/gpio/gpio_menu.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

docs/index.md
+21
View File
@@ -0,0 +1,21 @@
# PiKVM Handbook
**Welcome to the [PiKVM](https://pikvm.org) Handbook** - a complete documentation of Open and cheap DIY IP-KVM based on Raspberry Pi. Here you will find comprehensive information about all aspects of the operation of PiKVM, get answers to your most difficult questions and be able to solve the problems that have arisen.
## Where to start?
* **Learn about the [basics of working with PiKVM](first_steps.md).**
* If you are a happy **PiKVM v3 HAT** user then we have a [special guide for you](v3.md).
* **Explore the features of PiKVM** using the site's table of contents.
* **If you encounter a problem**, take a look at the **[FAQ](faq.md)**, but if nothing helped, contact our **[Discord chat](https://discord.gg/bpmXfz5)** - experienced users and the PiKVM team will definitely help you.
## Links
* Official website: **https://pikvm.org**
* Our GitHub: **https://github.com/pikvm**
* Discord server: [![Discord](https://img.shields.io/discord/580094191938437144?logo=discord)](https://discord.gg/bpmXfz5)
* Subreddit: [![Reddit](https://img.shields.io/badge/reddit-join-orange?logo=reddit)](https://www.reddit.com/r/pikvm)
docs/ipmi.md
+102
View File
@@ -0,0 +1,102 @@
# IPMI & Redfish
!!! info
This page is about the server-side emulation (if you want to manage PiKVM using ipmitool or so). If you want to use the PiKVM Web UI to manage the server using IPMI (that is, as an IPMI client), see [GPIO functions with IPMI plugin](gpio.md).
## IPMI BMC
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 PiKVM. Its advantage is that it is supported by many enterprise systems.
!!! warning
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 BMC follow these steps:
1. Switch the filesystem to the RW-mode:
```
# rw
```
2. Setup IPMI account in file `/etc/kvmd/ipmipasswd`.
3. Enable `kvmd-ipmi` daemon:
```
# systemctl enable --now kvmd-ipmi
```
4. Switch the filesystem back to the RO:
```
# ro
```
5. Here some examples (on the remote PC):
```
$ ipmitool -I lanplus -U admin -P admin -H pikvm power status
$ ipmitool -I lanplus -U admin -P admin -H pikvm power on
```
## IPMI SoL
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.
!!! warning
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 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`:
```yaml
ipmi:
sol:
device: /dev/ttyUSB0 # Path of your USB-COM adapter
speed: 115200
```
After enabling `kvmd-ipmi`, all requests that it receives over the network regarding the COM port will be forwarded to your server. For example:
```
$ ipmitool -I lanplus -U admin -P admin -H pikvm sol activate
```
## Redfish
[Redfish](https://www.dmtf.org/standards/redfish) is a more modern server management protocol designed to replace IPMI.
It is based on HTTP and fixes many security issues. If possible, we recommend using it instead of IPMI, or using the [KVMD API](api.md).
There're not special actions required to use Redfish. In addition, Redfish will use regular PiKVM credentials.
But for systems that have been upgraded to KVMD 2.0 (not a clean image installation), you will probably need to edit
the `/etc/kvmd/nginx/kvmd.ctx-server.conf` file to add these lines at the end:
```nginx
location /redfish {
proxy_pass http://kvmd;
include /etc/kvmd/nginx/loc-proxy.conf;
auth_request off;
}
```
!!! info Don't be confused by the parameter `auth_request off`. KVMD performs authorization on its own. The only open HTTP entrypoint is `/redfish/v1`, which returns a static document and does not change the state of the PiKVM. It's safe.
If there is a file in your system after the update `/etc/kvmd/nginx/kvmd.ctx-server.conf.pacnew` you can just move it:
```
# mv /etc/kvmd/nginx/kvmd.ctx-server.conf.pacnew /etc/kvmd/nginx/kvmd.ctx-server.conf
```
!!! warning
Be careful not to lose your local changes if you have done anything with this file before.
To access the Redfish API, use HTTP Basic Auth. Also you can use the [redfishtool](https://github.com/DMTF/Redfishtool):
```
$ redfishtool -S Never -r pikvm root
$ redfishtool -S Never -u admin -p admin -r pikvm Systems
$ redfishtool -S Never -u admin -p admin -r pikvm Systems reset ForceOff
```
docs/mouse.md
+90
View File
@@ -0,0 +1,90 @@
# Mouse
There are two modes of pointer device: absolute and relative.
In absolute mode, the input device transmits the exact coordinates `(X,Y)` where the cursor should be moved. This is how touchscreens or drawing tablets work.
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, 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 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 [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.
## Relative mouse on v2+ platform (OTG HID)
### Dual mode
Using dual mouse mode you can switch between the absolute and relative mouse in the `System` menu without reloading.
This is more convenient, but for compatibility reasons it is disabled by default. To enable it, do the following:
1. Switch filesystem to RW-mode using command `rw`.
2. Edit `/etc/kvmd/override.yaml` and add these lines:
```yaml
kvmd:
hid:
mouse_alt:
device: /dev/kvmd-hid-mouse-alt
```
3. Perform `reboot`. After that reboot your PC.
### Single relative mode
1. Switch filesystem to RW-mode using command `rw`.
2. Edit `/etc/kvmd/override.yaml` and add these lines:
```yaml
kvmd:
hid:
mouse:
absolute: false
```
3. Perform `reboot`. After that reboot your PC.
4. If the mouse is still not detected by the BIOS/UEFI, try disabling horizontal scrolling to achieve the maximum compatibility:
```yaml
kvmd:
hid:
mouse:
absolute: false
horizontal_wheel: false
```
5. Don't forget to perform `reboot`.
## Relative mouse on v0 platform (Arduino HID)
Mode switching for [Arduino HID](arduino_hid.md) can be performed on-the-fly starting with KVMD 2.6 and the corresponding firmware. No additional actions are required.
## Fixing the absolute mouse on Windows 98
Due to an ancient buggy driver, the absolute mouse on Windows 98 moves only within the upper-left quarter of the screen. To fix this, you need to activate some magic workaround in `/etc/kvmd/override.yaml`:
```yaml
kvmd:
hid:
mouse:
absolute_win98_fix: true
```
... and run `systemctl restart kvmd`.
docs/msd.md
+284
View File
@@ -0,0 +1,284 @@
# Mass Storage Drive
## Basics
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:
!!! info "The size of the CD-ROM image is limited to 2.2 GB"
This is a [limitation](https://github.com/pikvm/pikvm/issues/322) of the Linux kernel, which currently cannot emulate a DVD.
To use a larger boot image, use Flash emulation. If this is not possible (the image does not support Flash, for example, for Windows),
use [this](#create-a-microsoft-windows-based-flash-disk-image) recipe.
!!! info "Changing the media type between CD-ROM and Flash is possible only when the device is reconnected"
For PiKVM v3 HAT, this can be done using the switch `System -> Connect main USB`.
In this case, the **media type is determined at the time of connecting the image, and not by clicking on the switch**.
The switch affects the settings of the future connection. For non-v3 devices,
you need to either reboot your server or otherwise reinitialize the connection.
-----
## Disable MSD
To disable mass storage emulation altogether, you can place the following piece of configuration into `/etc/kvmd/override.yaml`:
``` yaml
kvmd:
msd:
type: disabled
```
## Upload images manually (without Web UI)
1. Remount internal storage to rw (read-write):
```
# 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 PiKVM that the uploaded image is okay and can be used. For example:
```
/var/lib/kvmd/msd/meta/ubuntu-18.04.4-desktop-amd64.iso.complete
```
4. Remount internal storage back to ro (read-only):
```
# kvmd-helper-otgmsd-remount ro
```
-----
## Multiple and writable drives
Unless explicitly [disabled](#disable-msd) by default, PiKVM creates only one drive for Mass Storage emulation.
However, you can create additional drives and manage them manually via the terminal.
This is useful if you want to boot the server from a ISO CD (specified in the web interface), then connect a virtual flash drive
to the server and download some files from to PiKVM from it.
!!! info
The presence of an additional Mass Storage Drive should not interfere with the boot, but for reasons of compatibility paranoia, this is disabled by default. We recommend setting up the drives in advance, making sure that booting from the ISO CD is still working, and then using the drives as needed.
### How to enable extra drives
1. Switch the root filesystem to `rw` mode.
2. Edit `/etc/kvmd/override.yaml` and add these lines:
``` yaml
otg:
devices:
drives:
enabled: true # Set it to true to enable
count: 1 # +1 drive, default value
default: # Default configuration for the all extra drives
cdrom: false # Default value (false for the generic flash drive)
rw: false # Read-only by default
```
If you specify `count: N`, you will create `N` additional drives configured the same way, as described in the `default` section.
3. Perform `reboot`.
### How to create RW flash drive
1. Switch the root filesystem to `rw` mode:
```
# rw
```
2. Create the empty image file of the desire size (1Gb in this example).
```
# dd if=/dev/zero of=/root/flash.img bs=1M count=1000 status=progress
```
3. Connect it to the drive 1:
```
# kvmd-otgmsd -i 1 --set-rw=1 --set-cdrom=0 --set-image=/root/flash.img
```
After that you will have access to the flash drive from the server. **Drive 0 represents a drive that is controlled via a web interface and API. Don't use it with kvmd-otgmsd if you don't know exactly what you're doing.**
4. View the driver state:
```
# kvmd-otgmsd -i 1
Image file: /root/flash.img
CD-ROM flag: no
RW flag: yes
```
5. To disable the flash drive and view the files on it from the KVM, run:
```
# kvmd-otgmsd -i 1 --unlock --eject
```
**This command will interrupt the current IO operation on ALL DRIVES** including the one that is managed via the web interface. The same result is achieved by clicking the disable media button in the web interface. Right now, the Linux kernel does not allow to distinguish between internal threads that manage different drives. It is recommended to eject the media when you know that this will not cause problems for the other media.
6. Don't forget to remount the root filesystem to read-only mode:
```
# ro
```
7. You can download the resulting image via SCP or mount it as a loop device on the PiKVM.
-----
## Create a Windows based Flash disk image
An alternative version of this can be found below that does not require a physical usb flash
This procedure will create a disk image of a USB stick. This is mostly required for Windows based images since they are larger than the CDROM based limit of 2.2GB.
You can create a bootable USB stick with the normal Microsoft tools, e.g. Media Creation Tool.
Creating a bootable USB stick can also be made from an ISO file with other tools like Rufus.
Without resizing, the full size of the USB stick will be used, so keep the stick as small as possible (e.g. 4GB or 8GB) but still large enough for all Windows files. The Media Creation tool will tell you what the minimum size is.
Before creating the image file, you can use a tool like "EaseUS Partition Master Free" or "GParted" to resize the main FAT32 partition on the USB stick. This will save space on PiKVM.
You can also perform these steps on a separate unix machine and transfer the image over to pikvm with e.g. SCP.
Or, on Windows you could use a program like PassMark ImageUSB (only for full USB size images) or 'dd' for Windows to create the image. Then use WinSCP to transfer the image over to PiKVM.
Once you have the desired USB stick perform the following on the RPi to create the image directly to the PiKVM image storage folder.
1. Insert Windows based USB stick into Pi4, generated with Microsoft USB creation tool. SSH to PiKVM as root.
```
# dmesg
[ 3025.025401] usb-storage 2-1:1.0: USB Mass Storage device detected
[ 3025.038911] scsi host0: usb-storage 2-1:1.0
[ 3026.132248] scsi 0:0:0:0: Direct-Access Kingston DataTraveler 3.0 PMAP PQ: 0 ANSI: 6
[ 3026.771425] sd 0:0:0:0: [sda] 15360000 512-byte logical blocks: (7.86 GB/7.32 GiB)
[ 3026.790276] sd 0:0:0:0: [sda] Write Protect is off
[ 3026.802530] sd 0:0:0:0: [sda] Mode Sense: 23 00 00 00
[ 3026.804450] sd 0:0:0:0: [sda] No Caching mode page found
[ 3026.814082] sd 0:0:0:0: [sda] Assuming drive cache: write through
[ 3026.908712] sda: sda1
[ 3026.922794] sd 0:0:0:0: [sda] Attached SCSI removable disk
[root@pikvm ~]#
```
USB devices shows as `sda`. We will use `sda1` as the Windows partition.
2. mount msd folder as read/write
```
# kvmd-helper-otgmsd-remount rw
```
3. Create image of USB data PARTITION to an image file, this will take some time, in this case about 12 minutes (RPi4).
```
# dd if=/dev/sda1 of=/var/lib/kvmd/msd/images/windows10-2004.bin bs=8M status=progress
4458545152 bytes (4.5 GB, 4.2 GiB) copied, 736 s, 6.1 MB/s
531+1 records in
531+1 records out
4458545152 bytes (4.5 GB, 4.2 GiB) copied, 736.213 s, 6.1 MB/s
```
4. Correct ownership of new image and make sure the website reports the file as complete (pay attention to the different folder).
```
# chown kvmd:kvmd /var/lib/kvmd/msd/images/windows10-2004.bin
# touch /var/lib/kvmd/msd/meta/windows10-2004.bin.complete
```
5. Remount msd folder as read only
```
# kvmd-helper-otgmsd-remount ro
```
6. On PiKVM webpage, under Storage select the new image and connect it in Drive Mode: Flash to the server.
Boot the server and select boot device like you normally would.
E.g. in a AMI BIOS the boot device is called "Linux File-CD Gadget 0504".
-----
## Create a drive image on macOS
1. Open Disk Utility.
2. `File > New Image > Blank Image`.
3. Save As: `pikvm-image.dmg`. Name: `pikvm-image`. Size: 100 MB (or whatever size you want). Format: `MS-DOS (FAT)`. Partitions: `Single partition - GUID Partition Map`. Image Format: `read/write disk image`.
4. Click Save.
5. The drive will automatically be mounted.
6. Copy files (such as BIOS updates) onto the new image (via terminal or drag and drop in Finder).
7. Eject image.
8. Upload image to PiKVM interface under "Drive".
9. Select Drive Mode: `Flash` and then `Connect drive to Server`.
You should be able to then mount it locally on the server, or reboot the device to do things like BIOS updates.
-----
## An alternative to making a Windows boot image that does not require a physical usb flash drive
* Physical USB is not needed but external system is mandatory.
* Create Ventoy image (on Ubuntu x86 machine) (Unaware of a windows version).
```
dd if=/dev/zero of=ventoy.img bs=1M count=4700 status=progress
```
* This makes a ventoy.img file, I would name this what it is EG: `ventoy_win10.img`
* At the same time, download Media Creation Tool and select iso
* On the Ubuntu machine
* At the time of this, it was 1.0.51, change to latest version
```
wget https://github.com/ventoy/Ventoy/releases/download/v1.0.51/ventoy-1.0.51-linux.tar.gz
tar zxvf ventoy-1.0.51-linux.tar.gz
sudo losetup -f ventoy.img
sudo losetup -l | grep ventoy (To locate which loop device was used)
sudo losetup /dev/loopXX ventoy.img
sudo sh ~/ventoy-1.0.51/Ventoy2Disk.sh -i /dev/loopXX (This will make a loopXXp1 and a loopXXp2 and will format both partitions
cd /media/XXX (Usually your login)
mkdir ventoy
sudo mount /dev/loopXXp1 /media/XXX/ventoy
```
* Either cp/scp over the .iso you downloaded from the Media tool or use a NFS mount
```
sudo cp windows.iso /media/XXX/ventoy
sudo umount /dev/loopXX
sudo losetup -d /dev/loopXX
```
ssh into the Ubuntu system (Or whatever OS you are using)
* On PiKVM
```
cd /var/lib/kvmd/msd
mount -o remount,rw .
```
* On Ubuntu
```
scp ventoy.img root@pikvm:/var/lib/kvmd/msd/images
```
* On PiKVM
```
touch /var/lib/kvmd/msd/meta/ventoy.img.complete
```
* Mount `ventoy.img` as normal flash and select the PiKVM boot device, it should popup with the VenToy logo with the window.iso as a selection
docs/multiport.md
+37
View File
@@ -0,0 +1,37 @@
# Multiport KVM over IP
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, 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 (PiKVM supports this configuration).
!!! warning
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.
## List of tested KVMs
Here the status is:
* ✔ - Everything is working as expected. There may be some subtleties.
* ☹ - Something wrong.
* ✘ - The keyboard or mouse does not work at all, the switch loses the image, etc.
| 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 PiKVM](ezcoo.md) - 4 Port is the ONLY supported KVM, 2 Port does not work the same and is not supported |
| [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) |
| [XH-HK4401 4-port HDMI USB KVM Switch](https://www.aliexpress.com/item/4000849336545.html) | ✔ | [Using with PiKVM](xh_hk4401.md) - USB MSD works, requires the HDMI backpower solutions found below |
| [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 |
Limitations:
* HDMI backpower solutions:
* See [here](https://github.com/pikvm/pikvm/issues/128)
* See [here](https://github.com/pikvm/pikvm/issues/382) - Advanced soldering required
* [This loop capture device](https://www.amazon.com/gp/product/B08B346353)
* v3 HAT v3.3 (Kickstarter model and later) also takes care of the back power issue
* MSD workaround (will not work OOB)
* RPi4 OTG needs to be in the KB port for mouse and KB funtionality, ZeroW is required and needs to be connected to the HUB port for HK switching and MSD functionality - ✔**KNOWN WORKING**✔
* See [here](https://github.com/pikvm/pikvm/issues/371) - Advanced soldering required - allows use of GPIO menu to change input
docs/port_forwarding.md
+11
View File
@@ -0,0 +1,11 @@
# Port forwarding
If your ISP has provided you with an external IP address for the router, you can configure port forwarding to access PiKVM.
!!! warning
[Change passwords](first_steps.md#getting-access-to-pikvm) before opening access to PiKVM from the outside Internet
* The Web UI runs on port `80` and `443`.
* [VNC](vnc.md) (if you use it) runs on port `5900`.
If you don't have an external IP address, then we recommend trying [Tailscale VPN](tailscale.md).
docs/prometheus.md
+102
View File
@@ -0,0 +1,102 @@
# Prometheus metrics
[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).
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:
```yaml
scrape_configs:
- job_name: "pikvm"
metrics_path: "/api/export/prometheus/metrics"
basic_auth:
username: admin
password: admin
static_configs:
- targets: ["https://pikvm"]
tls_config:
insecure_skip_verify: true # For self-signed certificate
```
## Output example
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).
```bash
$ curl -k -HX-KVMD-User:admin -HX-KVMD-Passwd:admin https://pikvm/api/export/prometheus/metrics
# TYPE pikvm_atx_enabled gauge
pikvm_atx_enabled 1
# TYPE pikvm_atx_power gauge
pikvm_atx_power 0
# TYPE pikvm_gpio_input_online_led1 gauge
pikvm_gpio_input_online_led1 0
# TYPE pikvm_gpio_input_state_led1 gauge
pikvm_gpio_input_state_led1 0
# TYPE pikvm_gpio_input_online_led2 gauge
pikvm_gpio_input_online_led2 0
# TYPE pikvm_gpio_input_state_led2 gauge
pikvm_gpio_input_state_led2 0
# TYPE pikvm_gpio_output_online_button1 gauge
pikvm_gpio_output_online_button1 0
# TYPE pikvm_gpio_output_state_button1 gauge
pikvm_gpio_output_state_button1 0
# TYPE pikvm_gpio_output_online_button2 gauge
pikvm_gpio_output_online_button2 0
# TYPE pikvm_gpio_output_state_button2 gauge
pikvm_gpio_output_state_button2 0
# TYPE pikvm_gpio_output_online_relay1 gauge
pikvm_gpio_output_online_relay1 0
# TYPE pikvm_gpio_output_state_relay1 gauge
pikvm_gpio_output_state_relay1 0
# TYPE pikvm_gpio_output_online_relay2 gauge
pikvm_gpio_output_online_relay2 0
# TYPE pikvm_gpio_output_state_relay2 gauge
pikvm_gpio_output_state_relay2 0
# TYPE pikvm_hw_temp_cpu gauge
pikvm_hw_temp_cpu 36.511
# TYPE pikvm_hw_temp_gpu gauge
pikvm_hw_temp_gpu 35.0
# TYPE pikvm_hw_throttling_freq_capped_now gauge
pikvm_hw_throttling_freq_capped_now 0
# TYPE pikvm_hw_throttling_freq_capped_past gauge
pikvm_hw_throttling_freq_capped_past 0
# TYPE pikvm_hw_throttling_throttled_now gauge
pikvm_hw_throttling_throttled_now 0
# TYPE pikvm_hw_throttling_throttled_past gauge
pikvm_hw_throttling_throttled_past 0
# TYPE pikvm_hw_throttling_undervoltage_now gauge
pikvm_hw_throttling_undervoltage_now 0
# TYPE pikvm_hw_throttling_undervoltage_past gauge
pikvm_hw_throttling_undervoltage_past 0
# TYPE pikvm_hw_throttling_raw_flags gauge
pikvm_hw_throttling_raw_flags 0
* Connection #0 to host localhost left intact
```
docs/stl/v3.2/case_a.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 65 KiB

docs/stl/v3.2/case_a.stl
BIN
View File
Binary file not shown.
docs/stl/v3.2/case_a_no_oled.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 58 KiB

docs/stl/v3.2/case_a_no_oled.stl
BIN
View File
Binary file not shown.
docs/stl/v3.2/case_b.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 57 KiB

docs/stl/v3.2/case_b.stl
BIN
View File
Binary file not shown.
docs/stl/v3.2/case_b_no_aum.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 56 KiB

docs/stl/v3.2/case_b_no_aum.stl
BIN
View File
Binary file not shown.
docs/stl/v3.2/index.md
+44
View File
@@ -0,0 +1,44 @@
# 3D printable case for PiKVM v3.2 HAT
When printing the case, you can choose the following options:
* The presence or absence of an OLED screen (used to display the IP address and other information).
* The presence or absence of holes for the AUM v3.3 (Advanced USB Module, most likely you don't have it).
## Buy options
* [Small 5v fan](https://www.amazon.com/GeeekPi-Raspberry-30x30x7mm-Brushless-Retroflag/dp/B07C9C99RM) **strongly recommended** to avoid overheating in the case.
* [I2C OLED screen](https://www.amazon.com/Pieces-Display-Module-SSD1306-Screen/dp/B08TLXYKS6).
## Building
![type:video](https://www.youtube.com/embed/-SRL92VJ870)
## Parts
### The front part
**Choose ONE of them.**
| Variant | Description |
|---------|-------------|
| <img src="case_a_no_oled.png" width=200 /> | [The front part](case_a_no_oled.stl) of the case **WITHOUT a hole** for the OLED |
| <img src="case_a.png" width=200 /> | [The front part](case_a.stl) of the case with a hole **for installing the OLED** |
### The back part
**Choose ONE of them.**
| Variant | Description |
|---------|-------------|
| <img src="case_b_no_aum.png" width=200 /> | [The back part](case_b_no_aum.stl) of the case **WITHOUT AUM holes** |
| <img src="case_b.png" width=200 /> | [The back part](case_b.stl) of the case **for installing the AUM** |
### Spacers
| Type | Description |
|------|-------------|
| <img src="spacer_6.2mm.png" width=200 /> | [6.2mm spacer](spacer_6.2mm.stl), required **TWO** pieces |
| <img src="spacer_2mm.png" width=200 /> | [2mm spacer](spacer_2mm.stl) required **ONE without AUM** or **TWO for AUM** |
| <img src="spacer_1mm.png" width=200 /> | [1mm spacer](spacer_1mm.stl) required **ONE for AUM only** |
| <img src="low_spacer.png" width=200 /> | [Low spacer](low_spacer.stl) required **ONE** |
docs/stl/v3.2/low_spacer.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

docs/stl/v3.2/low_spacer.stl
BIN
View File
Binary file not shown.
docs/stl/v3.2/spacer_1mm.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB

docs/stl/v3.2/spacer_1mm.stl
BIN
View File
Binary file not shown.
docs/stl/v3.2/spacer_2mm.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

docs/stl/v3.2/spacer_2mm.stl
BIN
View File
Binary file not shown.
docs/stl/v3.2/spacer_6.2mm.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

docs/stl/v3.2/spacer_6.2mm.stl
BIN
View File
Binary file not shown.
docs/stl/v3.3/case_a.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 65 KiB

docs/stl/v3.3/case_a.stl
BIN
View File
Binary file not shown.
docs/stl/v3.3/case_a_no_oled.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 58 KiB

docs/stl/v3.3/case_a_no_oled.stl
BIN
View File
Binary file not shown.
docs/stl/v3.3/case_b.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 119 KiB

docs/stl/v3.3/case_b.stl
BIN
View File
Binary file not shown.
docs/stl/v3.3/index.md
+38
View File
@@ -0,0 +1,38 @@
# PiKVM v3.3 Plastic Case for 3D printing
When printing the case, you can choose the following options:
* The presence or absence of an OLED screen (used to display the IP address and other information).
## Buy options
* [Small 5v fan](https://www.amazon.com/GeeekPi-Raspberry-30x30x7mm-Brushless-Retroflag/dp/B07C9C99RM) **strongly recommended** to avoid overheating in the case.
* [I2C OLED screen](https://www.amazon.com/Pieces-Display-Module-SSD1306-Screen/dp/B08TLXYKS6).
## Building
![type:video](https://www.youtube.com/embed/-SRL92VJ870)
## Parts
### The front part
**Choose ONE of them.**
| Variant | Description |
|---------|-------------|
| <img src="case_a_no_oled.png" width=200 /> | [The front part](case_a_no_oled.stl) of the case **WITHOUT a hole** for the OLED |
| <img src="case_a.png" width=200 /> | [The front part](case_a.stl) of the case with a hole **for installing the OLED** |
### The back part
| Variant | Description |
|---------|-------------|
| <img src="case_b.png" width=200 /> | [The back part](case_b.stl) of the case |
### Spacers
| Type | Description |
|------|-------------|
| <img src="spacer_6.2mm.png" width=200 /> | [6.2mm spacer](spacer_6.2mm.stl), required **TWO** pieces |
| <img src="spacer_1mm.png" width=200 /> | [1mm spacer](spacer_1mm.stl) required **TWO** pieces |
| <img src="low_spacer.png" width=200 /> | [Low spacer](low_spacer.stl) required **ONE** piece |
docs/stl/v3.3/low_spacer.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

docs/stl/v3.3/low_spacer.stl
BIN
View File
Binary file not shown.
docs/stl/v3.3/spacer_1mm.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB

docs/stl/v3.3/spacer_1mm.stl
BIN
View File
Binary file not shown.
docs/stl/v3.3/spacer_6.2mm.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

docs/stl/v3.3/spacer_6.2mm.stl
BIN
View File
Binary file not shown.
docs/tailscale.md
+31
View File
@@ -0,0 +1,31 @@
# Tailscale VPN
[Tailscale](https://tailscale.com/) can be used to access PiKVM on the internal network. This is a convenient and free (for private use) tool for organizing a small VPN network. This document is provided as an example for accessing your pikvm over the inet but you can also use zerotier or remote.it. Basic support like whats shown below is provided as an example, any other setting or functionality needs to be redirected to the appropriate community.
## Installation
### On the PiKVM side
1. Use these commands:
```
# rw
# pacman -Syy
# pacman -S tailscale-pikvm
# systemctl enable --now tailscaled
# tailscale up
```
2. Follow the link to authorize this installation.
3. After success, perform soft reboot using `reboot` command to make sure that everything will work correctly.
4. Perform command `ip addr show tailscale0` to view the Tailscale IP address.
### On the workstation side
* [Download](https://tailscale.com/download) and install tailscale for your OS.
* Check the [admin 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 PiKVM web interface.
docs/tesmart.md
+109
View File
@@ -0,0 +1,109 @@
# TESMART managed multiport KVM switch
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.
1. Connect the USB-A cable from the Raspberry Pi OTG port to one of the TESMART switch USB 2 output ports on the back of the switch (not the keyboard/mouse ports).
2. Connect the HDMI out from the TESMART switch to the Raspberry Pi CSI-2 to HMDI input.
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.
!!! warning
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
In some ways, this is the most complex part of this. The default IP address of the TESMART switch is 192.168.1.10. If that happens to work with your IP addressing scheme and current set of addresses, then you may be all set. This IP address is not configurable via DHCP or other standard mechanisms. The only way to change it is with a Windows utility available on the [TESMART Downloads Page](https://buytesmart.com/pages/downloads).
If you need to change it, you will first need to connect to the switch with a Windows machine, most easily directly through an ethernet cord, with your Windows laptop (or VM) up and assigned to a fixed IP address, such as 192.168.1.5. Once you've launched the utility you will see this screen:
<img src="tesmart_controller_1.png" alt="Configuration screen for TESMART Windows controller utility"/>
On this screen, ensure you are on the "General" tab. Click the radio button for "Network control". Change the IP address to the default for the switch (may already be this -- 192.168.1.10). Press the "Connect" button. Should make the status light go green, as well as the selected port. If you do not get a connection here, you cannot proceed to change the IP address. To change the IP address, change to the "Settings" tab at the top. You will then see this screen:
<img src="tesmart_controller_2.png" alt="Configuration screen for TESMART Windows controller utility"/>
On this screen, change to your desired IP address, gateway, mask, and port. Then press apply. Watch the box on the right to see if it applied OK. Press Query again to double-check. The actual IP address will not be changed until you power off/power on the switch. Make sure you have these settings correct, because if you get them wrong you would have to connect over RS232/serial and not the network.
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 PiKVM UI after clicking the "Switches" menu button in the KVM view.
1. Enable read-write mode on the SD card via `rw`
2. Edit the `/etc/kvmd/override.yaml` file and include the following:
```yaml
kvmd:
gpio:
drivers:
tes:
type: tesmart
host: 10.10.1.10
port: 5000
scheme:
server0_led:
driver: tes
pin: 0
mode: input
server0_switch:
driver: tes
pin: 0
mode: output
switch: false
server1_led:
driver: tes
pin: 1
mode: input
server1_switch:
driver: tes
pin: 1
mode: output
switch: false
server2_led:
driver: tes
pin: 2
mode: input
server2_switch:
driver: tes
pin: 2
mode: output
switch: false
server3_led:
driver: tes
pin: 3
mode: input
server3_switch:
driver: tes
pin: 3
mode: output
switch: false
view:
table:
- ["TESMART Switch"]
- []
- ["#Server 1", server0_led, server0_switch|Switch]
- ["#Server 2", server1_led, server1_switch|Switch]
- ["#Server 3", server2_led, server2_switch|Switch]
- ["#Server 4", server3_led, server3_switch|Switch]
```
3. Return to read-only mode for the sd card via `ro`
4. Restart the `kvmd` service: `systemctl restart kvmd`
## Switching between hosts in the UI
To switch between hosts, enter the KVM UI and click the "Switches" menu. You should see your inputs, one of which will have a green circle indicating it is currently selected. Click the other inputs to change the selected host.
docs/tesmart/tesmart_controller_1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

docs/tesmart/tesmart_controller_2.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

docs/usb_ethernet.md
+70
View File
@@ -0,0 +1,70 @@
# Ethernet-over-USB network
## Basic configuration
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.
1. Edit `/etc/kvmd/override.yaml` and add these lines:
``` yaml
otg:
devices:
ethernet:
enabled: true
driver: ecm
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 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:
allow_tcp: [80, 443]
```
To view other available configuration parameters, use the command `kvmd -m`.
3. To enable the service, use the command `systemctl enable kvmd-otgnet`.
4. Perform `reboot`.
## Routing via PiKVM
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::
```yaml
otgnet:
firewall:
forward_iface: eth0
```
3. Add DNS server to provide host name resolution service. For example, adding `8.8.8.8` as DNS server requires addition of `dnsmasq` dhcp options. This can be done by adding following lines to `/etc/kvmd/override.yaml`:
```yaml
otgnet:
commands:
post_start_cmd_append:
- "--dhcp-option=6,8.8.8.8"
```
4. Combining above two together::
```yaml
otgnet:
firewall:
forward_iface: eth0
commands:
post_start_cmd_append:
- "--dhcp-option=6,8.8.8.8"
```
5. Don't forget to `reboot`.
docs/usb_serial.md
+36
View File
@@ -0,0 +1,36 @@
# Serial-over-USB connection
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` and add these lines:
```yaml
otg:
devices:
serial:
enabled: true
```
2. Run the following command:
```
# echo ttyGS0 >> /etc/securetty
```
3. Create the directory `/etc/systemd/system/getty@ttyGS0.service.d` and add a file file named `ttyGS0.override` into it. Afterwards edit the file and copy this into it:
```ini
[Service]
TTYReset=no
TTYVHangup=no
TTYVTDisallocate=no
```
4. Run these comands:
```
# systemctl enable getty@ttyGS0.service
# reboot
```
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`.
docs/v3.md
+107
View File
@@ -0,0 +1,107 @@
# PiKVM v3 HAT
<img src="assembled.jpg" width="400" />
## Installation requirements
??? note "If you have an assembly kit, you will need the following things"
* Raspberry Pi 4 with 1Gb RAM or more.
* MicroSD card (at least 16Gb, class 10 recommended).
* USB-C to USB-A cable.
* HDMI cable.
* [Straight Ethernet cable](https://www.home-network-help.com/straight.html) (for the ATX expansion board connection).
* Power supply unit (5.1V 3A USB-C, recommended by the Raspberry Pi).
## Basic setup
If you have a kit without a metal case, you can use our free 3D printing case drawing: [v3.3](stl/v3.3/index.md){target=_blank} for the Kickstarter/Store model, [v3.2](stl/v3.2/index.md){target=_blank} for the pre-release.
1. **[Flash the memory card.](flashing_os.md){target=_blank}**
2. **Build PiKVM** according to the video instruction:
: ??? tip "With the metal case"
![type:video](https://www.youtube.com/embed/jdqiwHKQcD4)
: ??? tip "Device with or without the 3D-printed case"
![type:video](https://www.youtube.com/embed/-SRL92VJ870)
3. **Connect PiKVM** to the computer according to the diagram below:
| Back side | Front side |
|-----------|------------|
| <img src="basic_back.jpg" width="300" /> | <img src="basic_front.jpg" width="300" /> |
* **HDMI input** and **USB emulation** port must be connected to the computer. **ATX** too, but it's optional, [read below](#atx-connection). There should be no USB hub between PiKVM and the computer, as some UEFI/BIOS cannot detect them at the boot stage.
* Connect **Ethernet** to the network and **USB Power** to the Raspberry Pi power supply.
4. **Turn on the power supply.**
5. **Carefully read [the "First steps" guide](first_steps.md){target=_blank}** - how to find a device on the network, how to log in there, change passwords, and so on. **Follow the steps described there and come back here**.
6. ??? note "If your kit includes the OLED display and/or the fan, you'll need to turn them on"
Log in to PiKVM and run these commands:
```
# rw
# systemctl enable --now kvmd-oled
# systemctl enable --now kvmd-fan
# ro
```
7. !!! danger "Just reminding again: CHANGE THE PASSWORDS! :)"
How to do this was written in [the "First steps" guide](first_steps.md){target=_blank}
8. **Try to manage the computer using PiKVM with the Web Interface.** Make sure that you see the image, and the keyboard and mouse are working. If something doesn't work, check out our [FAQ](faq.md) (it's really useful). If nothing helped, you can get support in our [Discord chat](https://discord.gg/bpmXfz5).
9. ??? note "Check the HDMI backpowering problem"
Try restarting PiKVM using the `reboot` command executed in the terminal. If PiKVM hangs during boot (you can't get the Web Interface for a long time), then you are faced with this rare problem. **Don't worry, it's easy to fix.** Turn off the PiKVM, disconnect all cables from it, take a close look at the [diagram of its ports and jumpers](#io-ports-and-jumpers), and **remove jumper #14** (it is to the right of the CSI connector). Then you can connect and power up PiKVM again. Now everything will be fine.
10. !!! warning "IO ports and other things"
**Before using GPIO** pins to control a relay, KVM switch, or anything else, be sure to [check the HAT pinout](#io-ports-and-jumpers). Many ports are busy with internal functions. Before using them for your own use, you must disable them, otherwise you may damage the device.
## ATX connection
**======================== TODO =========================**
## IO ports and jumpers
??? note "See the diagram"
<img src="v3_features.jpg" />
1. **ATX controller** interface (power on/off, reboot control, PWR and HDD ACT LEDs).
2. **HDMI reset** jumper.
3. **SPI and GPIO** for the custom extension boards.
4. **Audio capture** jumpers.
5. **UART access** pins.
6. **Serial console port** (for the Raspberry Pi or server console access).
7. **USB-C console port**.
8. **Power** and **activity LEDs**.
9. **USB-C power input**.
10. **I2C display connector**.
11. **Alternate +5V power input/output** header pins.
12. **RTC clock** supercapacitor (rechargeable).
13. **FAN connector** - PWM controlled.
14. **CSI-2 interface** and **HDMI backpowering** jumper.
15. Built-in **power splitter** port.
16. **HDMI capture port** (max 1080p @ 50Hz) with **sound capture** support.
17. **USB emulation pins** for alternative access.
18. **USB-C emulation port** - this port is doing the emulation of a USB keyboard, mouse, Virtual CD-ROM or USB Flash Drive, USB-Ethernet, USB-Serial port and a lot of other Linux-supported features.
19. **1-Wire** & **Neo-pixel** interface (under, advanced user feature).
**================ PINOUT TODO ====================**
??? note "ATX RJ-45 pinout"
The pinout of the RJ-45 connector is the same on the AT and ATX adapter.
<img src="rj45.jpg" />
??? note "ATX LED wiring example"
<img src="atx_led.jpg" />
## Known issues and 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**.
* 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.
* Pre-release v3.2 board (NOT Kickstarter/Store edition) doesn't have HDMI backpowering workaround jumper.
docs/v3/assembled.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 78 KiB

docs/v3/atx_led.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 58 KiB

docs/v3/basic_back.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 142 KiB

docs/v3/basic_front.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 168 KiB

docs/v3/rj45.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 158 KiB

docs/v3/v3_features.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 73 KiB

docs/video.md
+41
View File
@@ -0,0 +1,41 @@
# Working with video
## Video recording
!!! info
H.264 is available on Pi 3 and Pi 4. Older boards won't handle it. Best of all this feature only works for HDMI to CSI bridge. For the USB HDMI dongle, there will be a decrease in FPS to 10-15 for 1080p. Work in progress.
1. Perform full system update to get the latest uStreamer and install ffmpeg:
```
# rw
# pacman -Syu
# pacman -S ffmpeg
```
2. For USB dongle only: Add line `gpu_mem=256` to `/boot/config.txt`.
3. Perform `reboot` command.
4. Run `rw` after the reboot.
6. To record a video, you need to enable the stream (open the web interface or connect via VNC). Then run something like this in the console:
```
# rw
# ustreamer-dump --sink kvmd::ustreamer::h264 --output - | ffmpeg -use_wallclock_as_timestamps 1 -i pipe: -c:v copy test.mp4
```
7. Press `Ctrl+C` to stop recording. Your video will be in the file `test.mp4`.
8. After finishing work, do not forget to switch the file system to read-only mode using `ro` command.
## Take a screenshot via console on PiKVM
!!! note
You must have a stream running
```
# curl --unix-socket /run/kvmd/ustreamer.sock http://localhost/snapshot -o /tmp/screen.jpg
```
docs/vnc.md
+64
View File
@@ -0,0 +1,64 @@
# VNC
As an alternative to the web interface, you can use VNC with various desktop clients. The main advantage of VNC over the browser is the ability to expand the image to the full screen, as well as complete interception of all keyboard keys. In some cases, VNC will be more responsive than the browser, especially on weak computers.
!!! warning
Don't use 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 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`:
```yaml
vnc:
keymap: /usr/share/kvmd/keymaps/ru
```
All available keymaps are located in `/usr/share/kvmd/keymaps`:
<img src="keymaps.png" />
3. *Optional:* This step is not nessessory if using TigerVNC. Some VNC clients (for example TightVNC) can't use user/password authentication. In this case you can enable passphrases mode in `/etc/kvmd/override.yaml`:
```yaml
vnc:
auth:
vncauth:
enabled: true
```
To set passphrases edit file `/etc/kvmd/vncpasswd`.
4. Enable `kvmd-vnc` daemon. VNC will be available on the port 5900: `systemctl enable --now kvmd-vnc`.
5. Switch filesystem back to read-only: `ro`.
## Configuring the client
We recommend [TigerVNC](https://tigervnc.org) for a better experience on desktop.
Here are our recommended settings for TigerVNC:
* **Compression** tab:
* Choose **Tight** encoding as preferred and color-level **Full**.
* Disable automatic quality adjust settings **Auto Select**.
* Enable **Allow JPEG compression**.
* **Security** tab:
* Enable **None**, **X.509 TLS** and **Anonymous TLS** encryption (or choose one preferred mode).
* Enable **Username and password** authentication.
For iOS and Android the recommended application is bVNC:
* [Google Play](https://play.google.com/store/apps/details?id=com.iiordanov.bVNC)
* [App Store](https://apps.apple.com/us/app/bvnc-pro/id1506461202)
## Unsupported clients
* **RealVNC** - Does not support most widely used open VNC protocol extensions.
* **Guacamole** - Incorrectly implements vencrypt, no JPEG compression.
* **Vinagre** - Incorrectly implements vencrypt.
docs/vnc/keymaps.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.5 KiB

docs/webrtc.md
+77
View File
@@ -0,0 +1,77 @@
# H.264 / WebRTC
This is a new alternative video transfer mode available for Raspberry Pi 4 users with an HDMI-CSI bridge (including PiKVM v3 HAT).
It uses H.264 encoding instead of MJPEG and provides significantly less traffic consumption. ZeroW is NOT supported.
If you use an OS image built after 2021.06.10, this mode will be available by default.
If you are upgrading to an older version of the OS, you will need to manually enable the WebRTC gateway:
```
# systemctl enable --now kvmd-janus
```
Then reload the Web UI and then in the **System** menu you will see the video mode switch.
!!! note
If you do not see the switch, it means that either your browser does not support WebRTC, or the `kvmd-janus` service was not started.
## Basics
The MJPEG video stream uses the same HTTP connection that you use to get the web interface.
This means that for remote access, you just need to forward ports 80 and 443 on your router.
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 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 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,
you can choose [any other STUN server](https://www.voip-info.org/stun/) at your discretion, or set up your own.
Edit `/etc/kvmd/override.yaml`:
```yaml
janus:
stun:
host: stun.stunprotocol.org
port: 3478
```
... and restart `kvmd-janus` service using `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 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`.
```
# systemctl disable --now kvmd-janus
...
# systemctl enable --now kvmd-janus-static
```
## Troubleshooting
In rare cases, WebRTC may not work. The most common reasons are:
* 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` where is a 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.
* For instance: On Fedora you can install the rpmfusion repos, then use the `chromium-freeworld` package instead of `chromium`
docs/wifi.md
+129
View File
@@ -0,0 +1,129 @@
# Setting up Wi-Fi
The following describes how to setup a Wi-Fi connection on the default pikvm builds based on Arch Linux. The process might vary for other Linux distros. We recommend to do this while having a display and keyboard connected directly to the Raspberry Pi as you will loose network connectivity once you connect to a Wi-Fi. Alternatively you can connect to the PiKVM via SSH. The built-in Web Terminal (available through the browser) should also work.
!!! warning
There is nothing more reliable than wired Ethernet, so it's better to use it. But who are we to stop you... :)
## Step by step
1. Make filesystem writable using `rw` command.
2. *Optional:* If you want your Raspberry Pi to automatically connect to any configured and available Wi-Fi networks you have to set the following option. On Raspberry Pis `wlan0` is the default name of the wlan device.
```
# systemctl enable netctl-auto@wlan0.service
```
3. Create Wi-Fi profiles
* **Using the interactive dialog**
You can create Wi-Fi profiles either manually or by using `wifi-menu`. This requires the Wi-Fi you want to connect to in signal range.
```
# wifi-menu -o
```
The `-o` makes sure that the Wi-Fi passphrase is stored encrypted. Otherwise it will be stored in cleartext in the profile file. `wifi-menu` will scan for all available Wi-Fi networks and provide you a list:
<img src="wifi-1.png" />
Select the Wi-Fi you want to connect to and give the profile file a name. The default name is `wlan0-wifiname`:
<img src="wifi-2.png" />
Enter the WPA-Passphrase:
<img src="wifi-3.png" />
Afterwards `wifi-menu` will try to connect to the Wi-Fi. If you're connected via ssh or the Web Terminal you'll loose connection to the Raspberry Pi. Most DHCP servers will give the Raspberry Pi a new (and usually different) IP address for each interface (LAN / WLAN).
If everything worked out you should be connected to your Wi-Fi now. `wifi-menu` created a new profile file for you in */etc/netctl*.
* **Manually**
If you want to store the Wi-Fi passphrase encrypted you have to generate it via `wpa_passphrase`:
```
# wpa_passphrase wifiname this_is_my_great_and_secure_key_1234567890
```
<img src="wifi-4.png" />
Copy the second hexadecimal string without `psk=`. In this example `814c45d0f88f60636532b034c463639a506670f8ba3c7965e62cdbc1989f6d66`.
Create a new file with the editor of your choice (nano, vim, etc.):
```
# nano /etc/netctl/wlan0-wifiname
```
Copy the following template into the file and modify it with your parameters.
Note the `\"` after `Key=` is required for encrypted passphrases. If you want to put your Wi-Fi passphrase in cleartext the \\" is not required. See [this](https://github.com/joukewitteveen/netctl/blob/master/docs/netctl.profile.5.txt) for the quoting rules and more Wi-Fi profile configuration options.
```bash
Description='My great Wi-Fi'
Interface=wlan0
Connection=wireless
Security=wpa
ESSID=wifiname
IP=dhcp
Key=\"814c45d0f88f60636532b034c463639a506670f8ba3c7965e62cdbc1989f6d66
```
Save the file and you're good to go. You can manually connect to the profile you've just created with:
```
# netctl-auto switch-to wlan0-wifiname
```
4. To add the hidden ESSID you need to edit `/etc/netctl/wlan0-<SSID>` file and add the hidden option:
```bash
Description='Hidden SSID template'
Interface=wlan0
Connection=wireless
Security=wpa
ESSID=WIFI-Name
IP=dhcp
Key=supersecretpassword
Hidden=yes
```
5. *Optional:* If you want to connect to a 5GHz Wi-Fi in the US and it's not listed, create `/etc/wpa_supplicant/wpa_supplicant-wlan0.conf` with a single line `country=US`, and enable it with:
```
# systemctl enable wpa_supplicant@wlan0
```
6. Make filesystem read-only again using `ro` command
## Useful console commands
* `iwconfig` - Manipulate the basic wireless parameters.
* `iwlist` - Allow's you to initiate scanning and list frequencies, bit-rates, encryption keys, etc.
* `iwspy` - Displays per node link quality.
* `iwpriv` - Allow's you to manipulate the Wireless Extensions specific to a driver (private).
!!! example "Some examples"
```
# iw dev wlan0 scan | egrep "signal:|SSID:" | sed -e "s/\tsignal: //" -e "s/\tSSID: //" | awk '{ORS = (NR % 2 == 0)? "\n" : " "; print}' | sort
```
```
# iwlist wlan0 scan | egrep "Cell|ESSID|Signal|Rates"
```
```
# iwlist wlan0 scan
```
```
# iw wlan0 info
```
## Additional resources
* [Arch Linux Wiki for netctl](https://wiki.archlinux.org/index.php/Netctl)
docs/wifi/wifi-1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

docs/wifi/wifi-2.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.0 KiB

docs/wifi/wifi-3.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.5 KiB

docs/wifi/wifi-4.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

docs/wiring_examples.md
+31
View File
@@ -0,0 +1,31 @@
### Some example wiring setups
# CSI (Geekworm) (Any brand will be the same)
<img src="img/csi_wiring.jpg" alt="drawing">
List of items: (WARNING! Links may dissappear or no longer work, this just gives you an idea)
- USB-A male to USB-A male (For data)
- [PortaPow USB Power Blocker](https://www.amazon.com/gp/product/B092MLT2J3)
- [USB C OTG Splitter](https://www.amazon.com/gp/product/B08C5FWQND)
- Normal HDMI Cable
- DisplayPort TO HDMI pigtail (Cable) (Pic is displayed wrong)
- TARGET (Anything you want to control)
# Another CSI example using the PCB splitter
<img src="img/csi_wiring_w_pcb_splitter.jpg" alt="drawing">
# USB
<img src="img/usb_capture_wiring.jpg" alt="drawing">
# Direct connect to target
<img src="img/direct_connect_to_target.jpg" alt="drawing">
Explanation of pic
- USB-C from PI to USB-A onto target which also powers the PI
Use case:
- Trying to determine if the data cable is truly a data cable and not just a power cable
- Testing to see if the splitter or cable is defective
- Basic troubleshooting
docs/wol.md
+28
View File
@@ -0,0 +1,28 @@
# Wake-on-LAN
## Simplified method (one host)
To use Wake-on-LAN with your server you must define some options such as the server's MAC address and (optionally) IP address. Use `/etc/kvmd/override.yaml`. The format is:
```yaml
kvmd:
wol:
mac: ff:ff:ff:ff:ff:ff
```
Replace `ff:ff:ff:ff:ff:ff` with the MAC of your server. By default, a packet is sent via a broadcast request to the entire IPv4 network (`255.255.255.255`, port `9`), but you can address it to a specific static address:
```yaml
kvmd:
wol:
mac: ff:ff:ff:ff:ff:ff
ip: 192.168.0.100
# port: 9 # By default
```
... then restart `kvmd` using `systemctl restart kvmd`. It will now show up in the system button in the upper right corner.
## GPIO method (multiple hosts)
Follow the [manual for building the GPIO menu](gpio.md) and use the `wol` driver to build a menu with many buttons tied to different hosts.
docs/xh_hk4401.md
+128
View File
@@ -0,0 +1,128 @@
# XH-HK4401 4-port HDMI USB KVM Switch
<img src="xh-hk4401.jpg" alt="drawing" width="300"/>
This KVM is [sold](https://www.aliexpress.com/item/4000849336545.html) under many names, and comes in two versions.
The only way these two versions differ is that one has one of its USB ports replaced with a PS/2 port. The
identifying feature is that they come with a small external control unit with 4 buttons. This controller is
connected to the main KVM via a micro USB cable, however this is **NOT** as USB connection.
!!! warning
Audio was not tested, it is assumed to be non-functional
## Connections
1. Connect the USB-A cable from the Raspberry Pi OTG port to to any of the USB ports on the XH-HK4401 switch. All 3/4 USB ports work exactly the same, internally they are just connected to a USB HUB.
2. Connect the HDMI out from the XH-HK4401 switch to the Raspberry Pi CSI-2 to HDMI input.
3. Connect host USB and HDMI cables from the XH-HK4401 switch to the machines to be managed per the switch instructions.
4. Finally see below for details about connecting to the control micro USB port. **This it not a normal USB micro port.**
!!! warning
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 HDMI-CSI bridge. These limitations apply equally when using the XH-HK4401 KVM switch. If video is not present in PiKVM, try keeping all host machines off and connecting them directly to the XH-HK4401 switch before powering the hosts on.
## RS-232 control cable
The control unit communicates to the KVM using the RS-232 protocol (at 5v) not USB, and one of the following
solutions must be used.
### An inverter circuit
For this you will need:
* 2x 2n7000 MOSFETs
* 2x 10K resistors
* 1x USB Micro connector, or sacrificial micro USB cable
* *Optional:* USB UART adapter
<img src="xh-hk4401_circuit.jpg" />
You can connect this either via a USB UART adapter, or directly to the Raspberry Pi: `GND -> Pin 6`, `TX -> Pin 8`, `RX -> Pin 10`.
On the v3 PiKVM hat you will need to disable the UART jumpers to use the on-board UART.
!!! note
Please search online for USB pinouts to ensure you connect it properly.
### Inverting USB UART adapter
Some USB UART adapters have the rare feature to invert the logic level of the RX/TX signals. For example the FTDI FT232 can
be configured via the FTDI configuration GUI to do this. With such an adapter, the circuit above is not required. All you
need is to connect it to a micro-USB connector.
## 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 PiKVM UI after clicking the "GPIO" menu button in the KVM view.
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 you are using a USB UART present on `/dev/ttyUSB0`:
```yaml
kvmd:
gpio:
drivers:
hk:
type: xh_hk4401
device: /dev/ttyUSB0
scheme:
ch0_led:
driver: hk
pin: 0
mode: input
ch1_led:
driver: hk
pin: 1
mode: input
ch2_led:
driver: hk
pin: 2
mode: input
ch3_led:
driver: hk
pin: 3
mode: input
ch0_button:
driver: hk
pin: 0
mode: output
switch: false
ch1_button:
driver: hk
pin: 1
mode: output
switch: false
ch2_button:
driver: hk
pin: 2
mode: output
switch: false
ch3_button:
driver: hk
pin: 3
mode: output
switch: false
view:
table:
- ["#Input 1", ch0_led, ch0_button]
- ["#Input 2", ch1_led, ch1_button]
- ["#Input 3", ch2_led, ch2_button]
- ["#Input 4", ch3_led, ch3_button]
```
4. Return to read-only mode for the sd card via `ro`
5. Restart the kvmd service: `systemctl restart kvmd`
## Switching between hosts in the UI
To switch between hosts, enter the KVM UI and click the "GPIO" menu. You should see 4 inputs, one of which will have a green circle indicating it is currently selected. Click the other inputs to change the selected host.
docs/xh_hk4401/xh-hk4401.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

docs/xh_hk4401/xh-hk4401_circuit.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 61 KiB