granicus.if.org Git - esp-idf/blob - components/esp32/include/esp_wifi_types.h

   1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6
   7 //     http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15
  16 #ifndef __ESP_WIFI_TYPES_H__
  17 #define __ESP_WIFI_TYPES_H__
  18
  19 #include <stdint.h>
  20 #include <stdbool.h>
  21 #include "rom/queue.h"
  22 #include "esp_err.h"
  23 #include "esp_interface.h"
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 typedef enum {
  30     WIFI_MODE_NULL = 0,  /**< null mode */
  31     WIFI_MODE_STA,       /**< WiFi station mode */
  32     WIFI_MODE_AP,        /**< WiFi soft-AP mode */
  33     WIFI_MODE_APSTA,     /**< WiFi station + soft-AP mode */
  34     WIFI_MODE_MAX
  35 } wifi_mode_t;
  36
  37 typedef esp_interface_t wifi_interface_t;
  38
  39 #define WIFI_IF_STA ESP_IF_WIFI_STA
  40 #define WIFI_IF_AP  ESP_IF_WIFI_AP
  41
  42 typedef enum {
  43     WIFI_COUNTRY_POLICY_AUTO,   /**< Country policy is auto, use the country info of AP to which the station is connected */
  44     WIFI_COUNTRY_POLICY_MANUAL, /**< Country policy is manual, always use the configured country info */
  45 } wifi_country_policy_t;
  46
  47 /** @brief Structure describing WiFi country-based regional restrictions. */
  48 typedef struct {
  49     char                  cc[3];   /**< country code string */
  50     uint8_t               schan;   /**< start channel */
  51     uint8_t               nchan;   /**< total channel number */
  52     wifi_country_policy_t policy;  /**< country policy */
  53 } wifi_country_t;
  54
  55 typedef enum {
  56     WIFI_AUTH_OPEN = 0,         /**< authenticate mode : open */
  57     WIFI_AUTH_WEP,              /**< authenticate mode : WEP */
  58     WIFI_AUTH_WPA_PSK,          /**< authenticate mode : WPA_PSK */
  59     WIFI_AUTH_WPA2_PSK,         /**< authenticate mode : WPA2_PSK */
  60     WIFI_AUTH_WPA_WPA2_PSK,     /**< authenticate mode : WPA_WPA2_PSK */
  61     WIFI_AUTH_WPA2_ENTERPRISE,  /**< authenticate mode : WPA2_ENTERPRISE */
  62     WIFI_AUTH_MAX
  63 } wifi_auth_mode_t;
  64
  65 typedef enum {
  66     WIFI_REASON_UNSPECIFIED              = 1,
  67     WIFI_REASON_AUTH_EXPIRE              = 2,
  68     WIFI_REASON_AUTH_LEAVE               = 3,
  69     WIFI_REASON_ASSOC_EXPIRE             = 4,
  70     WIFI_REASON_ASSOC_TOOMANY            = 5,
  71     WIFI_REASON_NOT_AUTHED               = 6,
  72     WIFI_REASON_NOT_ASSOCED              = 7,
  73     WIFI_REASON_ASSOC_LEAVE              = 8,
  74     WIFI_REASON_ASSOC_NOT_AUTHED         = 9,
  75     WIFI_REASON_DISASSOC_PWRCAP_BAD      = 10,
  76     WIFI_REASON_DISASSOC_SUPCHAN_BAD     = 11,
  77     WIFI_REASON_IE_INVALID               = 13,
  78     WIFI_REASON_MIC_FAILURE              = 14,
  79     WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT   = 15,
  80     WIFI_REASON_GROUP_KEY_UPDATE_TIMEOUT = 16,
  81     WIFI_REASON_IE_IN_4WAY_DIFFERS       = 17,
  82     WIFI_REASON_GROUP_CIPHER_INVALID     = 18,
  83     WIFI_REASON_PAIRWISE_CIPHER_INVALID  = 19,
  84     WIFI_REASON_AKMP_INVALID             = 20,
  85     WIFI_REASON_UNSUPP_RSN_IE_VERSION    = 21,
  86     WIFI_REASON_INVALID_RSN_IE_CAP       = 22,
  87     WIFI_REASON_802_1X_AUTH_FAILED       = 23,
  88     WIFI_REASON_CIPHER_SUITE_REJECTED    = 24,
  89
  90     WIFI_REASON_BEACON_TIMEOUT           = 200,
  91     WIFI_REASON_NO_AP_FOUND              = 201,
  92     WIFI_REASON_AUTH_FAIL                = 202,
  93     WIFI_REASON_ASSOC_FAIL               = 203,
  94     WIFI_REASON_HANDSHAKE_TIMEOUT        = 204,
  95 } wifi_err_reason_t;
  96
  97 typedef enum {
  98     WIFI_SECOND_CHAN_NONE = 0,  /**< the channel width is HT20 */
  99     WIFI_SECOND_CHAN_ABOVE,     /**< the channel width is HT40 and the second channel is above the primary channel */
 100     WIFI_SECOND_CHAN_BELOW,     /**< the channel width is HT40 and the second channel is below the primary channel */
 101 } wifi_second_chan_t;
 102
 103 typedef enum {
 104     WIFI_SCAN_TYPE_ACTIVE = 0,  /**< active scan */
 105     WIFI_SCAN_TYPE_PASSIVE,     /**< passive scan */
 106 } wifi_scan_type_t;
 107
 108 /** @brief Range of active scan times per channel */
 109 typedef struct {
 110     uint32_t min;  /**< minimum active scan time per channel, units: millisecond */
 111     uint32_t max;  /**< maximum active scan time per channel, units: millisecond, values above 1500ms may
 112                                           cause station to disconnect from AP and are not recommended.  */
 113 } wifi_active_scan_time_t;
 114
 115 /** @brief Aggregate of active & passive scan time per channel */
 116 typedef union {
 117     wifi_active_scan_time_t active;  /**< active scan time per channel, units: millisecond. */
 118     uint32_t passive;                /**< passive scan time per channel, units: millisecond, values above 1500ms may
 119                                           cause station to disconnect from AP and are not recommended. */
 120 } wifi_scan_time_t;
 121
 122 /** @brief Parameters for an SSID scan. */
 123 typedef struct {
 124     uint8_t *ssid;               /**< SSID of AP */
 125     uint8_t *bssid;              /**< MAC address of AP */
 126     uint8_t channel;             /**< channel, scan the specific channel */
 127     bool show_hidden;            /**< enable to scan AP whose SSID is hidden */
 128     wifi_scan_type_t scan_type;  /**< scan type, active or passive */
 129     wifi_scan_time_t scan_time;  /**< scan time per channel */
 130 } wifi_scan_config_t;
 131
 132 typedef enum {
 133     WIFI_CIPHER_TYPE_NONE = 0,   /**< the cipher type is none */
 134     WIFI_CIPHER_TYPE_WEP40,      /**< the cipher type is WEP40 */
 135     WIFI_CIPHER_TYPE_WEP104,     /**< the cipher type is WEP104 */
 136     WIFI_CIPHER_TYPE_TKIP,       /**< the cipher type is TKIP */
 137     WIFI_CIPHER_TYPE_CCMP,       /**< the cipher type is CCMP */
 138     WIFI_CIPHER_TYPE_TKIP_CCMP,  /**< the cipher type is TKIP and CCMP */
 139     WIFI_CIPHER_TYPE_UNKNOWN,    /**< the cipher type is unknown */
 140 } wifi_cipher_type_t;
 141
 142 /** @brief Description of an WiFi AP */
 143 typedef struct {
 144     uint8_t bssid[6];                     /**< MAC address of AP */
 145     uint8_t ssid[33];                     /**< SSID of AP */
 146     uint8_t primary;                      /**< channel of AP */
 147     wifi_second_chan_t second;            /**< second channel of AP */
 148     int8_t  rssi;                         /**< signal strength of AP */
 149     wifi_auth_mode_t authmode;            /**< authmode of AP */
 150     wifi_cipher_type_t pairwise_cipher;   /**< pairwise cipher of AP */
 151     wifi_cipher_type_t group_cipher;      /**< group cipher of AP */
 152     uint32_t phy_11b:1;                   /**< bit: 0 flag to identify if 11b mode is enabled or not */
 153     uint32_t phy_11g:1;                   /**< bit: 1 flag to identify if 11g mode is enabled or not */
 154     uint32_t phy_11n:1;                   /**< bit: 2 flag to identify if 11n mode is enabled or not */
 155     uint32_t phy_lr:1;                    /**< bit: 3 flag to identify if low rate is enabled or not */
 156     uint32_t wps:1;                       /**< bit: 4 flag to identify if WPS is supported or not */
 157     uint32_t reserved:27;                 /**< bit: 5..31 reserved */
 158 } wifi_ap_record_t;
 159
 160 typedef enum {
 161     WIFI_FAST_SCAN = 0,                   /**< Do fast scan, scan will end after find SSID match AP */
 162     WIFI_ALL_CHANNEL_SCAN,                /**< All channel scan, scan will end after scan all the channel */
 163 }wifi_scan_method_t;
 164
 165 typedef enum {
 166     WIFI_CONNECT_AP_BY_SIGNAL = 0,        /**< Sort match AP in scan list by RSSI */
 167     WIFI_CONNECT_AP_BY_SECURITY,          /**< Sort match AP in scan list by security mode */
 168 }wifi_sort_method_t;
 169
 170 /** @brief Structure describing parameters for a WiFi fast scan */
 171 typedef struct {
 172     int8_t              rssi;             /**< The minimum rssi to accept in the fast scan mode */
 173     wifi_auth_mode_t    authmode;         /**< The weakest authmode to accept in the fast scan mode */
 174 }wifi_fast_scan_threshold_t;
 175
 176 typedef enum {
 177     WIFI_PS_NONE,        /**< No power save */
 178     WIFI_PS_MIN_MODEM,   /**< Minimum modem power saving. In this mode, station wakes up to receive beacon every DTIM period */
 179     WIFI_PS_MAX_MODEM,   /**< Maximum modem power saving. In this mode, interval to receive beacons is determined by the listen_interval parameter in wifi_sta_config_t */
 180 } wifi_ps_type_t;
 181
 182 #define WIFI_PS_MODEM WIFI_PS_MIN_MODEM /**< @deprecated Use WIFI_PS_MIN_MODEM or WIFI_PS_MAX_MODEM instead */
 183
 184 #define WIFI_PROTOCOL_11B         1
 185 #define WIFI_PROTOCOL_11G         2
 186 #define WIFI_PROTOCOL_11N         4
 187 #define WIFI_PROTOCOL_LR          8
 188
 189 typedef enum {
 190     WIFI_BW_HT20 = 1, /* Bandwidth is HT20 */
 191     WIFI_BW_HT40,     /* Bandwidth is HT40 */
 192 } wifi_bandwidth_t;
 193
 194 /** @brief Soft-AP configuration settings for the ESP32 */
 195 typedef struct {
 196     uint8_t ssid[32];           /**< SSID of ESP32 soft-AP */
 197     uint8_t password[64];       /**< Password of ESP32 soft-AP */
 198     uint8_t ssid_len;           /**< Length of SSID. If softap_config.ssid_len==0, check the SSID until there is a termination character; otherwise, set the SSID length according to softap_config.ssid_len. */
 199     uint8_t channel;            /**< Channel of ESP32 soft-AP */
 200     wifi_auth_mode_t authmode;  /**< Auth mode of ESP32 soft-AP. Do not support AUTH_WEP in soft-AP mode */
 201     uint8_t ssid_hidden;        /**< Broadcast SSID or not, default 0, broadcast the SSID */
 202     uint8_t max_connection;     /**< Max number of stations allowed to connect in, default 4, max 4 */
 203     uint16_t beacon_interval;   /**< Beacon interval, 100 ~ 60000 ms, default 100 ms */
 204 } wifi_ap_config_t;
 205
 206 /** @brief STA configuration settings for the ESP32 */
 207 typedef struct {
 208     uint8_t ssid[32];      /**< SSID of target AP*/
 209     uint8_t password[64];  /**< password of target AP*/
 210     wifi_scan_method_t scan_method;    /**< do all channel scan or fast scan */
 211     bool bssid_set;        /**< whether set MAC address of target AP or not. Generally, station_config.bssid_set needs to be 0; and it needs to be 1 only when users need to check the MAC address of the AP.*/
 212     uint8_t bssid[6];     /**< MAC address of target AP*/
 213     uint8_t channel;       /**< channel of target AP. Set to 1~13 to scan starting from the specified channel before connecting to AP. If the channel of AP is unknown, set it to 0.*/
 214     uint16_t listen_interval;   /**< Listen interval for ESP32 station to receive beacon when WIFI_PS_MAX_MODEM is set. Units: AP beacon intervals. Defaults to 3 if set to 0. */
 215     wifi_sort_method_t sort_method;    /**< sort the connect AP in the list by rssi or security mode */
 216     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. */
 217 } wifi_sta_config_t;
 218
 219 /** @brief Configuration data for ESP32 AP or STA.
 220  *
 221  * The usage of this union (for ap or sta configuration) is determined by the accompanying
 222  * interface argument passed to esp_wifi_set_config() or esp_wifi_get_config()
 223  *
 224  */
 225 typedef union {
 226     wifi_ap_config_t  ap;  /**< configuration of AP */
 227     wifi_sta_config_t sta; /**< configuration of STA */
 228 } wifi_config_t;
 229
 230 /** @brief Description of STA associated with AP */
 231 typedef struct {
 232     uint8_t mac[6];  /**< mac address */
 233     uint32_t phy_11b:1;      /**< bit: 0 flag to identify if 11b mode is enabled or not */
 234     uint32_t phy_11g:1;      /**< bit: 1 flag to identify if 11g mode is enabled or not */
 235     uint32_t phy_11n:1;      /**< bit: 2 flag to identify if 11n mode is enabled or not */
 236     uint32_t phy_lr:1;       /**< bit: 3 flag to identify if low rate is enabled or not */
 237     uint32_t reserved:28;    /**< bit: 4..31 reserved */
 238 } wifi_sta_info_t;
 239
 240 #define ESP_WIFI_MAX_CONN_NUM  (10)       /**< max number of stations which can connect to ESP32 soft-AP */
 241
 242 /** @brief List of stations associated with the ESP32 Soft-AP */
 243 typedef struct {
 244     wifi_sta_info_t sta[ESP_WIFI_MAX_CONN_NUM]; /**< station list */
 245     int       num; /**< number of stations in the list (other entries are invalid) */
 246 } wifi_sta_list_t;
 247
 248 typedef enum {
 249     WIFI_STORAGE_FLASH,  /**< all configuration will strore in both memory and flash */
 250     WIFI_STORAGE_RAM,    /**< all configuration will only store in the memory */
 251 } wifi_storage_t;
 252
 253 /**
 254   * @brief     Vendor Information Element type
 255   *
 256   * Determines the frame type that the IE will be associated with.
 257   */
 258 typedef enum {
 259     WIFI_VND_IE_TYPE_BEACON,
 260     WIFI_VND_IE_TYPE_PROBE_REQ,
 261     WIFI_VND_IE_TYPE_PROBE_RESP,
 262     WIFI_VND_IE_TYPE_ASSOC_REQ,
 263     WIFI_VND_IE_TYPE_ASSOC_RESP,
 264 } wifi_vendor_ie_type_t;
 265
 266 /**
 267   * @brief     Vendor Information Element index
 268   *
 269   * Each IE type can have up to two associated vendor ID elements.
 270   */
 271 typedef enum {
 272     WIFI_VND_IE_ID_0,
 273     WIFI_VND_IE_ID_1,
 274 } wifi_vendor_ie_id_t;
 275
 276 #define WIFI_VENDOR_IE_ELEMENT_ID 0xDD
 277
 278 /**
 279  * @brief Vendor Information Element header
 280  *
 281  * The first bytes of the Information Element will match this header. Payload follows.
 282  */
 283 typedef struct {
 284     uint8_t element_id;      /**< Should be set to WIFI_VENDOR_IE_ELEMENT_ID (0xDD) */
 285     uint8_t length;          /**< Length of all bytes in the element data following this field. Minimum 4. */
 286     uint8_t vendor_oui[3];   /**< Vendor identifier (OUI). */
 287     uint8_t vendor_oui_type; /**< Vendor-specific OUI type. */
 288     uint8_t payload[0];      /**< Payload. Length is equal to value in 'length' field, minus 4. */
 289 } vendor_ie_data_t;
 290
 291 /** @brief Received packet radio metadata header, this is the common header at the beginning of all promiscuous mode RX callback buffers */
 292 typedef struct {
 293     signed rssi:8;            /**< signal intensity of packet */
 294     unsigned rate:5;          /**< data rate */
 295     unsigned :1;              /**< reserve */
 296     unsigned sig_mode:2;      /**< 0:is not 11n packet; 1:is 11n packet */
 297     unsigned :16;             /**< reserve */
 298     unsigned mcs:7;           /**< if is 11n packet, shows the modulation(range from 0 to 76) */
 299     unsigned cwb:1;           /**< if is 11n packet, shows if is HT40 packet or not */
 300     unsigned :16;             /**< reserve */
 301     unsigned smoothing:1;     /**< reserve */
 302     unsigned not_sounding:1;  /**< reserve */
 303     unsigned :1;              /**< reserve */
 304     unsigned aggregation:1;   /**< Aggregation */
 305     unsigned stbc:2;          /**< STBC */
 306     unsigned fec_coding:1;    /**< Flag is set for 11n packets which are LDPC */
 307     unsigned sgi:1;           /**< SGI */
 308     unsigned noise_floor:8;   /**< noise floor */
 309     unsigned ampdu_cnt:8;     /**< ampdu cnt */
 310     unsigned channel:4;       /**< which channel this packet in */
 311     unsigned :12;             /**< reserve */
 312     unsigned timestamp:32;    /**< timestamp */
 313     unsigned :32;             /**< reserve */
 314     unsigned :32;             /**< reserve */
 315     unsigned sig_len:12;      /**< length of packet */
 316     unsigned :12;             /**< reserve */
 317     unsigned rx_state:8;      /**< rx state */
 318 } wifi_pkt_rx_ctrl_t;
 319
 320 /** @brief Payload passed to 'buf' parameter of promiscuous mode RX callback.
 321  */
 322 typedef struct {
 323     wifi_pkt_rx_ctrl_t rx_ctrl; /**< metadata header */
 324     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. */
 325 } wifi_promiscuous_pkt_t;
 326
 327 /**
 328   * @brief Promiscuous frame type
 329   *
 330   * Passed to promiscuous mode RX callback to indicate the type of parameter in the buffer.
 331   *
 332   */
 333 typedef enum {
 334     WIFI_PKT_MGMT,  /**< Management frame, indicates 'buf' argument is wifi_promiscuous_pkt_t */
 335     WIFI_PKT_DATA,  /**< Data frame, indiciates 'buf' argument is wifi_promiscuous_pkt_t */
 336     WIFI_PKT_MISC,  /**< Other type, such as MIMO etc. 'buf' argument is wifi_promiscuous_pkt_t but the payload is zero length. */
 337 } wifi_promiscuous_pkt_type_t;
 338
 339
 340 #define WIFI_PROMIS_FILTER_MASK_ALL         (0xFFFFFFFF)  /**< filter all packets */
 341 #define WIFI_PROMIS_FILTER_MASK_MGMT        (1)           /**< filter the packets with type of WIFI_PKT_MGMT */
 342 #define WIFI_PROMIS_FILTER_MASK_DATA        (1<<1)        /**< filter the packets with type of WIFI_PKT_DATA */
 343 #define WIFI_PROMIS_FILTER_MASK_MISC        (1<<2)        /**< filter the packets with type of WIFI_PKT_MISC */
 344 #define WIFI_PROMIS_FILTER_MASK_DATA_MPDU   (1<<3)        /**< filter the MPDU which is a kind of WIFI_PKT_DATA */
 345 #define WIFI_PROMIS_FILTER_MASK_DATA_AMPDU  (1<<4)        /**< filter the AMPDU which is a kind of WIFI_PKT_DATA */
 346
 347 /** @brief Mask for filtering different packet types in promiscuous mode. */
 348 typedef struct {
 349     uint32_t filter_mask; /**< OR of one or more filter values WIFI_PROMIS_FILTER_* */
 350 } wifi_promiscuous_filter_t;
 351
 352 #ifdef __cplusplus
 353 }
 354 #endif
 355
 356 #endif /* __ESP_WIFI_TYPES_H__ */