alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'doc/esp_wifi_types' into 'master'

Browse Source 
docs: Add esp_wifi_types.h items to wifi API reference

See merge request !1320
This commit is contained in:
Angus Gratton 2017-11-15 15:03:02 +08:00
commit b83792f504
5 changed files with 72 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
components/esp32/include/esp_wifi.h
View File

@ -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

23
components/esp32/include/esp_wifi_crypto_types.h
View File

@ -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
}

54
components/esp32/include/esp_wifi_types.h
View File

@ -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 */
@ -61,7 +62,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 +92,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 */
@ -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

2
docs/Doxyfile
View File

@ -25,7 +25,7 @@ INPUT = \
## Wi-Fi - API Reference
##
../components/esp32/include/esp_wifi.h \
../components/esp32/include/esp_wifi_crypto_types.h \
../components/esp32/include/esp_wifi_types.h \
../components/esp32/include/esp_smartconfig.h \
../components/esp32/include/esp_now.h \
## Bluetooth - API Reference

16
docs/api-reference/wifi/esp_wifi.rst
View File

@ -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
--------------------
@ -22,4 +28,6 @@ API Reference
-------------
.. include:: /_build/inc/esp_wifi.inc
.. include:: /_build/inc/esp_wifi_types.inc