Initial V3 docs update

- Applied the same general structure as with V4
- Added front matter
- Explained the HAT vs pre-assembled thing
- Moved assembly bits to the assembly instructions page
- Enhanced the assembly instructions page

TODO:

- The Interface part needs to be V3-specific (copy-pasted from V4)
This commit is contained in:
Aleksandr Prokudin 2025-04-23 15:05:22 +02:00
parent 0dd1052b0e
commit 1bd8e46f16
2 changed files with 280 additions and 89 deletions

View File

@ -1,60 +1,226 @@
# PiKVM V3 HAT
---
title: PiKVM V3 HAT & pre-assembled quick start
description: Getting started with PiKVM V3 & pre-assembled
---
# PiKVM V3 HAT & pre-assembled quick start
<img src="assembled.jpg" width="400" />
PiKVM is a feature-rich, production grade, open-source, Raspberry Pi based KVM over IP device. It allows you to turn on/off or restart your computer, configure the UEFI/BIOS, and even reinstall the OS using the Virtual CD-ROM or Flash Drive.
## Installation requirements
You can use your remote keyboard and mouse or PiKVM can simulate a keyboard, mouse, and a monitor, which are then presented in a web browser as if you were working on a remote system directly.
??? note "If you have an assembly kit, you will need the following things"
* Raspberry Pi 4 with 1Gb RAM or more.
* Heat sinks (Optional)
* MicroSD card (at least 16Gb, class 10 recommended).
* USB-C to USB-A cable.
* HDMI cable.
* <a target="_blank" href="../atx_board/straight.png">Straight Ethernet cable.</a>
* Power supply unit (5.1V 3A USB-C, recommended by the Raspberry Pi).
PiKVM V3 is available as an assembly kit (HAT) and as a pre-assembled unit in a metallic box. The two versions have the same ports and functionality.
!!! tip
* Please review the back of the box. All parts are required before the HAT is fully functional.
* The USB-C bridge is located in with the ATX end which includes a pink foam spacer.
* Please assemble the HAT onto the RPi and test all of the parts before installing in the case, it's easier to install in the case than to dissasemble it.
* If going from a V2 to a V3, the splitter is **no longer needed**.
## What's in the box
=== "HAT"
## Basic setup
- The PiKVM V3 HAT for Raspberry Pi 4
- USB-C bridge board
- ATX adapter board with mounting brackets and motherboard interface wiring
- 2x Flat CSI-2 cables
- 7x jumpers, assorted colors
- 8x brass standoffs
- 8x screws
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.
=== "Pre-Assembled"
1. **[Flash the memory card.](flashing_os.md){target=_blank}**. Please use the V3 image, V2 image is not compatible.
- PiKVM V3.3 pre-assembled
- ATX adapter board with mounting brackets and motherboard interface wiring
- A 32 GB MicroSD card pre-imaged with the PiKVM OS
2. **Build PiKVM** according to the video instruction or review the [illustrated instructions](v3_illustrated_install_instructions.md):
??? tip "Video Guide: Metal case step by step"
NOTE: OLED will not light up till step 5 is performed, video was performed after it was already configured, heat sinks NOT included.
![type:video](https://www.youtube.com/embed/jdqiwHKQcD4)
## HAT setup
??? tip "Video Guide: Step by step with HAT device with or without the 3D-printed case"
![type:video](https://www.youtube.com/embed/-SRL92VJ870)
If you have an assembly kit without a metal case, you can use our free 3D printing case drawing:
!!! warning
OLED glass can crack if force is used to install it, please handle with care and rock back and forth on the pins side to install.
- [V3.2](stl/v3.2/index.md){target=_blank} is the pre-release model.
- [V3.3](stl/v3.3/index.md){target=_blank} is the Kickstarter/Store model.
Once you have that, do the following:
3. **Connect PiKVM** to the computer according to the diagram below:
1. **[Flash the memory card](flashing_os.md){target=_blank}**. Please use the V3 image, V2 image is not compatible.
| Back side | Front side |
|-----------|------------|
| <img src="basic_back.jpg" width="300" /> | <img src="basic_front.jpg" width="300" /> |
2. **Build PiKVM** according to the [illustrated instructions](v3_illustrated_install_instructions.md).
* **HDMI input** and **USB emulation** port must be connected to the computer. 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. On the HDMI the HAT, like the CSI bridge, supports 1080p50Hz or 720p60Hz or lower.
## Interface
* Connect **Ethernet** to the network and **USB power** to the Raspberry Pi power supply.
=== "Front view"
4. **Carefully read and follow [the "First steps" guide](first_steps.md){target=_blank}.**<br>
It describes how to find PiKVM on the network, how to log in there, change passwords, and so on.<br>
**Follow the steps described there and come back to this page.**
![MISSING FRONT VIEW IMAGE](v4-plus-front-view.svg){ width="300" }
5. ??? 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)"
1. Activity LED (Red)
2. Power LED (Green)
3. Power Input 5.1V 3A
4. Power Input 12V 2A **(V4 Plus only)**
5. Micro SD card slot
6. USB 3.0 port 1 **(V4 Plus only)**
7. RJ45 Serial console port **(V4 Plus only)**
8. RJ45 1Gb Ethernet port
9. Serial console active LED / Beacon LED (Green)
10. USB 2.0 Serial console port
=== "Rear view"
![MISSING REAR VIEW IMAGE](v4-plus-front-view.svg){ width="300" }
1. Beacon LED
2. USB 2.0 OTG connector
3. Mount holes for WiFi SMA antenna connector **(only one in V4 Mini)**
3. RJ45 ATX control port
4. USB 3.0 port 2 **(V4 Plus only)**
5. HDMI video output port 1 **(V4 Plus only)**
6. HDMI video output port 2 **(V4 Plus only)**
7. Optional antennas mounting holes
8. Video source ready status LED
9. HDMI video input port
10. Video capture ready status LED
11. Ventilation holes
=== "Right view"
![MISSING SIDE VIEW IMAGE](v4-plus-front-view.svg){ width="300" }
1. Ventilation holes
2. Service switches
3. Kensington Security Slot
=== "Top view"
![MISSING TOP VIEW IMAGE](v4-plus-front-view.svg){ width="300" }
1. Display
## Wiring
Both the HAT and the pre-assembled version require several items available separately:
- Ethernet cable
- Optional RJ-45 cable for ATX
- USB-C cable
- HDMI cable
- 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" /> |
Connect **Ethernet** (**bottom right** on the **front** side) to the network, e.g., to the WiFI router.
**HDMI input** (the **top right** on the **back** side) and **OTG** port (USB emulation) should be connected to the computer.
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.
## Power up
![MISSING POWER IMAGE](power-up.jpg)
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. Once it's done, the PiKVM will show a greeting on the built-in display.
![MISSING GREETING IMAGE](greeting.jpg)
## 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%
```
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)
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 desktop, connect to the PiKVM over SSH, or log out:
![Initial UI](../v4/initial-ui.png)
### Change the default passwords
For security's sake, it's best to change the default passwords immediately after running PiKVM for the first time. 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:
![MISSING SCREENSHOT](../v4/pikvm-web-terminal-start.png)
2. Gain 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 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 desktop.
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)
## 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:
@ -65,7 +231,7 @@ If you have a kit without a metal case, you can use our free 3D printing case dr
[root@pikvm ~]# ro
```
6. ??? note "Using Fahrenheit instead of Celsius on the OLED"
??? note "Using Fahrenheit instead of Celsius on the OLED"
```console
[root@pikvm ~]# mkdir -p /etc/systemd/system/kvmd-oled.service.d
@ -81,42 +247,35 @@ If you have a kit without a metal case, you can use our free 3D printing case dr
Then run `systemctl restart kvmd-oled`. In some cases, if you still do not see Fahrenheit being displayed, reboot the device.
7. **Just reminding again:**
## Further steps
{!_passwd.md!}
1. **Get to know PiKVM OS**: read [this help section](webui.md) to better understand all the possibilities of the web user interface.
8. **Try to manage the computer using PiKVM with the Web Interface.**<br>
Make sure that you get an image and both 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).
2. **Update and customize the system**:
9. ??? note "Check the HDMI backpowering problem. ONLY applicable under specific circumstances. NOT getting NO SIGNAL."
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. If you are interested in the technical background, it is described [here](https://www.kickstarter.com/projects/mdevaev/pikvm-v3-hat/posts/3296343). Also, just for information: not a single case of negative consequences from the removal of the jumper has been recorded.
- [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).
- Enable [HDMI pass-through](pass.md).
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.
3. **Configure hardware**:
11. Enable [audio speakers and microphone](audio.md){target=_blank} if you want.
- Set up [ATX connection](atx_board.md).
- Configure [DIP switches](dip_switches.md)
- Install and set up [Wi-Fi antenna](wifi.md).
- Install and set up [LTE/5G modem](modem.md) (**only for PiKVM V4 Plus**).
- Set up [USB 3.0](usb3v4.md) (**only for PiKVM V4 Plus**).
12. Configure access to PiKVM from the Internet using [port forwarding](https://docs.pikvm.org/port_forwarding)
or [Tailscale VPN](https://docs.pikvm.org/tailscale), if you need it.
-----
## Known issues and limitations
13. Explore the features of PiKVM using the site's table of contents and have fun!
* **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.
## Video modes
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).
## ATX connection
[See here](atx_board.md).
## IO ports and jumpers
??? note "See the diagram"
??? 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).
@ -139,7 +298,7 @@ PiKVM V3 supports maximum resolution 1920x1080@50Hz, 60Hz will not work. You can
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 "GPIO pinout"
??? note "The GPIO pinout"
!!! warning
Before proceeding, make sure that the mb you are using has normal ATX headers
@ -168,12 +327,11 @@ PiKVM V3 supports maximum resolution 1920x1080@50Hz, 60Hz will not work. You can
The standard Raspberry Pi HDMI output (marked as `VIDEO OUT` on the PiKVM case) displays its own PiKVM OS console.
## Basic troubleshooting
{!_basic_troubleshooting.md!}
-----
## Getting user support
## Known issues and limitations
* 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 great 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. In the last case, [USB dynamic configuration](usb.md) will solve the problem.
* Pre-release V3.2 board (NOT Kickstarter/Store edition) doesn't have HDMI backpowering workaround jumper.
If something doesn't work, check out our [FAQ](faq.md). Otherwise, head straight to our [Discord chat](https://discord.gg/bpmXfz5).

View File

@ -1,8 +1,41 @@
# Step 1
---
title: Assembling PiKVM V3 HAT
description: How to build PiKVM V3 HAT from the assembly kit
---
Remove contents from box.
# Assembling PiKVM V3 HAT
PiKVM V3 HAT is an assembly kit. You can build it without any case whatsoever, order a metallic case separately, or 3D-print a case yourself. These videos cover all those use cases.
??? tip "Video guide: Assembly with a metal case"
NOTE: OLED will not light up till step 5 is performed, video was performed after it was already configured, heat sinks NOT included.
![type:video](https://www.youtube.com/embed/jdqiwHKQcD4)
??? tip "Video guide: Assembly with or without a 3D-printed case"
![type:video](https://www.youtube.com/embed/-SRL92VJ870)
## Step 1
Get the parts that are not in the assembly kit:
* Raspberry Pi 4 with 1Gb RAM or more
* Heat sinks (Optional)
* MicroSD card (at least 16Gb, class 10 recommended)
* USB-C to USB-A cable
* HDMI cable
* [Straight Ethernet cable](./atx_board/straight.png)
* Power supply unit (5.1V 3A USB-C, recommended by the Raspberry Pi)
!!! tip
* Please review the back of the box. All parts are required before the HAT is fully functional.
* The USB-C bridge is located in with the ATX end which includes a pink foam spacer.
* Please assemble the HAT onto the RPi and test all of the parts before installing in the case, it's easier to install in the case than to dissasemble it.
* If going from a V2 to a V3, the splitter is **no longer needed**.
## Step 2
Remove contents from assembly kit box:
# Contents:
* 8x M.2 5x12mm screws for the case
* 4x M.2 5x12mm screws for the fan
* 4x bolts for the fan
@ -16,9 +49,9 @@ Remove contents from box.
* 2x small FCC ribbon cables
* 1x small rubber square that break out to 4x small rubber feet
!!! warning "OLED is sensitive to pressure, do NOT push down on the very thin glass as it will crack thereby making the OLED non-functional"
!!! warning "OLED is sensitive to pressure, do NOT push down on the very thin glass as it will crack and become non-functional"
# Step 2
## Step 3
Take bottom part of the case, insert the RPI4 into the bottom case at an angle, you will need to flex the other side ever so slightly to get it to slot in.
@ -26,7 +59,7 @@ Take bottom part of the case, insert the RPI4 into the bottom case at an angle,
??? note "IF you bought heatsink's (sold seperatly), it's advised to install them now before installing the HAT"
# Step 3
## Step 4
Insert HAT at the same angle, take care to line up the pins on the Rpi with the HAT pin sleeve, the trick to this is to push the Rpi all of the way to the left then all of the way to the right for proper alignment, do NOT force till the pins are aligned. If properly aligned the pins will match up without issue.
@ -36,7 +69,7 @@ Insert HAT at the same angle, take care to line up the pins on the Rpi with the
??? note "ALTERNATIVE: As an alternative to the above, you can pre assemble the hat+fcc cable onto the RPI4, then insert them into the bottom portion of the case however you will need to flex the sides more whereby creating a bigger gap when fully assembled."
# Step 4
## Step 5
There are 2 ways to insert the FCC cable, you can add it when you insert the RPI in Step 2 OR wait till you also have the HAT installed and slide it into the slot.
@ -44,9 +77,9 @@ There are 2 ways to insert the FCC cable, you can add it when you insert the RPI
??? note "The blue stripes on the ends of the cable will ALWAYS face the side that will be used to tighten the FCC to the camera port or have it positioned towards the power - Ignore the smaller FCC cable that plugs into the USB, was phased out during the KS campaign. This image was used as a means of illustrating FCC placement and orientation"
# Step 5
## Step 6
Install USB-C bridge.
Install the USB-C bridge.
??? note "This is packaged with the ATX board"
<img src="PiKVM_ATX_Packaging.png" width="400" />
@ -56,13 +89,13 @@ Install USB-C bridge.
??? note "If you do not install this bridge, mouse/kb will not work"
??? note "HAT will still power on without this bridge installed"
# Step 6
## Step 7
Turn the bottom of the case upside down, install the 2 bottom plastic risers, it's best to install in a wing formation. Top first by inserting the top screws then slide the bottom part aligning the plastic to the holes then inserting the screws. At this point its OK to tighten the bottom screws. There is no need to use force, just tighten enough to prohibit movement.
<img src="HAT_install_plastic_risers_bottom.jpg" width="400" />
# Step 7
## Step 8
Take the plastic OLED holder, turn the OLED over where the back side is facing you and insert at an angle so as to create a space between the OLED and holder arm, take a flat head screwdriver (medium normal) and twist it enough so you can clear the electronics on the bottom of the OLED and continue to gently slide in the remaining OLED till its fully inserted.
@ -70,25 +103,25 @@ Take the plastic OLED holder, turn the OLED over where the back side is facing y
!!! warning "Be careful on handling this display, slight pressure will damage the OLED, however in the event that this does happen, replacements are cheap and can be found in most electronic stores or Amazon, look for any IIC (I2C) .91 inch display for Arduino"
# Step 8
## Step 9
Insert the OLED holder with the OLED display into the plug by gently rocking it back and forth till it's fully inserted.
<img src="HAT_install_OLED_holder.jpg" width="400" />
# Step 8a
## Step 10
Install plastic spacer.
<img src="HAT_install_plastic spacer.jpg" width="400" />
# Step 9
## Step 11
Install the screws and bolts to secure the fan, it does not matter the orientation of the fan, push or pulling air will result in the same behavior, its personal preference.
<img src="HAT_install_fan_to_top.jpg" width="400" />
# Step 10
## Step 12
Insert the fan leads and align Red with positive and Black with negative.
@ -96,12 +129,12 @@ Insert the fan leads and align Red with positive and Black with negative.
!!! warning "You can damage the fan if installed incorrectly"
# Step 11
## Step 13
Install the top of the case to the bottom, use the 4 remaining screws to secure the top.
<img src="HAT2_insert_top_part_of_case.jpg" width="400" />
# Step 12
## Step 14
Please follow the V3 guide and First Steps guide to activate your PiKVM.
Please follow the [V3 quick start](../v3/) guide to activate your PiKVM.