public_git
/
pikvm
mirror of https://github.com/pikvm/pikvm.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
pikvm/docs/v1.md

322 lines
11 KiB
Markdown
Raw Blame History

---
title: DIY PiKVM V1 quickstart guide
description: Getting started with PiKVM V1
---
# DIY PiKVM V1 quickstart guide
!!! tip "So many choices!"
There are many different options with sub-items, so you can choose what will suit you.<br>
However, we marked the recommended way by sign **`✮ ✮ ✮`**
-----
## Required parts
1. **MicroSD card minimum 8Gb class 10.**
2. **[Official USB-Micro Power Supply](https://www.amazon.com/Capture-Streaming-Broadcasting-Conference-Teaching/dp/B09FLN63B3)**.
3. **Raspberry Pi board:**
* **[✮ ✮ ✮ Raspberry Pi 3](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/)**.<br>
* ... or [Raspberry Pi 2](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/).<br>
*Does not support H.264 even with HDMI-CSI bridge.*
* ... or [Raspberry Pi Zero 2 W](https://www.raspberrypi.com/products/raspberry-pi-zero-2-w/).<br>
*Compact and cheap, but not so reliable solution because of lack of the wired Ethernet.
Note that the better way to use Pi Zero is making [PiKVM V2](v2.md) - it supports more USB features.*
4. **Video capture device:**
* **[✮ ✮ ✮ HDMI-CSI bridge based on TC358743 chip](https://www.amazon.com/waveshare-HDMI-CSI-Camera-Adapter/dp/B08TR7R6RL/)**.<br>
*Supports H.264 video encoding on Raspberry Pi 3, automatic resolution selection and the lowest possible latency.*
* ... or [HDMI-USB dongle](https://www.amazon.com/Capture-Streaming-Broadcasting-Conference-Teaching/dp/B09FLN63B3).<br>
*Only heavy MJPEG video, no resolution detection, big latency compared to HDMI-CSI.
Some users report hardware problems: the dongle may not work in the BIOS or simply stop working after a while.
It's a black box, and no one knows what's inside it. If you have problems with it, it will not be possible to fix them.*
5. **The Pico HID Keyboard & mouse emulator:**
{!_pico_hid_parts.md!}
6. **Board-specific parts:**
!!! success "✮ ✮ ✮ "Nothing special for Raspberry Pi 2 or 3"
??? note "Raspberry Pi Zero 2 W"
??? note "✮ ✮ ✮ HDMI-CSI bridge"
* *x1* [Raspberry Pi Zero Camera Cable](https://www.amazon.com/Arducam-Raspberry-Camera-Ribbon-Extension/dp/B085RW9K13). *Not compatible with Auvidea B101*.
??? note "... or HDMI-USB dongle"
* *x1* USB-A socket to USB-Micro adapter (female-male).
7. **Optional features:**
??? success "✮ ✮ ✮ ATX controller to manage the target host's power"
{!_diy_parts_atx.md!}
??? note "PS/2 Keyboard & mouse"
The use of PS/2 is intended for advanced users. Check out the additional list of details in advance
in the [corresponding paragraph](pico_hid.md#ps2-keyboard-mouse) of the Pico HID manual.
??? note "VGA video capture"
If you want to capture VGA from your server instead of HDMI,
buy the [VGA-to-HDMI converter](https://aliexpress.com/item/3256801728005613.html).
Some converters have issues with not supporting all resolutions and refresh rates.
-----
## Setting up the hardware
1. **Video capture device:**
??? success "✮ ✮ ✮ HDMI-CSI bridge"
{!_diy_setup_video_csi.md!}
??? note "... or HDMI-USB dongle"
??? note "Raspberry Pi 2 & 3"
{!_diy_setup_video_usb.md!}
??? note "Raspberry Pi Zero 2 W"
Connect the USB dongle to USB-to-Micro adapter, and connect it to the USB port marked as `USB` (not `PWR`)
on the Pi Zero board:
<img src="../_diy/usbcap_zero2w.jpg" width="400"/>
2. **The Pico HID and ATX controller:**
Connect all the parts according to this scheme:
??? success "✮ ✮ ✮ With ATX controller"
??? example "Simple wiring diagram"
<img src="../v1/v1_breadboard.png" />
??? example "Electrical schematic diagram for advanced users"
<a target="_blank" href="../v1/v1_scheme.png"><img src="../v1/v1_scheme.png" /></a>
??? note "... or without ATX controller"
??? example "Simple wiring diagram"
<img src="../pico_hid/basic_breadboard.png" />
??? example "Electrical schematic diagram for advanced users"
<img src="../pico_hid/basic_scheme.png" />
3. **[Flash firmware to the Pico HID.](pico_hid.md){target=_blank}**
4. **[Flash the memory card with PiKVM OS](https://docs.pikvm.org/flashing_os){target=_blank}** and insert it to Raspberry Pi.
-----
## Wiring
!!! warning
Double check that the circuit is assembled correctly to avoid any damage of the hardware.
PiKVM V1 requires several items available separately:
- Ethernet cable **(Raspberry Pi 2 and 3 only)**
- HDMI cable
Let's connect all the wires before you power up the device.
1. Connect the HDMI video capture device to the video output port on the target host.
2. Connect the Pico HID to the USB port on the target host.
3. **Raspberry Pi 2/3**: connect **Ethernet** to the network, e.g., to the Wi-Fi router.
4. ??? example "Connect the ATX controller if you built it"
{!_diy_wiring_atx.md!}
-----
## Power up
If everything is assembled correctly, attach the power supply to the Raspberry Pi.
After turning on the power, PiKVM OS generates unique SSH keys and certificates and performs all necessary operations on the memory card. It takes a few minutes.
**Do not turn off the device until it's fully booted for the first time.**
-----
## Configure the display
The operating system on your remote computer will treat PiKVM as an additional display and use it in the Extend mode by default. That's why you will see an empty desktop when you first connect.
To avoid that, go to the display settings in your remote computer's operating system and enable the mirror mode for the external screen that you operating system identifies as PiKVM. Refer to your operating system's documentation on that.
-----
## Access PiKVM
You need to know PiKVM's IP address in the network to be able to access it. Unlike [PiKVM V3](v3.md) and [V4](v4.md), PiKVM V1 doesn't have an OLED to display the IP address it receives automatically. You need to discover it manually. There are several ways to do that.
* **Common way:** Open the web interface of your router and find the list of issued IP addresses there.
* **Linux-only:** Use the `arp-scan --localnet` command.
* **Linux, MacOS, Windows:** Download and run [Angry IP Scanner](https://angryip.org).
* **Windows PowerShell:** Use the `arp -a` command.
Let's assume that PiKVM has received the address `192.168.0.26` and has also been assigned a hostname `pikvm`.
Type the URL in the browser's address bar and press **Enter**: https://192.168.0.26/ or https://pikvm/.
![Login screen](../v4/login-prompt.png){ width="450" }
Submit the default credentials and click **Login**:
- Username: `admin`
- Password: `admin`
- 2FA Code: disabled by default, skip this field
You will see the initial dashboard screen of the PiKVM where you can access the remote host, connect to the PiKVM command line, or log out:
![Initial UI](../v4/initial-ui.png){ width="450" }
### Change the default passwords
For security's sake, it's best to change the default passwords immediately after running PiKVM for the first time.
!!! danger "Passwords are important!"
Please ensure that you change **both** passwords: for Web UI access and for the Linux superuser (root).
To do that:
1. On the initial dashboard screen, click the **Terminal** button to open the web terminal. You will see this command line interface:
![PiKVM WebTerm](../v4/pikvm-web-terminal-start.png){ width="450" }
2. Gain Linux superuser privileges:
```console
$ su -
```
When prompted for password, use `root`.
3. Run `rw` to change the access to the SD card to the write mode:
```console
[root@pikvm ~]# rw
```
4. Change the password for the Linux superuser:
```console
[root@pikvm ~]# passwd root
```
Submit the new password, retype it the second time to confirm, press **Enter**, and you should see this:
```console
passwd: password updated successfully
```
5. Change the password for web access:
```console
[root@pikvm ~]# kvmd-htpasswd set admin
```
Submit the new password, retype it the second time to confirm, and press **Enter**.
6. Run `ro` to change the access to the SD card back to the read-only mode:
```console
[root@pikvm ~]# ro
```
7. Press **Ctrl+D** or type "exit" and press **Enter** to drop the root privileges.
8. Go back one page in the browser. You should be back to the initial dashboard screen.
### Access the remote system
1. On the initial dashboard screen, click the **KVM** button to access the remote host.
2. You should now see the host system's display and interact with it remotely using a keyboard and a mouse.
![Work remotely](../v4/remote-screen.png){ width="450" }
-----
## Important next steps
- **We strongly recommend to update the PiKVM OS** after the first launch:
{!_update_os.md!}
- Learn about basics of **PiKVM OS Configuration**: where to find configs, how to edit the, etc.
{!_config.md!}
- **Get to know PiKVM Web UI**: read [this help section](webui.md) to better understand all the possibilities of the web user interface.
- Tune the HDMI dongle capture device if you're using it:
??? note "Persistent HDMI cable connection with USB dongle"
Many USB 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:
```console
[root@pikvm ~]# rw
```
* Edit file `/etc/kvmd/override.yaml` and add these lines:
```yaml
kvmd:
streamer:
forever: true
cmd_append: [--slowdown]
```
* Finish:
```console
[root@pikvm ~]# ro
[root@pikvm ~]# systemctl restart kvmd
```
* Check that everything is working.
-----
## Further recommendations
- [Harden the remote access](auth.md) by enabling 2FA and setting session expiration time.
- Configure access to PiKVM from the Internet using [port forwarding](port_forwarding.md) or [Tailscale VPN](tailscale.md).
- [Learn](config.md) how configuration files are structured.
- Read how PiKVM is [identified](id.md) on the target host.
-----
## Known issues and limitations
* **Max resolution**.<br>PiKVM V1 with CSI bridge can only handle the maximum resolution 1920x1080@50Hz, 60Hz is not supported due hardware limitation. You can use any other resolution less than the specified one, for example 1280x720@60Hz. If you have any problems with video on CSI bridge, follow [this guide](edid.md).
-----
## Basic troubleshooting
{!_basic_troubleshooting.md!}
-----
## Getting user support
If something doesn't work, check out our [FAQ](faq.md). Otherwise, head straight to our [Discord chat](https://discord.gg/bpmXfz5).
Reference in New Issue View Git Blame Copy Permalink