WiFi

Wi-Fi network management interface. More...

Collaboration diagram for WiFi:

Data Structures
struct	hw_wifi_network_t
	Describes a discovered Wi‑Fi network (scan result). More...

Enumerations
enum	hw_wifi_auth_t {   hw_wifi_auth_open = (1 << 0), hw_wifi_auth_wep = (1 << 1), hw_wifi_auth_wpa_tkip = (1 << 2), hw_wifi_auth_wpa_aes = (1 << 3),   hw_wifi_auth_wpa2_tkip = (1 << 4), hw_wifi_auth_wpa2_aes = (1 << 5), hw_wifi_auth_wpa3_sae = (1 << 6), hw_wifi_auth_enterprise = (1 << 7) }
	Authentication and cipher modes for Wi‑Fi networks. More...
enum	hw_wifi_event_t {   hw_wifi_event_scan = (1 << 0), hw_wifi_event_joining = (1 << 1), hw_wifi_event_connected = (1 << 2), hw_wifi_event_disconnected = (1 << 3),   hw_wifi_event_badauth, hw_wifi_event_notfound = (1 << 5), hw_wifi_event_error = (1 << 6) }
	Callback events. More...

Functions
hw_wifi_t *	hw_wifi_init (const char *country_code, hw_wifi_callback_t callback, void *user_data)
	Initialize Wi-Fi management. More...
bool	hw_wifi_valid (hw_wifi_t *wifi)
	Determine if the Wi-Fi handle is initialized and usable. More...
void	hw_wifi_finalize (hw_wifi_t *wifi)
	Finalize and release any resources. More...
bool	hw_wifi_scan (hw_wifi_t *wifi)
	Begin an asynchronous scan for nearby Wi‑Fi networks. More...
bool	hw_wifi_connect (hw_wifi_t *wifi, const hw_wifi_network_t *network, const char *password)
	Begin an asynchronous connection to a Wi‑Fi network. More...
bool	hw_wifi_disconnect (hw_wifi_t *wifi)
	Disconnect from a previously-connected Wi‑Fi network. More...

Detailed Description

Wi-Fi network management interface.

The Wi-Fi management interface provides discovery of, and connection to networks with authentication. The three main methods for connecting, disconnecting and scanning are asynchronous and call the provided callback function to update operation status.

When connecting, the callback will be invoked with the current status of the connection attempt, including any relevant network information. The callback will then be called occasionally with updates on the connection status (for example, the signal strength).

When scanning, the callback will be invoked with the results of the scan, including information about any discovered networks. The scan is completed when the callback is invoked with a NULL network pointer.

Enumeration Type Documentation

hw_wifi_auth_t

enum hw_wifi_auth_t

Authentication and cipher modes for Wi‑Fi networks.

Bitmask describing the advertised/required authentication/cipher modes. Multiple bits may be set if a network supports more than one.

Enumerator
hw_wifi_auth_open	Open (no authentication)
hw_wifi_auth_wep	WEP (legacy)
hw_wifi_auth_wpa_tkip	WPA‑PSK TKIP.
hw_wifi_auth_wpa_aes	WPA‑PSK CCMP/AES.
hw_wifi_auth_wpa2_tkip	WPA2‑PSK TKIP.
hw_wifi_auth_wpa2_aes	WPA2‑PSK CCMP/AES.
hw_wifi_auth_wpa3_sae	WPA3‑SAE.
hw_wifi_auth_enterprise	802.1X Enterprise (EAP)

Definition at line 45 of file wifi.h.

             {
  hw_wifi_auth_open = (1 << 0),      
  hw_wifi_auth_wep = (1 << 1),       
  hw_wifi_auth_wpa_tkip = (1 << 2),  
  hw_wifi_auth_wpa_aes = (1 << 3),   
  hw_wifi_auth_wpa2_tkip = (1 << 4), 
  hw_wifi_auth_wpa2_aes = (1 << 5),  
  hw_wifi_auth_wpa3_sae = (1 << 6),  
  hw_wifi_auth_enterprise = (1 << 7) 
} hw_wifi_auth_t;

hw_wifi_event_t

enum hw_wifi_event_t

Callback events.

Enumerator
hw_wifi_event_scan	Scan result available.
hw_wifi_event_joining	Joining a network.
hw_wifi_event_connected	Successfully connected.
hw_wifi_event_disconnected	Disconnected.
hw_wifi_event_badauth	Bad authentication during connection attempt.
hw_wifi_event_notfound	Network not found.
hw_wifi_event_error	Other error occurred.

Definition at line 60 of file wifi.h.

             {
  hw_wifi_event_scan = (1 << 0),         
  hw_wifi_event_joining = (1 << 1),      
  hw_wifi_event_connected = (1 << 2),    
  hw_wifi_event_disconnected = (1 << 3), 
  hw_wifi_event_badauth =
      (1 << 4), 
  hw_wifi_event_notfound = (1 << 5), 
  hw_wifi_event_error = (1 << 6)     
} hw_wifi_event_t;

Function Documentation

hw_wifi_connect()

bool hw_wifi_connect	(	hw_wifi_t *	wifi,
		const hw_wifi_network_t *	network,
		const char *	password
	)

Begin an asynchronous connection to a Wi‑Fi network.

Parameters

wifi	Initialized Wi‑Fi handle.
network	Target network to connect to (SSID, BSSID, etc).
password	NUL‑terminated password string (may be empty for open networks).

Returns

true if the connection attempt was started, false otherwise.

Initiates a non‑blocking connection attempt to the specified network using the provided password. The callback will be invoked to report connection progress and completion. The function returns immediately.

The ssid and auth parameters must be filled in by the caller, and the bssid parameter can optionally be set to the BSSID of the target access point (if known).

The password must be a NUL‑terminated string (may be empty or NULL for open networks).

Only one connection attempt may be active at a time per Wi‑Fi handle, and false will be returned if a connection attempt or scanning is already in progress.

Examples:

examples/runtime/ntp/main.c, and examples/runtime/wificonnect/main.c.

hw_wifi_disconnect()

bool hw_wifi_disconnect

(

hw_wifi_t *

wifi

)

Disconnect from a previously-connected Wi‑Fi network.

Parameters

wifi	Initialized Wi‑Fi handle.

Returns

true if a disconnect was initiated, false if not connected.

Initiates a disconnect from the current network. The function returns immediately. If not currently connected, this is a no‑op, and if a connection attempt or scan is in progress, it will be aborted and false will be returned.

Examples:

examples/runtime/ntp/main.c, and examples/runtime/wificonnect/main.c.

hw_wifi_finalize()

void hw_wifi_finalize

(

hw_wifi_t *

wifi

)

Finalize and release any resources.

Parameters

wifi	Wi-Fi handle

Safe to call on an already finalized; in that case it is a no‑op. After finalization, hw_wifi_valid() returns false.

Examples:

examples/runtime/ntp/main.c, examples/runtime/wificonnect/main.c, and examples/runtime/wifiscan/main.c.

hw_wifi_init()

hw_wifi_t* hw_wifi_init	(	const char *	country_code,
		hw_wifi_callback_t	callback,
		void *	user_data
	)

Initialize Wi-Fi management.

Parameters

country_code	Country code for the Wi-Fi region (e.g., "US", "EU"). If NULL, defaults to "XX" (worldwide).
callback	Callback to notify progress/completion of connection, disconnection and scanning asyncronous operations (must not be NULL).
user_data	Opaque user pointer supplied to the callback.

Returns

Wi-Fi handle or NULL on failure.

This function initializes the Wi-Fi management subsystem and returns a handle to the Wi-Fi instance. If initialization fails (for example, if WiFi is not available), it returns NULL.

Examples:

examples/runtime/ntp/main.c, examples/runtime/wificonnect/main.c, and examples/runtime/wifiscan/main.c.

hw_wifi_scan()

bool hw_wifi_scan

(

hw_wifi_t *

wifi

)

Begin an asynchronous scan for nearby Wi‑Fi networks.

Parameters

wifi	Initialized Wi‑Fi handle.

Returns

true if the scan was started, false otherwise.

Starts a non‑blocking scan. The provided callback will be invoked for each result (network != NULL) and once more with network == NULL when the scan completes. The function returns immediately.

If a operation (connection, disconnection or scanning) is already in progress or Wi‑Fi is disconnected, the function returns false and no callback will be invoked.

Examples:

examples/runtime/wifiscan/main.c.

hw_wifi_valid()

bool hw_wifi_valid

(

hw_wifi_t *

wifi

)

Determine if the Wi-Fi handle is initialized and usable.

Parameters

wifi	Wi-Fi handle

Returns

True if initialized and not finalized; false otherwise.

Examples:

examples/runtime/ntp/main.c, examples/runtime/wificonnect/main.c, and examples/runtime/wifiscan/main.c.