From beba74ff61f37b5b93be6e4259edc2e6154b73c2 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Wed, 27 Sep 2017 11:09:21 +1000 Subject: [PATCH] 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 37aba7331..6d47d2a5a 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 438ad0182..88108bf0a 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