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

Finalize updating the V2 quickstart guide

This commit is contained in:
Aleksandr Prokudin 2025-04-27 19:55:36 +02:00
parent 8680bade34
commit 3bda5fe5ac
1 changed files with 19 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

142
docs/v2.md
View File

@ -9,8 +9,6 @@ description: Getting started with PiKVM V2
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 16Gb class 10.**
@ -81,8 +79,6 @@ description: Getting started with PiKVM V2
*Kit parts suitable for assembly are also on [sale in Poland](https://3mdeb.com/shop/open-source-hardware/pikvm/).*
-----
## Setting up the hardware
1. **Video capture device:**
@ -150,53 +146,40 @@ description: Getting started with PiKVM V2
## Wiring
Both the HAT and the pre-assembled version require several items available separately:
PiKVM V2 requires several items available separately:
- Ethernet cable
- Optional RJ-45 cable for ATX
- Ethernet cable **(Raspberry Pi 4 only)**
- RJ-45 cable for ATX (optional)
- USB-C cable
- HDMI cable
- USB power adapter
- 5V USB power adapter
Let's connect all the wires before you power up the device.
| Back side | Front side |
|-----------|------------|
| <img src="basic_back.jpg" width="300" /> | <img src="basic_front.jpg" width="300" /> |
1. Connect the HDMI video capture device to the video output port on the target host.
Connect **Ethernet** (**bottom right** on the **front** side) to the network, e.g., to the WiFI router.
2. Using the Y-cable, connect the Pi's OTG port to the USB on the target host.
**HDMI input** (the **top right** on the **back** side) and **OTG** port (USB emulation) should be connected to the computer.
3. **Raspberry Pi 4**: connect **Ethernet** to the network, e.g., to the WiFI router.
Optionally, the **[ATX port](atx_board.md)** can be connected to control the power. There should be no USB hub between PiKVM and the computer, as some UEFI/BIOS cannot detect them at the boot stage.
4. ??? example "Connect the ATX controller if you built it"
{!_diy_wiring_atx.md!}
## Power up
![MISSING POWER IMAGE](power-up.jpg)
Attach the USB-C 5V power supply to the Raspberry Pi.
V3 comes has a USB-C 5V power supply. Attach the appropriate connector on the **front** side (**top left**). Do **not** block the ventilation holes on the sides of the device.
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.
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. Once it's done, the PiKVM will show a greeting on the built-in display.
## Access PiKVM
![MISSING GREETING IMAGE](greeting.jpg)
You need to know PiKVM's IP address in the network to be able to access it. Unlike V3 and V4, PiKVM V2 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.
## Connect and set up
### 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
By default, PiKVM receives a dynamic IP address via DHCP and shows it in the top row of the OLED display:
```console
192.168.0.26
(|) iface: eth0
cpu: 1% mem: 13%
```
* **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`.
@ -274,35 +257,6 @@ For security's sake, it's best to change the default passwords immediately after
![Work remotely](../v4/remote-screen.png)
## Additional setting up
??? note "If your kit includes the OLED display and/or the fan, you'll need to turn them on (this is only needed for the older V3 image for the HAT, in the box image everything is enabled by default)"
Log in to PiKVM and run these commands:
```console
[root@pikvm ~]# rw
[root@pikvm ~]# systemctl enable --now kvmd-oled kvmd-oled-reboot kvmd-oled-shutdown
[root@pikvm ~]# systemctl enable --now kvmd-fan
[root@pikvm ~]# ro
```
??? note "Using Fahrenheit instead of Celsius on the OLED"
```console
[root@pikvm ~]# mkdir -p /etc/systemd/system/kvmd-oled.service.d
```
Create file `/etc/systemd/system/kvmd-oled.service.d/override.conf`:
```ini
[Service]
ExecStart=
ExecStart=/usr/bin/kvmd-oled --clear-on-exit --fahrenheit
```
Then run `systemctl restart kvmd-oled`. In some cases, if you still do not see Fahrenheit being displayed, reboot the device.
## Further steps
1. **Get to know PiKVM OS**: read [this help section](webui.md) to better understand all the possibilities of the web user interface.
@ -312,78 +266,20 @@ For security's sake, it's best to change the default passwords immediately after
- [Update](_update_os.md) the PiKVM operating system.
- [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).
- Enable a microphone for [two-way audio](audio.md).
3. **Configure hardware**:
- Set up [ATX connection](atx_board.md).
- Set up [USB 3.0](usb3v4.md)
-----
## Known issues and limitations
* **Max resolution**. PiKVM V3 supports maximum resolution 1920x1080@50Hz, 60Hz will not work. You can use any other resolution less than the specified one, for example: 1600x1200@60Hz, 1280x720@60Hz, etc. If you have problems with the video, follow [this guide](edid.md).
* **Motherboards compatibility**. There may be compatibility issues with some motherboards, such as HP or DELL. 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. In the latter case, [USB dynamic configuration](usb.md) will solve the problem.
* **HDMI backpowering**. Under specific circumstances, PiKVM may hang during the boot. Turn off the PiKVM, disconnect all cables from it, take a close look at the diagram of its ports and jumpers below, and **remove jumper #14** (it is to the right of the CSI connector, **not available on the V3.2 board**). Then you can connect and power up PiKVM again. (Technical background s described [here](https://www.kickstarter.com/projects/mdevaev/pikvm-v3-hat/posts/3296343).)
* **IO ports**. **Before using GPIO** pins to control a relay, KVM switch, or anything else, be sure to check the HAT pinout below. Many ports are busy with internal functions. Before using them for your own use, you must disable them, otherwise you may damage the device.
??? note "The ports and jumpers diagram"
<img src="v3_features.jpg" />
1. [**ATX controller** interface](atx_board.md) (power on/off, reboot control, PWR and HDD ACT LEDs).
2. **HDMI reset** jumper. Connects GPIO 17 and RESET pin to HDMI capture chip. Currently not used, don't touch it.
3. **SPI and GPIO** for the custom extension boards.
4. **Audio capture** jumpers. Connects I2S pins 18, 19, 20 to HDMI capture chip.
5. **UART access** jumpers. Connects GPIO 14 and 15 to the RJ-45 and USB console ports.
6. **Serial console port** (default: /dev/ttyAMA0, RS232 input, outputs +6V/-6V, for the Raspberry Pi or server console access, use the [Cisco/Mikrotik-style](https://wiki.mikrotik.com/wiki/File:Rj45-pinout.gif.png) cable).
7. **USB-C console port** (shared with #6 above, takes priority over RJ45).
8. **Power** and **activity LEDs**. On the left of the LEDs the watchdog jumper is located. Don't touch it.
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, see [Step 9 of the Basic Setup](#basic-setup). Open: (jumper removed) diode will stop current from HDMI input (backpower will be fixed), closed: (jumper connected to both pins) will allow current from HDMI device.
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).
??? note "The GPIO pinout"
!!! warning
Before proceeding, make sure that the mb you are using has normal ATX headers
* **ATX control**
- `power led = GPIO 24` - Used for reading the host power state.
- `hdd led = 22` - Same for the HDD activity.
- `power switch = 23` - Used for pressing the power button of the host.
- `reset switch = 27` - Same for the reset button.
These pins can't be used for any other purposes even if ATX function is disabled.
* **I2C bus** - `GPIO 2, 3` - Can be used as I2C ONLY (OLED/RTC).
* **1-Wire [19]** - `GPIO 4` - Also available under ATX RJ-45 port (point [19] on the above) as bi-directional buffered open-drain 5V for regular 1-Wire usage.
* **UART** - `GPIO 14, 15` - Can be used as UART only for the serial console. When jumpers [5] are removed, you can connect to pins 14 and 15 directly using GPIO header. Also you can remove jumper [5] and disable UART console in the `/boot/config.txt` and `/boot/cmdline.txt` to use this pins for any purpose. But it's not recommended.
* **Red activity led on the front [8]** - `GPIO 13` - Can be disabled in `/boot/config.txt` and available on the Neo-pixel port [19].
* **PWM fan controller** - `GPIO 12`. Can be used for custom purposes if the fan disconnected and `kvmd-fan` service is stopped.
* **I2S HDMI sound** - `GPIO 18, 19, 20, 21`. Can be used for custom purposes if the `tc358743-audio` overlay in `/boot/config.txt` is disabled **AND** jumpers [4] are removed.
* **USB breaker** - `GPIO 5` - Can't be used for any other purposes.
The standard Raspberry Pi HDMI output (marked as `VIDEO OUT` on the PiKVM case) displays its own PiKVM OS console.
**Max resolution**. PiKVM V2 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).