ESP8266_RTOS_SDK v1.4.0

- Main Page
- Modules
- Data Structures
- Files

Data Structures | Typedefs | Enumerations | Functions
Common APIs
WiFi Related APIs

WiFi common APIs. More...

## Data Structures
struct | ip_info
struct | Event_StaMode_ScanDone_t
struct | Event_StaMode_Connected_t
struct | Event_StaMode_Disconnected_t
struct | Event_StaMode_AuthMode_Change_t
struct | Event_StaMode_Got_IP_t
struct | Event_SoftAPMode_StaConnected_t
struct | Event_SoftAPMode_StaDisconnected_t
struct | Event_SoftAPMode_ProbeReqRecved_t
union | Event_Info_u
struct | _esp_event

## Typedefs
typedef struct _esp_event | System_Event_t
typedef void(* | wifi_event_handler_cb_t) (System_Event_t *event)
| The Wi-Fi event handler. More...
typedef void(* | freedom_outside_cb_t) (uint8 status)
| Callback of sending user-define 802.11 packets. More...
typedef void(* | rfid_locp_cb_t) (uint8 *frm, int len, sint8 rssi)
| RFID LOCP (Location Control Protocol) receive callback . More...

## Enumerations
enum | WIFI_MODE { NULL_MODE = 0, STATION_MODE, SOFTAP_MODE, STATIONAP_MODE, MAX_MODE }
enum | AUTH_MODE { AUTH_OPEN = 0, AUTH_WEP, AUTH_WPA_PSK, AUTH_WPA2_PSK, AUTH_WPA_WPA2_PSK, AUTH_MAX }
enum | WIFI_INTERFACE { STATION_IF = 0, SOFTAP_IF, MAX_IF }
enum | WIFI_PHY_MODE { PHY_MODE_11B = 1, PHY_MODE_11G = 2, PHY_MODE_11N = 3 }
enum | SYSTEM_EVENT { EVENT_STAMODE_SCAN_DONE = 0, EVENT_STAMODE_CONNECTED, 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, REASON_DISASSOC_SUPCHAN_BAD = 11, REASON_IE_INVALID = 13, REASON_MIC_FAILURE = 14, REASON_4WAY_HANDSHAKE_TIMEOUT = 15, REASON_GROUP_KEY_UPDATE_TIMEOUT = 16, REASON_IE_IN_4WAY_DIFFERS = 17, REASON_GROUP_CIPHER_INVALID = 18, REASON_PAIRWISE_CIPHER_INVALID = 19, REASON_AKMP_INVALID = 20, REASON_UNSUPP_RSN_IE_VERSION = 21, REASON_INVALID_RSN_IE_CAP = 22, REASON_802_1X_AUTH_FAILED = 23, REASON_CIPHER_SUITE_REJECTED = 24, REASON_BEACON_TIMEOUT = 200, REASON_NO_AP_FOUND = 201, REASON_AUTH_FAIL = 202, REASON_ASSOC_FAIL = 203, REASON_HANDSHAKE_TIMEOUT = 204 }
enum | sleep_type { NONE_SLEEP_T = 0, LIGHT_SLEEP_T, MODEM_SLEEP_T }

## Functions
WIFI_MODE | wifi_get_opmode (void)
| Get the current operating mode of the WiFi. More...
WIFI_MODE | wifi_get_opmode_default (void)
| Get the operating mode of the WiFi saved in the Flash. More...
bool | wifi_set_opmode (WIFI_MODE opmode)
| Set the WiFi operating mode, and save it to Flash. More...
bool | wifi_set_opmode_current (WIFI_MODE opmode)
| Set the WiFi operating mode, and will not save it to Flash. More...
bool | wifi_get_ip_info (WIFI_INTERFACE if_index, struct ip_info *info)
| Get the IP address of the ESP8266 WiFi station or the soft-AP interface. More...
bool | wifi_set_ip_info (WIFI_INTERFACE if_index, struct ip_info *info)
| Set the IP address of the ESP8266 WiFi station or the soft-AP interface. More...
bool | wifi_get_macaddr (WIFI_INTERFACE if_index, uint8 *macaddr)
| Get MAC address of the ESP8266 WiFi station or the soft-AP interface. More...
bool | wifi_set_macaddr (WIFI_INTERFACE if_index, uint8 *macaddr)
| Set MAC address of the ESP8266 WiFi station or the soft-AP interface. More...
void | wifi_status_led_install (uint8 gpio_id, uint32 gpio_name, uint8 gpio_func)
| Install the WiFi status LED. More...
void | wifi_status_led_uninstall (void)
| Uninstall the WiFi status LED. More...
WIFI_PHY_MODE | wifi_get_phy_mode (void)
| Get the ESP8266 physical mode (802.11b/g/n). More...
bool | wifi_set_phy_mode (WIFI_PHY_MODE mode)
| Set the ESP8266 physical mode (802.11b/g/n). More...
bool | wifi_set_event_handler_cb (wifi_event_handler_cb_t cb)
| Register the Wi-Fi event handler. More...
sint32 | wifi_register_send_pkt_freedom_cb (freedom_outside_cb_t cb)
| Register a callback for sending user-define 802.11 packets. More...
void | wifi_unregister_send_pkt_freedom_cb (void)
| Unregister the callback for sending user-define 802.11 packets. More...
sint32 | wifi_send_pkt_freedom (uint8 *buf, uint16 len, bool sys_seq)
| Send user-define 802.11 packets. More...
sint32 | wifi_rfid_locp_recv_open (void)
| Enable RFID LOCP (Location Control Protocol) to receive WDS packets. More...
void | wifi_rfid_locp_recv_close (void)
| Disable RFID LOCP (Location Control Protocol) . More...
sint32 | wifi_register_rfid_locp_recv_cb (rfid_locp_cb_t cb)
| Register a callback of receiving WDS packets. More...
void | wifi_unregister_rfid_locp_recv_cb (void)
| Unregister the callback of receiving WDS packets. More...
bool | wifi_set_sleep_type (sleep_type type)
| Sets sleep type. More...
sleep_type | wifi_get_sleep_type (void)
| Gets sleep type. More...

## Detailed Description

WiFi common APIs.

The Flash system parameter area is the last 16KB of the Flash.

## Typedef Documentation

typedef void(* freedom_outside_cb_t) (uint8 status)

Callback of sending user-define 802.11 packets.

Parameters

  uint8 | status : 0, packet sending succeed; otherwise, fail.

Returns
  null

typedef void(* rfid_locp_cb_t) (uint8 *frm, int len, sint8 rssi)

RFID LOCP (Location Control Protocol) receive callback .

Parameters

  uint8 | *frm : point to the head of 802.11 packet
  int | len : packet length
  int | rssi : signal strength

Returns
  null

typedef void(* wifi_event_handler_cb_t) (System_Event_t *event)

The Wi-Fi event handler.

Attention
  No complex operations are allowed in callback. If users want to execute any complex operations, please post message to another task instead.

Parameters

  System_Event_t | *event : WiFi event

Returns
  null

## Enumeration Type Documentation

enum AUTH_MODE

Enumerator
AUTH_OPEN | authenticate mode : open
AUTH_WEP | authenticate mode : WEP
AUTH_WPA_PSK | authenticate mode : WPA_PSK
AUTH_WPA2_PSK | authenticate mode : WPA2_PSK
AUTH_WPA_WPA2_PSK | authenticate mode : WPA_WPA2_PSK

enum SYSTEM_EVENT

Enumerator
EVENT_STAMODE_SCAN_DONE | ESP8266 station finish scanning AP
EVENT_STAMODE_CONNECTED | ESP8266 station connected to AP
EVENT_STAMODE_DISCONNECTED | ESP8266 station disconnected to AP
EVENT_STAMODE_AUTHMODE_CHANGE | the auth mode of AP connected by ESP8266 station changed
EVENT_STAMODE_GOT_IP | ESP8266 station got IP from connected AP
EVENT_STAMODE_DHCP_TIMEOUT | ESP8266 station dhcp client got IP timeout
EVENT_SOFTAPMODE_STACONNECTED | a station connected to ESP8266 soft-AP
EVENT_SOFTAPMODE_STADISCONNECTED | a station disconnected to ESP8266 soft-AP
EVENT_SOFTAPMODE_PROBEREQRECVED | Receive probe request packet in soft-AP interface

enum WIFI_INTERFACE

Enumerator
STATION_IF | ESP8266 station interface
SOFTAP_IF | ESP8266 soft-AP interface

enum WIFI_MODE

Enumerator
NULL_MODE | null mode
STATION_MODE | WiFi station mode
SOFTAP_MODE | WiFi soft-AP mode
STATIONAP_MODE | WiFi station + soft-AP mode

enum WIFI_PHY_MODE

Enumerator
PHY_MODE_11B | 802.11b
PHY_MODE_11G | 802.11g
PHY_MODE_11N | 802.11n

## Function Documentation

bool wifi_get_ip_info | ( | WIFI_INTERFACE | if_index,
|  | struct ip_info * | info
| ) |  |

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.

Parameters

  WIFI_INTERFACE | if_index : get the IP address of the station or the soft-AP interface, 0x00 for STATION_IF, 0x01 for SOFTAP_IF.
  struct | ip_info *info : the IP information obtained.

Returns
  true : succeed
  false : fail

bool wifi_get_macaddr | ( | WIFI_INTERFACE | if_index,
|  | uint8 * | macaddr
| ) |  |

Get MAC address of the ESP8266 WiFi station or the soft-AP interface.

Parameters

  WIFI_INTERFACE | if_index : get the IP address of the station or the soft-AP interface, 0x00 for STATION_IF, 0x01 for SOFTAP_IF.
  uint8 | *macaddr : the MAC address.

Returns
  true : succeed
  false : fail

WIFI_MODE wifi_get_opmode | ( | void |  | ) |

Get the current operating mode of the WiFi.

Parameters

  null |

Returns
  WiFi operating modes:
  - 0x01: station mode;
  - 0x02: soft-AP mode
  - 0x03: station+soft-AP mode

WIFI_MODE wifi_get_opmode_default | ( | void |  | ) |

Get the operating mode of the WiFi saved in the Flash.

Parameters

  null |

Returns
  WiFi operating modes:
  - 0x01: station mode;
  - 0x02: soft-AP mode
  - 0x03: station+soft-AP mode

WIFI_PHY_MODE wifi_get_phy_mode | ( | void |  | ) |

Get the ESP8266 physical mode (802.11b/g/n).

Parameters

  null |

Returns
  enum WIFI_PHY_MODE

sleep_type wifi_get_sleep_type | ( | void |  | ) |

Gets sleep type.

Parameters

  null |

Returns
  sleep type

sint32 wifi_register_rfid_locp_recv_cb | ( | rfid_locp_cb_t | cb | ) |

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.

Parameters

  rfid_locp_cb_t | cb : callback

Returns
  0, succeed;
  otherwise, fail.

sint32 wifi_register_send_pkt_freedom_cb | ( | freedom_outside_cb_t | cb | ) |

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.

Parameters

  freedom_outside_cb_t | cb : sent callback

Returns
  0, succeed;
  -1, fail.

void wifi_rfid_locp_recv_close | ( | void |  | ) |

Disable RFID LOCP (Location Control Protocol) .

Parameters

  null |

Returns
  null

sint32 wifi_rfid_locp_recv_open | ( | void |  | ) |

Enable RFID LOCP (Location Control Protocol) to receive WDS packets.

Parameters

  null |

Returns
  0, succeed;
  otherwise, fail.

sint32 wifi_send_pkt_freedom | ( | uint8 * | buf,
|  | uint16 | len,
|  | bool | sys_seq
| ) |  |

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.
  2. Duration area is invalid for user, it will be filled in SDK.
  3. The rate of sending packet is same as the management packet which is the same as the system rate of sending packets.
  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.

Parameters

  uint8 | *buf : pointer of packet
  uint16 | len : packet length
  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.

Returns
  0, succeed;
  -1, fail.

bool wifi_set_event_handler_cb | ( | wifi_event_handler_cb_t | cb | ) |

Register the Wi-Fi event handler.

Parameters

  wifi_event_handler_cb_t | cb : callback function

Returns
  true : succeed
  false : fail

bool wifi_set_ip_info | ( | WIFI_INTERFACE | if_index,
|  | struct ip_info * | info
| ) |  |

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

Parameters

  WIFI_INTERFACE | if_index : get the IP address of the station or the soft-AP interface, 0x00 for STATION_IF, 0x01 for SOFTAP_IF.
  struct | ip_info *info : the IP information obtained.

Returns
  true : succeed
  false : fail

bool wifi_set_macaddr | ( | WIFI_INTERFACE | if_index,
|  | uint8 * | macaddr
| ) |  |

Set MAC address of the ESP8266 WiFi station or the soft-AP interface.

Attention
  1. This API can only be called in user_init.
  2. Users need to enable the target interface (station or soft-AP) by wifi_set_opmode first.
  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".

Parameters

  WIFI_INTERFACE | if_index : get the IP address of the station or the soft-AP interface, 0x00 for STATION_IF, 0x01 for SOFTAP_IF.
  uint8 | *macaddr : the MAC address.

Returns
  true : succeed
  false : fail

bool wifi_set_opmode | ( | WIFI_MODE | opmode | ) |

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.

Parameters

  uint8 | opmode : WiFi operating modes: 0x01: station mode; 0x02: soft-AP mode 0x03: station+soft-AP mode

Returns
  true : succeed
  false : fail

bool wifi_set_opmode_current | ( | WIFI_MODE | opmode | ) |

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.

Parameters

  uint8 | opmode : WiFi operating modes: 0x01: station mode; 0x02: soft-AP mode 0x03: station+soft-AP mode

Returns
  true : succeed
  false : fail

bool wifi_set_phy_mode | ( | WIFI_PHY_MODE | mode | ) |

Set the ESP8266 physical mode (802.11b/g/n).

Attention
  The ESP8266 soft-AP only supports bg.

Parameters

  WIFI_PHY_MODE | mode : physical mode

Returns
  true : succeed
  false : fail

bool wifi_set_sleep_type | ( | sleep_type | type | ) |

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.

Parameters

  sleep_type | type : sleep type

Returns
  true : succeed
  false : fail

void wifi_status_led_install | ( | uint8 | gpio_id,
|  | uint32 | gpio_name,
|  | uint8 | gpio_func
| ) |  |

Install the WiFi status LED.

Parameters

  uint8 | gpio_id : GPIO ID
  uint8 | gpio_name : GPIO mux name
  uint8 | gpio_func : GPIO function

Returns
  null

void wifi_status_led_uninstall | ( | void |  | ) |

Uninstall the WiFi status LED.

Parameters

  null |

Returns
  null

void wifi_unregister_rfid_locp_recv_cb | ( | void |  | ) |

Unregister the callback of receiving WDS packets.

Parameters

  null |

Returns
  null

void wifi_unregister_send_pkt_freedom_cb | ( | void |  | ) |

Unregister the callback for sending user-define 802.11 packets.

Parameters

  null |

Returns
  null