432 lines
15 KiB
C
432 lines
15 KiB
C
/*
|
|
* ESPRSSIF MIT License
|
|
*
|
|
* Copyright (c) 2015 <ESPRESSIF SYSTEMS (SHANGHAI) PTE LTD>
|
|
*
|
|
* Permission is hereby granted for use on ESPRESSIF SYSTEMS ESP8266 only, in which case,
|
|
* it is free of charge, to any person obtaining a copy of this software and associated
|
|
* documentation files (the "Software"), to deal in the Software without restriction, including
|
|
* without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
|
* and/or sell copies of the Software, and to permit persons to whom the Software is furnished
|
|
* to do so, subject to the following conditions:
|
|
*
|
|
* The above copyright notice and this permission notice shall be included in all copies or
|
|
* substantial portions of the Software.
|
|
*
|
|
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
|
* FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
|
* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
|
* IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
|
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
*
|
|
*/
|
|
|
|
#ifndef __ESP_STA_H__
|
|
#define __ESP_STA_H__
|
|
|
|
#include "queue.h"
|
|
#include "esp_wifi.h"
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/** \defgroup WiFi_APIs WiFi Related APIs
|
|
* @brief WiFi APIs
|
|
*/
|
|
|
|
/** @addtogroup WiFi_APIs
|
|
* @{
|
|
*/
|
|
|
|
/** \defgroup Station_APIs Station APIs
|
|
* @brief ESP8266 station APIs
|
|
* @attention To call APIs related to ESP8266 station has to enable station mode
|
|
* first (wifi_set_opmode)
|
|
*/
|
|
|
|
/** @addtogroup Station_APIs
|
|
* @{
|
|
*/
|
|
|
|
struct station_config {
|
|
uint8 ssid[32]; /**< SSID of target AP*/
|
|
uint8 password[64]; /**< password of target AP*/
|
|
uint8 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.*/
|
|
uint8 bssid[6]; /**< MAC address of target AP*/
|
|
};
|
|
|
|
/**
|
|
* @brief Get the current configuration of the ESP8266 WiFi station.
|
|
*
|
|
* @param struct station_config *config : ESP8266 station configuration
|
|
*
|
|
* @return true : succeed
|
|
* @return false : fail
|
|
*/
|
|
bool wifi_station_get_config(struct station_config *config);
|
|
|
|
/**
|
|
* @brief Get the configuration parameters saved in the Flash of the ESP8266 WiFi station.
|
|
*
|
|
* @param struct station_config *config : ESP8266 station configuration
|
|
*
|
|
* @return true : succeed
|
|
* @return false : fail
|
|
*/
|
|
bool wifi_station_get_config_default(struct station_config *config);
|
|
|
|
/**
|
|
* @brief Set the configuration of the ESP8266 station and save it to the Flash.
|
|
*
|
|
* @attention 1. This API can be called only when the ESP8266 station is enabled.
|
|
* @attention 2. If wifi_station_set_config is called in user_init , there is no
|
|
* need to call wifi_station_connect.
|
|
* The ESP8266 station will automatically connect to the AP (router)
|
|
* after the system initialization. Otherwise, wifi_station_connect should be called.
|
|
* @attention 3. 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.
|
|
* @attention 4. This configuration will be saved in the Flash system parameter area if changed.
|
|
*
|
|
* @param struct station_config *config : ESP8266 station configuration
|
|
*
|
|
* @return true : succeed
|
|
* @return false : fail
|
|
*/
|
|
bool wifi_station_set_config(struct station_config *config);
|
|
|
|
/**
|
|
* @brief Set the configuration of the ESP8266 station. And the configuration
|
|
* will not be saved to the Flash.
|
|
*
|
|
* @attention 1. This API can be called only when the ESP8266 station is enabled.
|
|
* @attention 2. If wifi_station_set_config_current is called in user_init , there
|
|
* is no need to call wifi_station_connect.
|
|
* The ESP8266 station will automatically connect to the AP (router)
|
|
* after the system initialization. Otherwise, wifi_station_connect
|
|
* should be called.
|
|
* @attention 3. 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.
|
|
*
|
|
* @param struct station_config *config : ESP8266 station configuration
|
|
*
|
|
* @return true : succeed
|
|
* @return false : fail
|
|
*/
|
|
bool wifi_station_set_config_current(struct station_config *config);
|
|
|
|
/**
|
|
* @brief Connect the ESP8266 WiFi station to the AP.
|
|
*
|
|
* @attention 1. This API should be called when the ESP8266 station is enabled,
|
|
* and the system initialization is completed. Do not call this API in user_init.
|
|
* @attention 2. If the ESP8266 is connected to an AP, call wifi_station_disconnect to disconnect.
|
|
*
|
|
* @param null
|
|
*
|
|
* @return true : succeed
|
|
* @return false : fail
|
|
*/
|
|
bool wifi_station_connect(void);
|
|
|
|
/**
|
|
* @brief Disconnect the ESP8266 WiFi station from the AP.
|
|
*
|
|
* @attention This API should be called when the ESP8266 station is enabled,
|
|
* and the system initialization is completed. Do not call this API in user_init.
|
|
*
|
|
* @param null
|
|
*
|
|
* @return true : succeed
|
|
* @return false : fail
|
|
*/
|
|
bool wifi_station_disconnect(void);
|
|
|
|
typedef enum {
|
|
WIFI_SCAN_TYPE_ACTIVE = 0, /**< active scan */
|
|
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, 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;
|
|
|
|
struct scan_config {
|
|
uint8 *ssid; /**< SSID of AP */
|
|
uint8 *bssid; /**< MAC address of AP */
|
|
uint8 channel; /**< channel, scan the specific channel */
|
|
uint8 show_hidden; /**< enable to scan AP whose SSID is hidden */
|
|
wifi_scan_type_t scan_type; /**< scan type, active or passive */
|
|
wifi_scan_time_t scan_time; /**< scan time per channel */
|
|
};
|
|
|
|
typedef enum {
|
|
CIPHER_NONE = 0, /**< the cipher type is none */
|
|
CIPHER_WEP40, /**< the cipher type is WEP40 */
|
|
CIPHER_WEP104, /**< the cipher type is WEP104 */
|
|
CIPHER_TKIP, /**< the cipher type is TKIP */
|
|
CIPHER_CCMP, /**< the cipher type is CCMP */
|
|
CIPHER_TKIP_CCMP, /**< the cipher type is TKIP and CCMP */
|
|
CIPHER_UNKNOWN, /**< the cipher type is unknown */
|
|
} CIPHER_TYPE;
|
|
|
|
struct bss_info {
|
|
STAILQ_ENTRY(bss_info) next; /**< information of next AP */
|
|
|
|
uint8 bssid[6]; /**< MAC address of AP */
|
|
uint8 ssid[32]; /**< SSID of AP */
|
|
uint8 ssid_len; /**< SSID length */
|
|
uint8 channel; /**< channel of AP */
|
|
sint8 rssi; /**< single strength of AP */
|
|
AUTH_MODE authmode; /**< authmode of AP */
|
|
uint8 is_hidden; /**< SSID of current AP is hidden or not. */
|
|
sint16 freq_offset; /**< frequency offset */
|
|
sint16 freqcal_val;
|
|
uint8 *esp_mesh_ie;
|
|
CIPHER_TYPE pairwise_cipher; /**< pairwise cipher of AP */
|
|
CIPHER_TYPE group_cipher; /**< group cipher of AP */
|
|
uint32_t phy_11b:1; /**< bit: 0 flag to identify if 11b mode is enabled or not */
|
|
uint32_t phy_11g:1; /**< bit: 1 flag to identify if 11g mode is enabled or not */
|
|
uint32_t phy_11n:1; /**< bit: 2 flag to identify if 11n mode is enabled or not */
|
|
uint32_t wps:1; /**< bit: 3 flag to identify if WPS is supported or not */
|
|
uint32_t reserved:28; /**< bit: 4..31 reserved */
|
|
};
|
|
|
|
/**
|
|
* @brief Callback function for wifi_station_scan.
|
|
*
|
|
* @param void *arg : information of APs that are found; save them as linked list;
|
|
* refer to struct bss_info
|
|
* @param STATUS status : status of scanning
|
|
*
|
|
* @return null
|
|
*/
|
|
typedef void (* scan_done_cb_t)(void *arg, STATUS status);
|
|
|
|
/**
|
|
* @brief Scan all available APs.
|
|
*
|
|
* @attention This API should be called when the ESP8266 station is enabled, and
|
|
* the system initialization is completed. Do not call this API in user_init.
|
|
*
|
|
* @param struct scan_config *config : configuration of scanning
|
|
* @param struct scan_done_cb_t cb : callback of scanning
|
|
*
|
|
* @return true : succeed
|
|
* @return false : fail
|
|
*/
|
|
bool wifi_station_scan(struct scan_config *config, scan_done_cb_t cb);
|
|
|
|
/**
|
|
* @brief Check if the ESP8266 station will connect to the recorded AP automatically
|
|
* when the power is on.
|
|
*
|
|
* @param null
|
|
*
|
|
* @return true : connect to the AP automatically
|
|
* @return false : not connect to the AP automatically
|
|
*/
|
|
bool wifi_station_get_auto_connect(void);
|
|
|
|
/**
|
|
* @brief Set whether the ESP8266 station will connect to the recorded AP
|
|
* automatically when the power is on. It will do so by default.
|
|
*
|
|
* @attention 1. If this API is called in user_init, it is effective immediately
|
|
* after the power is on. If it is called in other places, it will
|
|
* be effective the next time when the power is on.
|
|
* @attention 2. This configuration will be saved in Flash system parameter area if changed.
|
|
*
|
|
* @param bool set : If it will automatically connect to the AP when the power is on
|
|
* - true : it will connect automatically
|
|
* - false: it will not connect automatically
|
|
*
|
|
* @return true : succeed
|
|
* @return false : fail
|
|
*/
|
|
bool wifi_station_set_auto_connect(bool set);
|
|
|
|
/**
|
|
* @brief Check whether the ESP8266 station will reconnect to the AP after disconnection.
|
|
*
|
|
* @param null
|
|
*
|
|
* @return true : succeed
|
|
* @return false : fail
|
|
*/
|
|
bool wifi_station_get_reconnect_policy(void);
|
|
|
|
/**
|
|
* @brief Set whether the ESP8266 station will reconnect to the AP after disconnection.
|
|
* It will do so by default.
|
|
*
|
|
* @attention If users want to call this API, it is suggested that users call this API in user_init.
|
|
*
|
|
* @param bool set : if it's true, it will enable reconnection; if it's false,
|
|
* it will disable reconnection.
|
|
*
|
|
* @return true : succeed
|
|
* @return false : fail
|
|
*/
|
|
bool wifi_station_set_reconnect_policy(bool set);
|
|
|
|
typedef enum {
|
|
STATION_IDLE = 0, /**< ESP8266 station idle */
|
|
STATION_CONNECTING, /**< ESP8266 station is connecting to AP*/
|
|
STATION_WRONG_PASSWORD, /**< the password is wrong*/
|
|
STATION_NO_AP_FOUND, /**< ESP8266 station can not find the target AP*/
|
|
STATION_CONNECT_FAIL, /**< ESP8266 station fail to connect to AP*/
|
|
STATION_GOT_IP /**< ESP8266 station got IP address from AP*/
|
|
} STATION_STATUS;
|
|
|
|
/**
|
|
* @brief Get the connection status of the ESP8266 WiFi station.
|
|
*
|
|
* @param null
|
|
*
|
|
* @return the status of connection
|
|
*/
|
|
STATION_STATUS wifi_station_get_connect_status(void);
|
|
|
|
/**
|
|
* @brief Get the information of APs (5 at most) recorded by ESP8266 station.
|
|
*
|
|
* @param struct station_config config[] : information of the APs, the array size should be 5.
|
|
*
|
|
* @return The number of APs recorded.
|
|
*/
|
|
uint8 wifi_station_get_current_ap_id(void);
|
|
|
|
/**
|
|
* @brief Switch the ESP8266 station connection to a recorded AP.
|
|
*
|
|
* @param uint8 new_ap_id : AP's record id, start counting from 0.
|
|
*
|
|
* @return true : succeed
|
|
* @return false : fail
|
|
*/
|
|
bool wifi_station_ap_change(uint8 current_ap_id);
|
|
|
|
/**
|
|
* @brief Set the number of APs that can be recorded in the ESP8266 station.
|
|
* When the ESP8266 station is connected to an AP, the SSID and password
|
|
* of the AP will be recorded.
|
|
*
|
|
* @attention This configuration will be saved in the Flash system parameter area if changed.
|
|
*
|
|
* @param uint8 ap_number : the number of APs that can be recorded (MAX: 5)
|
|
*
|
|
* @return true : succeed
|
|
* @return false : fail
|
|
*/
|
|
bool wifi_station_ap_number_set(uint8 ap_number);
|
|
|
|
/**
|
|
* @brief Get the information of APs (5 at most) recorded by ESP8266 station.
|
|
*
|
|
* Example:
|
|
* <pre>
|
|
* struct station_config config[5];
|
|
* nt i = wifi_station_get_ap_info(config);
|
|
* </pre>
|
|
*
|
|
* @param struct station_config config[] : information of the APs, the array size should be 5.
|
|
*
|
|
* @return The number of APs recorded.
|
|
*/
|
|
uint8 wifi_station_get_ap_info(struct station_config config[]);
|
|
|
|
/**
|
|
* @brief Get rssi of the AP which ESP8266 station connected to.
|
|
*
|
|
* @param null
|
|
*
|
|
* @return 31 : fail, invalid value.
|
|
* @return others : succeed, value of rssi. In general, rssi value < 10
|
|
*/
|
|
sint8 wifi_station_get_rssi(void);
|
|
|
|
/**
|
|
* @brief Enable the ESP8266 station DHCP client.
|
|
*
|
|
* @attention 1. The DHCP is enabled by default.
|
|
* @attention 2. The DHCP and the static IP API ((wifi_set_ip_info)) influence each other,
|
|
* and if the DHCP is enabled, the static IP will be disabled;
|
|
* if the static IP is enabled, the DHCP will be disabled.
|
|
* It depends on the latest configuration.
|
|
*
|
|
* @param null
|
|
*
|
|
* @return true : succeed
|
|
* @return false : fail
|
|
*/
|
|
bool wifi_station_dhcpc_start(void);
|
|
|
|
/**
|
|
* @brief Disable the ESP8266 station DHCP client.
|
|
*
|
|
* @attention 1. The DHCP is enabled by default.
|
|
* @attention 2. The DHCP and the static IP API ((wifi_set_ip_info)) influence each other,
|
|
* and if the DHCP is enabled, the static IP will be disabled;
|
|
* if the static IP is enabled, the DHCP will be disabled.
|
|
* It depends on the latest configuration.
|
|
*
|
|
* @param null
|
|
*
|
|
* @return true : succeed
|
|
* @return false : fail
|
|
*/
|
|
bool wifi_station_dhcpc_stop(void);
|
|
|
|
/**
|
|
* @brief Get the ESP8266 station DHCP client status.
|
|
*
|
|
* @param null
|
|
*
|
|
* @return enum dhcp_status
|
|
*/
|
|
enum dhcp_status wifi_station_dhcpc_status(void);
|
|
|
|
/**
|
|
* @brief Set ESP8266 station DHCP hostname.
|
|
*
|
|
* @param char *name : hostname of ESP8266 station
|
|
*
|
|
* @return true : succeed
|
|
* @return false : fail
|
|
*/
|
|
bool wifi_station_set_hostname(char *name);
|
|
|
|
/**
|
|
* @brief Get ESP8266 station DHCP hostname.
|
|
*
|
|
* @param null
|
|
*
|
|
* @return the hostname of ESP8266 station
|
|
*/
|
|
char* wifi_station_get_hostname(void);
|
|
|
|
/**
|
|
* @}
|
|
*/
|
|
|
|
/**
|
|
* @}
|
|
*/
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|