From 3984d96acbc0de6dda137367f1de6084434ba0fd Mon Sep 17 00:00:00 2001 From: Liu Zhi Fu Date: Mon, 12 Dec 2016 10:00:24 +0800 Subject: [PATCH] esp32: refactor to sniffer 1. TW8657, WIFI send the whole packet to smartconfig; 2. modify API annotation of smartconfig and sniffer; 3. export smartconfig APIs to programming guide; --- components/esp32/include/esp_smartconfig.h | 99 ++++++++++------------ components/esp32/include/esp_wifi.h | 12 ++- components/esp32/include/esp_wifi_types.h | 49 ++++++++++- docs/Doxyfile | 3 +- docs/api/esp_smartconfig.rst | 25 ++++++ docs/index.rst | 1 + 6 files changed, 125 insertions(+), 64 deletions(-) mode change 100644 => 100755 components/esp32/include/esp_wifi.h mode change 100644 => 100755 components/esp32/include/esp_wifi_types.h create mode 100644 docs/api/esp_smartconfig.rst diff --git a/components/esp32/include/esp_smartconfig.h b/components/esp32/include/esp_smartconfig.h index b30ce1a11..916c4c170 100644 --- a/components/esp32/include/esp_smartconfig.h +++ b/components/esp32/include/esp_smartconfig.h @@ -3,7 +3,7 @@ // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at - +// // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software @@ -11,10 +11,12 @@ // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. + #ifndef __ESP_SMARTCONFIG_H__ #define __ESP_SMARTCONFIG_H__ + #include -#include +#include #include "esp_err.h" #ifdef __cplusplus @@ -22,11 +24,11 @@ extern "C" { #endif typedef enum { - SC_STATUS_WAIT = 0, /**< waiting, do not start connection in this phase */ - SC_STATUS_FIND_CHANNEL, /**< find target channel, start connection by APP in this phase */ - SC_STATUS_GETTING_SSID_PSWD, /**< getting SSID and password of target AP */ - SC_STATUS_LINK, /**< connecting to target AP */ - SC_STATUS_LINK_OVER, /**< got IP, connect to AP successfully */ + SC_STATUS_WAIT = 0, /**< Waiting to start connect */ + SC_STATUS_FIND_CHANNEL, /**< Finding target channel */ + SC_STATUS_GETTING_SSID_PSWD, /**< Getting SSID and password of target AP */ + SC_STATUS_LINK, /**< Connecting to target AP */ + SC_STATUS_LINK_OVER, /**< Connected to AP successfully */ } smartconfig_status_t; typedef enum { @@ -38,48 +40,38 @@ typedef enum { /** * @brief The callback of SmartConfig, executed when smart-config status changed. * - * @param smartconfig_status_t status : status of SmartConfig: - * - if status == SC_STATUS_GETTING_SSID_PSWD, parameter void *pdata is a pointer - of smartconfig_type_t, means SmartConfig type: AirKiss or ESP-TOUCH. - * - if status == SC_STATUS_LINK, parameter void *pdata is a pointer of struct station_config; - * - if status == SC_STATUS_LINK_OVER, parameter void *pdata is a pointer of mobile - * phone's IP address, 4 bytes. This is only available in ESPTOUCH, otherwise, - * it is NULL. - * - otherwise, parameter void *pdata is NULL. - * @param void *pdata : data of SmartConfig + * @param status Status of SmartConfig: + * - SC_STATUS_GETTING_SSID_PSWD : pdata is a pointer of smartconfig_type_t, means config type. + * - SC_STATUS_LINK : pdata is a pointer of struct station_config. + * - SC_STATUS_LINK_OVER : pdata is a pointer of phone's IP address(4 bytes) if pdata unequal NULL. + * - otherwise : parameter void *pdata is NULL. + * @param pdata According to the different status have different values. * - * @return null */ typedef void (*sc_callback_t)(smartconfig_status_t status, void *pdata); /** * @brief Get the version of SmartConfig. * - * @param null - * - * @return SmartConfig version + * @return + * - SmartConfig version const char. */ const char *esp_smartconfig_get_version(void); /** - * @brief Start SmartConfig mode. + * @brief Start SmartConfig, config ESP device to connect AP. You need to broadcast information by phone APP. + * Device sniffer special packets from the air that containing SSID and password of target AP. * - * Start SmartConfig mode, to connect ESP32 station to AP, by sniffing - * for special packets from the air, containing SSID and password of desired AP. - * You need to broadcast the SSID and password (e.g. from mobile device or computer) - * with the SSID and password encoded. - * - * @attention 1. This API can only be called in station mode. - * @attention 2. During SmartConfig, ESP32 station and soft-AP are disabled. - * @attention 3. Can not call esp_smartconfig_start twice before it finish, please call + * @attention 1. This API can be called in station or softAP-station mode. + * @attention 2. Can not call esp_smartconfig_start twice before it finish, please call * esp_smartconfig_stop first. - * @attention 4. Don't call any other APIs during SmartConfig, please call esp_smartconfig_stop first. * - * @param sc_callback_t cb : SmartConfig callback; executed when SmartConfig status changed; - * @param uint8 log : 1, UART output logs; otherwise, UART only outputs the result. + * @param cb SmartConfig callback function. + * @param ... log 1: UART output logs; 0: UART only outputs the result. * - * @return ESP_OK : succeed - * @return others : fail + * @return + * - ESP_OK: succeed + * - others: fail */ esp_err_t esp_smartconfig_start(sc_callback_t cb, ...); @@ -89,23 +81,22 @@ esp_err_t esp_smartconfig_start(sc_callback_t cb, ...); * @attention Whether connect to AP succeed or not, this API should be called to free * memory taken by smartconfig_start. * - * @param null - * - * @return ESP_OK : succeed - * @return others : fail + * @return + * - ESP_OK: succeed + * - others: fail */ esp_err_t esp_smartconfig_stop(void); /** - * @brief Set timeout of SmartConfig. + * @brief Set timeout of SmartConfig process. * - * @attention SmartConfig timeout start at SC_STATUS_FIND_CHANNEL, SmartConfig will - * restart if timeout. + * @attention Timing starts from SC_STATUS_FIND_CHANNEL status. SmartConfig will restart if timeout. * - * @param uint8 time_s : range 15s~255s, offset:45s. + * @param time_s range 15s~255s, offset:45s. * - * @return ESP_OK : succeed - * @return others : fail + * @return + * - ESP_OK: succeed + * - others: fail */ esp_err_t esp_esptouch_set_timeout(uint8_t time_s); @@ -115,27 +106,29 @@ esp_err_t esp_esptouch_set_timeout(uint8_t time_s); * @attention If users need to set the SmartConfig type, please set it before calling * esp_smartconfig_start. * - * @param smartconfig_type_t type : AirKiss, ESP-TOUCH or both. + * @param type Choose from the smartconfig_type_t. * - * @return ESP_OK : succeed - * @return others : fail + * @return + * - ESP_OK: succeed + * - others: fail */ esp_err_t esp_smartconfig_set_type(smartconfig_type_t type); /** * @brief Set mode of SmartConfig. default normal mode. * - * @attention If users need to set the SmartConfig mode, please set it before calling - * esp_smartconfig_start. Different mode should match different APP(phone). + * @attention 1. Please call it before API esp_smartconfig_start. + * @attention 2. Fast mode have corresponding APP(phone). + * @attention 3. Two mode is compatible. * - * @param bool enable : false-disable(default); true-enable; + * @param enable false-disable(default); true-enable; * - * @return ESP_OK : succeed - * @return others : fail + * @return + * - ESP_OK: succeed + * - others: fail */ esp_err_t esp_smartconfig_fast_mode(bool enable); - #ifdef __cplusplus } #endif diff --git a/components/esp32/include/esp_wifi.h b/components/esp32/include/esp_wifi.h old mode 100644 new mode 100755 index 00e9ec1d6..68d06aae5 --- a/components/esp32/include/esp_wifi.h +++ b/components/esp32/include/esp_wifi.h @@ -507,16 +507,14 @@ esp_err_t esp_wifi_set_mac(wifi_interface_t ifx, uint8_t mac[6]); esp_err_t esp_wifi_get_mac(wifi_interface_t ifx, uint8_t mac[6]); /** - * @brief The RX callback function in the promiscuous mode. + * @brief The RX callback function in the promiscuous mode. + * Each time a packet is received, the callback function will be called. * - * Each time a packet is received, the callback function will be called. + * @param buf Data received. Type of data in buffer (wifi_promiscuous_pkt_t or wifi_pkt_rx_ctrl_t) indicated by 'type' parameter. + * @param type promiscuous packet type. * - * @param buf the data received - * @param len data length - * - * @return none */ -typedef void (* wifi_promiscuous_cb_t)(void *buf, uint16_t len); +typedef void (* wifi_promiscuous_cb_t)(void *buf, wifi_promiscuous_pkt_type_t type); /** * @brief Register the RX callback function in the promiscuous mode. diff --git a/components/esp32/include/esp_wifi_types.h b/components/esp32/include/esp_wifi_types.h old mode 100644 new mode 100755 index c5dd021fe..583d7a6a9 --- a/components/esp32/include/esp_wifi_types.h +++ b/components/esp32/include/esp_wifi_types.h @@ -150,13 +150,14 @@ typedef union { typedef struct { uint8_t mac[6]; /**< mac address of sta that associated with ESP32 soft-AP */ -}wifi_sta_info_t; +} wifi_sta_info_t; #define ESP_WIFI_MAX_CONN_NUM (10) /**< max number of stations which can connect to 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 */ -}wifi_sta_list_t; +} wifi_sta_list_t; typedef enum { WIFI_STORAGE_FLASH, /**< all configuration will strore in both memory and flash */ @@ -184,10 +185,52 @@ typedef enum { WIFI_VND_IE_ID_1, } wifi_vendor_ie_id_t; +typedef struct { + signed rssi:8; /**< signal intensity of packet */ + unsigned rate:5; /**< data rate */ + unsigned :1; /**< reserve */ + unsigned sig_mode:2; /**< 0:is not 11n packet; 1:is 11n packet */ + unsigned :16; /**< reserve */ + unsigned mcs:7; /**< if is 11n packet, shows the modulation(range from 0 to 76) */ + unsigned cwb:1; /**< if is 11n packet, shows if is HT40 packet or not */ + unsigned :16; /**< reserve */ + unsigned smoothing:1; /**< reserve */ + unsigned not_sounding:1; /**< reserve */ + 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 sgi:1; /**< SGI */ + unsigned noise_floor:8; /**< noise floor */ + unsigned ampdu_cnt:8; /**< ampdu cnt */ + unsigned channel:4; /**< which channel this packet in */ + unsigned :12; /**< reserve */ + unsigned timestamp:32; /**< timestamp */ + unsigned :32; /**< reserve */ + unsigned :32; /**< reserve */ + unsigned sig_len:12; /**< It is really lenth of packet */ + unsigned :12; /**< reserve */ + unsigned rx_state:8; /**< rx state */ +} wifi_pkt_rx_ctrl_t; + +typedef struct { + wifi_pkt_rx_ctrl_t rx_ctrl; + char payload[0]; /**< ieee80211 packet buff, The length of payload is described by sig_len */ +} wifi_promiscuous_pkt_t; + +/** + * @brief Promiscuous frame type + * + */ +typedef enum { + WIFI_PKT_CTRL, /**< control type, receive packet buf is wifi_pkt_rx_ctrl_t */ + 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, receive packet buf is wifi_promiscuous_pkt_t */ +} wifi_promiscuous_pkt_type_t; #ifdef __cplusplus } #endif - #endif /* __ESP_WIFI_TYPES_H__ */ diff --git a/docs/Doxyfile b/docs/Doxyfile index 2456b6c2e..e2c85f0de 100755 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -30,7 +30,8 @@ INPUT = ../components/esp32/include/esp_wifi.h \ ../components/ulp/include/esp32/ulp.h \ ../components/esp32/include/esp_intr_alloc.h \ ../components/esp32/include/esp_heap_alloc_caps.h \ - ../components/freertos/include/freertos/heap_regions.h + ../components/freertos/include/freertos/heap_regions.h \ + ../components/esp32/include/esp_smartconfig.h ## Get warnings for functions that have no documentation for their parameters or return value ## diff --git a/docs/api/esp_smartconfig.rst b/docs/api/esp_smartconfig.rst new file mode 100644 index 000000000..262218aa8 --- /dev/null +++ b/docs/api/esp_smartconfig.rst @@ -0,0 +1,25 @@ +Smart Config +=== + +API Reference +------------- + +Header Files +^^^^^^^^^^^^ + + * `esp32/include/esp_smartconfig.h `_ + +Type Definitions +^^^^^^^^^^^^^^^^ + +.. doxygentypedef:: sc_callback_t + +Functions +^^^^^^^^^ + +.. doxygenfunction:: esp_smartconfig_get_version +.. doxygenfunction:: esp_smartconfig_start +.. doxygenfunction:: esp_smartconfig_stop +.. doxygenfunction:: esp_esptouch_set_timeout +.. doxygenfunction:: esp_smartconfig_set_type +.. doxygenfunction:: esp_smartconfig_fast_mode diff --git a/docs/index.rst b/docs/index.rst index 8a42e762c..f6ee6a133 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -97,6 +97,7 @@ Contents: :maxdepth: 1 Wi-Fi + Smart Config Bluetooth Watchdogs OTA