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

@@ -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 <stdint.h>
-#include <esp_types.h>
+#include <stdbool.h>
 #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_WAIT = 0,             /**< Waiting to start connect */
-    SC_STATUS_FIND_CHANNEL,         /**< find target channel, start connection by APP in this phase */
+    SC_STATUS_FIND_CHANNEL,         /**< Finding target channel */
-    SC_STATUS_GETTING_SSID_PSWD,    /**< getting SSID and password of target AP */
+    SC_STATUS_GETTING_SSID_PSWD,    /**< Getting SSID and password of target AP */
-    SC_STATUS_LINK,                 /**< connecting to target AP */
+    SC_STATUS_LINK,                 /**< Connecting to target AP */
-    SC_STATUS_LINK_OVER,            /**< got IP, connect to AP successfully */
+    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:
+  * @param  status  Status of SmartConfig:
-  *    -  if status == SC_STATUS_GETTING_SSID_PSWD, parameter void *pdata is a pointer
+  *    - SC_STATUS_GETTING_SSID_PSWD : pdata is a pointer of smartconfig_type_t, means config type.
-                       of smartconfig_type_t, means SmartConfig type: AirKiss or ESP-TOUCH.
+  *    - SC_STATUS_LINK : pdata is a pointer of struct station_config.
-  *    -  if status == SC_STATUS_LINK, parameter void *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.
-  *    -  if status == SC_STATUS_LINK_OVER, parameter void *pdata is a pointer of mobile
+  *    - otherwise : parameter void *pdata is NULL.
-  *                    phone's IP address, 4 bytes. This is only available in ESPTOUCH, otherwise,
+  * @param  pdata  According to the different status have different values.
-  *                    it is NULL.
-  *    -  otherwise, parameter void *pdata is NULL.
-  * @param  void *pdata : data of SmartConfig
   *
-  * @return null
   */
 typedef void (*sc_callback_t)(smartconfig_status_t status, void *pdata);
 
 /**
   * @brief  Get the version of SmartConfig.
   *
-  * @param  null
+  * @return
-  *
+  *     - SmartConfig version const char.
-  * @return SmartConfig version
   */
 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
+  * @attention 1. This API can be called in station or softAP-station mode.
-  *            for special packets from the air, containing SSID and password of desired AP.
+  * @attention 2. Can not call esp_smartconfig_start twice before it finish, please call
-  *            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
   *               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     cb  SmartConfig callback function.
-  * @param     uint8 log : 1, UART output logs; otherwise, UART only outputs the result.
+  * @param     ... log  1: UART output logs; 0: UART only outputs the result.
   *
-  * @return    ESP_OK : succeed
+  * @return
-  * @return    others : fail
+  *     - 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    ESP_OK : succeed
+  *     - others: fail
-  * @return    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
+  * @attention Timing starts from SC_STATUS_FIND_CHANNEL status. SmartConfig will restart if timeout.
-  *            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
-  * @return    others : fail
+  *     - 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
-  * @return    others : fail
+  *     - 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
+  * @attention 1. Please call it before API esp_smartconfig_start.
-  *            esp_smartconfig_start. Different mode should match different APP(phone).
+  * @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
-  * @return    others : fail
+  *     - ESP_OK: succeed
+  *     - others: fail
   */
 esp_err_t esp_smartconfig_fast_mode(bool enable);
 
-
 #ifdef __cplusplus
 }
 #endif

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.

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__ */

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

docs/api/esp_smartconfig.rst

@@ -0,0 +1,25 @@
+Smart Config
+===
+
+API Reference
+-------------
+
+Header Files
+^^^^^^^^^^^^
+
+  * `esp32/include/esp_smartconfig.h <https://github.com/espressif/esp-idf/blob/master/components/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

docs/index.rst

@@ -97,6 +97,7 @@ Contents:
    :maxdepth: 1
 
    Wi-Fi <api/esp_wifi>
+   Smart Config <api/esp_smartconfig>
    Bluetooth <api/bt>
    Watchdogs <api/wdts>
    OTA <api/ota>