5afa727eef
Initial documentation of the WAPI (Wireless API). Currently, `wapi` is the only interface provided to handle Wi-Fi networking from the userspace.
122 lines
3.3 KiB
ReStructuredText
122 lines
3.3 KiB
ReStructuredText
==============================
|
|
Configuring a Wireless Network
|
|
==============================
|
|
|
|
``wapi`` is used to connect to an Access Point by setting its parameters.
|
|
|
|
.. note:: Usually, one single wireless interface refers to an operational
|
|
mode: Station Mode (STA) or SoftAP. For instance, ``wlan0`` may refer to
|
|
the STA mode and ``wlan1``. Setting the passphrase and the ESSID of a
|
|
STA-enabled interface would make it connect to a wireless network while
|
|
setting the same parameters for a SoftAP-enabled interface would provide
|
|
a network wireless with these connection parameters. Please check
|
|
:ref:`ESP32 Wi-Fi Station Mode (wlan0) <esp32_wi-fi_sta>` and
|
|
:ref:`ESP32 Wi-Fi SoftAP Mode (wlan1) <esp32_wi-fi_softap>` sections.
|
|
|
|
Setting the Passphrase
|
|
======================
|
|
|
|
``wapi psk`` command is used for setting the AP authentication security. Its
|
|
arguments are::
|
|
|
|
wapi psk <ifname> <passphrase> <index/flag> [wpa]
|
|
|
|
- ``<ifname>`` is the name of the interface set as Station Mode (STA);
|
|
- ``<passphrase>`` is the password. Its length depends on the authentication
|
|
algorithm. Please note that ``wapi psk`` command is also used to set auth
|
|
as open, but this parameter comes next, so it may be necessary to set a
|
|
"dummy" passphrase just to set auth to none;
|
|
- ``<index/flag>`` can be set numerically or textually, as follows:
|
|
|
|
- [0] WPA_ALG_NONE - to connect to an open AP;
|
|
- [1] WPA_ALG_WEP - to connect to a WEP-secured AP (not recommended);
|
|
- [2] WPA_ALG_TKIP - to use TKIP algorithm (not recommended);
|
|
- [3] WPA_ALG_CCMP - to use CCMP algorithm (recommended);
|
|
|
|
- ``[wpa]`` sets the WPA version (if applicable):
|
|
|
|
- [0] WPA_VER_NONE;
|
|
- [1] WPA_VER_1;
|
|
- [2] WPA_VER_2 (default, if not selected otherwise);
|
|
- [3] WPA_VER_3;
|
|
|
|
Setting the Network Name (ESSID)
|
|
================================
|
|
|
|
The name of the Wireless Network can be set using ``wapi essid`` command::
|
|
|
|
wapi essid <ifname> <essid> <index/flag>
|
|
|
|
- ``<ifname>`` is the name of the interface set as Station Mode (STA);
|
|
- ``<essid>`` is the name of the Wireless Network;
|
|
- ``<index/flag>`` selects whether to connect to the AP or not:
|
|
|
|
- [0] WAPI_ESSID_OFF - Don't connect to the AP;
|
|
- [1] WAPI_ESSID_ON - Connect to the AP indicated by the provided ESSID;
|
|
- [2] WAPI_ESSID_DELAY_ON - Delay AP connection;
|
|
|
|
Examples
|
|
========
|
|
|
|
Connecting to an Open Network
|
|
-----------------------------
|
|
|
|
::
|
|
|
|
wapi psk wlan0 mypasswd WPA_ALG_NONE
|
|
wapi essid wlan0 myssid WAPI_ESSID_ON
|
|
|
|
or, equivalently
|
|
|
|
::
|
|
|
|
wapi psk wlan0 mypasswd 0
|
|
wapi essid wlan0 myssid 1
|
|
|
|
Connecting to a WPA2-PSK Network
|
|
--------------------------------
|
|
|
|
::
|
|
|
|
wapi psk wlan0 mypasswd WPA_ALG_CCMP
|
|
wapi essid wlan0 myssid WAPI_ESSID_ON
|
|
|
|
or, equivalently:
|
|
|
|
::
|
|
|
|
wapi psk wlan0 mypasswd 3
|
|
wapi essid wlan0 myssid 1
|
|
|
|
Connecting to a WPA3-SAE Network
|
|
--------------------------------
|
|
|
|
::
|
|
|
|
wapi psk wlan0 mypasswd WPA_ALG_CCMP WPA_VER_3
|
|
wapi essid wlan0 myssid WAPI_ESSID_ON
|
|
|
|
or, equivalently:
|
|
|
|
::
|
|
|
|
wapi psk wlan0 mypasswd 3 3
|
|
wapi essid wlan0 myssid 1
|
|
|
|
Connecting to a Hidden (WPA2-PSK) Network
|
|
-----------------------------------------
|
|
|
|
::
|
|
|
|
wapi psk wlan0 mypasswd WPA_ALG_CCMP
|
|
wapi essid wlan0 myssid WAPI_ESSID_DELAY_ON
|
|
wapi ap wlan0 aa:bb:cc:dd:dd:ff
|
|
|
|
or, equivalently:
|
|
|
|
::
|
|
|
|
wapi psk wlan0 mypasswd 3
|
|
wapi essid wlan0 myssid 2
|
|
wapi ap wlan0 aa:bb:cc:dd:dd:ff
|