WiFi Station

group wifi_sta

Control and monitoring of WiFi station interface.

See also

Note

The WiFi station interface provides client access to a WiFi network. Control of WiFi connection including WiFi SSID and password and IP address, DHCP, etc.

Defines

WPS_STATUS_MAP(XX)

XX(name)

XX(name)

Typedefs

using ScanCompletedDelegate = Delegate<void(bool success, BssList &list)>: Scan complete handler function.

using SmartConfigDelegate = Delegate<bool(SmartConfigEvent event, const SmartConfigEventInfo &info)>

Smart configuration handler function.

Param event:
Param info:
Retval bool:: return true to perform default configuration

using WPSConfigDelegate = Delegate<bool(WpsStatus status)>

WPS configuration callback function.

Param status:
Retval bool:: return true to perform default configuration

Enums

enum StationConnectionStatus

WiFi station connection states.

Values:

enumerator eSCS_Idle: Connection idle.

enumerator eSCS_Connecting: Connecting.

enumerator eSCS_WrongPassword: Wrong password.

enumerator eSCS_AccessPointNotFound: AP not found.

enumerator eSCS_ConnectionFailed: Connection failed.

enumerator eSCS_GotIP: Got IP address.

enum SmartConfigType

Smart configuration type.

Values:

enumerator SCT_None

enumerator SCT_EspTouch: ESP Touch.

enumerator SCT_AirKiss: Air Kiss.

enumerator SCT_EspTouch_AirKiss: ESP Touch and Air Kiss.

enumerator SCT_EspTouch_V2: ESP Touch version 2.

enum SmartConfigEvent

Smart configuration event.

Values:

enumerator SCE_Wait: Wait.

enumerator SCE_FindChannel: Find channel.

enumerator SCE_GettingSsid: Getting SSID & password.

enumerator SCE_Link: Link established.

enumerator SCE_LinkOver: Link-over.

enum class WpsStatus

WiFi WPS callback status.

Values:

enumerator XX

Functions

String toString(WpsStatus status)

Variables

StationClass &WifiStation

Global instance of WiFi station object.

Note

Use WifiStation.function to access WiFi station functions

Note

Example:

if(WifiStation.config("My_WiFi", "My_Password"))
           WifiStation.enable(true);

struct SmartConfigEventInfo

#include <Station.h>

Smart Config callback information.

Public Members

SmartConfigType type = SCT_None : Type of configuration underway.

String ssid: AP SSID.

String password: AP Password.

bool bssidSet = false: true if connection should match both SSID and BSSID

MacAddress bssid: AP BSSID.

class StationClass

#include <Station.h>

WiFi station class.

Public Functions

virtual void enable(bool enabled, bool save = false) = 0

Enable / disable WiFi station.

Note

Disabling WiFi station will also disable and clear the handler set with waitConnection.

Parameters:

enabled – True to enable station. False to disable.
save – True to save operational mode to flash, False to set current operational mode only

virtual bool isEnabled() const = 0

Get WiFi station enable status.

Return values:: bool – True if WiFi station enabled

virtual bool config(const Config &config) = 0

Configure WiFi station.

Parameters:

ssid – WiFi SSID
password – WiFi password
autoConnectOnStartup – True to auto connect. False for manual. (Default: True)
save – True to save the SSID and password in Flash. False otherwise. (Default: True)

inline bool config(const String &ssid, const String &password, bool autoConnectOnStartup = true, bool save = true)

Configure WiFi station.

Parameters:

ssid – WiFi SSID
password – WiFi password
autoConnectOnStartup – True to auto connect. False for manual. (Default: True)
save – True to save the SSID and password in Flash. False otherwise. (Default: True)

virtual bool connect() = 0: Connect WiFi station to network.

virtual bool disconnect() = 0: Disconnect WiFi station from network.

bool isConnected() const

Get WiFi station connectoin status.

Return values:: bool – True if connected.

bool isConnectionFailed() const

Get WiFi station connection failure status.

Return values:: bool – True if connection failed

virtual StationConnectionStatus getConnectionStatus() const = 0

Get WiFi station connection status.

Return values:: StationConnectionStatus – Connection status structure

String getConnectionStatusName() const

Get WiFi station connection status name.

Return values:: String – String representing connection status

virtual bool isEnabledDHCP() const = 0

Get WiFi station DHCP enabled status.

Return values:: bool – True if DHCP enabled

virtual void enableDHCP(bool enable) = 0

Enable or disable WiFi station DHCP.

Parameters:: enable – True to enable WiFi station DHCP

virtual void setHostname(const String &hostname) = 0

Set WiFi station DHCP hostname.

Parameters:: hostname – - WiFi station DHCP hostname

virtual String getHostname() const = 0

Set WiFi station DHCP hostname.

Return values:: WiFi – station DHCP hostname

virtual IpAddress getIP() const = 0

Get WiFi station IP address.

Return values:: IpAddress – IP address of WiFi station

virtual MacAddress getMacAddress() const = 0

Get WiFi station MAC address.

Return values:: MacAddress –

String getMAC(char sep = '\0') const

Get WiFi station MAC address.

Parameters:: sep – Optional separator between bytes (e.g. ‘:’)
Return values:: String – WiFi station MAC address

virtual bool setMacAddress(const MacAddress &addr) const = 0

Set WiFi station MAC address.

Must be called from init() before activating station. Espressif place certain limitations on MAC addresses:

Bit 0 of the first byte of the MAC address can not be 1. For example:

OK: “1a:XX:XX:XX:XX:XX” NOT OK: “15:XX:XX:XX:XX:XX”

Parameters:: addr – The new MAC address
Return values:: bool – true on success

virtual IpAddress getNetworkMask() const = 0

Get WiFi station network mask.

Return values:: IpAddress – WiFi station network mask

virtual IpAddress getNetworkGateway() const = 0

Get WiFi station default gateway.

Return values:: IpAddress – WiFi station default gateway

virtual IpAddress getNetworkBroadcast() const = 0

GetWiFi station broadcast address.

Return values:: IpAddress – WiFi station broadcast address

inline bool isLocal(IpAddress address)

Determine if the given address is on the same subnet.

Note

Use to prevent external access to services

Parameters:: address –
Return values:: bool – true if address is local

bool setIP(IpAddress address)

Set WiFi station IP address.

Parameters:: address – IP address
Return values:: bool – True on success

virtual bool setIP(IpAddress address, IpAddress netmask, IpAddress gateway) = 0

Set WiFi station IP parameters.

Parameters:

address – IP address
netmask – Network mask
gateway – Default gateway

Return values:

bool – True on success

virtual String getSSID() const = 0

Get WiFi station SSID (Service Set Identifier)

Return values:: String – WiFi station SSID

virtual MacAddress getBSSID() const = 0

Get BSSID (Basic Service Set Identifier) for connected AP.

Return values:: MacAddress – Identifier of connected Access Point

virtual String getPassword() const = 0

Get WiFi station password.

Return values:: String – WiFi station password

virtual int8_t getRssi() const = 0

Get WiFi signal strength.

Return values:: int8_t – Value in dBm

virtual uint8_t getChannel() const = 0

Get active WiFi channel.

Return values:: uint8_t – channel number

virtual bool startScan(ScanCompletedDelegate scanCompleted) = 0

Start WiFi station network scan.

Parameters:: scanCompleted – Function to call when scan completes
Return values:: bool – True on success

struct Config

#include <Station.h>

Station configuration passed to config method.

Public Members

String ssid: Service Set to connect to (may be advertised by multiple access points)

String password: Password (if required)

MacAddress bssid: Set this to connect to a specific access point.

bool autoConnectOnStartup = true: Auto connect to this AP on system restart.

bool save = true: Store new settings in NV memory.