mirror of https://github.com/pikvm/pikvm
docs.pikvm.org
Maxim Devaev
3 years ago
parent
888f128a6a
commit
ddd1baf604
@ -0,0 +1,16 @@
|
||||
name: ci
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- uses: actions/setup-python@v2
|
||||
with:
|
||||
python-version: 3.x
|
||||
- run: pip install mkdocs-material mkdocs-video
|
||||
- run: mkdocs gh-deploy --force
|
||||
@ -0,0 +1 @@
|
||||
/site/
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 2.0 KiB |
@ -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;
|
||||
}
|
||||
@ -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.
|
||||
@ -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`.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 273 KiB |
|
Before Width: | Height: | Size: 266 KiB After Width: | Height: | Size: 266 KiB |
|
Before Width: | Height: | Size: 1.1 MiB After Width: | Height: | Size: 1.1 MiB |
|
Before Width: | Height: | Size: 1.4 MiB After Width: | Height: | Size: 1.4 MiB |
|
Before Width: | Height: | Size: 91 KiB After Width: | Height: | Size: 91 KiB |
@ -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
|
||||
```
|
||||
@ -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).
|
||||
@ -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.
|
||||
|
Before Width: | Height: | Size: 921 KiB After Width: | Height: | Size: 921 KiB |
|
Before Width: | Height: | Size: 315 KiB After Width: | Height: | Size: 315 KiB |
@ -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).
|
||||
@ -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
|
||||
```
|
||||
@ -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.
|
||||
|
Before Width: | Height: | Size: 20 KiB After Width: | Height: | Size: 20 KiB |
|
Before Width: | Height: | Size: 21 KiB After Width: | Height: | Size: 21 KiB |
|
Before Width: | Height: | Size: 30 KiB After Width: | Height: | Size: 30 KiB |
|
Before Width: | Height: | Size: 20 KiB After Width: | Height: | Size: 20 KiB |
|
Before Width: | Height: | Size: 63 KiB After Width: | Height: | Size: 63 KiB |
@ -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"]
|
||||
|
||||
```
|
||||
|
Before Width: | Height: | Size: 21 KiB After Width: | Height: | Size: 21 KiB |
@ -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: [](https://discord.gg/bpmXfz5)
|
||||
* Subreddit: [](https://www.reddit.com/r/pikvm)
|
||||
|
||||
|
||||
@ -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).
|
||||
|
Before Width: | Height: | Size: 65 KiB After Width: | Height: | Size: 65 KiB |
|
Before Width: | Height: | Size: 58 KiB After Width: | Height: | Size: 58 KiB |
|
Before Width: | Height: | Size: 57 KiB After Width: | Height: | Size: 57 KiB |
|
Before Width: | Height: | Size: 56 KiB After Width: | Height: | Size: 56 KiB |
@ -1,30 +1,41 @@
|
||||
# PiKVM v3.2 Plastic Case for 3D printing
|
||||
# 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).
|
||||
|
||||
* 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
|
||||
See [this](https://www.youtube.com/watch?v=-SRL92VJ870) video.
|
||||
|
||||
|
||||
|
||||
## Parts
|
||||
|
||||
### The front part
|
||||
|
||||
# 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
|
||||
### 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
|
||||
### Spacers
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| <img src="spacer_6.2mm.png" width=200 /> | [6.2mm spacer](spacer_6.2mm.stl), required **TWO** pieces |
|
||||
|
Before Width: | Height: | Size: 21 KiB After Width: | Height: | Size: 21 KiB |
|
Before Width: | Height: | Size: 19 KiB After Width: | Height: | Size: 19 KiB |
|
Before Width: | Height: | Size: 24 KiB After Width: | Height: | Size: 24 KiB |
|
Before Width: | Height: | Size: 24 KiB After Width: | Height: | Size: 24 KiB |
|
Before Width: | Height: | Size: 65 KiB After Width: | Height: | Size: 65 KiB |
|
Before Width: | Height: | Size: 58 KiB After Width: | Height: | Size: 58 KiB |
|
Before Width: | Height: | Size: 119 KiB After Width: | Height: | Size: 119 KiB |
@ -1,27 +1,36 @@
|
||||
# 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).
|
||||
|
||||
* 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
|
||||
See [this](https://www.youtube.com/watch?v=-SRL92VJ870) video.
|
||||
|
||||
# The front part
|
||||
|
||||
|
||||
## 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
|
||||
### The back part
|
||||
|
||||
| Variant | Description |
|
||||
|---------|-------------|
|
||||
| <img src="case_b.png" width=200 /> | [The back part](case_b.stl) of the case |
|
||||
|
||||
# Spacers
|
||||
### Spacers
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| <img src="spacer_6.2mm.png" width=200 /> | [6.2mm spacer](spacer_6.2mm.stl), required **TWO** pieces |
|
||||
|
Before Width: | Height: | Size: 21 KiB After Width: | Height: | Size: 21 KiB |
|
Before Width: | Height: | Size: 19 KiB After Width: | Height: | Size: 19 KiB |
|
Before Width: | Height: | Size: 24 KiB After Width: | Height: | Size: 24 KiB |
@ -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.
|
||||
|
Before Width: | Height: | Size: 26 KiB After Width: | Height: | Size: 26 KiB |
|
Before Width: | Height: | Size: 21 KiB After Width: | Height: | Size: 21 KiB |
@ -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`.
|
||||
@ -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"
|
||||
|
||||
: ??? tip "Device with or without the 3D-printed case"
|
||||
|
||||
|
||||
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.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 78 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 142 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 168 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 158 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 73 KiB |
@ -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
|
||||
```
|
||||
@ -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.
|
||||
|
Before Width: | Height: | Size: 4.5 KiB After Width: | Height: | Size: 4.5 KiB |
@ -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)
|
||||
|
Before Width: | Height: | Size: 12 KiB After Width: | Height: | Size: 12 KiB |
|
Before Width: | Height: | Size: 4.0 KiB After Width: | Height: | Size: 4.0 KiB |
|
Before Width: | Height: | Size: 3.5 KiB After Width: | Height: | Size: 3.5 KiB |
|
Before Width: | Height: | Size: 12 KiB After Width: | Height: | Size: 12 KiB |
@ -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.
|
||||
|
Before Width: | Height: | Size: 22 KiB After Width: | Height: | Size: 22 KiB |
|
Before Width: | Height: | Size: 61 KiB After Width: | Height: | Size: 61 KiB |
@ -0,0 +1,90 @@
|
||||
# https://squidfunk.github.io/mkdocs-material/getting-started
|
||||
# https://squidfunk.github.io/mkdocs-material/reference/admonitions
|
||||
# https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml
|
||||
|
||||
|
||||
site_name: PiKVM Handbook
|
||||
site_description: Open and cheap DIY IP-KVM on Raspberry Pi
|
||||
site_author: Maxim Devaev
|
||||
site_url: https://pikvm.github.io/pikvm
|
||||
|
||||
repo_name: pikvm/pikvm
|
||||
repo_url: https://github.com/pikvm/pikvm
|
||||
edit_uri: ""
|
||||
|
||||
copyright: "Copyright © 2018-2021 Maxim Devaev"
|
||||
|
||||
docs_dir: docs
|
||||
|
||||
theme:
|
||||
logo: _assets/logo.png
|
||||
favicon: _assets/favicon.ico
|
||||
name: material
|
||||
palette:
|
||||
accent: pink
|
||||
features:
|
||||
- navigation.indexes
|
||||
- navigation.sections
|
||||
- navigation.top
|
||||
- navigation.tracking
|
||||
- navigation.expand
|
||||
- search.highlight
|
||||
- search.share
|
||||
- search.suggest
|
||||
|
||||
extra_css:
|
||||
- _assets/user.css
|
||||
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- def_list
|
||||
- attr_list
|
||||
- pymdownx.tilde
|
||||
- pymdownx.details
|
||||
- pymdownx.superfences
|
||||
- pymdownx.magiclink
|
||||
- toc:
|
||||
permalink: true
|
||||
- codehilite:
|
||||
guess_lang: false
|
||||
- markdown_include.include:
|
||||
base_path: docs
|
||||
|
||||
plugins:
|
||||
- search:
|
||||
lang: en
|
||||
- mkdocs-video
|
||||
|
||||
nav:
|
||||
- "Getting started":
|
||||
- "PiKVM v3 HAT guide": v3.md
|
||||
- "First steps": first_steps.md
|
||||
- "FAQ": faq.md
|
||||
- "Networking":
|
||||
- "Internet access":
|
||||
- "Port forwarding": port_forwarding.md
|
||||
- "Tailscale VPN": tailscale.md
|
||||
- "Setting up Wi-Fi": wifi.md
|
||||
- "Video":
|
||||
- "H.264 / WebRTC": webrtc.md
|
||||
- "Working with video": video.md
|
||||
- "Tuning HDMI EDID": edid.md
|
||||
- "Peripheral devices":
|
||||
- "Keyboard & mouse":
|
||||
- "Mouse modes": mouse.md
|
||||
- "Bluetooth HID": bluetooth_hid.md
|
||||
- "Arduino HID (USB, PS/2)": arduino_hid.md
|
||||
- "Mass Storage Drive": msd.md
|
||||
- "Ethernet-over-USB": usb_ethernet.md
|
||||
- "Serial-over-USB": usb_serial.md
|
||||
- "GPIO (pins, relays, lamps, etc)": gpio.md
|
||||
- "Advanced usage":
|
||||
- "Using VNC": vnc.md
|
||||
- "Multiport KVM-over-IP": multiport.md
|
||||
- "Wake-on-LAN the server": wol.md
|
||||
- "IPMI & Redfish integration": ipmi.md
|
||||
- "Prometheus monitoring": prometheus.md
|
||||
- "Development":
|
||||
- "Cases for 3D printing": 3d_printing.md
|
||||
- "Building PiKVM OS": building_os.md
|
||||
- "HTTP API reference": api.md
|
||||
@ -1,343 +0,0 @@
|
||||
# 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` parameter to disable SSL certificate verification, since the self-signed certificateis used in the default installation.
|
||||
|
||||
## Authorization: `/api/auth`
|
||||
All APIs are restricted to authorization. To make requests, you either need to authorize each request individually,
|
||||
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.
|
||||
|
||||
## The main web socket: `/api/ws`
|
||||
Most of the data during the user's work with pikvm is transmitted over a web socket. 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 a web socket, 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 a web socket. 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
|
||||
```
|
||||
<details>
|
||||
<summary>Output with initial events</summary>
|
||||
|
||||
```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": {}}
|
||||
```
|
||||
</details>
|
||||
|
||||
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": {}}`.
|
||||
|
||||
### Sending keypress events
|
||||
|
||||
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"
|
||||
header = {"X-KVMD-User": "admin", "X-KVMD-Passwd": "admin"}
|
||||
ws = websocket.WebSocket(sslopt={"cert_reqs": ssl.CERT_NONE})
|
||||
ws.connect(uri, header=header)
|
||||
ws.send(r'{"event_type": "key", "event": {"key": "Enter", "state": true}}')
|
||||
time.sleep(0.05)
|
||||
ws.send(r'{"event_type": "key", "event": {"key": "Enter", "state": false}}')
|
||||
ws.close()
|
||||
```
|
||||
|
||||
## System info: `/api/info`
|
||||
On `GET` this handle will return general information about the PiKVM device. If you specify the `fields` query parameter, only the requested category will be selected, like `fields=system,hw`. By default all categories will be displayed:
|
||||
|
||||
```
|
||||
$ curl -k -u admin:admin https://<pikvm-ip>/api/info
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>Example</summary>
|
||||
|
||||
```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
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
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.
|
||||
|
||||
## System log: `/api/log`
|
||||
On `GET` this handle will display messages from all KVMD services as plain text. The `follow=1` request parameter turns the request into an infinite one and you will receive new log messages in real time. The seek parameter runs the log for the specified time in seconds. For example, `seek=3600` will show the log for the last hour. Both the `seek` and `follow` parameters can be used together.
|
||||
|
||||
```
|
||||
$ curl -k -u admin:admin https://<pikvm-ip>/api/log
|
||||
```
|
||||
|
||||
## Get ATX state: `/api/atx`
|
||||
On `GET` it will show current ATX state.
|
||||
|
||||
```
|
||||
$ curl -k -u admin:admin https://<pikvm-ip>/api/atx
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>Example</summary>
|
||||
|
||||
```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
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
### Set ATX PSU state: `/api/atx/power`
|
||||
On `POST` it will change ATX power supply state to desired.
|
||||
Parameters:
|
||||
- `action` describes desired state:
|
||||
* `on` - turned on (do nothing in case PSU is already on);
|
||||
* `off` - turned off (aka soft-off), emulates short-press on the power button;
|
||||
* `off_hard` - emulates long (5+ seconds) press on the power button;
|
||||
* `reset_hard` emulates pressing reset button (hardware hot reset).
|
||||
- `wait` - Boolean. 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
|
||||
```
|
||||
|
||||
### Emulate pressing buttons on computer case: `/api/atx/click`
|
||||
On `POST` send button press events to {front-}panel header (like you pressing buttins on your computer's case).
|
||||
Parameters:
|
||||
- `button` specifies the desired computer case button you would like to press. Currently supported options are:
|
||||
* `power` — for short press on power button;
|
||||
* `power_long` — for pressing POWER button for 4+ seconds (force OFF);
|
||||
* `reset` — to initiate cold-reset.
|
||||
- `wait` Boolean. 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
|
||||
```
|
||||
|
||||
## Get Mass Storage Drive (*msd*) state: `/api/msd`
|
||||
On `GET` it will show current *msd* state.
|
||||
|
||||
```
|
||||
$ curl -k -u admin:admin https://<pikvm-ip>/api/msd
|
||||
```
|
||||
|
||||
### Upload image: `/api/msd/write`
|
||||
On `POST` upload an image to the drive. This API uses HTTP POST data.
|
||||
Parameters:
|
||||
- `image` specify the image name.
|
||||
- `data` multipart POST data to be uploaded.
|
||||
|
||||
```
|
||||
$ # create 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 image by URL: `/api/msd/write_remote`
|
||||
On `POST` download an image to the drive from HTTP(S) URL.
|
||||
Parameters:
|
||||
- `image` specify the image name.
|
||||
- `timeout` remote request timeout, 10 seconds by default.
|
||||
|
||||
```
|
||||
$ # 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: `/api/msd/set_params`
|
||||
On `POST` select the image and change media type. Parameters:
|
||||
- `image` specify the image name.
|
||||
- `cdrom` Boolean. Select media type:
|
||||
* `true` - CD-ROM;
|
||||
* `false` - Flash.
|
||||
|
||||
```
|
||||
$ curl -X POST -k -u admin:admin "https://<pikvm-ip>/api/msd/set_params?image=test.iso&cdrom=true"
|
||||
```
|
||||
|
||||
### Connect the device: `/api/msd/set_connected`
|
||||
On `POST` select if the drive should be connected. Parameters:
|
||||
- `connected` Boolean. Connect drive:
|
||||
* `true` - connect drive;
|
||||
* `false` - disconnect drive.
|
||||
|
||||
```
|
||||
$ curl -X POST -k -u admin:admin https://<pikvm-ip>/api/msd/set_connected?connected=true
|
||||
```
|
||||
|
||||
### Remove image: `/api/msd/remove`
|
||||
On `POST` select the image that should be removed. Parameters:
|
||||
- `image` specify the image name.
|
||||
|
||||
```
|
||||
$ curl -X POST -k -u admin:admin https://<pikvm-ip>/api/msd/remove?image=test.iso
|
||||
```
|
||||
|
||||
### Reset *msd*: `/api/msd/reset`
|
||||
On `POST` resets the mass storage drive.
|
||||
|
||||
```
|
||||
$ curl -X POST -k -u admin:admin https://<pikvm-ip>/api/msd/reset
|
||||
```
|
||||
|
||||
## Get GPIO state: `/api/gpio`
|
||||
On `GET` it will show current GPIO state.
|
||||
|
||||
```
|
||||
$ curl -k -u admin:admin https://<pikvm-ip>/api/gpio
|
||||
```
|
||||
|
||||
### Switch GPIO driver channel: `/api/gpio/switch`
|
||||
On `POST` it will interact with selected GPIO driver channel in `switch` mode. Parameters:
|
||||
- `channel` specify the GPIO driver channel.
|
||||
- `state` Boolean. Select the new switch state.
|
||||
- `wait` Boolean. Says if call should return immediately or just after finishing operation.
|
||||
|
||||
### Pulse GPIO driver channel: `/api/gpio/pulse`
|
||||
On `POST` it will interact with selected GPIO driver channel in `pulse` mode. Parameters:
|
||||
- `channel` specify the GPIO driver channel.
|
||||
- `delay` Float. Defines the pulse time in seconds, `0` for disable pulsing.
|
||||
- `wait` Boolean. Says if call should return immediately or just after finishing operation.
|
||||
|
||||
## Get Prometheus metrics: `/api/export/prometheus/metrics`
|
||||
On `GET` it will return the exported Prometheus metrics. Also see [here](prometheus.md) for details.
|
||||
|
||||
```
|
||||
$ curl -k -u admin:admin https://<pikvm-ip>/api/export/prometheus/metrics
|
||||
```
|
||||
|
||||
|
||||
# To be continued ===>
|
||||
Unfortunately, the developer doesn't have enough time to fully describe the API. 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.
|
||||
@ -1,174 +0,0 @@
|
||||
# Hardware Arduino HID instead of the OTG
|
||||
Using Arduino HID on non-v0 platforms 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.
|
||||
|
||||
- NOTE: AIMOS KVM switches do not work with the aruduino, please consider using an alternitive.
|
||||
|
||||
## USB keyboard & mouse
|
||||
* Build and connect HID according to the [diagram](../README.md#setting-up-the-v0) (the bottom part with transistor, level-shifter and Arduino).
|
||||
* Switch to RW-mode using command `rw`.
|
||||
* Add these lines to `/etc/kvmd/override.yaml` (remove `{}` in the file before):
|
||||
```yaml
|
||||
kvmd:
|
||||
hid:
|
||||
type: serial
|
||||
reset_pin: 4
|
||||
device: /dev/kvmd-hid
|
||||
```
|
||||
* Create file `/etc/udev/rules.d/99-kvmd-extra.rules`:
|
||||
```udev
|
||||
KERNEL=="ttyAMA0", SYMLINK+="kvmd-hid"
|
||||
```
|
||||
* Run `systemctl disable getty@ttyAMA0.service`.
|
||||
* Remove `console=ttyAMA0,115200`or `console=serial0,115200` and `kgdboc=ttyAMA0,115200` or `kgdboc=serial0,115200` from `/boot/cmdline.txt`.
|
||||
* [Flash the Arduino HID](flashing_hid.md).
|
||||
* Run `reboot`.
|
||||
|
||||
## PS/2 keyboard
|
||||
Using the PS/2 firmware currently has the following 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, you need to follow the instructions for USB, but with one exception. Before `make` you need to edit file `platformio.ini`. Open it 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, you need to 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.
|
||||
|
||||
Follow this diagram:
|
||||
| Female PS/2 port (front view) | Pinout |
|
||||
|-------------------------------|--------|
|
||||
| <img src="https://raw.githubusercontent.com/pikvm/pikvm/master/img/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 |
|
||||
|
||||
**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).**
|
||||
|
||||
## 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, you need to recompile the firmware with uncommented flag `-DHID_WITH_USB_WIN98` in `platformio.ini`.
|
||||
|
||||
## SPI connection to Arduino Micro
|
||||
Using an SPI connection, an Arduino Micro 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="https://raw.githubusercontent.com/pikvm/pikvm/master/img/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 microcontroller 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="https://raw.githubusercontent.com/pikvm/pikvm/master/img/arduino_spi_hid_rpi.jpg" alt="A closeup of the Raspberry Pi wired to the breadboard." width=300/> | <img src="https://raw.githubusercontent.com/pikvm/pikvm/master/img/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 microcontroller'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 microcontroller
|
||||
|
||||
Instructions on flashing the microcontroller 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 microcontroller 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 on Discord at 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
|
||||
|
||||
```sh
|
||||
systemctl restart kvmd
|
||||
```
|
||||
|
||||
If your device is still in read-write mode, `ro` will put the SD back in read-only mode.
|
||||
@ -1,128 +0,0 @@
|
||||
# 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.
|
||||
|
||||
Latest Arch Linux is working.
|
||||
|
||||
0. 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.
|
||||
```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.
|
||||
|
||||
1. Git checkout the build toolchain:
|
||||
```shell
|
||||
[user@localhost ~]$ git clone https://github.com/pikvm/os
|
||||
[user@localhost ~]$ cd os
|
||||
```
|
||||
|
||||
2. 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=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).
|
||||
|
||||
3. Create the config file `config.mk` for the target system. You must specify the path to the SD card on your local computer (this will be used to format and install the system) and the version of your Raspberry Pi and platform. You can change other parameters as you wish. Please note: if your password contains the # character, you must escape it using a backslash like `ROOT_PASSWD = pass\#word`.
|
||||
```Makefile
|
||||
[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
|
||||
```
|
||||
|
||||
5a. 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
|
||||
```
|
||||
|
||||
5b. Make the image to copy elsewhere and burn on to SD
|
||||
```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
|
||||
```
|
||||
|
||||
8. **Only for v0**: [Flash the Arduino HID](flashing_hid.md).
|
||||
|
||||
9. Congratulations! Your PiKVM will be available via SSH (`ssh root@<addr>` with password `root` by default) and HTTPS (try to open in a browser the URL `https://<addr>`, the login `admin` and password `admin` by default). For HTTPS a self-signed certificate is used by default.
|
||||
|
||||
*The latest versions of Chrome do not allow access to the page with a self signed certificate. You can proceed by typing ```thisisunsafe``` and Chrome will then load the page*
|
||||
|
||||
10. To change the root password use command `passwd` via SSH or webterm. To change PiKVM web password use `kvmd-htpasswd set admin`. As indicated on the login screen use `rw` to make the root filesystem writable, before issuing these commands. After making changes, make sure to run the command `ro`.
|
||||
|
||||
11. Important **note for HDMI-USB dongle** users only. Because of this, many video capture devices tell the server's video card that the HDMI cable is supposedly disconnected. This may lead to the fact that if you boot the server without an active stream, the server will not detect your capture card. This is easy to fix:
|
||||
* Switch filesystem to RW-mode:
|
||||
```
|
||||
# rw
|
||||
```
|
||||
* Edit file `/etc/kvmd/override.yaml` and add these lines:
|
||||
```yaml
|
||||
kvmd:
|
||||
streamer:
|
||||
forever: true
|
||||
cmd_append: [--slowdown]
|
||||
```
|
||||
* Finish:
|
||||
```
|
||||
# ro
|
||||
# systemctl restart kvmd
|
||||
```
|
||||
|
||||
12. **27.08.2020 note about systemd**: the latest version of Arch Linux has a slightly broken systemd. The problem is that SSH to the PiKVM host may not work the first time, but the second or third. The PiKVM build environment contains a workaround for this problem: in the file `/etc/pam.d/system-login` line `-session optional pam_systemd.so` is commented. This does not have any negative impact on the PiKVM functionality, but if you want to, after fixing the systemd (in a couple of months with the next update), you can uncomment this line.
|
||||
|
||||
## Further Help
|
||||
If you have any problems or questions, contact us using Discord: https://discord.gg/bpmXfz5
|
||||
|
||||
Subscribe to our Subreddit to follow news and releases: https://www.reddit.com/r/pikvm
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue