espterm
/
espterm-firmware
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
ESPTerm - ESP8266 terminal emulator. Branches: [master] patches, [work] next release
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
316 Commits
4 Branches
45 Tags
3.9 MiB
 
 
 
 
 
 
Tag: Branch: Tree: e3ae34a932
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'e3ae34a932'
${ noResults }
espterm-firmware/esp_iot_sdk_v1.5.2/include/user_interface.h

2029 lines
63 KiB
Raw Blame History

/*
* Copyright (C) 2013 -2014 Espressif System
*
*/
#ifndef __USER_INTERFACE_H__
#define __USER_INTERFACE_H__
#include "os_type.h"
#ifdef LWIP_OPEN_SRC
#include "lwip/ip_addr.h"
#else
#include "ip_addr.h"
#endif
#include "queue.h"
#include "user_config.h"
#include "spi_flash.h"
#ifndef MAC2STR
#define MAC2STR(a) (a)[0], (a)[1], (a)[2], (a)[3], (a)[4], (a)[5]
#define MACSTR "%02x:%02x:%02x:%02x:%02x:%02x"
#endif
enum rst_reason {
REASON_DEFAULT_RST = 0, /**< normal startup by power on */
REASON_WDT_RST, /**< hardware watch dog reset */
REASON_EXCEPTION_RST, /**< exception reset, GPIO status won't change */
REASON_SOFT_WDT_RST, /**< software watch dog reset, GPIO status won't change */
REASON_SOFT_RESTART, /**< software restart ,system_restart , GPIO status won't change */
REASON_DEEP_SLEEP_AWAKE, /**< wake up from deep-sleep */
REASON_EXT_SYS_RST /**< external system reset */
};
struct rst_info{
uint32 reason; /**< enum rst_reason */
uint32 exccause;
uint32 epc1;
uint32 epc2;
uint32 epc3;
uint32 excvaddr;
uint32 depc;
};
/**
* @brief Get the reason of restart.
*
* @param null
*
* @return struct rst_info* : information of the system restart
*/
struct rst_info* system_get_rst_info(void);
#define UPGRADE_FW_BIN1 0x00
#define UPGRADE_FW_BIN2 0x01
/**
* @brief Reset to default settings.
*
* Reset to default settings of the following APIs : wifi_station_set_auto_connect,
* wifi_set_phy_mode, wifi_softap_set_config related, wifi_station_set_config
* related, and wifi_set_opmode.
*
* @param null
*
* @return null
*/
void system_restore(void);
/**
* @brief Restart system.
*
* @param null
*
* @return null
*/
void system_restart(void);
/**
* @brief Call this API before system_deep_sleep to set the activity after the
* next deep-sleep wakeup.
*
* If this API is not called, default to be system_deep_sleep_set_option(1).
*
* @param uint8 option :
* @param 0 : Radio calibration after the deep-sleep wakeup is decided by byte
* 108 of esp_init_data_default.bin (0~127byte).
* @param 1 : Radio calibration will be done after the deep-sleep wakeup. This
* will lead to stronger current.
* @param 2 : Radio calibration will not be done after the deep-sleep wakeup.
* This will lead to weaker current.
* @param 4 : Disable radio calibration after the deep-sleep wakeup (the same
* as modem-sleep). This will lead to the weakest current, but the device
* can't receive or transmit data after waking up.
*
* @return true : succeed
* @return false : fail
*/
bool system_deep_sleep_set_option(uint8 option);
/**
* @brief Set the chip to deep-sleep mode.
*
* The device will automatically wake up after the deep-sleep time set
* by the users. Upon waking up, the device boots up from user_init.
*
* @attention 1. XPD_DCDC should be connected to EXT_RSTB through 0 ohm resistor
* in order to support deep-sleep wakeup.
* @attention 2. system_deep_sleep(0): there is no wake up timer; in order to wake
* up, connect a GPIO to pin RST, the chip will wake up by a falling-edge
* on pin RST
*
* @param uint32 time_in_us : deep-sleep time, unit: microsecond
*
* @return null
*/
void system_deep_sleep(uint32 time_in_us);
uint8 system_upgrade_userbin_check(void);
void system_upgrade_reboot(void);
uint8 system_upgrade_flag_check();
void system_upgrade_flag_set(uint8 flag);
void system_timer_reinit(void);
/**
* @brief Get system time, unit: microsecond.
*
* @param null
*
* @return System time, unit: microsecond.
*/
uint32 system_get_time(void);
/* user task's prio must be 0/1/2 !!!*/
enum {
USER_TASK_PRIO_0 = 0,
USER_TASK_PRIO_1,
USER_TASK_PRIO_2,
USER_TASK_PRIO_MAX
};
bool system_os_task(os_task_t task, uint8 prio, os_event_t *queue, uint8 qlen);
bool system_os_post(uint8 prio, os_signal_t sig, os_param_t par);
/**
* @brief Print the system memory distribution, including data/rodata/bss/heap.
*
* @param null
*
* @return null
*/
void system_print_meminfo(void);
/**
* @brief Get the size of available heap.
*
* @param null
*
* @return Available heap size.
*/
uint32 system_get_free_heap_size(void);
void system_set_os_print(uint8 onoff);
uint8 system_get_os_print();
uint64 system_mktime(uint32 year, uint32 mon, uint32 day, uint32 hour, uint32 min, uint32 sec);
uint32 system_get_chip_id(void);
typedef void (* init_done_cb_t)(void);
void system_init_done_cb(init_done_cb_t cb);
/**
* @brief Get the RTC clock cycle.
*
* @attention 1. The RTC clock cycle has decimal part.
* @attention 2. The RTC clock cycle will change according to the temperature,
* so RTC timer is not very precise.
*
* @param null
*
* @return RTC clock period (unit: microsecond), bit11~ bit0 are decimal.
*/
uint32 system_rtc_clock_cali_proc(void);
/**
* @brief Get RTC time, unit: RTC clock cycle.
*
* Example:
* If system_get_rtc_time returns 10 (it means 10 RTC cycles), and
* system_rtc_clock_cali_proc returns 5.75 (it means 5.75 microseconds per RTC clock cycle),
* (then the actual time is 10 x 5.75 = 57.5 microseconds.
*
* @attention System time will return to zero because of system_restart, but the
* RTC time still goes on. If the chip is reset by pin EXT_RST or pin
* CHIP_EN (including the deep-sleep wakeup), situations are shown as below:
* @attention 1. reset by pin EXT_RST : RTC memory won't change, RTC timer returns to zero
* @attention 2. watchdog reset : RTC memory won't change, RTC timer won't change
* @attention 3. system_restart : RTC memory won't change, RTC timer won't change
* @attention 4. power on : RTC memory is random value, RTC timer starts from zero
* @attention 5. reset by pin CHIP_EN : RTC memory is random value, RTC timer starts from zero
*
* @param null
*
* @return RTC time.
*/
uint32 system_get_rtc_time(void);
/**
* @brief Read user data from the RTC memory.
*
* The user data segment (512 bytes, as shown below) is used to store user data.
*
* |<---- system data(256 bytes) ---->|<----------- user data(512 bytes) --------->|
*
* @attention Read and write unit for data stored in the RTC memory is 4 bytes.
* @attention src_addr is the block number (4 bytes per block). So when reading data
* at the beginning of the user data segment, src_addr will be 256/4 = 64,
* n will be data length.
*
* @param uint8 src : source address of rtc memory, src_addr >= 64
* @param void *dst : data pointer
* @param uint16 n : data length, unit: byte
*
* @return true : succeed
* @return false : fail
*/
bool system_rtc_mem_read(uint8 src_addr, void *des_addr, uint16 load_size);
/**
* @brief Write user data to the RTC memory.
*
* During deep-sleep, only RTC is working. So users can store their data
* in RTC memory if it is needed. The user data segment below (512 bytes)
* is used to store the user data.
*
* |<---- system data(256 bytes) ---->|<----------- user data(512 bytes) --------->|
*
* @attention Read and write unit for data stored in the RTC memory is 4 bytes.
* @attention src_addr is the block number (4 bytes per block). So when storing data
* at the beginning of the user data segment, src_addr will be 256/4 = 64,
* n will be data length.
*
* @param uint8 src : source address of rtc memory, src_addr >= 64
* @param void *dst : data pointer
* @param uint16 n : data length, unit: byte
*
* @return true : succeed
* @return false : fail
*/
bool system_rtc_mem_write(uint8 des_addr, const void *src_addr, uint16 save_size);
/**
* @brief UART0 swap.
*
* Use MTCK as UART0 RX, MTDO as UART0 TX, so ROM log will not output from
* this new UART0. We also need to use MTDO (U0CTS) and MTCK (U0RTS) as UART0 in hardware.
*
* @param null
*
* @return null
*/
void system_uart_swap(void);
/**
* @brief Disable UART0 swap.
*
* Use the original UART0, not MTCK and MTDO.
*
* @param null
*
* @return null
*/
void system_uart_de_swap(void);
/**
* @brief Measure the input voltage of TOUT pin 6, unit : 1/1024 V.
*
* @attention 1. system_adc_read can only be called when the TOUT pin is connected
* to the external circuitry, and the TOUT pin input voltage should
* be limited to 0~1.0V.
* @attention 2. When the TOUT pin is connected to the external circuitry, the 107th
* byte (vdd33_const) of esp_init_data_default.bin(0~127byte) should be
* set as the real power voltage of VDD3P3 pin 3 and 4.
* @attention 3. The unit of vdd33_const is 0.1V, the effective value range is [18, 36];
* if vdd33_const is in [0, 18) or (36, 255), 3.3V is used to optimize RF by default.
*
* @param null
*
* @return Input voltage of TOUT pin 6, unit : 1/1024 V
*/
uint16 system_adc_read(void);
/**
* @brief Measure the power voltage of VDD3P3 pin 3 and 4, unit : 1/1024 V.
*
* @attention 1. system_get_vdd33 can only be called when TOUT pin is suspended.
* @attention 2. The 107th byte in esp_init_data_default.bin (0~127byte) is named
* as "vdd33_const", when TOUT pin is suspended vdd33_const must be
* set as 0xFF, that is 255.
*
* @param null
*
* @return Power voltage of VDD33, unit : 1/1024 V
*/
uint16 system_get_vdd33(void);
/**
* @brief Get information of the SDK version.
*
* @param null
*
* @return Information of the SDK version.
*/
const char *system_get_sdk_version(void);
#define SYS_BOOT_ENHANCE_MODE 0
#define SYS_BOOT_NORMAL_MODE 1
#define SYS_BOOT_NORMAL_BIN 0
#define SYS_BOOT_TEST_BIN 1
/**
* @brief Get information of the boot version.
*
* @attention If boot version >= 1.3 , users can enable the enhanced boot mode
* (refer to system_restart_enhance).
*
* @param null
*
* @return Information of the boot version.
*/
uint8 system_get_boot_version(void);
/**
* @brief Get the address of the current running user bin (user1.bin or user2.bin).
*
* @param null
*
* @return The address of the current running user bin.
*/
uint32 system_get_userbin_addr(void);
/**
* @brief Get the boot mode.
*
* @param null
*
* @return #define SYS_BOOT_ENHANCE_MODE 0
* @return #define SYS_BOOT_NORMAL_MODE 1
*/
uint8 system_get_boot_mode(void);
/**
* @brief Restarts the system, and enters the enhanced boot mode.
*
* @attention SYS_BOOT_TEST_BIN is used for factory test during production; users
* can apply for the test bin from Espressif Systems.
*
* @param uint8 bin_type : type of bin
* - #define SYS_BOOT_NORMAL_BIN 0 // user1.bin or user2.bin
* - #define SYS_BOOT_TEST_BIN 1 // can only be Espressif test bin
* @param uint32 bin_addr : starting address of the bin file
*
* @return true : succeed
* @return false : fail
*/
bool system_restart_enhance(uint8 bin_type, uint32 bin_addr);
#define SYS_CPU_80MHZ 80
#define SYS_CPU_160MHZ 160
/**
* @brief Set CPU frequency. Default is 80MHz.
*
* System bus frequency is 80MHz, will not be affected by CPU frequency.
* The frequency of UART, SPI, or other peripheral devices, are divided
* from system bus frequency, so they will not be affected by CPU frequency either.
*
* @param uint8 freq : CPU frequency, 80 or 160.
*
* @return true : succeed
* @return false : fail
*/
bool system_update_cpu_freq(uint8 freq);
/**
* @brief Get CPU frequency.
*
* @param null
*
* @return CPU frequency, unit : MHz.
*/
uint8 system_get_cpu_freq(void);
typedef enum {
FLASH_SIZE_4M_MAP_256_256 = 0, /**< Flash size : 4Mbits. Map : 256KBytes + 256KBytes */
FLASH_SIZE_2M, /**< Flash size : 2Mbits. Map : 256KBytes */
FLASH_SIZE_8M_MAP_512_512, /**< Flash size : 8Mbits. Map : 512KBytes + 512KBytes */
FLASH_SIZE_16M_MAP_512_512, /**< Flash size : 16Mbits. Map : 512KBytes + 512KBytes */
FLASH_SIZE_32M_MAP_512_512, /**< Flash size : 32Mbits. Map : 512KBytes + 512KBytes */
FLASH_SIZE_16M_MAP_1024_1024, /**< Flash size : 16Mbits. Map : 1024KBytes + 1024KBytes */
FLASH_SIZE_32M_MAP_1024_1024 /**< Flash size : 32Mbits. Map : 1024KBytes + 1024KBytes */
} flash_size_map;
/**
* @brief Get the current Flash size and Flash map.
*
* Flash map depends on the selection when compiling, more details in document
* "2A-ESP8266__IOT_SDK_User_Manual"
*
* @param null
*
* @return enum flash_size_map
*/
flash_size_map system_get_flash_size_map(void);
/**
* @brief Set the maximum value of RF TX Power, unit : 0.25dBm.
*
* @param uint8 max_tpw : the maximum value of RF Tx Power, unit : 0.25dBm, range [0, 82].
* It can be set refer to the 34th byte (target_power_qdb_0)
* of esp_init_data_default.bin(0~127byte)
*
* @return null
*/
void system_phy_set_max_tpw(uint8 max_tpw);
/**
* @brief Adjust the RF TX Power according to VDD33, unit : 1/1024 V.
*
* @attention 1. When TOUT pin is suspended, VDD33 can be measured by system_get_vdd33.
* @attention 2. When TOUT pin is connected to the external circuitry, system_get_vdd33
* can not be used to measure VDD33.
*
* @param uint16 vdd33 : VDD33, unit : 1/1024V, range [1900, 3300]
*
* @return null
*/
void system_phy_set_tpw_via_vdd33(uint16 vdd33);
/**
* @brief Enable RF or not when wakeup from deep-sleep.
*
* @attention 1. This API can only be called in user_rf_pre_init.
* @attention 2. Function of this API is similar to system_deep_sleep_set_option,
* if they are both called, it will disregard system_deep_sleep_set_option
* which is called before deep-sleep, and refer to system_phy_set_rfoption
* which is called when deep-sleep wake up.
* @attention 3. Before calling this API, system_deep_sleep_set_option should be called
* once at least.
*
* @param uint8 option :
* - 0 : Radio calibration after deep-sleep wake up depends on esp_init_data_default.bin (0~127byte) byte 108.
* - 1 : Radio calibration is done after deep-sleep wake up; this increases the
* current consumption.
* - 2 : No radio calibration after deep-sleep wake up; this reduces the current consumption.
* - 4 : Disable RF after deep-sleep wake up, just like modem sleep; this has the
* least current consumption; the device is not able to transmit or receive
* data after wake up.
*
* @return null
*/
void system_phy_set_rfoption(uint8 option);
void system_phy_set_powerup_option(uint8 option);
/**
* @brief Write data into flash with protection.
*
* Flash read/write has to be 4-bytes aligned.
*
* Protection of flash read/write :
* use 3 sectors (4KBytes per sector) to save 4KB data with protect,
* sector 0 and sector 1 are data sectors, back up each other,
* save data alternately, sector 2 is flag sector, point out which sector
* is keeping the latest data, sector 0 or sector 1.
*
* @param uint16 start_sec : start sector (sector 0) of the 3 sectors which are
* used for flash read/write protection.
* - For example, in IOT_Demo we can use the 3 sectors (3 * 4KB) starting from flash
* 0x3D000 for flash read/write protection, so the parameter start_sec should be 0x3D
* @param void *param : pointer of the data to be written
* @param uint16 len : data length, should be less than a sector, which is 4 * 1024
*
* @return true : succeed
* @return false : fail
*/
bool system_param_save_with_protect(uint16 start_sec, void *param, uint16 len);
/**
* @brief Read the data saved into flash with the read/write protection.
*
* Flash read/write has to be 4-bytes aligned.
*
* Read/write protection of flash:
* use 3 sectors (4KB per sector) to save 4KB data with protect, sector
* 0 and sector 1 are data sectors, back up each other, save data alternately,
* sector 2 is flag sector, point out which sector is keeping the latest data,
* sector 0 or sector 1.
*
* @param uint16 start_sec : start sector (sector 0) of the 3 sectors used for
* flash read/write protection. It cannot be sector 1 or sector 2.
* - For example, in IOT_Demo, the 3 sectors (3 * 4KB) starting from flash 0x3D000
* can be used for flash read/write protection.
* The parameter start_sec is 0x3D, and it cannot be 0x3E or 0x3F.
* @param uint16 offset : offset of data saved in sector
* @param void *param : data pointer
* @param uint16 len : data length, offset + len =< 4 * 1024
*
* @return true : succeed
* @return false : fail
*/
bool system_param_load(uint16 start_sec, uint16 offset, void *param, uint16 len);
void system_soft_wdt_stop(void);
void system_soft_wdt_restart(void);
void system_soft_wdt_feed(void);
void system_show_malloc(void);
typedef enum {
NULL_MODE = 0, /**< null mode */
STATION_MODE = 1, /**< WiFi station mode */
SOFTAP_MODE = 2, /**< WiFi soft-AP mode */
STATIONAP_MODE = 3, /**< WiFi station + soft-AP mode */
MAX_MODE
} WIFI_MODE;
typedef enum {
AUTH_OPEN = 0, /**< authenticate mode : open */
AUTH_WEP = 1, /**< authenticate mode : WEP */
AUTH_WPA_PSK = 2, /**< authenticate mode : WPA_PSK */
AUTH_WPA2_PSK = 3, /**< authenticate mode : WPA2_PSK */
AUTH_WPA_WPA2_PSK = 4, /**< authenticate mode : WPA_WPA2_PSK */
AUTH_MAX
} AUTH_MODE;
/**
* @brief Get the current operating mode of the WiFi.
*
* @param null
*
* @return WiFi operating modes:
* - 0x01: station mode;
* - 0x02: soft-AP mode
* - 0x03: station+soft-AP mode
*/
WIFI_MODE wifi_get_opmode(void);
/**
* @brief Get the operating mode of the WiFi saved in the Flash.
*
* @param null
*
* @return WiFi operating modes:
* - 0x01: station mode;
* - 0x02: soft-AP mode
* - 0x03: station+soft-AP mode
*/
WIFI_MODE wifi_get_opmode_default(void);
/**
* @brief Set the WiFi operating mode, and save it to Flash.
*
* Set the WiFi operating mode as station, soft-AP or station+soft-AP,
* and save it to Flash. The default mode is soft-AP mode.
*
* @attention This configuration will be saved in the Flash system parameter area if changed.
*
* @param uint8 opmode : WiFi operating modes:
* - 0x01: station mode;
* - 0x02: soft-AP mode
* - 0x03: station+soft-AP mode
*
* @return true : succeed
* @return false : fail
*/
bool wifi_set_opmode(WIFI_MODE opmode);
/**
* @brief Set the WiFi operating mode, and will not save it to Flash.
*
* Set the WiFi operating mode as station, soft-AP or station+soft-AP, and
* the mode won't be saved to the Flash.
*
* @param uint8 opmode : WiFi operating modes:
* - 0x01: station mode;
* - 0x02: soft-AP mode
* - 0x03: station+soft-AP mode
*
* @return true : succeed
* @return false : fail
*/
bool wifi_set_opmode_current(WIFI_MODE opmode);
uint8 wifi_get_broadcast_if(void);
bool wifi_set_broadcast_if(uint8 interface);
struct bss_info {
STAILQ_ENTRY(bss_info) next;
uint8 bssid[6];
uint8 ssid[32];
uint8 ssid_len;
uint8 channel;
sint8 rssi;
AUTH_MODE authmode;
uint8 is_hidden;
sint16 freq_offset;
sint16 freqcal_val;
uint8 *esp_mesh_ie;
};
typedef struct _scaninfo {
STAILQ_HEAD(, bss_info) *pbss;
struct espconn *pespconn;
uint8 totalpage;
uint8 pagenum;
uint8 page_sn;
uint8 data_cnt;
} scaninfo;
/**
* @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);
struct station_config {
uint8 ssid[32];
uint8 password[64];
uint8 bssid_set; // Note: If bssid_set is 1, station will just connect to the router
// with both ssid[] and bssid[] matched. Please check about this.
uint8 bssid[6];
};
/**
* @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);
/**
* @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);
struct scan_config {
uint8 *ssid; // Note: ssid == NULL, don't filter ssid.
uint8 *bssid; // Note: bssid == NULL, don't filter bssid.
uint8 channel; // Note: channel == 0, scan all channels, otherwise scan set channel.
uint8 show_hidden; // Note: show_hidden == 1, can get hidden ssid routers' info.
};
/**
* @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);
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;
enum dhcp_status {
DHCP_STOPPED,
DHCP_STARTED
};
/**
* @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 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);
bool wifi_station_dhcpc_set_maxtry(uint8 num);
char* wifi_station_get_hostname(void);
bool wifi_station_set_hostname(char *name);
int wifi_station_set_cert_key(uint8 *client_cert, int client_cert_len,
uint8 *private_key, int private_key_len,
uint8 *private_key_passwd, int private_key_passwd_len);
void wifi_station_clear_cert_key(void);
/** \defgroup SoftAP_APIs SoftAP APIs
* @brief ESP8266 Soft-AP APIs
* @attention To call APIs related to ESP8266 soft-AP has to enable soft-AP mode first (wifi_set_opmode)
*/
struct softap_config {
uint8 ssid[32]; /**< SSID of ESP8266 soft-AP */
uint8 password[64]; /**< Password of ESP8266 soft-AP */
uint8 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. */
uint8 channel; /**< Channel of ESP8266 soft-AP */
AUTH_MODE authmode; /**< Auth mode of ESP8266 soft-AP. Do not support AUTH_WEP in soft-AP mode */
uint8 ssid_hidden; /**< Broadcast SSID or not, default 0, broadcast the SSID */
uint8 max_connection; /**< Max number of stations allowed to connect in, default 4, max 4 */
uint16 beacon_interval; /**< Beacon interval, 100 ~ 60000 ms, default 100 */
};
/**
* @brief Get the current configuration of the ESP8266 WiFi soft-AP
*
* @param struct softap_config *config : ESP8266 soft-AP configuration
*
* @return true : succeed
* @return false : fail
*/
bool wifi_softap_get_config(struct softap_config *config);
/**
* @brief Get the configuration of the ESP8266 WiFi soft-AP saved in the flash
*
* @param struct softap_config *config : ESP8266 soft-AP configuration
*
* @return true : succeed
* @return false : fail
*/
bool wifi_softap_get_config_default(struct softap_config *config);
/**
* @brief Set the configuration of the WiFi soft-AP and save it to the Flash.
*
* @attention 1. This configuration will be saved in flash system parameter area if changed
* @attention 2. The ESP8266 is limited to only one channel, so when in the soft-AP+station mode,
* the soft-AP will adjust its channel automatically to be the same as
* the channel of the ESP8266 station.
*
* @param struct softap_config *config : ESP8266 soft-AP configuration
*
* @return true : succeed
* @return false : fail
*/
bool wifi_softap_set_config(struct softap_config *config);
/**
* @brief Set the configuration of the WiFi soft-AP; the configuration will
* not be saved to the Flash.
*
* @attention The ESP8266 is limited to only one channel, so when in the soft-AP+station mode,
* the soft-AP will adjust its channel automatically to be the same as
* the channel of the ESP8266 station.
*
* @param struct softap_config *config : ESP8266 soft-AP configuration
*
* @return true : succeed
* @return false : fail
*/
bool wifi_softap_set_config_current(struct softap_config *config);
struct station_info {
STAILQ_ENTRY(station_info) next;
uint8 bssid[6];
struct ip_addr ip;
};
struct dhcps_lease {
bool enable;
struct ip_addr start_ip;
struct ip_addr end_ip;
};
enum dhcps_offer_option{
OFFER_START = 0x00,
OFFER_ROUTER = 0x01,
OFFER_END
};
/**
* @brief Get the number of stations connected to the ESP8266 soft-AP.
*
* @attention The ESP8266 is limited to only one channel, so when in the soft-AP+station mode,
* the soft-AP will adjust its channel automatically to be the same as
* the channel of the ESP8266 station.
*
* @param null
*
* @return the number of stations connected to the ESP8266 soft-AP
*/
uint8 wifi_softap_get_station_num(void);
/**
* @brief Get the information of stations connected to the ESP8266 soft-AP,
* including MAC and IP.
*
* @attention wifi_softap_get_station_info can not get the static IP, it can only
* be used when DHCP is enabled.
*
* @param null
*
* @return struct station_info* : station information structure
*/
struct station_info *wifi_softap_get_station_info(void);
/**
* @brief Free the space occupied by station_info when wifi_softap_get_station_info is called.
*
* @attention The ESP8266 is limited to only one channel, so when in the soft-AP+station mode,
* the soft-AP will adjust its channel automatically to be the same as
* the channel of the ESP8266 station.
*
* @param null
*
* @return null
*/
void wifi_softap_free_station_info(void);
/**
* @brief Enable the ESP8266 soft-AP DHCP server.
*
* @attention 1. The DHCP is enabled by default.
* @attention 2. The DHCP and the static IP related API (wifi_set_ip_info) influence
* each other, 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_softap_dhcps_start(void);
/**
* @brief Disable the ESP8266 soft-AP DHCP server. The DHCP is enabled by default.
*
* @param null
*
* @return true : succeed
* @return false : fail
*/
bool wifi_softap_dhcps_stop(void);
/**
* @brief Get the ESP8266 soft-AP DHCP server status.
*
* @param null
*
* @return enum dhcp_status
*/
enum dhcp_status wifi_softap_dhcps_status(void);
/**
* @brief Query the IP range that can be got from the ESP8266 soft-AP DHCP server.
*
* @attention This API can only be called during ESP8266 soft-AP DHCP server enabled.
*
* @param struct dhcps_lease *please : IP range of the ESP8266 soft-AP DHCP server.
*
* @return true : succeed
* @return false : fail
*/
bool wifi_softap_get_dhcps_lease(struct dhcps_lease *please);
/**
* @brief Set the IP range of the ESP8266 soft-AP DHCP server.
*
* @attention 1. The IP range should be in the same sub-net with the ESP8266
* soft-AP IP address.
* @attention 2. This API should only be called when the DHCP server is disabled
* (wifi_softap_dhcps_stop).
* @attention 3. This configuration will only take effect the next time when the
* DHCP server is enabled (wifi_softap_dhcps_start).
* - If the DHCP server is disabled again, this API should be called to set the IP range.
* - Otherwise, when the DHCP server is enabled later, the default IP range will be used.
*
* @param struct dhcps_lease *please : IP range of the ESP8266 soft-AP DHCP server.
*
* @return true : succeed
* @return false : fail
*/
bool wifi_softap_set_dhcps_lease(struct dhcps_lease *please);
/**
* @brief Get ESP8266 soft-AP DHCP server lease time.
*
* @attention This API can only be called during ESP8266 soft-AP DHCP server enabled.
*
* @param null
*
* @return lease time, uint: minute.
*/
uint32 wifi_softap_get_dhcps_lease_time(void);
/**
* @brief Set ESP8266 soft-AP DHCP server lease time, default is 120 minutes.
*
* @attention This API can only be called during ESP8266 soft-AP DHCP server enabled.
*
* @param uint32 minute : lease time, uint: minute, range:[1, 2880].
*
* @return true : succeed
* @return false : fail
*/
bool wifi_softap_set_dhcps_lease_time(uint32 minute);
/**
* @brief Reset ESP8266 soft-AP DHCP server lease time which is 120 minutes by default.
*
* @attention This API can only be called during ESP8266 soft-AP DHCP server enabled.
*
* @param null
*
* @return true : succeed
* @return false : fail
*/
bool wifi_softap_reset_dhcps_lease_time(void);
/**
* @brief Set the ESP8266 soft-AP DHCP server option.
*
* Example:
* <pre>
* uint8 mode = 0;
* wifi_softap_set_dhcps_offer_option(OFFER_ROUTER, &mode);
* </pre>
*
* @param uint8 level : OFFER_ROUTER, set the router option.
* @param void* optarg :
* - bit0, 0 disable the router information;
* - bit0, 1 enable the router information.
*
* @return true : succeed
* @return false : fail
*/
bool wifi_softap_set_dhcps_offer_option(uint8 level, void *optarg);
typedef enum {
STATION_IF = 0, /**< ESP8266 station interface */
SOFTAP_IF, /**< ESP8266 soft-AP interface */
MAX_IF
} WIFI_INTERFACE;
/**
* @brief Get the IP address of the ESP8266 WiFi station or the soft-AP interface.
*
* @attention Users need to enable the target interface (station or soft-AP) by wifi_set_opmode first.
*
* @param WIFI_INTERFACE if_index : get the IP address of the station or the soft-AP interface,
* 0x00 for STATION_IF, 0x01 for SOFTAP_IF.
* @param struct ip_info *info : the IP information obtained.
*
* @return true : succeed
* @return false : fail
*/
bool wifi_get_ip_info(WIFI_INTERFACE if_index, struct ip_info *info);
/**
* @brief Set the IP address of the ESP8266 WiFi station or the soft-AP interface.
*
* @attention 1. Users need to enable the target interface (station or soft-AP) by
* wifi_set_opmode first.
* @attention 2. To set static IP, users need to disable DHCP first (wifi_station_dhcpc_stop
* or wifi_softap_dhcps_stop):
* - 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 WIFI_INTERFACE if_index : get the IP address of the station or the soft-AP interface,
* 0x00 for STATION_IF, 0x01 for SOFTAP_IF.
* @param struct ip_info *info : the IP information obtained.
*
* @return true : succeed
* @return false : fail
*/
bool wifi_set_ip_info(WIFI_INTERFACE if_index, struct ip_info *info);
/**
* @brief Get MAC address of the ESP8266 WiFi station or the soft-AP interface.
*
* @param WIFI_INTERFACE if_index : get the IP address of the station or the soft-AP interface,
* 0x00 for STATION_IF, 0x01 for SOFTAP_IF.
* @param uint8 *macaddr : the MAC address.
*
* @return true : succeed
* @return false : fail
*/
bool wifi_get_macaddr(WIFI_INTERFACE if_index, uint8 *macaddr);
/**
* @brief Set MAC address of the ESP8266 WiFi station or the soft-AP interface.
*
* @attention 1. This API can only be called in user_init.
* @attention 2. Users need to enable the target interface (station or soft-AP) by wifi_set_opmode first.
* @attention 3. ESP8266 soft-AP and station have different MAC addresses, do not set them to be the same.
* - The bit0 of the first byte of ESP8266 MAC address can not be 1. For example, the MAC address
* can set to be "1a:XX:XX:XX:XX:XX", but can not be "15:XX:XX:XX:XX:XX".
*
* @param WIFI_INTERFACE if_index : get the IP address of the station or the soft-AP interface,
* 0x00 for STATION_IF, 0x01 for SOFTAP_IF.
* @param uint8 *macaddr : the MAC address.
*
* @return true : succeed
* @return false : fail
*/
bool wifi_set_macaddr(WIFI_INTERFACE if_index, uint8 *macaddr);
/**
* @brief Get the channel number for sniffer functions.
*
* @param null
*
* @return channel number
*/
uint8 wifi_get_channel(void);
/**
* @brief Set the channel number for sniffer functions.
*
* @param uint8 channel : channel number
*
* @return true : succeed
* @return false : fail
*/
bool wifi_set_channel(uint8 channel);
/**
* @brief Install the WiFi status LED.
*
* @param uint8 gpio_id : GPIO ID
* @param uint8 gpio_name : GPIO mux name
* @param uint8 gpio_func : GPIO function
*
* @return null
*/
void wifi_status_led_install(uint8 gpio_id, uint32 gpio_name, uint8 gpio_func);
/**
* @brief Uninstall the WiFi status LED.
*
* @param null
*
* @return null
*/
void wifi_status_led_uninstall();
/** Get the absolute difference between 2 u32_t values (correcting overflows)
* 'a' is expected to be 'higher' (without overflow) than 'b'. */
#define ESP_U32_DIFF(a, b) (((a) >= (b)) ? ((a) - (b)) : (((a) + ((b) ^ 0xFFFFFFFF) + 1)))
/**
* @brief Enable the promiscuous mode.
*
* @attention 1. The promiscuous mode can only be enabled in the ESP8266 station mode.
* @attention 2. When in the promiscuous mode, the ESP8266 station and soft-AP are disabled.
* @attention 3. Call wifi_station_disconnect to disconnect before enabling the promiscuous mode.
* @attention 4. Don't call any other APIs when in the promiscuous mode. Call
* wifi_promiscuous_enable(0) to quit sniffer before calling other APIs.
*
* @param uint8 promiscuous :
* - 0: to disable the promiscuous mode
* - 1: to enable the promiscuous mode
*
* @return null
*/
void wifi_promiscuous_enable(uint8 promiscuous);
/**
* @brief The RX callback function in the promiscuous mode.
*
* Each time a packet is received, the callback function will be called.
*
* @param uint8 *buf : the data received
* @param uint16 len : data length
*
* @return null
*/
typedef void (* wifi_promiscuous_cb_t)(uint8 *buf, uint16 len);
/**
* @brief Register the RX callback function in the promiscuous mode.
*
* Each time a packet is received, the registered callback function will be called.
*
* @param wifi_promiscuous_cb_t cb : callback
*
* @return null
*/
void wifi_set_promiscuous_rx_cb(wifi_promiscuous_cb_t cb);
/**
* @brief Set the MAC address filter for the sniffer mode.
*
* @attention This filter works only for the current sniffer mode.
* If users disable and then enable the sniffer mode, and then enable
* sniffer, they need to set the MAC address filter again.
*
* @param const uint8_t *address : MAC address
*
* @return true : succeed
* @return false : fail
*/
void wifi_promiscuous_set_mac(const uint8_t *address);
typedef enum {
PHY_MODE_11B = 1, /**< 802.11b */
PHY_MODE_11G = 2, /**< 802.11g */
PHY_MODE_11N = 3 /**< 802.11n */
} WIFI_PHY_MODE;
/**
* @brief Get the ESP8266 physical mode (802.11b/g/n).
*
* @param null
*
* @return enum WIFI_PHY_MODE
*/
WIFI_PHY_MODE wifi_get_phy_mode(void);
/**
* @brief Set the ESP8266 physical mode (802.11b/g/n).
*
* @attention The ESP8266 soft-AP only supports bg.
*
* @param WIFI_PHY_MODE mode : physical mode
*
* @return true : succeed
* @return false : fail
*/
bool wifi_set_phy_mode(WIFI_PHY_MODE mode);
typedef enum {
NONE_SLEEP_T = 0,
LIGHT_SLEEP_T,
MODEM_SLEEP_T
} sleep_type;
/**
* @brief Sets sleep type.
*
* Set NONE_SLEEP_T to disable sleep. Default to be Modem sleep.
*
* @attention Sleep function only takes effect in station-only mode.
*
* @param sleep_type type : sleep type
*
* @return true : succeed
* @return false : fail
*/
bool wifi_set_sleep_type(sleep_type type);
/**
* @brief Gets sleep type.
*
* @param null
*
* @return sleep type
*/
sleep_type wifi_get_sleep_type(void);
/**
* @brief Enable force sleep function.
*
* @attention Force sleep function is disabled by default.
*
* @param null
*
* @return null
*/
void wifi_fpm_open(void);
/**
* @brief Disable force sleep function.
*
* @param null
*
* @return null
*/
void wifi_fpm_close(void);
/**
* @brief Wake ESP8266 up from MODEM_SLEEP_T force sleep.
*
* @attention This API can only be called when MODEM_SLEEP_T force sleep function
* is enabled, after calling wifi_fpm_open.
* This API can not be called after calling wifi_fpm_close.
*
* @param null
*
* @return null
*/
void wifi_fpm_do_wakeup(void);
/**
* @brief Force ESP8266 enter sleep mode, and it will wake up automatically when time out.
*
* @attention 1. This API can only be called when force sleep function is enabled, after
* calling wifi_fpm_open. This API can not be called after calling wifi_fpm_close.
* @attention 2. If this API returned 0 means that the configuration is set successfully,
* but the ESP8266 will not enter sleep mode immediately, it is going to sleep
* in the system idle task. Please do not call other WiFi related function right
* after calling this API.
*
* @param uint32 sleep_time_in_us : sleep time, ESP8266 will wake up automatically
* when time out. Unit: us. Range: 10000 ~ 268435455(0xFFFFFFF).
* - If sleep_time_in_us is 0xFFFFFFF, the ESP8266 will sleep till
* - if wifi_fpm_set_sleep_type is set to be LIGHT_SLEEP_T, ESP8266 can wake up by GPIO.
* - if wifi_fpm_set_sleep_type is set to be MODEM_SLEEP_T, ESP8266 can wake up by wifi_fpm_do_wakeup.
*
* @return 0, setting succeed;
* @return -1, fail to sleep, sleep status error;
* @return -2, fail to sleep, force sleep function is not enabled.
*/
sint8 wifi_fpm_do_sleep(uint32 sleep_time_in_us);
/**
* @brief Set sleep type for force sleep function.
*
* @attention This API can only be called before wifi_fpm_open.
*
* @param sleep_type type : sleep type
*
* @return null
*/
void wifi_fpm_set_sleep_type(sleep_type type);
/**
* @brief Get sleep type of force sleep function.
*
* @param null
*
* @return sleep type
*/
sleep_type wifi_fpm_get_sleep_type(void);
enum {
EVENT_STAMODE_CONNECTED = 0,
EVENT_STAMODE_DISCONNECTED,
EVENT_STAMODE_AUTHMODE_CHANGE,
EVENT_STAMODE_GOT_IP,
EVENT_STAMODE_DHCP_TIMEOUT,
EVENT_SOFTAPMODE_STACONNECTED,
EVENT_SOFTAPMODE_STADISCONNECTED,
EVENT_SOFTAPMODE_PROBEREQRECVED,
EVENT_MAX
};
enum {
REASON_UNSPECIFIED = 1,
REASON_AUTH_EXPIRE = 2,
REASON_AUTH_LEAVE = 3,
REASON_ASSOC_EXPIRE = 4,
REASON_ASSOC_TOOMANY = 5,
REASON_NOT_AUTHED = 6,
REASON_NOT_ASSOCED = 7,
REASON_ASSOC_LEAVE = 8,
REASON_ASSOC_NOT_AUTHED = 9,
REASON_DISASSOC_PWRCAP_BAD = 10, /* 11h */
REASON_DISASSOC_SUPCHAN_BAD = 11, /* 11h */
REASON_IE_INVALID = 13, /* 11i */
REASON_MIC_FAILURE = 14, /* 11i */
REASON_4WAY_HANDSHAKE_TIMEOUT = 15, /* 11i */
REASON_GROUP_KEY_UPDATE_TIMEOUT = 16, /* 11i */
REASON_IE_IN_4WAY_DIFFERS = 17, /* 11i */
REASON_GROUP_CIPHER_INVALID = 18, /* 11i */
REASON_PAIRWISE_CIPHER_INVALID = 19, /* 11i */
REASON_AKMP_INVALID = 20, /* 11i */
REASON_UNSUPP_RSN_IE_VERSION = 21, /* 11i */
REASON_INVALID_RSN_IE_CAP = 22, /* 11i */
REASON_802_1X_AUTH_FAILED = 23, /* 11i */
REASON_CIPHER_SUITE_REJECTED = 24, /* 11i */
REASON_BEACON_TIMEOUT = 200,
REASON_NO_AP_FOUND = 201,
REASON_AUTH_FAIL = 202,
REASON_ASSOC_FAIL = 203,
REASON_HANDSHAKE_TIMEOUT = 204,
};
typedef struct {
uint8 ssid[32];
uint8 ssid_len;
uint8 bssid[6];
uint8 channel;
} Event_StaMode_Connected_t;
typedef struct {
uint8 ssid[32];
uint8 ssid_len;
uint8 bssid[6];
uint8 reason;
} Event_StaMode_Disconnected_t;
typedef struct {
uint8 old_mode;
uint8 new_mode;
} Event_StaMode_AuthMode_Change_t;
typedef struct {
struct ip_addr ip;
struct ip_addr mask;
struct ip_addr gw;
} Event_StaMode_Got_IP_t;
typedef struct {
uint8 mac[6];
uint8 aid;
} Event_SoftAPMode_StaConnected_t;
typedef struct {
uint8 mac[6];
uint8 aid;
} Event_SoftAPMode_StaDisconnected_t;
typedef struct {
int rssi;
uint8 mac[6];
} Event_SoftAPMode_ProbeReqRecved_t;
typedef union {
Event_StaMode_Connected_t connected;
Event_StaMode_Disconnected_t disconnected;
Event_StaMode_AuthMode_Change_t auth_change;
Event_StaMode_Got_IP_t got_ip;
Event_SoftAPMode_StaConnected_t sta_connected;
Event_SoftAPMode_StaDisconnected_t sta_disconnected;
Event_SoftAPMode_ProbeReqRecved_t ap_probereqrecved;
} Event_Info_u;
typedef struct _esp_event {
uint32 event;
Event_Info_u event_info;
} System_Event_t;
/**
* @brief The Wi-Fi event handler.
*
* @attention No complex operations are allowed in callback.
* If you want to execute any complex operations, please post message to another task instead.
*
* @param System_Event_t *event : WiFi event
*
* @return null
*/
typedef void (* wifi_event_handler_cb_t)(System_Event_t *event);
/**
* @brief Register the Wi-Fi event handler.
*
* @param wifi_event_handler_cb_t cb : callback function
*
* @return true : succeed
* @return false : fail
*/
bool wifi_set_event_handler_cb(wifi_event_handler_cb_t cb);
/* WPS can only be used when ESP8266 station is enabled. */
typedef enum wps_type {
WPS_TYPE_DISABLE = 0,
WPS_TYPE_PBC, // Only this is supported
WPS_TYPE_PIN,
WPS_TYPE_DISPLAY,
WPS_TYPE_MAX,
} WPS_TYPE_t;
enum wps_cb_status {
WPS_CB_ST_SUCCESS = 0, /**< WPS succeed */
WPS_CB_ST_FAILED, /**< WPS fail */
WPS_CB_ST_TIMEOUT, /**< WPS timeout, fail */
WPS_CB_ST_WEP, /**< WPS failed because that WEP is not supported */
WPS_CB_ST_SCAN_ERR, /**< can not find the target WPS AP */
};
/**
* @brief Enable Wi-Fi WPS function.
*
* @attention WPS can only be used when ESP8266 station is enabled.
*
* @param WPS_TYPE_t wps_type : WPS type, so far only WPS_TYPE_PBC is supported
*
* @return true : succeed
* @return false : fail
*/
bool wifi_wps_enable(WPS_TYPE_t wps_type);
/**
* @brief Disable Wi-Fi WPS function and release resource it taken.
*
* @param null
*
* @return true : succeed
* @return false : fail
*/
bool wifi_wps_disable(void);
/**
* @brief WPS starts to work.
*
* @attention WPS can only be used when ESP8266 station is enabled.
*
* @param null
*
* @return true : WPS starts to work successfully, but does not mean WPS succeed.
* @return false : fail
*/
bool wifi_wps_start(void);
/**
* @brief WPS callback.
*
* @param int status : status of WPS, enum wps_cb_status.
* - If parameter status == WPS_CB_ST_SUCCESS in WPS callback, it means WPS got AP's
* information, user can call wifi_wps_disable to disable WPS and release resource,
* then call wifi_station_connect to connect to target AP.
* - Otherwise, it means that WPS fail, user can create a timer to retry WPS by
* wifi_wps_start after a while, or call wifi_wps_disable to disable WPS and release resource.
*
* @return null
*/
typedef void (*wps_st_cb_t)(int status);
/**
* @brief Set WPS callback.
*
* @attention WPS can only be used when ESP8266 station is enabled.
*
* @param wps_st_cb_t cb : callback.
*
* @return true : WPS starts to work successfully, but does not mean WPS succeed.
* @return false : fail
*/
bool wifi_set_wps_cb(wps_st_cb_t cb);
/**
* @brief Callback of sending user-define 802.11 packets.
*
* @param uint8 status : 0, packet sending succeed; otherwise, fail.
*
* @return null
*/
typedef void (*freedom_outside_cb_t)(uint8 status);
/**
* @brief Register a callback for sending user-define 802.11 packets.
*
* @attention Only after the previous packet was sent, entered the freedom_outside_cb_t,
* the next packet is allowed to send.
*
* @param freedom_outside_cb_t cb : sent callback
*
* @return 0, succeed;
* @return -1, fail.
*/
sint32 wifi_register_send_pkt_freedom_cb(freedom_outside_cb_t cb);
/**
* @brief Unregister the callback for sending user-define 802.11 packets.
*
* @param null
*
* @return null
*/
void wifi_unregister_send_pkt_freedom_cb(void);
/**
* @brief Send user-define 802.11 packets.
*
* @attention 1. Packet has to be the whole 802.11 packet, does not include the FCS.
* The length of the packet has to be longer than the minimum length
* of the header of 802.11 packet which is 24 bytes, and less than 1400 bytes.
* @attention 2. Duration area is invalid for user, it will be filled in SDK.
* @attention 3. The rate of sending packet is same as the management packet which
* is the same as the system rate of sending packets.
* @attention 4. Only after the previous packet was sent, entered the sent callback,
* the next packet is allowed to send. Otherwise, wifi_send_pkt_freedom
* will return fail.
*
* @param uint8 *buf : pointer of packet
* @param uint16 len : packet length
* @param bool sys_seq : follow the system's 802.11 packets sequence number or not,
* if it is true, the sequence number will be increased 1 every
* time a packet sent.
*
* @return 0, succeed;
* @return -1, fail.
*/
sint32 wifi_send_pkt_freedom(uint8 *buf, uint16 len, bool sys_seq);
/**
* @brief Enable RFID LOCP (Location Control Protocol) to receive WDS packets.
*
* @param null
*
* @return 0, succeed;
* @return otherwise, fail.
*/
sint32 wifi_rfid_locp_recv_open(void);
/**
* @brief Disable RFID LOCP (Location Control Protocol) .
*
* @param null
*
* @return null
*/
void wifi_rfid_locp_recv_close(void);
/**
* @brief RFID LOCP (Location Control Protocol) receive callback .
*
* @param uint8 *frm : point to the head of 802.11 packet
* @param int len : packet length
* @param int rssi : signal strength
*
* @return null
*/
typedef void (*rfid_locp_cb_t)(uint8 *frm, int len, sint8 rssi);
/**
* @brief Register a callback of receiving WDS packets.
*
* Register a callback of receiving WDS packets. Only if the first MAC
* address of the WDS packet is a multicast address.
*
* @param rfid_locp_cb_t cb : callback
*
* @return 0, succeed;
* @return otherwise, fail.
*/
sint32 wifi_register_rfid_locp_recv_cb(rfid_locp_cb_t cb);
/**
* @brief Unregister the callback of receiving WDS packets.
*
* @param null
*
* @return null
*/
void wifi_unregister_rfid_locp_recv_cb(void);
enum FIXED_RATE {
PHY_RATE_48 = 0x8,
PHY_RATE_24 = 0x9,
PHY_RATE_12 = 0xA,
PHY_RATE_6 = 0xB,
PHY_RATE_54 = 0xC,
PHY_RATE_36 = 0xD,
PHY_RATE_18 = 0xE,
PHY_RATE_9 = 0xF,
};
#define FIXED_RATE_MASK_NONE 0x00
#define FIXED_RATE_MASK_STA 0x01
#define FIXED_RATE_MASK_AP 0x02
#define FIXED_RATE_MASK_ALL 0x03
/**
* @brief Set the fixed rate and mask of sending data from ESP8266.
*
* @attention 1. Only if the corresponding bit in enable_mask is 1, ESP8266 station
* or soft-AP will send data in the fixed rate.
* @attention 2. If the enable_mask is 0, both ESP8266 station and soft-AP will not
* send data in the fixed rate.
* @attention 3. ESP8266 station and soft-AP share the same rate, they can not be
* set into the different rate.
*
* @param uint8 enable_mask : 0x00 - disable the fixed rate
* - 0x01 - use the fixed rate on ESP8266 station
* - 0x02 - use the fixed rate on ESP8266 soft-AP
* - 0x03 - use the fixed rate on ESP8266 station and soft-AP
* @param uint8 rate : value of the fixed rate
*
* @return 0 : succeed
* @return otherwise : fail
*/
sint32 wifi_set_user_fixed_rate(uint8 enable_mask, uint8 rate);
/**
* @brief Get the fixed rate and mask of ESP8266.
*
* @param uint8 *enable_mask : pointer of the enable_mask
* @param uint8 *rate : pointer of the fixed rate
*
* @return 0 : succeed
* @return otherwise : fail
*/
int wifi_get_user_fixed_rate(uint8 *enable_mask, uint8 *rate);
enum support_rate {
RATE_11B5M = 0,
RATE_11B11M = 1,
RATE_11B1M = 2,
RATE_11B2M = 3,
RATE_11G6M = 4,
RATE_11G12M = 5,
RATE_11G24M = 6,
RATE_11G48M = 7,
RATE_11G54M = 8,
RATE_11G9M = 9,
RATE_11G18M = 10,
RATE_11G36M = 11,
};
/**
* @brief Set the support rate of ESP8266.
*
* Set the rate range in the IE of support rate in ESP8266's beacon,
* probe req/resp and other packets.
* Tell other devices about the rate range supported by ESP8266 to limit
* the rate of sending packets from other devices.
* Example : wifi_set_user_sup_rate(RATE_11G6M, RATE_11G24M);
*
* @attention This API can only support 802.11g now, but it will support 802.11b in next version.
*
* @param uint8 min : the minimum value of the support rate, according to enum support_rate.
* @param uint8 max : the maximum value of the support rate, according to enum support_rate.
*
* @return 0 : succeed
* @return otherwise : fail
*/
sint32 wifi_set_user_sup_rate(uint8 min, uint8 max);
enum RATE_11B_ID {
RATE_11B_B11M = 0,
RATE_11B_B5M = 1,
RATE_11B_B2M = 2,
RATE_11B_B1M = 3,
};
enum RATE_11G_ID {
RATE_11G_G54M = 0,
RATE_11G_G48M = 1,
RATE_11G_G36M = 2,
RATE_11G_G24M = 3,
RATE_11G_G18M = 4,
RATE_11G_G12M = 5,
RATE_11G_G9M = 6,
RATE_11G_G6M = 7,
RATE_11G_B5M = 8,
RATE_11G_B2M = 9,
RATE_11G_B1M = 10
};
enum RATE_11N_ID {
RATE_11N_MCS7S = 0,
RATE_11N_MCS7 = 1,
RATE_11N_MCS6 = 2,
RATE_11N_MCS5 = 3,
RATE_11N_MCS4 = 4,
RATE_11N_MCS3 = 5,
RATE_11N_MCS2 = 6,
RATE_11N_MCS1 = 7,
RATE_11N_MCS0 = 8,
RATE_11N_B5M = 9,
RATE_11N_B2M = 10,
RATE_11N_B1M = 11
};
#define RC_LIMIT_11B 0
#define RC_LIMIT_11G 1
#define RC_LIMIT_11N 2
#define RC_LIMIT_P2P_11G 3
#define RC_LIMIT_P2P_11N 4
#define RC_LIMIT_NUM 5
#define LIMIT_RATE_MASK_NONE 0x00
#define LIMIT_RATE_MASK_STA 0x01
#define LIMIT_RATE_MASK_AP 0x02
#define LIMIT_RATE_MASK_ALL 0x03
/**
* @brief Limit the initial rate of sending data from ESP8266.
*
* Example:
* wifi_set_user_rate_limit(RC_LIMIT_11G, 0, RATE_11G_G18M, RATE_11G_G6M);
*
* @attention The rate of retransmission is not limited by this API.
*
* @param uint8 mode : WiFi mode
* - #define RC_LIMIT_11B 0
* - #define RC_LIMIT_11G 1
* - #define RC_LIMIT_11N 2
* @param uint8 ifidx : interface of ESP8266
* - 0x00 - ESP8266 station
* - 0x01 - ESP8266 soft-AP
* @param uint8 max : the maximum value of the rate, according to the enum rate
* corresponding to the first parameter mode.
* @param uint8 min : the minimum value of the rate, according to the enum rate
* corresponding to the first parameter mode.
*
* @return 0 : succeed
* @return otherwise : fail
*/
bool wifi_set_user_rate_limit(uint8 mode, uint8 ifidx, uint8 max, uint8 min);
/**
* @brief Get the interfaces of ESP8266 whose rate of sending data is limited by
* wifi_set_user_rate_limit.
*
* @param null
*
* @return LIMIT_RATE_MASK_NONE - disable the limitation on both ESP8266 station and soft-AP
* @return LIMIT_RATE_MASK_STA - enable the limitation on ESP8266 station
* @return LIMIT_RATE_MASK_AP - enable the limitation on ESP8266 soft-AP
* @return LIMIT_RATE_MASK_ALL - enable the limitation on both ESP8266 station and soft-AP
*/
uint8 wifi_get_user_limit_rate_mask(void);
/**
* @brief Set the interfaces of ESP8266 whose rate of sending packets is limited by
* wifi_set_user_rate_limit.
*
* @param uint8 enable_mask :
* - LIMIT_RATE_MASK_NONE - disable the limitation on both ESP8266 station and soft-AP
* - LIMIT_RATE_MASK_STA - enable the limitation on ESP8266 station
* - LIMIT_RATE_MASK_AP - enable the limitation on ESP8266 soft-AP
* - LIMIT_RATE_MASK_ALL - enable the limitation on both ESP8266 station and soft-AP
*
* @return true : succeed
* @return false : fail
*/
bool wifi_set_user_limit_rate_mask(uint8 enable_mask);
typedef enum {
USER_IE_BEACON = 0,
USER_IE_PROBE_REQ,
USER_IE_PROBE_RESP,
USER_IE_ASSOC_REQ,
USER_IE_ASSOC_RESP,
USER_IE_MAX
} user_ie_type;
/**
* @brief User IE received callback.
*
* @param user_ie_type type : type of user IE.
* @param const uint8 sa[6] : source address of the packet.
* @param const uint8 m_oui[3] : factory tag.
* @param uint8 *user_ie : pointer of user IE.
* @param uint8 ie_len : length of user IE.
* @param sint32 rssi : signal strength.
*
* @return null
*/
typedef void (*user_ie_manufacturer_recv_cb_t)(user_ie_type type, const uint8 sa[6], const uint8 m_oui[3], uint8 *ie, uint8 ie_len, sint32 rssi);
/**
* @brief Set user IE of ESP8266.
*
* The user IE will be added to the target packets of user_ie_type.
*
* @param bool enable :
* - true, enable the corresponding user IE function, all parameters below have to be set.
* - false, disable the corresponding user IE function and release the resource,
* only the parameter "type" below has to be set.
* @param uint8 *m_oui : factory tag, apply for it from Espressif System.
* @param user_ie_type type : IE type. If it is USER_IE_BEACON, please disable the
* IE function and enable again to take the configuration
* effect immediately .
* @param uint8 *user_ie : user-defined information elements, need not input the whole
* 802.11 IE, need only the user-define part.
* @param uint8 len : length of user IE, 247 bytes at most.
*
* @return true : succeed
* @return false : fail
*/
bool wifi_set_user_ie(bool enable, uint8 *m_oui, user_ie_type type, uint8 *user_ie, uint8 len);
/**
* @brief Register user IE received callback.
*
* @param user_ie_manufacturer_recv_cb_t cb : callback
*
* @return 0 : succeed
* @return -1 : fail
*/
sint32 wifi_register_user_ie_manufacturer_recv_cb(user_ie_manufacturer_recv_cb_t cb);
/**
* @brief Unregister user IE received callback.
*
* @param null
*
* @return null
*/
void wifi_unregister_user_ie_manufacturer_recv_cb(void);
#endif