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 board connection).
    * Power supply unit (5.1V 3A USB-C, recommended by the Raspberry Pi).

!!! tip "Before assembling"
    * Please review the back of the box. All parts are required before hat is fully functional.
    * The USB-C Bridge is located in with the ATX end which includes a pink foam spacer.
    * Please assemble 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**.


## 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.

!!! warning "Please use the v3 image, V2 image is not compatible"

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

2. **Build PiKVM** according to the video instruction or review the [illustrated instructions](v3_illustrated_install_instructions.md):
:   ??? tip "With the metal case - NOTE: OLED will not light up till step 5 is performed, video was performed after it was already assembled"
        ![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)

!!! 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."


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. On the HDMI the HAT, like the CSI bridge, supports 1080p50Hz or 720p60Hz or lower.

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

4. **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**.

5. ??? 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 kvmd-oled-reboot kvmd-oled-shutdown
    # systemctl enable --now kvmd-fan
    # ro
    ```
    If you want the temperature to be displayed and in Fahreneit on the OLED and you do not want to update the whole system, then you will need to do this first after going to root:
    ```
    # rw
    # pacman -Syy
    # pacman -S kvmd-oled
    # systemctl enable --now kvmd-oled kvmd-oled-reboot kvmd-oled-shutdown
    ```
    
    If you want the temperature to be displayed in Fahrenheit on the OLED, make the following:
    ```
    # mkdir -p /etc/systemd/system/kvmd-oled.service.d
    ```
    Create file `touch or nano /etc/systemd/system/kvmd-oled.service.d/override.conf`:
    ```ini
    [Service]
    ExecStart=
    ExecStart=/usr/bin/kvmd-oled --height=32 --clear-on-exit --fahrenheit
    ```
    And run `systemctl restart kvmd-oled`. In some cases, if you still do not see Fahrenheit being displayed, reboot the pikvm.

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

7. **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).

8. ??? 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.

9. !!! 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

To manage the power of your computer, you will need to install an ATX adapter board inside the case and connect it to the motherboard.

1. Connect the rainbow wires as follows to the board. Optionally print [the mounting plate](stl/atx/index.md){target=_blank} for the PCI slot on a 3D-printer. Assemble everything like on pictures below. Secure wires in any convenient way (we used soft ties).

    ??? example
        <img src="atx_board_1.jpg" />

        <img src="atx_board_2.jpg" />

        <img src="atx_board_3.jpg" />

2. Find the pins on the motherboard responsible for connecting the buttons and LEDs of the front panel of the case. Usually wires and connectors on the motherboard have designations. If you're not sure, check the documentation on your motherboard.

    ??? example
        <img src="atx_board_4.jpg" />

        <img src="atx_board_5.jpg" />

3. Place the ATX board nearby and, focusing on the signatures, connect the male pins to the female pin of the front panel wires, observing the polarity (the polarity is indicated on the ATX board).

    ??? example
        <img src="atx_board_6.jpg" />

4. Repeat the procedure with the female pin of the ATX board by connecting them to the motherboard connector. Check the documentation on your motherboard.

    ??? example
        <img src="atx_board_7.jpg" />

5. Install the ATX board into the PCI slot of the case and fix it with a screw, or use a different mounting method at your discretion.

    ??? example
        <img src="atx_board_8.jpg" />

        <img src="atx_board_9.jpg" />

6. Arrange the wires in a way that is convenient for you and fix them if necessary.

    ??? example
        <img src="atx_board_10.jpg" />

7. Connect the ATX board to PiKVM using a [straight Ethernet cable](https://www.home-network-help.com/straight.html).

    ??? example
        <img src="basic_back.jpg" />


## 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.