.. include:: /keyword.rst

=====
Wi-Fi
=====

.. toctree::
    :hidden:

    Genio 350-EVK <Wi-Fi-350-evk>
    Genio 510/700-EVK <Wi-Fi-700-evk>
    Genio 1200-EVK <Wi-Fi-1200-evk>
    MT7663 Module <Wi-Fi-Module-MT7663>
    MT7921 Modules <Wi-Fi-Module-MT7921>

--------------------------------

This chapter describes common information and instructions of Wi-Fi on |IOT-YOCTO|,
such as command to configure DHCP or static IP and so on.

But Wi-Fi on different platforms may have some platform-specific instructions or test results. For example, you
will get different throughput on different platforms.

--------------------------------

.. contents:: Sections
    :local:
    :depth: 3

.. _Station (Client) mode:

Station (Client) mode
=====================

Connect to a Wi-Fi AP
---------------------

There are two methods to connect evaluation board to a Wi-Fi network: **NetworkManager** and **wpa_supplicant**.

`NetworkManager` is a high level service and should be used when possible, since it automatically configures `wpa_supplicant` and other system states.

Connect to a network via NetworkManager
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

First, make sure service **NetworkManager** (``NetworkManager``) is running:

.. prompt:: bash

    systemctl status NetworkManager.service

You should see an output line like this:

.. code::

    Active: active (running)

If not, launch NetworkManager:

.. prompt:: bash

    systemctl start NetworkManager.service


Now, please remove the old config file from ``/etc/wpasupplicant.conf``, if `wpa_supplicant` has been used before.
This configuration file interferes NetworkManager.

.. prompt:: bash

    rm -rf /etc/wpasupplicant.conf

Finally, run ``nmcli`` command to configure and connect the board to WIFI with NetworkManager:

.. note::

    Interface name **<IFNAME>**	may be different by modules. It should be **wlan0** or **wlp1s0** usually. The name depends on the driver default when the module is probed.

.. prompt:: bash

    nmcli device wifi connect <SSID> ifname <IFNAME> password <PASSWD>

``nmcli`` would report the connection result with following log:

.. code:: text

    Device 'wlan0' successfully activated with 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'.

If everything works fine, you should be able to connect to the internet:

.. prompt:: bash $ auto

    # Check if the board is actually connected to the internet.
    ping www.google.com

Connect to a network via `wpa_supplicant`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use this method only if you want to avoid using NetworkManager.

First, stop NetworkManager:

.. prompt:: bash

    systemctl stop NetworkManager.service

To double check that NetworkManager has been stopped:

.. prompt:: bash
    
    systemctl status NetworkManager.service

There should be a status log saying: ``Active: inactive (dead)``.

Now, configure ``/etc/wpa_supplicant.conf`` with this command:

.. prompt:: bash

    wpa_passphrase <SSID> <PASSWD> > /etc/wpa_supplicant.conf

And then verify the configuration file by running the following command:

.. prompt:: bash
    
    cat /etc/wpa_supplicant.conf

The generated content of ``wpa_supplicant.conf`` should be similar to this:

.. code:: text

    network={
        ssid="<SSID>"
        #psk="<PASSWD>"
        psk=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    }

Please add the following to the top of the configuration file for runtime configuration.
By adding the following settings, user will be able to use ``wpa_cli`` to control the connection at runtime.

.. code:: text

    update_config=1
    ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel

And we also have to configure the DNS server address:

.. prompt:: bash
    
    echo "nameserver x.x.x.x " > /etc/resolv.conf
     
After setting ``resolv.conf``, restart ``systemd-resolved`` service:

.. prompt:: bash
    
    systemctl restart systemd-resolved.service

Finally, launch ``wpa_supplicant`` with new configuration file ``/etc/wpasupplicant.conf``:

.. prompt:: bash

    wpa_supplicant -B -i <IFNAME> -c /etc/wpa_supplicant.conf

And you should now be able to connect to the internet:

.. prompt:: bash

    ping www.google.com

.. _Enable WPA3 Client:

Enable WPA3 Client
------------------

.. note::

    |IOT-YOCTO| enables WPA3 by default. Modification of the configuration or patching of the Wi-Fi drivers should not be necessary.
    Before you try it, please make sure WPA3 has been enabled properly on the Wi-Fi Access Point.

WPA3 setting for NetworkManager
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If user wants to enable WPA with NetworkManager, simply enable ``key-mgmt`` as ``sae`` in interface configuration file ``wifi.nmconnection``.
The configuration file should be located in ``/etc/NetworkManager/system-connections`` folder with ``.nmconnection`` filename extension.
If the wireless Access Point is configured correctly, the settings should be automatically added by the NetworkManager.
However, if the settings are incorrect, you can execute the ``sed`` replacement command for the configuration file to enable WPA3.

.. prompt:: bash

    sudo sed -i -e '/key-mgmt=/s,wpa-psk,sae,' /etc/NetworkManager/system-connections/YOUR_WIFI_CONNECTION.nmconnection

The ``[wifi-security]`` section in the ``.nmconnection`` file should looks like this.

.. prompt:: text

    [wifi-security]
    key-mgmt=sae
    psk=12345679

WPA3 setting for `wpa_supplicant`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If ``wpa_supplicant`` is already running, use ``pkill`` to terminate it before updating new configurations.

.. prompt:: bash

    pkill wpa_supplicant

Please add and check the following settings to ``/etc/wpa_supplicant.conf`` for enabling WPA3 support with ``wpa_supplicant``.
There are some key configurations for WPA3, for example, ``sae_pwe``, ``key_mgmt``, ``ieee80211w``, and ``psk``.
The password here should use explicit content instead of encoded hex string.

.. prompt:: text

    update_config=1
    ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
    sae_pwe=0

    network={
        ssid="<SSID>"
        psk="<PASSWD>"
        # psk=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        pairwise=CCMP
        group=CCMP
        key_mgmt=SAE
        ieee80211w=2
    }

Finally, launch ``wpa_supplicant`` with new configuration file ``/etc/wpa_supplicant.conf``:

.. prompt:: bash

    wpa_supplicant -B -i <IFNAME> -c /etc/wpa_supplicant.conf

Use `wpa_cli` to configure `wpa_supplicant`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

By enabling the following settings, user could use ``wpa_cli`` to control `wpa_supplicant`

.. prompt:: text

    update_config=1
    ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel

Here are the ``wpa_cli`` examples.

.. prompt:: bash

    wpa_cli -i <IFNAME> remove_network all
    wpa_cli -i <IFNAME> add_network
    wpa_cli -i <IFNAME> set_network 0 ssid '"<SSID>"'
    wpa_cli -i <IFNAME> set_network 0 pairwise CCMP
    wpa_cli -i <IFNAME> set_network 0 group CCMP
    wpa_cli -i <IFNAME> set_network 0 key_mgmt SAE
    wpa_cli -i <IFNAME> set_network 0 psk '"<PASSWD>"'
    wpa_cli -i <IFNAME> set sae_pwe 0
    wpa_cli -i <IFNAME> set_network 0 ieee80211w 2
    wpa_cli -i <IFNAME> enable_network 0
    wpa_cli -i <IFNAME> select_network 0
    wpa_cli -i <IFNAME> status

.. _Reference Boards:

Reference Boards
================

Wi-Fi on different platforms may have some platform-specific instructions or test results. 
For example, you will get different benchmark results on different platforms. 
Please find more details about difference of Wi-Fi on each platform:

- :doc:`Genio 350-EVK Wireless Installation </sw/yocto/app-dev/Wi-Fi/Wi-Fi-350-evk>`.
- :doc:`Genio 510/700-EVK Wireless Installation </sw/yocto/app-dev/Wi-Fi/Wi-Fi-700-evk>`.
- :doc:`Genio 1200-EVK Wireless Installation </sw/yocto/app-dev/Wi-Fi/Wi-Fi-1200-evk>`.