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:
|
:caption: Contents:
|
||||||
|
|
||||||
nsh/index.rst
|
nsh/index.rst
|
||||||
|
wapi/index.rst
|
||||||
|
|
||||||
|
|||||||
103
Documentation/applications/wapi/commands.rst
Normal file
103
Documentation/applications/wapi/commands.rst
Normal file
@ -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
|
||||||
19
Documentation/applications/wapi/index.rst
Normal file
19
Documentation/applications/wapi/index.rst
Normal file
@ -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
|
||||||
121
Documentation/applications/wapi/wireless.rst
Normal file
121
Documentation/applications/wapi/wireless.rst
Normal file
@ -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
|
# Only configure the APP CPU
|
||||||
#set ESP32_ONLYCPU 2
|
#set ESP32_ONLYCPU 2
|
||||||
|
|
||||||
|
.. _esp32_wi-fi_sta:
|
||||||
|
|
||||||
Wi-Fi
|
Wi-Fi
|
||||||
=====
|
=====
|
||||||
|
|
||||||
@ -288,6 +290,8 @@ the result by running ``ifconfig`` afterwards.
|
|||||||
|
|
||||||
.. tip:: Boards usually expose a ``wifi`` defconfig which enables Wi-Fi
|
.. tip:: Boards usually expose a ``wifi`` defconfig which enables Wi-Fi
|
||||||
|
|
||||||
|
.. _esp32_wi-fi_softap:
|
||||||
|
|
||||||
Wi-Fi SoftAP
|
Wi-Fi SoftAP
|
||||||
============
|
============
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user