diff --git a/Documentation/applications/index.rst b/Documentation/applications/index.rst index 4c30087714..b71ba1569a 100644 --- a/Documentation/applications/index.rst +++ b/Documentation/applications/index.rst @@ -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 diff --git a/Documentation/applications/wapi/commands.rst b/Documentation/applications/wapi/commands.rst new file mode 100644 index 0000000000..bcd59caca3 --- /dev/null +++ b/Documentation/applications/wapi/commands.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 + wapi scan + wapi scan_results + wapi ip + wapi mask + wapi freq + wapi essid + wapi psk + wapi disconnect + wapi mode + wapi ap + wapi bitrate + wapi txpower + wapi country + wapi sense + wapi pta_prio + 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: + +```` +------------ + +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 ` for +platform-specific definitions. As an example, please check +:ref:`ESP32 Wi-Fi Station Mode ` and +:ref:`ESP32 Wi-Fi SoftAP Mode ` Wi-Fi sections. + +```` +---------------- + +The ```` 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 diff --git a/Documentation/applications/wapi/index.rst b/Documentation/applications/wapi/index.rst new file mode 100644 index 0000000000..0158ca1287 --- /dev/null +++ b/Documentation/applications/wapi/index.rst @@ -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 diff --git a/Documentation/applications/wapi/wireless.rst b/Documentation/applications/wapi/wireless.rst new file mode 100644 index 0000000000..b107770ac6 --- /dev/null +++ b/Documentation/applications/wapi/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) ` and + :ref:`ESP32 Wi-Fi SoftAP Mode (wlan1) ` sections. + +Setting the Passphrase +====================== + +``wapi psk`` command is used for setting the AP authentication security. Its +arguments are:: + + wapi psk [wpa] + +- ```` is the name of the interface set as Station Mode (STA); +- ```` 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; +- ```` 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 + +- ```` is the name of the interface set as Station Mode (STA); +- ```` is the name of the Wireless Network; +- ```` 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 diff --git a/Documentation/platforms/xtensa/esp32/index.rst b/Documentation/platforms/xtensa/esp32/index.rst index 9faad06c3d..362ae750b6 100644 --- a/Documentation/platforms/xtensa/esp32/index.rst +++ b/Documentation/platforms/xtensa/esp32/index.rst @@ -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 ============