WiFi Station (STA)

The WiFi station enables the ESP to scan for and connect to an exising WiFi access point.

API Reference

Header File

components/wifi/include/wifi_sta.hpp

Classes

class WifiSta : public espp::BaseComponent 

WiFi Station (STA)

see https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/wifi.html#esp32-wi-fi-station-general-scenario

WiFi Station Example

    espp::WifiSta wifi_sta({.ssid = CONFIG_ESP_WIFI_SSID,
                            .password = CONFIG_ESP_WIFI_PASSWORD,
                            .num_connect_retries = CONFIG_ESP_MAXIMUM_RETRY,
                            .on_connected = nullptr,
                            .on_disconnected = nullptr,
                            .on_got_ip =
                                [&](ip_event_got_ip_t *eventdata) {
                                  logger.info("got IP: {}.{}.{}.{}",
                                              IP2STR(&eventdata->ip_info.ip));
                                },
                            .log_level = espp::Logger::Verbosity::DEBUG});

    while (!wifi_sta.is_connected()) {
      std::this_thread::sleep_for(100ms);
    }

Note

If CONFIG_ESP32_WIFI_NVS_ENABLED is set to y (which is the default), then you must ensure that you call nvs_flash_init() prior to creating the WiFi Station.

Public Types

typedef std::function<void(void)> connect_callback: called when the WiFi station connects to an access point.

typedef std::function<void(void)> disconnect_callback: Called when the WiFi station is disconnected from the access point and has exceeded the configured Config::num_connect_retries.

typedef std::function<void(ip_event_got_ip_t *ip_evt)> ip_callback

Called whe nthe WiFi station has gotten an IP from the access point.

Param ip_evt:: Pointer to IP Event data structure (contains ip address).

Public Functions

inline explicit WifiSta(const Config &config)

Initialize the WiFi Station (STA)

Parameters:: config – WifiSta::Config structure with initialization information.

inline ~WifiSta(): Stop the WiFi station and deinit the wifi subystem.

inline bool is_connected() const

Whether the station is connected to an access point.

Returns:: true if it is currently connected, false otherwise.

inline std::string get_hostname()

Get the current hostname of the WiFi Station (STA).

Returns:: Current hostname of the station as a string.

inline bool set_hostname(const std::string &hostname, bool restart_dhcp = true)

Set the hostname for the WiFi Station (STA).

Note

The hostname is set for the station interface and will take effect after the DHCP client is stopped and restarted.

Parameters:

hostname – New hostname for the station.
restart_dhcp – Whether to restart the DHCP client to apply the new hostname.

Returns:

True if the operation was successful, false otherwise.

inline bool restart_dhcp_client()

Restart the DHCP client for the WiFi Station (STA).

Note

This is useful if you want to refresh the IP address, hostname, or apply new settings.

Returns:: True if the DHCP client was restarted successfully, false otherwise.

inline std::string get_mac()

Get the MAC address of the station.

Returns:: MAC address of the station.

inline std::string get_ip()

Get the IP address of the station.

Returns:: IP address of the station.

inline std::string get_ssid()

Get the SSID of the access point the station is connected to.

Returns:: SSID of the access point.

inline int32_t get_rssi()

Get the RSSI (Received Signal Strength Indicator) of the access point.

Returns:: RSSI of the access point.

inline uint8_t get_channel()

Get the channel of the access point the station is connected to.

Returns:: Channel of the access point.

inline std::string get_bssid()

Get the BSSID (MAC address) of the access point the station is connected to.

Returns:: BSSID of the access point.

inline void set_num_retries(size_t num_retries)

Set the number of retries to connect to the access point.

Parameters:: num_retries – Number of retries to connect to the access point.

inline void set_connect_callback(connect_callback callback)

Set the callback to be called when the station connects to the access point.

Parameters:: callback – Callback to be called when the station connects to the access point.

inline void set_disconnect_callback(disconnect_callback callback)

Set the callback to be called when the station disconnects from the access point.

Parameters:: callback – Callback to be called when the station disconnects from the access point.

inline void set_ip_callback(ip_callback callback)

Set the callback to be called when the station gets an IP address.

Parameters:: callback – Callback to be called when the station gets an IP address.

inline esp_netif_t *get_netif() const

Get the netif associated with this WiFi station.

Returns:: Pointer to the esp_netif_t associated with this WiFi station.

inline bool get_saved_config(wifi_config_t &wifi_config)

Get the saved WiFi configuration.

Parameters:: wifi_config – Reference to a wifi_config_t structure to store the configuration.
Returns:: true if the configuration was retrieved successfully, false otherwise.

inline bool connect()

Connect to the access point with the saved SSID and password.

Returns:: true if the connection was initiated successfully, false otherwise.

inline bool connect(std::string_view ssid, std::string_view password)

Connect to the access point with the given SSID and password.

Parameters:

ssid – SSID of the access point.
password – Password of the access point. If empty, the AP will be open / have no security.

Returns:

true if the connection was initiated successfully, false otherwise.

inline bool disconnect()

Disconnect from the access point.

Returns:: true if the disconnection was initiated successfully, false otherwise.

inline int scan(wifi_ap_record_t *ap_records, size_t max_records)

Scan for available access points.

Note

This is a blocking call that will wait for the scan to complete.

Parameters:

ap_records – Pointer to an array of wifi_ap_record_t to store the results.
max_records – Maximum number of access points to scan for.

Returns:

Number of access points found, or negative error code on failure.

inline const std::string &get_name() const

Get the name of the component

Note

This is the tag of the logger

Returns:: A const reference to the name of the component

inline void set_log_tag(const std::string_view &tag)

Set the tag for the logger

Parameters:: tag – The tag to use for the logger

inline espp::Logger::Verbosity get_log_level() const

Get the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Returns:: The verbosity level of the logger

inline void set_log_level(espp::Logger::Verbosity level)

Set the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Parameters:: level – The verbosity level to use for the logger

inline void set_log_verbosity(espp::Logger::Verbosity level)

Set the log verbosity for the logger

See also

set_log_level

See also

Logger::Verbosity

See also

Logger::set_verbosity

Note

This is a convenience method that calls set_log_level

Parameters:: level – The verbosity level to use for the logger

inline espp::Logger::Verbosity get_log_verbosity() const

Get the log verbosity for the logger

See also

get_log_level

See also

Logger::Verbosity

See also

Logger::get_verbosity

Note

This is a convenience method that calls get_log_level

Returns:: The verbosity level of the logger

inline void set_log_rate_limit(std::chrono::duration<float> rate_limit)

Set the rate limit for the logger

See also

Logger::set_rate_limit

Note

Only calls to the logger that have _rate_limit suffix will be rate limited

Parameters:: rate_limit – The rate limit to use for the logger

struct Config

Configuration structure for the WiFi Station.

Public Members

std::string ssid: SSID for the access point.

std::string password: Password for the access point. If empty, the AP will be open / have no security.

wifi_phy_rate_t phy_rate{WIFI_PHY_RATE_MCS0_LGI}

PHY rate to use for the station. Default is MCS0_LGI (6.5

13.5 Mbps Long Guard Interval).

size_t num_connect_retries{0}: Number of times to retry connecting to the AP before stopping. After this many retries, on_disconnected will be called.

connect_callback on_connected{nullptr}: Called when the station connects, or fails to connect.

disconnect_callback on_disconnected = {nullptr}: Called when the station disconnects.

ip_callback on_got_ip = {nullptr}: Called when the station gets an IP address.

uint8_t channel = {0}: Channel of target AP; set to 0 for unknown.

bool set_ap_mac = {false}: Whether to check MAC address of the AP (generally no). If yes, provide ap_mac.

uint8_t ap_mac[6] = {0}: MAC address of the AP to check if set_ap_mac is set to true.

Logger::Verbosity log_level = {Logger::Verbosity::WARN}: Verbosity of WifiSta logger.

Header File

components/wifi/include/wifi_sta_menu.hpp

Classes

class WifiStaMenu

A CLI menu for interacting with a WiFi station (STA) mode.

This class provides a CLI menu for interacting with a WiFi station. It provides options for setting the log verbosity, connecting to a WiFi network, disconnecting from a WiFi network, getting the current RSSI (Received Signal Strength Indicator), getting the current IP address, checking if the WiFi is connected, getting the current MAC address, and getting the current WiFi configuration.

Example

    espp::WifiSta wifi_sta({.ssid = "",     // CONFIG_ESP_WIFI_SSID,
                            .password = "", // CONFIG_ESP_WIFI_PASSWORD,
                            .num_connect_retries = CONFIG_ESP_MAXIMUM_RETRY,
                            .on_connected = nullptr,
                            .on_disconnected = nullptr,
                            .on_got_ip =
                                [&](ip_event_got_ip_t *eventdata) {
                                  logger.info("got IP: {}.{}.{}.{}",
                                              IP2STR(&eventdata->ip_info.ip));
                                },
                            .log_level = espp::Logger::Verbosity::DEBUG});
    auto sta_menu = espp::WifiStaMenu(wifi_sta);
    cli::Cli cli(sta_menu.get());
    cli::SetColor();
    cli.ExitAction([](auto &out) { out << "Goodbye and thanks for all the fish.\n"; });

    espp::Cli input(cli);
    input.SetInputHistorySize(10);
    input.Start();

Public Functions

inline explicit WifiStaMenu(std::reference_wrapper<espp::WifiSta> wifi_sta)

Construct a new WifiStaMenu object.

Parameters:: wifi_sta – A reference to the WifiSta object to interact with.

inline std::unique_ptr<cli::Menu> get(std::string_view name = "sta", std::string_view description = "WiFi STA menu")

Get the CLI menu for the WiFi station.

Parameters:

name – The name of the menu.
description – The description of the menu.

Returns:

A unique pointer to the WiFi STA menu that you can use to add to a CLI.