documentantion/applications: add WAPI documentation
Initial documentation of the WAPI (Wireless API). Currently, `wapi` is the only interface provided to handle Wi-Fi networking from the userspace.
This commit is contained in:
Tiago Medicci Serrano
Xiang Xiao
parent
bec4ed482d
commit
5afa727eef
|
|
@ -12,4 +12,5 @@ NuttX ships a large number of applications covering a wide spectrum of functiona
|
|||
:caption: Contents:
|
||||
|
||||
nsh/index.rst
|
||||
wapi/index.rst
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,103 @@
|
|||
========
|
||||
Commands
|
||||
========
|
||||
|
||||
This page shows ``wapi`` commands, their arguments and outputs. For a
|
||||
complete list of ``wapi`` commands available to the system, just run
|
||||
``wapi``::
|
||||
|
||||
nsh> wapi
|
||||
Usage:
|
||||
wapi show <ifname>
|
||||
wapi scan <ifname>
|
||||
wapi scan_results <ifname>
|
||||
wapi ip <ifname> <IP address>
|
||||
wapi mask <ifname> <mask>
|
||||
wapi freq <ifname> <frequency> <index/flag>
|
||||
wapi essid <ifname> <essid> <index/flag>
|
||||
wapi psk <ifname> <passphrase> <index/flag> <wpa>
|
||||
wapi disconnect <ifname>
|
||||
wapi mode <ifname> <index/mode>
|
||||
wapi ap <ifname> <MAC address>
|
||||
wapi bitrate <ifname> <bitrate> <index/flag>
|
||||
wapi txpower <ifname> <txpower> <index/flag>
|
||||
wapi country <ifname> <country code>
|
||||
wapi sense <ifname>
|
||||
wapi pta_prio <ifname> <index/flag>
|
||||
wapi help
|
||||
|
||||
Frequency Flags:
|
||||
[0] WAPI_FREQ_AUTO
|
||||
[1] WAPI_FREQ_FIXED
|
||||
|
||||
ESSID Flags:
|
||||
[0] WAPI_ESSID_OFF
|
||||
[1] WAPI_ESSID_ON
|
||||
|
||||
Passphrase algorithm Flags:
|
||||
[0] WPA_ALG_NONE
|
||||
[1] WPA_ALG_WEP
|
||||
[2] WPA_ALG_TKIP
|
||||
[3] WPA_ALG_CCMP
|
||||
|
||||
Passphrase WPA version:
|
||||
[0] WPA_VER_NONE
|
||||
[1] WPA_VER_1
|
||||
[2] WPA_VER_2
|
||||
[3] WPA_VER_3
|
||||
|
||||
Operating Modes:
|
||||
[0] WAPI_MODE_AUTO
|
||||
[1] WAPI_MODE_ADHOC
|
||||
[2] WAPI_MODE_MANAGED
|
||||
[3] WAPI_MODE_MASTER
|
||||
[4] WAPI_MODE_REPEAT
|
||||
[5] WAPI_MODE_SECOND
|
||||
[6] WAPI_MODE_MONITOR
|
||||
[7] WAPI_MODE_MESH
|
||||
|
||||
Bitrate Flags:
|
||||
[0] WAPI_BITRATE_AUTO
|
||||
[1] WAPI_BITRATE_FIXED
|
||||
|
||||
TX power Flags:
|
||||
[0] WAPI_TXPOWER_DBM
|
||||
[1] WAPI_TXPOWER_MWATT
|
||||
[2] WAPI_TXPOWER_RELATIVE
|
||||
|
||||
pta prio Flags:
|
||||
[0] WAPI_PTA_PRIORITY_COEX_MAXIMIZED
|
||||
[1] WAPI_PTA_PRIORITY_COEX_HIGH
|
||||
[2] WAPI_PTA_PRIORITY_BALANCED
|
||||
[3] WAPI_PTA_PRIORITY_WLAN_HIGHD
|
||||
[4] WAPI_PTA_PRIORITY_WLAN_MAXIMIZED
|
||||
|
||||
Arguments
|
||||
=========
|
||||
|
||||
Command's arguments are available on ``wapi``'s usage helper.
|
||||
|
||||
.. note:: ``<>`` means a required argument and ``[]`` an optional one.
|
||||
|
||||
A short explanation of them follows:
|
||||
|
||||
``<ifname>``
|
||||
------------
|
||||
|
||||
The interface name is arch-dependent and it's usually set for a specific
|
||||
operating mode. For instance, ``wlan0`` would be an interface used for STA
|
||||
mode and ``wlan1`` for SoftAP.
|
||||
|
||||
Please refer to the :doc:`Supported Platforms </platforms/index>` for
|
||||
platform-specific definitions. As an example, please check
|
||||
:ref:`ESP32 Wi-Fi Station Mode <esp32_wi-fi_sta>` and
|
||||
:ref:`ESP32 Wi-Fi SoftAP Mode <esp32_wi-fi_softap>` Wi-Fi sections.
|
||||
|
||||
``<index/flag>``
|
||||
----------------
|
||||
|
||||
The ``<index/flag>`` can be used as a numerical or textual value. For
|
||||
instance, considering the ``wapi psk`` command, one could use indistinctly::
|
||||
|
||||
nsh> wapi psk wlan0 mypasswd 3
|
||||
nsh> wapi psk wlan0 mypasswd WPA_ALG_CCMP
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
===================
|
||||
WAPI (Wireless API)
|
||||
===================
|
||||
|
||||
WAPI (Wireless API) provides an easy-to-use function set to configure
|
||||
wireless network interfaces on a GNU/Linux system, originally.
|
||||
|
||||
One can provide use ``wapi`` to connect to Access Points, configure an
|
||||
Access Point, set Wi-Fi related configurations and get information about it.
|
||||
|
||||
Currently, ``wapi`` is the only interface provided to handle Wi-Fi networking
|
||||
from the userspace.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents
|
||||
|
||||
commands.rst
|
||||
wireless.rst
|
||||
|
|
@ -0,0 +1,121 @@
|
|||
==============================
|
||||
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
|
||||
|
|
@ -272,6 +272,8 @@ following in ``scripts/esp32.cfg``::
|
|||
# Only configure the APP CPU
|
||||
#set ESP32_ONLYCPU 2
|
||||
|
||||
.. _esp32_wi-fi_sta:
|
||||
|
||||
Wi-Fi
|
||||
=====
|
||||
|
||||
|
|
@ -288,6 +290,8 @@ the result by running ``ifconfig`` afterwards.
|
|||
|
||||
.. tip:: Boards usually expose a ``wifi`` defconfig which enables Wi-Fi
|
||||
|
||||
.. _esp32_wi-fi_softap:
|
||||
|
||||
Wi-Fi SoftAP
|
||||
============
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue