WiFi Station

group wifi_sta

Control and monitoring of WiFi station interface.

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.

See

WiFi Access Point

See

WiFi Events Interface

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.

Parameters

• event –

• info –

Returns

bool – return true to perform default configuration

using WPSConfigDelegate = Delegate<bool(WpsStatus status)>

WPS configuration callback function.

Parameters

status –

Returns

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

Returns

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.

Returns

bool – True if connected.

bool isConnectionFailed() const

Get WiFi station connection failure status.

Returns

bool – True if connection failed

virtual StationConnectionStatus getConnectionStatus() const = 0

Get WiFi station connection status.

Returns

StationConnectionStatus – Connection status structure

String getConnectionStatusName() const

Get WiFi station connection status name.

Returns

String – String representing connection status

virtual bool isEnabledDHCP() const = 0

Get WiFi station DHCP enabled status.

Returns

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.

Returns

WiFi – station DHCP hostname

virtual IpAddress getIP() const = 0

Get WiFi station IP address.

Returns

IpAddress – IP address of WiFi station

virtual MacAddress getMacAddress() const = 0

Get WiFi station MAC address.

Returns

MacAddress –

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

Get WiFi station MAC address.

Parameters

sep – Optional separator between bytes (e.g. ‘:’)

Returns

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

Returns

bool – true on success

virtual IpAddress getNetworkMask() const = 0

Get WiFi station network mask.

Returns

IpAddress – WiFi station network mask

virtual IpAddress getNetworkGateway() const = 0

Get WiFi station default gateway.

Returns

IpAddress – WiFi station default gateway

virtual IpAddress getNetworkBroadcast() const = 0

GetWiFi station broadcast address.

Returns

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 –

Returns

bool – true if address is local

bool setIP(IpAddress address)

Set WiFi station IP address.

Parameters

address – IP address

Returns

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

Returns

bool – True on success

virtual String getSSID() const = 0

Get WiFi station SSID (Service Set Identifier)

Returns

String – WiFi station SSID

virtual MacAddress getBSSID() const = 0

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

Returns

MacAddress – Identifier of connected Access Point

virtual String getPassword() const = 0

Get WiFi station password.

Returns

String – WiFi station password

virtual int8_t getRssi() const = 0

Get WiFi signal strength.

Returns

int8_t – Value in dBm

virtual uint8_t getChannel() const = 0

Get active WiFi channel.

Returns

uint8_t – channel number

virtual bool startScan(ScanCompletedDelegate scanCompleted) = 0

Start WiFi station network scan.

Parameters

scanCompleted – Function to call when scan completes

Returns

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.