pikvm/docs/wifi.md

# Setting up Wi-Fi

The following describes how to setup a Wi-Fi connection on the default pikvm builds based on Arch Linux.
The process might vary for other Linux distros. We recommend to do this while having a display and keyboard
connected directly to the Raspberry Pi as you will loose network connectivity once you connect to a Wi-Fi.
Alternatively you can connect to the PiKVM via SSH. The built-in Web Terminal (available through the browser) should also work.

!!! warning
    There is nothing more reliable than wired Ethernet, so it's better to use it. But who are we to stop you... :)

!!! note "Moving Wi-Fi settings for OS older than 2021.10.19"
    Starting from 2021.10.19, the old way to configure Wi-Fi using `netctl` is deprecated.
    Instead, it is proposed to use a more native path with `systemd-networkd`, which is already used to configure Ethernet.
    Follow the guide and then delete the old netctl profile:

    ```
    # rw
    # systemctl disable netctl-auto@wlan0.service
    # rm /etc/netctl/wlan0-*
    # ro
    ```


## Step by step

1. Make filesystem writable using `rw` command.

2. Create Wi-Fi settings file `/etc/systemd/network/wlan0.network` with following content:

    ```ini
    [Match]
    Name=wlan0

    [Network]
    DHCP=yes
    DNSSEC=no

    # Use same IP by forcing to use MAC address for clientID
    [DHCP]
    ClientIdentifier=mac
    ```

3. Set network ESSID and password:

    ```
    # wpa_passphrase MyNetwork 'P@assw0rd' > /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
    ```
    
    !!! note "Using Wi-Fi with hidden ESSID"
        Add option `scan_ssid=1` to `/etc/wpa_supplicant/wpa_supplicant-wlan0.conf`

    !!! note "Using 5GHz Wi-Fi in the USA"
        Add option `country=US` to `/etc/wpa_supplicant/wpa_supplicant-wlan0.conf`

4. Enable WPA-supplicant service:
   ```
   systemctl enable wpa_supplicant@wlan0.service
   ```

5. Make filesystem read-only again using `ro` command


## Useful console commands

* `iwconfig` - Manipulate the basic wireless parameters.
* `iwlist` - Allow's you to initiate scanning and list frequencies, bit-rates, encryption keys, etc.
* `iwspy` - Displays per node link quality.
* `iwpriv` - Allow's you to manipulate the Wireless Extensions specific to a driver (private).

!!! example "Some examples"
    ```
    # iw dev wlan0 scan | egrep "signal:|SSID:" | sed -e "s/\tsignal: //" -e "s/\tSSID: //" | awk '{ORS = (NR % 2 == 0)? "\n" : " "; print}' | sort
    ```
    ```
    # iwlist wlan0 scan | egrep "Cell|ESSID|Signal|Rates"
    ```
    ```
    # iwlist wlan0 scan
    ```
    ```
    # iw wlan0 info
    ```


## Additional resources

* [Arch Linux Wiki for systemd-networkd](https://wiki.archlinux.org/title/systemd-networkd)