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

SoftAP (Software Enabled Access Point/Hotspot) Mode
===================================================

SoftAP (Software Enabled Access Point) allows a device to function as a wireless hotspot.
This feature enables the device to share its internet connection with nearby devices.

Starting with |IOT-YOCTO| v25.0, the :ref:`MT7921 Module` supports SoftAP.
However, it does not allow the device to be both an access point and a client simultaneously.
Below are the basic features available with the :ref:`MT7921 Module`.

Hotspot On/Off
--------------

You can turn the SoftAP feature on or off.
Turning it on lets other devices connect to the network you create, while turning it off disconnects all devices and stops the hotspot.

Enable Hotspot
^^^^^^^^^^^^^^

.. note::
    The ``hostapd`` (Host Access Point Daemon) is critical for enabling devices to act as a wireless hotspot by managing all wireless settings.
    By default, its configuration file should usually be located at ``/etc/hostapd.conf``.
    However, in the following demonstration, we will use the ``/usr/share/hostapd`` directory for storing template configurations and for demonstrating various settings.

.. _Enable-DHCP-Daemon:

Enable DHCP Daemon
''''''''''''''''''

.. important::

    You must disable ``NetworkManager`` before enabling SoftAP.

.. prompt:: bash

    systemctl stop NetworkManager
    systemctl disable NetworkManager

Enable the DHCP server to assign IP addresses to clients when they connect to the SoftAP.
Set up the DHCP daemon by configuring ``udhcpd.conf`` as shown:

.. prompt:: text

    start           192.168.1.20
    end             192.168.1.254
    interface       wlp1s0
    option subnet   255.255.255.0

Activate the Wi-Fi interface and set its IP address within the DHCP range.

.. prompt:: bash

    ifconfig wlp1s0 up
    ifconfig wlp1s0 192.168.1.1

Enable the DHCP server.

.. prompt:: bash

    udhcpd -f /etc/udhcpd.conf &

.. note::

    If you see the error: udhcpd: can't open ``/var/lib/misc/udhcpd.leases``: No such file or directory
    Run this command:
    touch /var/lib/misc/udhcpd.leases

Enable SoftAP with VHT80 Bandwidth on the 5GHz Band
'''''''''''''''''''''''''''''''''''''''''''''''''''

Create a configuration file ``/usr/share/hostapd/hostapd5_wpa3_80M.conf`` for ``hostapd`` to set up SoftAP with VHT80 bandwidth on the 5GHz band.

.. prompt:: bash

    mkdir -p /usr/share/hostapd
    touch /usr/share/hostapd/hostapd5_wpa3_80M.conf
    chmod 644 /usr/share/hostapd/hostapd5_wpa3_80M.conf

Add the following settings to ``/usr/share/hostapd/hostapd5_wpa3_80M.conf``:

.. note::

    Caution: Consider replacing the default ``ssid`` and ``wpa_passphrase`` for production environments.

.. prompt:: text

    interface=wlp1s0
    driver=nl80211
    ctrl_interface=/var/run/hostapd
    ctrl_interface_group=0
    channel=36
    vht_oper_centr_freq_seg0_idx=42
    country_code=CN
    beacon_int=100
    macaddr_acl=0
    wpa=2
    wpa_pairwise=CCMP
    wpa_key_mgmt=SAE WPA-PSK
    vht_capab=[SHORT-GI-80]
    eap_server=1
    require_vht=1
    wps_state=2
    ap_setup_locked=1
    config_methods=virtual_display virtual_push_button keypad
    hw_mode=a
    ieee80211n=1
    ht_capab=[HT40-][HT40+][SHORT-GI-20][SHORT-GI-40]
    ieee80211ac=1
    vht_oper_chwidth=1
    ieee80211ax=0
    ssid=SAP_5_wpa2_3_80M
    wpa_passphrase=12345678

Activate the SoftAP.

.. prompt:: bash

    hostapd -dd /usr/share/hostapd/hostapd5_wpa3_80M.conf &
    sleep 5; # Wait for 5 seconds for the service to be ready.

After activation, ``hostapd`` should display messages indicating successful setup:

.. prompt:: text

    wlp1s0: interface state COUNTRY_UPDATE-> ENABLED
    wlp1s0: AP-ENABLED
    wlp1s0: Setup of interface done.

Connect Station (Client) Device to SoftAP
'''''''''''''''''''''''''''''''''''''''''

Use another Genio EVK with ``NetworkManager`` to connect.

.. prompt:: bash

    nmcli device wifi rescan
    nmcli device wifi connect SAP_5_wpa2_3_80M ifname wlp1s0 password 12345678

Once connected, observe messages showing IP assignment:

.. prompt:: text

    udhcpd: sending OFFER to 192.168.1.20
    udhcpd: sending OFFER to 192.168.1.20
    udhcpd: sending ACK to 192.168.1.20

Try ``ping 192.168.1.1`` to test the connection.

.. _Disable-Hotspot:

Disable Hotspot
^^^^^^^^^^^^^^^

To disable SoftAP, simply run:

.. prompt:: bash

    killall hostapd
    sleep 5; # Wait for 5 seconds for the service to stop.

The following message indicates the SoftAP has been disabled:

.. prompt:: text

    wlp1s0: interface state ENABLED->DISABLED

Operating on Different Band
---------------------------

You can switch between 2.4 GHz and 5 GHz bands to optimize network performance based on device compatibility and environmental conditions.

The examples below assume the Wi-Fi interface is active and ``udhcpd`` is running.
Check: :ref:`Enable-DHCP-Daemon`. Stop any current SoftAP services before starting new ones: :ref:`Disable-Hotspot`.

Enable SoftAP on 2.4GHz Band
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Set up a SoftAP using ``hostapd`` on the 2.4 GHz band. Create a configuration file ``/usr/share/hostapd/hostapd24_wpa3.conf`` for ``hostapd``.

.. prompt:: bash

    mkdir -p /usr/share/hostapd
    touch /usr/share/hostapd/hostapd24_wpa3.conf
    chmod 644 /usr/share/hostapd/hostapd24_wpa3.conf

Add the following settings to ``/usr/share/hostapd/hostapd24_wpa3.conf``:

.. note::

    Caution: Consider replacing the default ``ssid`` and ``wpa_passphrase`` for production environments.

.. prompt:: text

    interface=wlp1s0
    driver=nl80211
    ctrl_interface=/var/run/hostapd
    ctrl_interface_group=0
    channel=6
    country_code=CN
    beacon_int=100
    macaddr_acl=0
    wpa=2
    wpa_key_mgmt=SAE
    ieee80211w=2
    wpa_pairwise=CCMP
    wpa_group_rekey=86400
    vht_capab=[SHORT-GI-80]
    eap_server=1
    require_vht=1
    wps_state=2
    ap_setup_locked=1
    config_methods=virtual_display virtual_push_button keypad
    hw_mode=g
    ieee80211n=1
    ht_capab=[SHORT-GI-20]
    ieee80211ac=0
    vht_oper_chwidth=0
    ieee80211ax=0
    ssid=SAP_24_wpa3
    wpa_passphrase=12345678

Activate the SoftAP.

.. prompt:: bash

    hostapd -dd /usr/share/hostapd/hostapd24_wpa3.conf &
    sleep 5; # Wait for 5 seconds for the service to be ready.

After activation, ``hostapd`` should display messages indicating successful setup:

.. prompt:: text

    wlp1s0: interface state COUNTRY_UPDATE-> ENABLED
    wlp1s0: AP-ENABLED
    wlp1s0: Setup of interface done.

Connect Station (Client) Device to SoftAP
'''''''''''''''''''''''''''''''''''''''''

If using a smartphone, find the hotspot ``SAP_24_wpa3`` and connect (password: 12345678).

Alternatively, use another Genio EVK with ``NetworkManager``.

.. prompt:: bash

    nmcli device wifi rescan
    nmcli device wifi connect SAP_24_wpa3 ifname wlp1s0 password 12345678

After connecting, observe IP assignment messages:

.. prompt:: text

    udhcpd: sending OFFER to 192.168.1.20
    udhcpd: sending OFFER to 192.168.1.20
    udhcpd: sending ACK to 192.168.1.20

Try ``ping 192.168.1.1`` to test the connection.

Enable SoftAP on 5GHz Band
^^^^^^^^^^^^^^^^^^^^^^^^^^

Set up a SoftAP using ``hostapd`` on the 5 GHz band. Create a configuration file ``/usr/share/hostapd/hostapd5_wpa3.conf`` for ``hostapd``.

.. prompt:: bash

    mkdir -p /usr/share/hostapd
    touch /usr/share/hostapd/hostapd5_wpa3.conf
    chmod 644 /usr/share/hostapd/hostapd5_wpa3.conf

Add the following settings to ``/usr/share/hostapd/hostapd5_wpa3.conf``:

.. note::

    Caution: Consider replacing the default ``ssid`` and ``wpa_passphrase`` for production environments.

.. prompt:: text

    interface=wlp1s0
    driver=nl80211
    ctrl_interface=/var/run/hostapd
    ctrl_interface_group=0
    channel=36
    country_code=CN
    beacon_int=100
    macaddr_acl=0
    wpa=2
    wpa_key_mgmt=SAE
    ieee80211w=2
    wpa_pairwise=CCMP
    wpa_group_rekey=86400
    vht_capab=[SHORT-GI-80]
    eap_server=1
    require_vht=1
    wps_state=2
    ap_setup_locked=1
    config_methods=virtual_display virtual_push_button keypad
    hw_mode=a
    ieee80211n=1
    ht_capab=[SHORT-GI-20]
    ieee80211ac=1
    vht_oper_chwidth=0
    ieee80211ax=0
    ssid=SAP_5G_wpa3 
    wpa_passphrase=12345678

Activate the SoftAP.

.. prompt:: bash

    hostapd -dd /usr/share/hostapd/hostapd5_wpa3.conf &
    sleep 5; # Wait for 5 seconds for the service to be ready.

After activation, ``hostapd`` should display messages indicating successful setup:

.. prompt:: text

    wlp1s0: interface state COUNTRY_UPDATE-> ENABLED
    wlp1s0: AP-ENABLED
    wlp1s0: Setup of interface done.

Connect Station (Client) Device to SoftAP
'''''''''''''''''''''''''''''''''''''''''

If you're using a smartphone to connect to SoftAP, look for the hotspot ``SAP_5G_wpa3`` and connect (password: 12345678).

You can also use another Genio EVK with ``NetworkManager``.

.. prompt:: bash

    nmcli device wifi rescan
    nmcli device wifi connect SAP_5G_wpa3 ifname wlp1s0 password 12345678

Once connected, observe messages showing IP assignment:

.. prompt:: text

    udhcpd: sending OFFER to 192.168.1.20
    udhcpd: sending OFFER to 192.168.1.20
    udhcpd: sending ACK to 192.168.1.20

Try ``ping 192.168.1.1`` to test the connection.

.. _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>`.