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

Macros
#define	HW_WIFI_SSID_MAX_LENGTH   32
	Maximum SSID length in bytes, excluding the NULL terminator.

Typedefs
typedef struct hw_wifi_t	hw_wifi_t
	Opaque Wi-Fi handle.
typedef void(*	hw_wifi_callback_t) (hw_wifi_t *wifi, hw_wifi_event_t event, const hw_wifi_network_t *network, void *userdata)
	Callback invoked for Wi-Fi operation notifications. 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 = (1 << 4), hw_wifi_event_notfound = (1 << 5), hw_wifi_event_error = (1 << 6), hw_wifi_event_status = (1 << 7) }
	Wi-Fi callback event flags. More...

Lifecycle
hw_wifi_t *	hw_wifi_init_client (const char *country_code, hw_wifi_callback_t callback, void *userdata)
	Initialize Wi-Fi as a client. More...
hw_wifi_t *	hw_wifi_init_accesspoint (const char *country_code, const char *ssid, const char *password, hw_wifi_auth_t auth)
	Initialize Wi-Fi as an access point. More...
hw_wifi_t *	hw_wifi_init_device (const char *device, hw_wifi_callback_t callback, void *userdata)
	Initialize Wi-Fi from a WPA supplicant device. More...
void	hw_wifi_deinit (hw_wifi_t *wifi)
	Deinitialize and release a Wi-Fi handle. More...

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

A handle operates in one of two mutually exclusive modes, chosen by which init function created it and fixed for that handle's lifetime - there's no way to switch an existing handle from one mode to the other, only to hw_wifi_deinit() it and init a new one in the other mode:

• Station mode (hw_wifi_init_client(), hw_wifi_init_device()): the device discovers and joins someone else's network. hw_wifi_scan(), hw_wifi_connect() and hw_wifi_disconnect() are asynchronous and call the provided callback function to update operation status.
• Access-point mode (hw_wifi_init_accesspoint()): the device broadcasts its own network for others to join. hw_wifi_scan(), hw_wifi_connect() and hw_wifi_disconnect() are unavailable in this mode - see their own documentation. There's no callback here at all: backends have no way to report individual stations joining or leaving (see hw_wifi_init_accesspoint()'s own doc), so there's nothing to notify. hw_wifi_deinit() stops broadcasting.

When connecting (station mode only), 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 (station mode only), 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.

Typedef Documentation

hw_wifi_callback_t

typedef void(* hw_wifi_callback_t) (hw_wifi_t *wifi, hw_wifi_event_t event, const hw_wifi_network_t *network, void *userdata)

Callback invoked for Wi-Fi operation notifications.

Parameters

wifi	The Wi-Fi handle associated with the operation.
event	The event type (see hw_wifi_event_t).
network	When event is hw_wifi_event_scan, this contains a pointer to the current scan result, or NULL to indicate the scan operation has completed.
userdata	User-defined data pointer supplied when the operation started.

This callback is used when connecting or disconnecting from a network, and when scanning for networks.

Definition at line 138 of file wifi.h.

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

Wi-Fi callback event flags.

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.
hw_wifi_event_status	Periodic status refresh while already connected (updated RSSI, channel, BSSID) - not a new connection; see hw_wifi_event_connected for the one-time "just joined" transition.

Definition at line 75 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_status = (1 << 7),       
} 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, from hw_wifi_init_client() or hw_wifi_init_device() - not hw_wifi_init_accesspoint(), see below.
network	Target network to connect to (SSID, BSSID, etc).
password	NUL-terminated password string. May be NULL or empty for open networks.

Return values

true	Connection attempt was started.
false	Handle or network is invalid, wifi is an access-point handle, or an operation (connection, disconnection or scanning) is already in progress.

Initiates a non-blocking connection attempt to the specified network using the provided password. The handle's callback is invoked to report connection progress and completion. This function returns immediately.

The bssid field of network can optionally be set to the BSSID of the target access point, if known.

A handle from hw_wifi_init_accesspoint() always fails here - an access point doesn't join other networks; other devices join it.

hw_wifi_deinit()

void hw_wifi_deinit

(

hw_wifi_t *

wifi

)

Deinitialize and release a Wi-Fi handle.

Parameters

wifi	Wi-Fi handle.

Safe to call on NULL. Requests that any in-progress connection, disconnection or scan stop first, but whether that request can actually interrupt an operation already under way is backend-dependent - some backends have no way to cancel a scan/connect once started (see hw_wifi_disconnect()'s own doc), in which case a callback for the old operation may still arrive after this call returns, referencing a handle that's already been released.

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, from hw_wifi_init_client() or hw_wifi_init_device() - not hw_wifi_init_accesspoint(), see below.

Return values

true	Disconnect was initiated.
false	Handle is invalid, is an access-point handle, or not currently connected, connecting or scanning.

Initiates a disconnect from the current network, or requests that an in-progress connection attempt or scan stop. This function returns immediately, but whether an in-progress operation can actually be interrupted is backend-dependent - some backends have no cancellation mechanism for a scan/connect already under way, in which case it runs to completion regardless and still delivers its own callback for whatever it was doing when this was called.

A handle from hw_wifi_init_accesspoint() always fails here - there is no "current network" for an access point to leave. Use hw_wifi_deinit() to stop broadcasting instead.

hw_wifi_init_accesspoint()

hw_wifi_t* hw_wifi_init_accesspoint	(	const char *	country_code,
		const char *	ssid,
		const char *	password,
		hw_wifi_auth_t	auth
	)

Initialize Wi-Fi as an access point.

Parameters

country_code	Country code for the Wi-Fi region (e.g. "US", "EU"). If NULL, defaults to "XX" (worldwide).
ssid	SSID to broadcast. Must not be NULL, and must not exceed HW_WIFI_SSID_MAX_LENGTH bytes.
password	NUL-terminated password string. May be NULL or empty only when auth is hw_wifi_auth_open.
auth	Authentication mode the access point requires. This selects exactly one mode, unlike hw_wifi_network_t's own auth field, which reports every mode a scanned network advertises support for.

Returns

Wi-Fi handle, or NULL when unsupported, ssid/auth are invalid, or another handle is already live (see hw_wifi_t).

Unlike hw_wifi_init_client()/hw_wifi_init_device(), this puts the radio into access-point mode - other devices connect to it, rather than it connecting to an existing network. Supported only where the backend's radio can run in AP mode (the CYW43 chip on Pico W/2W boards); NULL elsewhere.

There's no callback parameter: unlike station mode, backends have no way to report individual stations joining or leaving an access point (confirmed on Pico - the CYW43 driver's own low-level per-station association event handling for AP mode isn't wired up, and attempting to read the AP's aggregate link status from the polling loop was found to reliably deadlock the driver on real hardware). The access point itself stays up silently from here until hw_wifi_deinit().

hw_wifi_init_client()

hw_wifi_t* hw_wifi_init_client	(	const char *	country_code,
		hw_wifi_callback_t	callback,
		void *	userdata
	)

Initialize Wi-Fi as a client.

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 asynchronous operations (must not be NULL).
userdata	User-defined data pointer forwarded to callback.

Returns

Wi-Fi handle, or NULL when unsupported, on failure, or when another handle is already live (see hw_wifi_t).

hw_wifi_init_device()

hw_wifi_t* hw_wifi_init_device	(	const char *	device,
		hw_wifi_callback_t	callback,
		void *	userdata
	)

Initialize Wi-Fi from a WPA supplicant device.

Parameters

device	Device identifier for the Wi-Fi interface, e.g. /var/run/wpa_supplicant/wlan0.
callback	Callback to notify progress/completion of connection, disconnection and scanning asynchronous operations (must not be NULL).
userdata	User-defined data pointer forwarded to callback.

Returns

Wi-Fi handle, or NULL when unsupported, on failure, or when another handle is already live (see hw_wifi_t).

This entry point is intended for platforms where Wi-Fi is managed by a system service (wpa_supplicant) reachable over a control socket, rather than a radio directly driven by this process - on Linux, the standard way to manage Wi-Fi. Unsupported elsewhere.

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, from hw_wifi_init_client() or hw_wifi_init_device() - not hw_wifi_init_accesspoint(), see below.

Return values

true	Scan was started.
false	Handle is invalid, is an access-point handle, or an operation (connection, disconnection or scanning) is already in progress.

Starts a non-blocking scan. The handle's callback is invoked once per result (network != NULL) and once more with network == NULL when the scan completes. This function returns immediately.

A handle from hw_wifi_init_accesspoint() always fails here - scanning requires the radio to be in station mode.