pikvm/docs/v3.md

# PiKVM v3 HAT

<img src="assembled.jpg" width="400" />

## Installation requirements

??? note "If you have an assembly kit, you will need the following things"
    * Raspberry Pi 4 with 1Gb RAM or more.
    * MicroSD card (at least 16Gb, class 10 recommended).
    * USB-C to USB-A cable.
    * HDMI cable.
    * [Straight Ethernet cable](https://www.home-network-help.com/straight.html) (for the ATX expansion board connection).
    * Power supply unit (5.1V 3A USB-C, recommended by the Raspberry Pi).


## Basic setup

If you have a kit without a metal case, you can use our free 3D printing case drawing: [v3.3](stl/v3.3/index.md){target=_blank} for the Kickstarter/Store model, [v3.2](stl/v3.2/index.md){target=_blank} for the pre-release.

1. **[Flash the memory card.](flashing_os.md){target=_blank}**

2. **Build PiKVM** according to the video instruction:
:   ??? tip "With the metal case"
        ![type:video](https://www.youtube.com/embed/jdqiwHKQcD4)
:   ??? tip "Device with or without the 3D-printed case"
        ![type:video](https://www.youtube.com/embed/-SRL92VJ870)

3. **Connect PiKVM** to the computer according to the diagram below:

    | Back side | Front side |
    |-----------|------------|
    | <img src="basic_back.jpg" width="300" /> | <img src="basic_front.jpg" width="300" /> |

    * **HDMI input** and **USB emulation** port must be connected to the computer. **ATX** too, but it's optional, [read below](#atx-connection). There should be no USB hub between PiKVM and the computer, as some UEFI/BIOS cannot detect them at the boot stage.

    * Connect **Ethernet** to the network and **USB Power** to the Raspberry Pi power supply.

4. **Turn on the power supply.**

5. **Carefully read [the "First steps" guide](first_steps.md){target=_blank}** - how to find a device on the network, how to log in there, change passwords, and so on. **Follow the steps described there and come back here**.

6. ??? note "If your kit includes the OLED display and/or the fan, you'll need to turn them on"
    Log in to PiKVM and run these commands:
    ```
    # rw
    # systemctl enable --now kvmd-oled
    # systemctl enable --now kvmd-fan
    # ro
    ```

7. !!! danger "Just reminding again: CHANGE THE PASSWORDS! :)"
    How to do this was written in [the "First steps" guide](first_steps.md){target=_blank}

8. **Try to manage the computer using PiKVM with the Web Interface.** Make sure that you see the image, and the keyboard and mouse are working. If something doesn't work, check out our [FAQ](faq.md) (it's really useful). If nothing helped, you can get support in our [Discord chat](https://discord.gg/bpmXfz5).

9. ??? note "Check the HDMI backpowering problem"
    Try restarting PiKVM using the `reboot` command executed in the terminal. If PiKVM hangs during boot (you can't get the Web Interface for a long time), then you are faced with this rare problem. **Don't worry, it's easy to fix.** Turn off the PiKVM, disconnect all cables from it, take a close look at the [diagram of its ports and jumpers](#io-ports-and-jumpers), and **remove jumper #14** (it is to the right of the CSI connector). Then you can connect and power up PiKVM again. Now everything will be fine.

10. !!! warning "IO ports and other things"
    **Before using GPIO** pins to control a relay, KVM switch, or anything else, be sure to [check the HAT pinout](#io-ports-and-jumpers). Many ports are busy with internal functions. Before using them for your own use, you must disable them, otherwise you may damage the device.


## ATX connection

**======================== TODO =========================**


## IO ports and jumpers

??? note "See the diagram"
    <img src="v3_features.jpg" />

    1. **ATX controller** interface (power on/off, reboot control, PWR and HDD ACT LEDs).
    2. **HDMI reset** jumper.
    3. **SPI and GPIO** for the custom extension boards.
    4. **Audio capture** jumpers.
    5. **UART access** pins.
    6. **Serial console port** (for the Raspberry Pi or server console access).
    7. **USB-C console port**.
    8. **Power** and **activity LEDs**.
    9. **USB-C power input**.
    10. **I2C display connector**.
    11. **Alternate +5V power input/output** header pins.
    12. **RTC clock** supercapacitor (rechargeable).
    13. **FAN connector** - PWM controlled.
    14. **CSI-2 interface** and **HDMI backpowering** jumper.
    15. Built-in **power splitter** port.
    16. **HDMI capture port** (max 1080p @ 50Hz) with **sound capture** support.
    17. **USB emulation pins** for alternative access.
    18. **USB-C emulation port** - this port is doing the emulation of a USB keyboard, mouse, Virtual CD-ROM or USB Flash Drive, USB-Ethernet, USB-Serial port and a lot of other Linux-supported features.
    19. **1-Wire** & **Neo-pixel** interface (under, advanced user feature).

**================ PINOUT TODO ====================**

??? note "ATX RJ-45 pinout"
    The pinout of the RJ-45 connector is the same on the AT and ATX adapter.

    <img src="rj45.jpg" />

??? note "ATX LED wiring example"
    <img src="atx_led.jpg" />


## Known issues and limitations
* The actual frame rate of the image received via HDMI will depend on the network bandwidth, resolution and the load on the Raspberry Pi. This is usually **~20-24 FPS for 1080p over LAN**.
* There may be **compatibility** issues with some motherboards (such as **HP** or **DELL**) which are the same as those that exist with PiKVM v2. Not everything is perfect, but if you have already used PiKVM v2 - our new v3 will work perfectly and please you. If there is no image from the BIOS, you can fine-tune the HDMI settings, but it is possible that the Mass Storage devices will not be available in the BIOS.
* Pre-release v3.2 board (NOT Kickstarter/Store edition) doesn't have HDMI backpowering workaround jumper.