ESP32_RTOS_SDK V1.1.0

- Main Page
- Modules
- Data Structures
- Files

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

ESP32 station APIs. More...

## Data Structures

struct | station_config
struct | scan_config
struct | bss_info

## Typedefs

typedef void(* | scan_done_cb_t) (void *arg, STATUS status)
| Callback function for wifi_station_scan. More...

## Enumerations

enum | STATION_STATUS { STATION_IDLE = 0, STATION_CONNECTING, STATION_WRONG_PASSWORD, STATION_NO_AP_FOUND, STATION_CONNECT_FAIL, STATION_GOT_IP }

## Functions

bool | wifi_station_get_config (struct station_config *config)
| Get the current configuration of the ESP32 WiFi station. More...
bool | wifi_station_get_config_default (struct station_config *config)
| Get the configuration parameters saved in the Flash of the ESP32 WiFi station. More...
bool | wifi_station_set_config (struct station_config *config)
| Set the configuration of the ESP32 station and save it to the Flash. More...
bool | wifi_station_set_config_current (struct station_config *config)
| Set the configuration of the ESP32 station. And the configuration will not be saved to the Flash. More...
bool | wifi_station_connect (void)
| Connect the ESP32 WiFi station to the AP. More...
bool | wifi_station_disconnect (void)
| Disconnect the ESP32 WiFi station from the AP. More...
bool | wifi_station_scan (struct scan_config *config, scan_done_cb_t cb)
| Scan all available APs. More...
bool | wifi_station_get_auto_connect (void)
| Check if the ESP32 station will connect to the recorded AP automatically when the power is on. More...
bool | wifi_station_set_auto_connect (bool set)
| Set whether the ESP32 station will connect to the recorded AP automatically when the power is on. It will do so by default. More...
bool | wifi_station_get_reconnect_policy (void)
| Check whether the ESP32 station will reconnect to the AP after disconnection. More...
bool | wifi_station_set_reconnect_policy (bool set)
| Set whether the ESP32 station will reconnect to the AP after disconnection. It will do so by default. More...
STATION_STATUS | wifi_station_get_connect_status (void)
| Get the connection status of the ESP32 WiFi station. More...
uint8 | wifi_station_get_current_ap_id (void)
| Get the information of APs (5 at most) recorded by ESP32 station. More...
bool | wifi_station_ap_change (uint8 current_ap_id)
| Switch the ESP32 station connection to a recorded AP. More...
bool | wifi_station_ap_number_set (uint8 ap_number)
| Set the number of APs that can be recorded in the ESP32 station. When the ESP32 station is connected to an AP, the SSID and password of the AP will be recorded. More...
uint8 | wifi_station_get_ap_info (struct station_config config[])
| Get the information of APs (5 at most) recorded by ESP32 station. More...
sint8 | wifi_station_get_rssi (void)
| Get rssi of the AP which ESP32 station connected to. More...
bool | wifi_station_dhcpc_start (void)
| Enable the ESP32 station DHCP client. More...
bool | wifi_station_dhcpc_stop (void)
| Disable the ESP32 station DHCP client. More...
enum dhcp_status | wifi_station_dhcpc_status (void)
| Get the ESP32 station DHCP client status. More...

## Detailed Description

ESP32 station APIs.

Attention
  To call APIs related to ESP32 station has to enable station mode first (wifi_set_opmode)

## Typedef Documentation

typedef void(* scan_done_cb_t) (void *arg, STATUS status)

Callback function for wifi_station_scan.

Parameters

  void | *arg : information of APs that are found; save them as linked list; refer to struct bss_info
  STATUS | status : status of scanning

Returns
  null

## Enumeration Type Documentation

enum STATION_STATUS

Enumerator
STATION_IDLE | ESP32 station idle
STATION_CONNECTING | ESP32 station is connecting to AP
STATION_WRONG_PASSWORD | the password is wrong
STATION_NO_AP_FOUND | ESP32 station can not find the target AP
STATION_CONNECT_FAIL | ESP32 station fail to connect to AP
STATION_GOT_IP | ESP32 station got IP address from AP

## Function Documentation

bool wifi_station_ap_change | ( | uint8 | current_ap_id | ) |

Switch the ESP32 station connection to a recorded AP.

Parameters

  uint8 | new_ap_id : AP's record id, start counting from 0.

Returns
  true : succeed
  false : fail

bool wifi_station_ap_number_set | ( | uint8 | ap_number | ) |

Set the number of APs that can be recorded in the ESP32 station. When the ESP32 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.

Parameters

  uint8 | ap_number : the number of APs that can be recorded (MAX: 5)

Returns
  true : succeed
  false : fail

bool wifi_station_connect | ( | void |  | ) |

Connect the ESP32 WiFi station to the AP.

Attention
  1. This API should be called when the ESP32 station is enabled, and the system initialization is completed. Do not call this API in user_init.
  2. If the ESP32 is connected to an AP, call wifi_station_disconnect to disconnect.

Parameters

  null |

Returns
  true : succeed
  false : fail

bool wifi_station_dhcpc_start | ( | void |  | ) |

Enable the ESP32 station DHCP client.

Attention
  1. The DHCP is enabled by default.
  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.

Parameters

  null |

Returns
  true : succeed
  false : fail

enum dhcp_status wifi_station_dhcpc_status | ( | void |  | ) |

Get the ESP32 station DHCP client status.

Parameters

  null |

Returns
  enum dhcp_status

bool wifi_station_dhcpc_stop | ( | void |  | ) |

Disable the ESP32 station DHCP client.

Attention
  1. The DHCP is enabled by default.
  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.

Parameters

  null |

Returns
  true : succeed
  false : fail

bool wifi_station_disconnect | ( | void |  | ) |

Disconnect the ESP32 WiFi station from the AP.

Attention
  This API should be called when the ESP32 station is enabled, and the system initialization is completed. Do not call this API in user_init.

Parameters

  null |

Returns
  true : succeed
  false : fail

uint8 wifi_station_get_ap_info | ( | struct station_config | config[] | ) |

Get the information of APs (5 at most) recorded by ESP32 station.

Example:

            struct station_config config[5];
            nt i = wifi_station_get_ap_info(config);

Parameters

  struct | station_config config[] : information of the APs, the array size should be 5.

Returns
  The number of APs recorded.

bool wifi_station_get_auto_connect | ( | void |  | ) |

Check if the ESP32 station will connect to the recorded AP automatically when the power is on.

Parameters

  null |

Returns
  true : connect to the AP automatically
  false : not connect to the AP automatically

bool wifi_station_get_config | ( | struct station_config * | config | ) |

Get the current configuration of the ESP32 WiFi station.

Parameters

  struct | station_config *config : ESP32 station configuration

Returns
  true : succeed
  false : fail

bool wifi_station_get_config_default | ( | struct station_config * | config | ) |

Get the configuration parameters saved in the Flash of the ESP32 WiFi station.

Parameters

  struct | station_config *config : ESP32 station configuration

Returns
  true : succeed
  false : fail

STATION_STATUS wifi_station_get_connect_status | ( | void |  | ) |

Get the connection status of the ESP32 WiFi station.

Parameters

  null |

Returns
  the status of connection

uint8 wifi_station_get_current_ap_id | ( | void |  | ) |

Get the information of APs (5 at most) recorded by ESP32 station.

Parameters

  struct | station_config config[] : information of the APs, the array size should be 5.

Returns
  The number of APs recorded.

bool wifi_station_get_reconnect_policy | ( | void |  | ) |

Check whether the ESP32 station will reconnect to the AP after disconnection.

Parameters

  null |

Returns
  true : succeed
  false : fail

sint8 wifi_station_get_rssi | ( | void |  | ) |

Get rssi of the AP which ESP32 station connected to.

Parameters

  null |

Returns
  31 : fail, invalid value.
  others : succeed, value of rssi. In general, rssi value < 10

bool wifi_station_scan | ( | struct scan_config * | config,
|  | scan_done_cb_t | cb
| ) |  |

Scan all available APs.

Attention
  This API should be called when the ESP32 station is enabled, and the system initialization is completed. Do not call this API in user_init.

Parameters

  struct | scan_config *config : configuration of scanning
  struct | scan_done_cb_t cb : callback of scanning

Returns
  true : succeed
  false : fail

bool wifi_station_set_auto_connect | ( | bool | set | ) |

Set whether the ESP32 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.
  2. This configuration will be saved in Flash system parameter area if changed.

Parameters

  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

Returns
  true : succeed
  false : fail

bool wifi_station_set_config | ( | struct station_config * | config | ) |

Set the configuration of the ESP32 station and save it to the Flash.

Attention
  1. This API can be called only when the ESP32 station is enabled.
  2. If wifi_station_set_config is called in user_init , there is no need to call wifi_station_connect. The ESP32 station will automatically connect to the AP (router) after the system initialization. Otherwise, wifi_station_connect should be called.
  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.
  4. This configuration will be saved in the Flash system parameter area if changed.

Parameters

  struct | station_config *config : ESP32 station configuration

Returns
  true : succeed
  false : fail

bool wifi_station_set_config_current | ( | struct station_config * | config | ) |

Set the configuration of the ESP32 station. And the configuration will not be saved to the Flash.

Attention
  1. This API can be called only when the ESP32 station is enabled.
  2. If wifi_station_set_config_current is called in user_init , there is no need to call wifi_station_connect. The ESP32 station will automatically connect to the AP (router) after the system initialization. Otherwise, wifi_station_connect should be called.
  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.

Parameters

  struct | station_config *config : ESP32 station configuration

Returns
  true : succeed
  false : fail

bool wifi_station_set_reconnect_policy | ( | bool | set | ) |

Set whether the ESP32 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.

Parameters

  bool | set : if it's true, it will enable reconnection; if it's false, it will disable reconnection.

Returns
  true : succeed
  false : fail