From b3603ccf58aa361109e23272cd082c94d4ffde2a Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Thu, 29 Jun 2017 17:19:17 +1000 Subject: [PATCH 1/2] esp_wifi header: Fix typo --- components/esp32/include/esp_wifi.h | 69 +++++++++++++++-------------- 1 file changed, 35 insertions(+), 34 deletions(-) diff --git a/components/esp32/include/esp_wifi.h b/components/esp32/include/esp_wifi.h index 6e51bf2efa..6f1e8729ec 100755 --- a/components/esp32/include/esp_wifi.h +++ b/components/esp32/include/esp_wifi.h @@ -196,7 +196,7 @@ esp_err_t esp_wifi_deinit(void); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_ARG: invalid argument * - others: refer to error code in esp_err.h */ @@ -209,7 +209,7 @@ esp_err_t esp_wifi_set_mode(wifi_mode_t mode); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_ARG: invalid argument */ esp_err_t esp_wifi_get_mode(wifi_mode_t *mode); @@ -222,7 +222,7 @@ esp_err_t esp_wifi_get_mode(wifi_mode_t *mode); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_ARG: invalid argument * - ESP_ERR_WIFI_NO_MEM: out of memory * - ESP_ERR_WIFI_CONN: WiFi internal error, station or soft-AP control block wrong @@ -238,7 +238,7 @@ esp_err_t esp_wifi_start(void); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init */ esp_err_t esp_wifi_stop(void); @@ -253,7 +253,7 @@ esp_err_t esp_wifi_stop(void); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init */ esp_err_t esp_wifi_restore(void); @@ -265,7 +265,7 @@ esp_err_t esp_wifi_restore(void); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start * - ESP_ERR_WIFI_CONN: WiFi internal error, station or soft-AP control block wrong * - ESP_ERR_WIFI_SSID: SSID of AP which station connects is invalid @@ -277,7 +277,7 @@ esp_err_t esp_wifi_connect(void); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi was not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi was not initialized by esp_wifi_init * - ESP_ERR_WIFI_NOT_STARTED: WiFi was not started by esp_wifi_start * - ESP_ERR_WIFI_FAIL: other WiFi internal errors */ @@ -300,7 +300,7 @@ esp_err_t esp_wifi_clear_fast_connect(void); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_NOT_STARTED: WiFi was not started by esp_wifi_start * - ESP_ERR_WIFI_ARG: invalid argument * - ESP_ERR_WIFI_MODE: WiFi mode is wrong @@ -322,7 +322,7 @@ esp_err_t esp_wifi_deauth_sta(uint16_t aid); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_NOT_STARTED: WiFi was not started by esp_wifi_start * - ESP_ERR_WIFI_TIMEOUT: blocking scan is timeout * - others: refer to error code in esp_err.h @@ -334,7 +334,7 @@ esp_err_t esp_wifi_scan_start(wifi_scan_config_t *config, bool block); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start */ esp_err_t esp_wifi_scan_stop(void); @@ -348,7 +348,7 @@ esp_err_t esp_wifi_scan_stop(void); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start * - ESP_ERR_WIFI_ARG: invalid argument */ @@ -363,7 +363,7 @@ esp_err_t esp_wifi_scan_get_ap_num(uint16_t *number); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start * - ESP_ERR_WIFI_ARG: invalid argument * - ESP_ERR_WIFI_NO_MEM: out of memory @@ -415,7 +415,7 @@ esp_err_t esp_wifi_get_ps(wifi_ps_type_t *type); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_IF: invalid interface * - others: refer to error codes in esp_err.h */ @@ -429,7 +429,7 @@ esp_err_t esp_wifi_set_protocol(wifi_interface_t ifx, uint8_t protocol_bitmap); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_IF: invalid interface * - ESP_ERR_WIFI_ARG: invalid argument * - others: refer to error codes in esp_err.h @@ -447,7 +447,7 @@ esp_err_t esp_wifi_get_protocol(wifi_interface_t ifx, uint8_t *protocol_bitmap); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_IF: invalid interface * - ESP_ERR_WIFI_ARG: invalid argument * - others: refer to error codes in esp_err.h @@ -464,7 +464,7 @@ esp_err_t esp_wifi_set_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t bw); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_IF: invalid interface * - ESP_ERR_WIFI_ARG: invalid argument */ @@ -481,7 +481,7 @@ esp_err_t esp_wifi_get_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t *bw); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_IF: invalid interface * - ESP_ERR_WIFI_ARG: invalid argument */ @@ -497,7 +497,7 @@ esp_err_t esp_wifi_set_channel(uint8_t primary, wifi_second_chan_t second); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_ARG: invalid argument */ esp_err_t esp_wifi_get_channel(uint8_t *primary, wifi_second_chan_t *second); @@ -510,7 +510,7 @@ esp_err_t esp_wifi_get_channel(uint8_t *primary, wifi_second_chan_t *second); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_ARG: invalid argument * - others: refer to error code in esp_err.h */ @@ -523,7 +523,7 @@ esp_err_t esp_wifi_set_country(wifi_country_t country); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_ARG: invalid argument */ esp_err_t esp_wifi_get_country(wifi_country_t *country); @@ -541,7 +541,7 @@ esp_err_t esp_wifi_get_country(wifi_country_t *country); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_ARG: invalid argument * - ESP_ERR_WIFI_IF: invalid interface * - ESP_ERR_WIFI_MAC: invalid mac address @@ -558,7 +558,7 @@ esp_err_t esp_wifi_set_mac(wifi_interface_t ifx, uint8_t mac[6]); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_ARG: invalid argument * - ESP_ERR_WIFI_IF: invalid interface */ @@ -583,7 +583,7 @@ typedef void (* wifi_promiscuous_cb_t)(void *buf, wifi_promiscuous_pkt_type_t ty * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init */ esp_err_t esp_wifi_set_promiscuous_rx_cb(wifi_promiscuous_cb_t cb); @@ -594,7 +594,7 @@ esp_err_t esp_wifi_set_promiscuous_rx_cb(wifi_promiscuous_cb_t cb); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init */ esp_err_t esp_wifi_set_promiscuous(bool en); @@ -605,7 +605,7 @@ esp_err_t esp_wifi_set_promiscuous(bool en); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_ARG: invalid argument */ esp_err_t esp_wifi_get_promiscuous(bool *en); @@ -619,7 +619,7 @@ esp_err_t esp_wifi_get_promiscuous(bool *en); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init */ esp_err_t esp_wifi_set_promiscuous_filter(const wifi_promiscuous_filter_t *filter); @@ -630,7 +630,7 @@ esp_err_t esp_wifi_set_promiscuous_filter(const wifi_promiscuous_filter_t *filte * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_ARG: invalid argument */ esp_err_t esp_wifi_get_promiscuous_filter(wifi_promiscuous_filter_t *filter); @@ -648,7 +648,7 @@ esp_err_t esp_wifi_get_promiscuous_filter(wifi_promiscuous_filter_t *filter); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_ARG: invalid argument * - ESP_ERR_WIFI_IF: invalid interface * - ESP_ERR_WIFI_MODE: invalid mode @@ -666,7 +666,7 @@ esp_err_t esp_wifi_set_config(wifi_interface_t ifx, wifi_config_t *conf); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_ARG: invalid argument * - ESP_ERR_WIFI_IF: invalid interface */ @@ -681,7 +681,7 @@ esp_err_t esp_wifi_get_config(wifi_interface_t ifx, wifi_config_t *conf); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_ARG: invalid argument * - ESP_ERR_WIFI_MODE: WiFi mode is wrong * - ESP_ERR_WIFI_CONN: WiFi internal error, the station/soft-AP control block is invalid @@ -698,7 +698,7 @@ esp_err_t esp_wifi_ap_get_sta_list(wifi_sta_list_t *sta); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_ARG: invalid argument */ esp_err_t esp_wifi_set_storage(wifi_storage_t storage); @@ -711,7 +711,7 @@ esp_err_t esp_wifi_set_storage(wifi_storage_t storage); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_MODE: WiFi internal error, the station/soft-AP control block is invalid * - others: refer to error code in esp_err.h */ @@ -724,7 +724,7 @@ esp_err_t esp_wifi_set_auto_connect(bool en); * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init * - ESP_ERR_WIFI_ARG: invalid argument */ esp_err_t esp_wifi_get_auto_connect(bool *en); @@ -742,6 +742,7 @@ esp_err_t esp_wifi_get_auto_connect(bool *en); * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init * - ESP_ERR_WIFI_ARG: invalid argument * - ESP_ERR_WIFI_NO_MEM: out of memory + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init() */ esp_err_t esp_wifi_set_vendor_ie(bool enable, wifi_vendor_ie_type_t type, wifi_vendor_ie_id_t idx, uint8_t *vnd_ie); @@ -763,7 +764,7 @@ typedef void (*esp_vendor_ie_cb_t) (void *ctx, wifi_vendor_ie_type_t type, const * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init + * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init */ esp_err_t esp_wifi_set_vendor_ie_cb(esp_vendor_ie_cb_t cb, void *ctx); From 5c925bf96ed2ccf507f07c909a6430929212deb0 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Thu, 29 Jun 2017 17:20:45 +1000 Subject: [PATCH 2/2] esp_wifi.h: Document the Vendor-Specific Information Element functions --- components/esp32/include/esp_wifi.h | 39 ++++++++++++----------- components/esp32/include/esp_wifi_types.h | 21 ++++++++++-- 2 files changed, 39 insertions(+), 21 deletions(-) diff --git a/components/esp32/include/esp_wifi.h b/components/esp32/include/esp_wifi.h index 6f1e8729ec..5f7aa9c222 100755 --- a/components/esp32/include/esp_wifi.h +++ b/components/esp32/include/esp_wifi.h @@ -730,37 +730,38 @@ esp_err_t esp_wifi_set_auto_connect(bool en); esp_err_t esp_wifi_get_auto_connect(bool *en); /** - * @brief Set vendor specific element + * @brief Set 802.11 Vendor-Specific Information Element * - * @param enable enable or not - * @param type information element type - * @param idx information element index - * @param vnd_ie pointer to a vendor specific element + * @param enable If true, specified IE is enabled. If false, specified IE is removed. + * @param type Information Element type. Determines the frame type to associate with the IE. + * @param idx Index to set or clear. Each IE type can be associated with up to two elements (indices 0 & 1). + * @param vnd_ie Pointer to vendor specific element data. First 6 bytes should be a header with fields matching vendor_ie_data_t. + * If enable is false, this argument is ignored and can be NULL. Data does not need to remain valid after the function returns. * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init - * - ESP_ERR_WIFI_ARG: invalid argument - * - ESP_ERR_WIFI_NO_MEM: out of memory * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init() + * - ESP_ERR_WIFI_ARG: Invalid argument, including if first byte of vnd_ie is not WIFI_VENDOR_IE_ELEMENT_ID (0xDD) + * or second byte is an invalid length. + * - ESP_ERR_WIFI_NO_MEM: Out of memory */ -esp_err_t esp_wifi_set_vendor_ie(bool enable, wifi_vendor_ie_type_t type, wifi_vendor_ie_id_t idx, uint8_t *vnd_ie); +esp_err_t esp_wifi_set_vendor_ie(bool enable, wifi_vendor_ie_type_t type, wifi_vendor_ie_id_t idx, const void *vnd_ie); /** - * @brief Define function pointer for vendor specific element callback - * @param ctx reserved - * @param type information element type - * @param sa source address - * @param vnd_ie pointer to a vendor specific element - * @param rssi received signal strength indication + * @brief Function signature for received Vendor-Specific Information Element callback. + * @param ctx Context argument, as passed to esp_wifi_set_vendor_ie_cb() when registering callback. + * @param type Information element type, based on frame type received. + * @param sa Source 802.11 address. + * @param vnd_ie Pointer to the vendor specific element data received. + * @param rssi Received signal strength indication. */ -typedef void (*esp_vendor_ie_cb_t) (void *ctx, wifi_vendor_ie_type_t type, const uint8_t sa[6], const uint8_t *vnd_ie, int rssi); +typedef void (*esp_vendor_ie_cb_t) (void *ctx, wifi_vendor_ie_type_t type, const uint8_t sa[6], const vendor_ie_data_t *vnd_ie, int rssi); /** - * @brief Set vendor specific element callback + * @brief Register Vendor-Specific Information Element monitoring callback. * - * @param cb callback function - * @param ctx reserved + * @param cb Callback function + * @param ctx Context argument, passed to callback function. * * @return * - ESP_OK: succeed diff --git a/components/esp32/include/esp_wifi_types.h b/components/esp32/include/esp_wifi_types.h index f9a0467399..2410b73ce1 100755 --- a/components/esp32/include/esp_wifi_types.h +++ b/components/esp32/include/esp_wifi_types.h @@ -188,8 +188,9 @@ typedef enum { } wifi_storage_t; /** - * @brief Vendor IE type + * @brief Vendor Information Element type * + * Determines the frame type that the IE will be associated with. */ typedef enum { WIFI_VND_IE_TYPE_BEACON, @@ -200,14 +201,30 @@ typedef enum { } wifi_vendor_ie_type_t; /** - * @brief Vendor IE index + * @brief Vendor Information Element index * + * Each IE type can have up to two associated vendor ID elements. */ typedef enum { WIFI_VND_IE_ID_0, WIFI_VND_IE_ID_1, } wifi_vendor_ie_id_t; +#define WIFI_VENDOR_IE_ELEMENT_ID 0xDD + +/** + * @brief Vendor Information Element header + * + * The first bytes of the Information Element will match this header. Payload follows. + */ +typedef struct { + uint8_t element_id; /**< Should be set to WIFI_VENDOR_IE_ELEMENT_ID (0xDD) */ + uint8_t length; /**< Length of all bytes in the element data following this field. Minimum 4. */ + uint8_t vendor_oui[3]; /**< Vendor identifier (OUI). */ + uint8_t vendor_oui_type; /**< Vendor-specific OUI type. */ + uint8_t payload[0]; /**< Payload. Length is equal to value in 'length' field, minus 4. */ +} vendor_ie_data_t; + typedef struct { signed rssi:8; /**< signal intensity of packet */ unsigned rate:5; /**< data rate */