From 36692dbac704fbbb1e272d0f42254660fb7b2f24 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 26 Sep 2017 17:02:52 +1000 Subject: [PATCH 1/4] docs: Add esp_wifi_types.h items to wifi API reference Previously only items defined esp_wifi.h in esp_wifi_crypto_types.h were including in documentation reference. --- components/esp32/include/esp_wifi_types.h | 4 ++-- docs/Doxyfile | 1 + docs/api-reference/wifi/esp_wifi.rst | 2 ++ 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/components/esp32/include/esp_wifi_types.h b/components/esp32/include/esp_wifi_types.h index 61161037ce..438ad01827 100755 --- a/components/esp32/include/esp_wifi_types.h +++ b/components/esp32/include/esp_wifi_types.h @@ -61,7 +61,7 @@ typedef enum { WIFI_AUTH_MAX } wifi_auth_mode_t; -enum { +typedef enum { WIFI_REASON_UNSPECIFIED = 1, WIFI_REASON_AUTH_EXPIRE = 2, WIFI_REASON_AUTH_LEAVE = 3, @@ -91,7 +91,7 @@ enum { WIFI_REASON_AUTH_FAIL = 202, WIFI_REASON_ASSOC_FAIL = 203, WIFI_REASON_HANDSHAKE_TIMEOUT = 204, -}; +} wifi_err_reason_t; typedef enum { WIFI_SECOND_CHAN_NONE = 0, /**< the channel width is HT20 */ diff --git a/docs/Doxyfile b/docs/Doxyfile index c33ecbc9b2..2a91d72b79 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -25,6 +25,7 @@ INPUT = \ ## Wi-Fi - API Reference ## ../components/esp32/include/esp_wifi.h \ + ../components/esp32/include/esp_wifi_types.h \ ../components/esp32/include/esp_wifi_crypto_types.h \ ../components/esp32/include/esp_smartconfig.h \ ../components/esp32/include/esp_now.h \ diff --git a/docs/api-reference/wifi/esp_wifi.rst b/docs/api-reference/wifi/esp_wifi.rst index 976893e5e4..29ecb3e3b6 100644 --- a/docs/api-reference/wifi/esp_wifi.rst +++ b/docs/api-reference/wifi/esp_wifi.rst @@ -22,4 +22,6 @@ API Reference ------------- .. include:: /_build/inc/esp_wifi.inc +.. include:: /_build/inc/esp_wifi_types.inc + From beba74ff61f37b5b93be6e4259edc2e6154b73c2 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Wed, 27 Sep 2017 11:09:21 +1000 Subject: [PATCH 2/4] docs: Add esp_wifi_types.h descriptions --- components/esp32/include/esp_wifi.h | 14 +++---- components/esp32/include/esp_wifi_types.h | 50 ++++++++++++++++------- 2 files changed, 43 insertions(+), 21 deletions(-) diff --git a/components/esp32/include/esp_wifi.h b/components/esp32/include/esp_wifi.h index 37aba73314..6d47d2a5ab 100755 --- a/components/esp32/include/esp_wifi.h +++ b/components/esp32/include/esp_wifi.h @@ -641,11 +641,11 @@ esp_err_t esp_wifi_set_promiscuous(bool en); esp_err_t esp_wifi_get_promiscuous(bool *en); /** - * @brief Enable the promiscuous filter. + * @brief Enable the promiscuous mode packet type filter. * - * @attention 1. The default filter is to filter all packets except WIFI_PKT_MISC + * @note The default filter is to filter all packets except WIFI_PKT_MISC * - * @param filter the packet type filtered by promisucous + * @param filter the packet type filtered in promiscuous mode. * * @return * - ESP_OK: succeed @@ -673,7 +673,7 @@ esp_err_t esp_wifi_get_promiscuous_filter(wifi_promiscuous_filter_t *filter); * @attention 3. ESP32 is limited to only one channel, so when in the soft-AP+station mode, the soft-AP will adjust its channel automatically to be the same as * the channel of the ESP32 station. * - * @param ifx interface + * @param interface interface * @param conf station or soft-AP configuration * * @return @@ -686,12 +686,12 @@ esp_err_t esp_wifi_get_promiscuous_filter(wifi_promiscuous_filter_t *filter); * - ESP_ERR_WIFI_NVS: WiFi internal NVS error * - others: refer to the erro code in esp_err.h */ -esp_err_t esp_wifi_set_config(wifi_interface_t ifx, const wifi_config_t *conf); +esp_err_t esp_wifi_set_config(wifi_interface_t interface, wifi_config_t *conf); /** * @brief Get configuration of specified interface * - * @param ifx interface + * @param interface interface * @param[out] conf station or soft-AP configuration * * @return @@ -700,7 +700,7 @@ esp_err_t esp_wifi_set_config(wifi_interface_t ifx, const wifi_config_t *conf); * - ESP_ERR_WIFI_ARG: invalid argument * - ESP_ERR_WIFI_IF: invalid interface */ -esp_err_t esp_wifi_get_config(wifi_interface_t ifx, wifi_config_t *conf); +esp_err_t esp_wifi_get_config(wifi_interface_t interface, wifi_config_t *conf); /** * @brief Get STAs associated with soft-AP diff --git a/components/esp32/include/esp_wifi_types.h b/components/esp32/include/esp_wifi_types.h index 438ad01827..88108bf0a1 100755 --- a/components/esp32/include/esp_wifi_types.h +++ b/components/esp32/include/esp_wifi_types.h @@ -44,6 +44,7 @@ typedef enum { WIFI_COUNTRY_POLICY_MANUAL, /**< Country policy is manual, always use the configured country info */ } wifi_country_policy_t; +/** @brief Structure describing WiFi country-based regional restrictions. */ typedef struct { char cc[3]; /**< country code string */ uint8_t schan; /**< start channel */ @@ -104,18 +105,21 @@ typedef enum { WIFI_SCAN_TYPE_PASSIVE, /**< passive scan */ } wifi_scan_type_t; +/** @brief Range of active scan times per channel */ typedef struct { uint32_t min; /**< minimum active scan time per channel, units: millisecond */ uint32_t max; /**< maximum active scan time per channel, units: millisecond, values above 1500ms may cause station to disconnect from AP and are not recommended. */ } wifi_active_scan_time_t; +/** @brief Aggregate of active & passive scan time per channel */ typedef union { - wifi_active_scan_time_t active; /**< active scan time per channel */ + wifi_active_scan_time_t active; /**< active scan time per channel, units: millisecond. */ uint32_t passive; /**< passive scan time per channel, units: millisecond, values above 1500ms may cause station to disconnect from AP and are not recommended. */ } wifi_scan_time_t; +/** @brief Parameters for an SSID scan. */ typedef struct { uint8_t *ssid; /**< SSID of AP */ uint8_t *bssid; /**< MAC address of AP */ @@ -135,6 +139,7 @@ typedef enum { WIFI_CIPHER_TYPE_UNKNOWN, /**< the cipher type is unknown */ } wifi_cipher_type_t; +/** @brief Description of an WiFi AP */ typedef struct { uint8_t bssid[6]; /**< MAC address of AP */ uint8_t ssid[33]; /**< SSID of AP */ @@ -162,9 +167,10 @@ typedef enum { WIFI_CONNECT_AP_BY_SECURITY, /**< Sort match AP in scan list by security mode */ }wifi_sort_method_t; +/** @brief Structure describing parameters for a WiFi fast scan */ typedef struct { - int8_t rssi; /**< The minimum rssi to accept in the fast scan mode */ - wifi_auth_mode_t authmode; /**< The weakest authmode to accept in the fast scan mode */ + int8_t rssi; /**< The minimum rssi to accept in the fast scan mode */ + wifi_auth_mode_t authmode; /**< The weakest authmode to accept in the fast scan mode */ }wifi_fast_scan_threshold_t; typedef enum { @@ -182,6 +188,7 @@ typedef enum { WIFI_BW_HT40, /* Bandwidth is HT40 */ } wifi_bandwidth_t; +/** @brief Soft-AP configuration settings for the ESP32 */ typedef struct { uint8_t ssid[32]; /**< SSID of ESP32 soft-AP */ uint8_t password[64]; /**< Password of ESP32 soft-AP */ @@ -193,6 +200,7 @@ typedef struct { uint16_t beacon_interval; /**< Beacon interval, 100 ~ 60000 ms, default 100 ms */ } wifi_ap_config_t; +/** @brief STA configuration settings for the ESP32 */ typedef struct { uint8_t ssid[32]; /**< SSID of target AP*/ uint8_t password[64]; /**< password of target AP*/ @@ -204,20 +212,28 @@ typedef struct { wifi_fast_scan_threshold_t threshold; /**< When scan_method is set to WIFI_FAST_SCAN, only APs which have an auth mode that is more secure than the selected auth mode and a signal stronger than the minimum RSSI will be used. */ } wifi_sta_config_t; +/** @brief Configuration data for ESP32 AP or STA. + * + * The usage of this union (for ap or sta configuration) is determined by the accompanying + * interface argument passed to esp_wifi_set_config() or esp_wifi_get_config() + * + */ typedef union { wifi_ap_config_t ap; /**< configuration of AP */ wifi_sta_config_t sta; /**< configuration of STA */ } wifi_config_t; +/** @brief Description of STA associated with AP */ typedef struct { - uint8_t mac[6]; /**< mac address of sta that associated with ESP32 soft-AP */ + uint8_t mac[6]; /**< mac address */ } wifi_sta_info_t; #define ESP_WIFI_MAX_CONN_NUM (10) /**< max number of stations which can connect to ESP32 soft-AP */ +/** @brief List of stations associated with the ESP32 Soft-AP */ typedef struct { wifi_sta_info_t sta[ESP_WIFI_MAX_CONN_NUM]; /**< station list */ - int num; /**< number of station that associated with ESP32 soft-AP */ + int num; /**< number of stations in the list (other entries are invalid) */ } wifi_sta_list_t; typedef enum { @@ -263,6 +279,7 @@ typedef struct { uint8_t payload[0]; /**< Payload. Length is equal to value in 'length' field, minus 4. */ } vendor_ie_data_t; +/** @brief Received packet radio metadata header, this is the common header at the beginning of all promiscuous mode RX callback buffers */ typedef struct { signed rssi:8; /**< signal intensity of packet */ unsigned rate:5; /**< data rate */ @@ -277,7 +294,7 @@ typedef struct { unsigned :1; /**< reserve */ unsigned aggregation:1; /**< Aggregation */ unsigned stbc:2; /**< STBC */ - unsigned fec_coding:1; /**< if is 11n packet, shows if is LDPC packet or not */ + unsigned fec_coding:1; /**< Flag is set for 11n packets which are LDPC */ unsigned sgi:1; /**< SGI */ unsigned noise_floor:8; /**< noise floor */ unsigned ampdu_cnt:8; /**< ampdu cnt */ @@ -286,24 +303,28 @@ typedef struct { unsigned timestamp:32; /**< timestamp */ unsigned :32; /**< reserve */ unsigned :32; /**< reserve */ - unsigned sig_len:12; /**< It is really lenth of packet */ + unsigned sig_len:12; /**< length of packet */ unsigned :12; /**< reserve */ unsigned rx_state:8; /**< rx state */ } wifi_pkt_rx_ctrl_t; +/** @brief Payload passed to 'buf' parameter of promiscuous mode RX callback. + */ typedef struct { - wifi_pkt_rx_ctrl_t rx_ctrl; - uint8_t payload[0]; /**< ieee80211 packet buff, The length of payload is described by sig_len */ + wifi_pkt_rx_ctrl_t rx_ctrl; /**< metadata header */ + uint8_t payload[0]; /**< Data or management payload. Length of payload is described by rx_ctrl.sig_len. Type of content determined by packet type argument of callback. */ } wifi_promiscuous_pkt_t; /** - * @brief Promiscuous frame type + * @brief Promiscuous frame type + * + * Passed to promiscuous mode RX callback to indicate the type of parameter in the buffer. * */ typedef enum { - WIFI_PKT_MGMT, /**< management type, receive packet buf is wifi_promiscuous_pkt_t */ - WIFI_PKT_DATA, /**< data type, receive packet buf is wifi_promiscuous_pkt_t */ - WIFI_PKT_MISC, /**< other type, such as MIMO etc, receive packet buf is wifi_promiscuous_pkt_t but the payload is NULL!!! */ + WIFI_PKT_MGMT, /**< Management frame, indicates 'buf' argument is wifi_promiscuous_pkt_t */ + WIFI_PKT_DATA, /**< Data frame, indiciates 'buf' argument is wifi_promiscuous_pkt_t */ + WIFI_PKT_MISC, /**< Other type, such as MIMO etc. 'buf' argument is wifi_promiscuous_pkt_t but the payload is zero length. */ } wifi_promiscuous_pkt_type_t; @@ -314,8 +335,9 @@ typedef enum { #define WIFI_PROMIS_FILTER_MASK_DATA_MPDU (1<<3) /**< filter the MPDU which is a kind of WIFI_PKT_DATA */ #define WIFI_PROMIS_FILTER_MASK_DATA_AMPDU (1<<4) /**< filter the AMPDU which is a kind of WIFI_PKT_DATA */ +/** @brief Mask for filtering different packet types in promiscuous mode. */ typedef struct { - uint32_t filter_mask; + uint32_t filter_mask; /**< OR of one or more filter values WIFI_PROMIS_FILTER_* */ } wifi_promiscuous_filter_t; #ifdef __cplusplus From 9a96c8379e542ed17ece7436924f34ba3ce85c5e Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Wed, 27 Sep 2017 11:13:20 +1000 Subject: [PATCH 3/4] docs: Add introduction section for WiFi, replace boilerplate --- docs/api-reference/wifi/esp_wifi.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/api-reference/wifi/esp_wifi.rst b/docs/api-reference/wifi/esp_wifi.rst index 29ecb3e3b6..c8091e0078 100644 --- a/docs/api-reference/wifi/esp_wifi.rst +++ b/docs/api-reference/wifi/esp_wifi.rst @@ -1,12 +1,18 @@ Wi-Fi ===== -Overview --------- +Introduction +------------ -`Instructions`_ +The WiFi libraries provide support for configuring and monitoring the ESP32 WiFi networking functionality. This includes configuration for: -.. _Instructions: ../template.html +- Station mode (aka STA mode or WiFi client mode). ESP32 connects to an access point. +- AP mode (aka Soft-AP mode or Access Point mode). Stations connect to the ESP32. +- Combined AP-STA mode (ESP32 is concurrently an access point and a station connected to another access point). + +- Various security modes for the above (WPA, WPA2, WEP, etc.) +- Scanning for access points (active & passive scanning). +- Promiscuous mode monitoring of IEEE802.11 WiFi packets. Application Examples -------------------- From c40dc3681486dda021dbc2ea26f2f91fdfa777e8 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Wed, 27 Sep 2017 11:17:32 +1000 Subject: [PATCH 4/4] docs: Remove internal header esp_wifi_crypto_types.h from documentation --- .../esp32/include/esp_wifi_crypto_types.h | 23 +++++++++++-------- docs/Doxyfile | 1 - 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/components/esp32/include/esp_wifi_crypto_types.h b/components/esp32/include/esp_wifi_crypto_types.h index 10a55a7088..e1f2cf824c 100644 --- a/components/esp32/include/esp_wifi_crypto_types.h +++ b/components/esp32/include/esp_wifi_crypto_types.h @@ -16,15 +16,21 @@ #ifndef __ESP_WIFI_CRYPTO_TYPES_H__ #define __ESP_WIFI_CRYPTO_TYPES_H__ +/* This is an internal API header for configuring the implementation used for WiFi cryptographic + operations. + + During normal operation, you don't need to use any of these types or functions in this header. + See esp_wifi.h & esp_wifi_types.h instead. +*/ + #ifdef __cplusplus extern "C" { #endif /* - * This enumation is about alorigthm will be set when do crypt hash - * operation.When do wpa2 connecting, after invoke crypto_hash_xxx of - * fast_crypto_hash_xxx API, it will do relation crypt operation according - * to the enumation. + * Enumeration for hash operations. + * When WPA2 is connecting, this enum is used to + * request a hash algorithm via crypto_hash_xxx functions. */ typedef enum { ESP_CRYPTO_HASH_ALG_MD5, ESP_CRYPTO_HASH_ALG_SHA1, @@ -33,10 +39,9 @@ typedef enum { }esp_crypto_hash_alg_t; /* - * This enumation is about alorigthm will be set when do crypt cipher - * operation.When do wpa2 connecting, after invoke crypto_cipher_xxx of - * fast_crypto_cipher_xxx API, it will do relation crypt operation according - * to the enumation. + * Enumeration for block cipher operations. + * When WPA2 is connecting, this enum is used to request a block + * cipher algorithm via crypto_cipher_xxx functions. */ typedef enum { ESP_CRYPTO_CIPHER_NULL, ESP_CRYPTO_CIPHER_ALG_AES, ESP_CRYPTO_CIPHER_ALG_3DES, @@ -293,7 +298,7 @@ typedef struct { esp_crypto_cipher_deinit_t crypto_cipher_deinit; /**< function used to free context when use TLSV1 */ esp_sha256_vector_t sha256_vector; /**< function used to do X.509v3 certificate parsing and processing */ esp_crypto_mod_exp_t crypto_mod_exp; /**< function used to do key exchange when use TLSV1 */ -}wpa2_crypto_funcs_t; +} wpa2_crypto_funcs_t; #ifdef __cplusplus } diff --git a/docs/Doxyfile b/docs/Doxyfile index 2a91d72b79..7b5e1d4d51 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -26,7 +26,6 @@ INPUT = \ ## ../components/esp32/include/esp_wifi.h \ ../components/esp32/include/esp_wifi_types.h \ - ../components/esp32/include/esp_wifi_crypto_types.h \ ../components/esp32/include/esp_smartconfig.h \ ../components/esp32/include/esp_now.h \ ## Bluetooth - API Reference