ra8_wifi.h File Reference

A small, uniform Wi-Fi facade: init, connect, get an IP, disconnect. More...

#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for ra8_wifi.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ra8_wifi_mac
	One IEEE 802 address, by value. More...
struct	ra8_wifi_lease
	The IPv4 configuration an ra8_wifi_ip_bind_fn obtained. More...
struct	ra8_wifi_ap
	What the backend knows about the AP the station is on. More...
struct	ra8_wifi_status
	A single snapshot of where a handle is, without touching the wire. More...
struct	ra8_wifi_cfg
	Everything ra8_wifi_init needs that the facade cannot discover. More...
struct	ra8_wifi
	Caller-allocated Wi-Fi handle. More...

Typedefs
typedef struct ra8_wifi_mac	ra8_wifi_mac_t
typedef struct ra8_wifi_lease	ra8_wifi_lease_t
typedef struct ra8_wifi_ap	ra8_wifi_ap_t
typedef struct ra8_wifi_status	ra8_wifi_status_t
typedef ra8_err_t(*	ra8_wifi_ip_bind_fn) (void *ip_ctx, const ra8_wifi_mac_t *mac, ra8_wifi_lease_t *out)
	Caller-supplied hook that turns an associated station into a lease.
typedef struct ra8_wifi_backend	ra8_wifi_backend_t
	One radio's implementation of the operations this facade dispatches.
typedef struct ra8_wifi_cfg	ra8_wifi_cfg_t
typedef struct ra8_wifi	ra8_wifi_t

Enumerations
enum	ra8_wifi_limits_t : uint8_t {   k_ra8_wifi_mac_bytes = 6U ,   k_ra8_wifi_ssid_max = 32U }
	Fixed field capacities this facade works to. More...
enum	ra8_wifi_budget_t : uint16_t {   k_ra8_wifi_join_polls = 200U ,   k_ra8_wifi_poll_gap_ms = 50U }
	Bounds that turn "never associated" into a returned timeout. More...
enum	ra8_wifi_state_t : uint8_t {   k_ra8_wifi_state_down = 0U ,   k_ra8_wifi_state_associating = 1U ,   k_ra8_wifi_state_associated = 2U ,   k_ra8_wifi_state_ip_bound = 3U }
	Where a handle is on the path from powered-off to holding an IP. More...
enum	ra8_wifi_link_t : uint8_t {   k_ra8_wifi_link_down = 0U ,   k_ra8_wifi_link_up = 1U }
	The instantaneous association state a backend reports. More...

Functions
ra8_err_t	ra8_wifi_init (ra8_wifi_t *wifi, const ra8_wifi_cfg_t *cfg)
	Bring the radio and its link up and make a handle usable.
ra8_err_t	ra8_wifi_deinit (ra8_wifi_t *wifi)
	Release a handle and power its radio down.
ra8_err_t	ra8_wifi_connect (ra8_wifi_t *wifi, const char *ssid, const char *psk)
	Join a network by SSID and passphrase, blocking until associated.
ra8_err_t	ra8_wifi_disconnect (ra8_wifi_t *wifi)
	Disassociate the station and power the radio down.
ra8_err_t	ra8_wifi_wait_ip (ra8_wifi_t *wifi, ra8_wifi_lease_t *out)
	Obtain an IP address for the associated station, blocking until bound.
ra8_err_t	ra8_wifi_get_ip (const ra8_wifi_t *wifi, ra8_wifi_lease_t *out)
	Read the cached DHCP lease without touching the wire.
ra8_err_t	ra8_wifi_status (const ra8_wifi_t *wifi, ra8_wifi_status_t *out)
	Read a handle's cached status without touching the wire.
ra8_err_t	ra8_wifi_poll (ra8_wifi_t *wifi, ra8_wifi_link_t *out)
	Service the link once and refresh the cached association state.
ra8_err_t	ra8_wifi_get_mac (ra8_wifi_t *wifi, ra8_wifi_mac_t *out)
	Read the station's own MAC address.
ra8_err_t	ra8_wifi_get_ap (ra8_wifi_t *wifi, ra8_wifi_ap_t *out)
	Read what the backend knows about the associated AP.

Detailed Description

A small, uniform Wi-Fi facade: init, connect, get an IP, disconnect.

Tag

[Ring 4 / PAL] {World: NS}

The one place an application does Wi-Fi. Above this header there is no esp-hosted RPC, no protobuf, no TLV envelope, no SPI transaction pump, no interface index and no wifi_mode_t: there is a handle you initialise, a network you connect to by SSID and passphrase, and a leased IP you wait for. Everything specific to the radio that provides those operations lives behind ra8_wifi_backend_t, a function-pointer seam this facade dispatches through and never looks past.

Why a vtable and not a direct call into ra8_c6link

The same Dependency-Inversion pattern ra8_display_pal uses for panels and ra8_io uses for buses. The facade is a state machine over a backend it does not name: ra8_c6link is the first backend (k_ra8_wifi_backend_c6link in ra8_wifi_c6link.h), a second radio would be a second backend, and a host unit test drives the whole facade against a mock backend with no hardware at all. That is why this translation unit includes nothing from ra8_c6link.

The journey, in the order a caller makes it

ra8_wifi_init(&wifi, &cfg);            // radio + link up, ready to associate
ra8_wifi_connect(&wifi, ssid, psk);    // blocks until the station is joined
ra8_wifi_lease_t lease = {};
ra8_wifi_wait_ip(&wifi, &lease);       // DHCP -- lease.ip is the address
...                                    // use the socket API from here
ra8_wifi_disconnect(&wifi);            // leave and power the radio down
ra8_wifi_deinit(&wifi);

Where the IP comes from

Obtaining a lease is the IP stack's job, not the radio's, so it is not a backend operation. The caller supplies an ra8_wifi_ip_bind_fn in the configuration and ra8_wifi_wait_ip runs it once the station is associated. That keeps this facade free of any NetX Duo or ThreadX dependency and fully host-testable, while still letting the simple path reach a bound address. A ready-made provider ships alongside the backend when a stack is available.

Threading

A handle is single-threaded, like the link beneath it. Drive it from one bring-up context. Once ra8_wifi_wait_ip has bound an address the IP stack owns the wire; do not call ra8_wifi_poll after that point.

See also

ra8_wifi_c6link.h The ESP32-C6 backend that fills the seam

ra8_wifi_backend.h The seam a backend implements

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since

0.1.0

Definition in file ra8_wifi.h.

Typedef Documentation

ra8_wifi_ap_t

typedef struct ra8_wifi_ap ra8_wifi_ap_t

ra8_wifi_backend_t

typedef struct ra8_wifi_backend ra8_wifi_backend_t

One radio's implementation of the operations this facade dispatches.

Opaque here on purpose: an application selects a backend by taking the address of one a driver exports (for example k_ra8_wifi_backend_c6link) and never constructs or inspects the table. The full layout, for backend authors and tests, is in ra8_wifi_backend.h.

See also

ra8_wifi_backend.h

ra8_wifi_c6link.h

Since

0.1.0

Definition at line 342 of file ra8_wifi.h.

ra8_wifi_cfg_t

typedef struct ra8_wifi_cfg ra8_wifi_cfg_t

ra8_wifi_ip_bind_fn

typedef ra8_err_t(* ra8_wifi_ip_bind_fn) (void *ip_ctx, const ra8_wifi_mac_t *mac, ra8_wifi_lease_t *out)

Caller-supplied hook that turns an associated station into a lease.

The seam between this radio facade and whatever IP stack the application runs. ra8_wifi_wait_ip invokes it once the station is associated, hands it the station's MAC, and caches the lease it returns. Keeping it a caller hook is what lets this facade stay free of any particular stack.

Parameters

[in]	ip_ctx	Opaque context from ra8_wifi_cfg::ip_ctx.
[in]	mac	Station MAC the stack must adopt as its own; never null.
[out]	out	Lease to fill; never null. Leave bound false on failure.

Returns

ra8_err_t k_ra8_ok when out holds a usable lease, otherwise an error the provider chooses.

Note

Runs on the caller's thread inside ra8_wifi_wait_ip. It may block for as long as obtaining a lease takes.

Since

0.1.0

Definition at line 324 of file ra8_wifi.h.

ra8_wifi_lease_t

typedef struct ra8_wifi_lease ra8_wifi_lease_t

ra8_wifi_mac_t

typedef struct ra8_wifi_mac ra8_wifi_mac_t

ra8_wifi_status_t

typedef struct ra8_wifi_status ra8_wifi_status_t

ra8_wifi_t

typedef struct ra8_wifi ra8_wifi_t

Enumeration Type Documentation

ra8_wifi_budget_t

enum ra8_wifi_budget_t : uint16_t

Bounds that turn "never associated" into a returned timeout.

ra8_wifi_connect drives association by asking the backend to service the link a bounded number of times. The count exists to give that loop a statically provable bound (NASA Power of 10 Rule 2), and the gap is what turns that count into wall time: a service call costs whatever the radio takes to answer, which on a link that is answering promptly is tens of milliseconds, so a budget of attempts alone would be spent in a couple of seconds – less than an 802.11 association needs. The pair is the figure the bench proved: two hundred attempts, fifty milliseconds apart.

Invariant

k_ra8_wifi_join_polls is non-zero, so at least one association attempt is always made.

k_ra8_wifi_poll_gap_ms is non-zero, so the wait cannot busy-spin.

Example:

for (uint16_t i = 0U; i < (uint16_t)k_ra8_wifi_join_polls; i++) { ... }

See also

ra8_wifi_connect

Since

0.1.0

Enumerator
k_ra8_wifi_join_polls	Times ra8_wifi_connect services the link while waiting for the join to complete.
k_ra8_wifi_poll_gap_ms	Milliseconds the facade idles between two association attempts.

Definition at line 121 of file ra8_wifi.h.

ra8_wifi_limits_t

enum ra8_wifi_limits_t : uint8_t

Fixed field capacities this facade works to.

Both come from IEEE 802.11 and match the co-processor's own limits, so a value that fits here fits on the wire. They are restated rather than pulled from a backend header so that a consumer of this facade needs no backend include path.

Invariant

k_ra8_wifi_ssid_max is the longest SSID 802.11 allows.

k_ra8_wifi_mac_bytes is the octet count of an IEEE 802 address.

Example:

static_assert(k_ra8_wifi_ssid_max == 32U, "802.11 SSID bound");

See also

ra8_wifi_ap_t

Since

0.1.0

Enumerator
k_ra8_wifi_mac_bytes	Octets in an IEEE 802 address.
k_ra8_wifi_ssid_max	Octets in the longest 802.11 SSID.

Definition at line 90 of file ra8_wifi.h.

ra8_wifi_link_t

enum ra8_wifi_link_t : uint8_t

The instantaneous association state a backend reports.

Narrower than ra8_wifi_state_t: a backend knows only whether the station is currently associated, and the facade folds that into the lifecycle. Returned by ra8_wifi_poll and used internally by ra8_wifi_connect.

Invariant

k_ra8_wifi_link_up means the station is associated right now, not that it once was.

A backend never reports a value outside this enum.

Example:

ra8_wifi_link_t link = k_ra8_wifi_link_down;
(void)ra8_wifi_poll(&wifi, &link);

See also

ra8_wifi_poll

Since

0.1.0

Enumerator
k_ra8_wifi_link_down	Station is not associated.
k_ra8_wifi_link_up	Station is associated with an AP.

Definition at line 182 of file ra8_wifi.h.

ra8_wifi_state_t

enum ra8_wifi_state_t : uint8_t

Where a handle is on the path from powered-off to holding an IP.

A strictly increasing lifecycle: each successful step advances one level, and ra8_wifi_disconnect returns it to k_ra8_wifi_state_down. It is surfaced by ra8_wifi_status so a caller can drive or display progress without inferring it from a chain of return codes.

Invariant

The values order the lifecycle, so a numeric comparison such as state >= k_ra8_wifi_state_associated is a valid readiness test.

k_ra8_wifi_state_ip_bound is reached only through ra8_wifi_wait_ip.

Example:

ra8_wifi_status_t st = {};
(void)ra8_wifi_status(&wifi, &st);
if (st.state >= k_ra8_wifi_state_associated) { have_link(); }

See also

ra8_wifi_status

Since

0.1.0

Enumerator
k_ra8_wifi_state_down	Not associated; radio may be off.
k_ra8_wifi_state_associating	A join has been asked for.
k_ra8_wifi_state_associated	Station is joined; no IP yet.
k_ra8_wifi_state_ip_bound	A DHCP lease is held.

Definition at line 153 of file ra8_wifi.h.

Function Documentation

ra8_wifi_connect()

ra8_err_t ra8_wifi_connect ( ra8_wifi_t * wifi, const char * ssid, const char * psk )

nodiscard

Join a network by SSID and passphrase, blocking until associated.

Starts the radio if it is not already on, reads and caches the station MAC, asks the backend to associate, and services the link until the station joins or the attempt budget (k_ra8_wifi_join_polls) is spent, idling k_ra8_wifi_poll_gap_ms between attempts. On success the handle is at k_ra8_wifi_state_associated and ra8_wifi_wait_ip is the next step.

A quiet link is not a failed one

While an association is in flight the radio routinely has nothing to say, and a backend is entitled to report that as an error – k_ra8_wifi_backend_c6link returns k_ra8_err_hw_timeout when the co-processor does not arm its handshake line. Such a reading ends the attempt, never the wait: the loop keeps servicing until the budget is spent, and only surfaces a service error when no attempt in the whole budget succeeded, which is the reading that really does mean the radio is gone.

Parameters

[in,out]	wifi	Open handle; must be non-null.
[in]	ssid	Target SSID, NUL-terminated; must be non-null and 1.. k_ra8_wifi_ssid_max octets.
[in]	psk	Passphrase, NUL-terminated, or null for an open network.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The station is associated.
k_ra8_err_null_ptr	wifi or ssid was null.
k_ra8_err_not_initialized	wifi is not open.
k_ra8_err_invalid_size	ssid was empty or a credential was too long.
k_ra8_err_timeout	The join did not complete within the budget.
k_ra8_err_protocol_error	The radio refused a step of the join.
k_ra8_err_spi_error	The backend's transport refused every transfer of the whole budget.
k_ra8_err_hw_timeout	The radio answered no attempt of the whole budget.

Precondition

wifi has been initialised.

ssid names a network that is in range.

Postcondition

On success the handle reports k_ra8_wifi_state_associated.

On failure the handle is not left reporting associated.

Note

Not thread-safe; it drives the link.

Warning

Blocks for as long as association takes, up to the poll budget.

Example:

(void)ra8_wifi_connect(&wifi, "ra8-bench", secret);

See also

ra8_wifi_wait_ip

ra8_wifi_disconnect

Since

0.1.0

NASA Power of 10 Compliance:

• Rule 2: the association wait is bounded by k_ra8_wifi_join_polls.
• Rule 5: two preconditions and two postconditions are checked.

Definition at line 311 of file ra8_wifi.c.

References ra8_wifi::backend, ra8_wifi::backend_ctx, ra8_wifi_backend::get_mac, internal_await_association(), internal_ensure_radio_up(), ra8_wifi_backend::join, k_ra8_err_not_initialized, k_ra8_ok, k_ra8_wifi_state_associating, ra8_wifi::mac, ra8_wifi::mac_valid, ra8_wifi::open, RA8_CHECK_NULL_PTR, RA8_WIFI_TAG, and ra8_wifi::state.

Referenced by wifi_hal_join_run().

ra8_wifi_deinit()

ra8_err_t ra8_wifi_deinit ( ra8_wifi_t * wifi )

nodiscard

Release a handle and power its radio down.

Asks the backend to close its link and drop the transport binding, then marks the handle closed. Safe to call from any state; a handle that never associated closes just as cleanly as one that held a lease.

Parameters

[in,out]

wifi

Open handle; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The handle is closed.
k_ra8_err_null_ptr	wifi was null.
k_ra8_err_not_initialized	wifi was not open.

Precondition

No other context is driving wifi.

The caller no longer needs the cached lease or status.

Postcondition

The handle reports closed.

The backend has released its link.

Note

Not thread-safe; close from the context that opened.

Example:

(void)ra8_wifi_deinit(&wifi);

See also

ra8_wifi_init

Since

0.1.0

Definition at line 195 of file ra8_wifi.c.

References ra8_wifi::backend, ra8_wifi::backend_ctx, ra8_wifi_backend::close, k_ra8_err_not_initialized, k_ra8_wifi_state_down, ra8_wifi::open, RA8_CHECK_NULL_PTR, RA8_WIFI_TAG, ra8_wifi::radio_on, and ra8_wifi::state.

ra8_wifi_disconnect()

ra8_err_t ra8_wifi_disconnect ( ra8_wifi_t * wifi )

nodiscard

Disassociate the station and power the radio down.

Asks the backend to leave the network and stop the radio, clears the cached lease, and returns the handle to k_ra8_wifi_state_down. The handle stays open and can associate again with a fresh ra8_wifi_connect.

Parameters

[in,out]

wifi

Open handle; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The station has left and the radio is stopped.
k_ra8_err_null_ptr	wifi was null.
k_ra8_err_not_initialized	wifi is not open.
k_ra8_err_protocol_error	A teardown step was refused; the rest still ran.
k_ra8_err_spi_error	The backend's transport refused a transfer.

Precondition

wifi has been initialised.

The caller has stopped using the IP stack over this link.

Postcondition

The handle reports k_ra8_wifi_state_down.

The cached lease is cleared.

Note

Not thread-safe; it drives the link.

Example:

(void)ra8_wifi_disconnect(&wifi);

See also

ra8_wifi_connect

Since

0.1.0

Definition at line 338 of file ra8_wifi.c.

References ra8_wifi::backend, ra8_wifi::backend_ctx, k_ra8_err_not_initialized, k_ra8_ok, k_ra8_wifi_state_down, ra8_wifi::lease, ra8_wifi_backend::leave, ra8_wifi::open, RA8_CHECK_NULL_PTR, RA8_WIFI_TAG, ra8_wifi_backend::radio_down, ra8_wifi::radio_on, and ra8_wifi::state.

ra8_wifi_get_ap()

ra8_err_t ra8_wifi_get_ap ( ra8_wifi_t * wifi, ra8_wifi_ap_t * out )

nodiscard

Read what the backend knows about the associated AP.

Asks the backend for the co-processor's own association record – BSSID, SSID, channel, signal level and auth mode – and caches the signal level for ra8_wifi_status. A useful post-connect sanity check on what the radio actually settled on.

Parameters

[in,out]	wifi	Open handle; must be non-null.
[out]	out	Record to fill; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	out describes the current association.
k_ra8_err_null_ptr	wifi or out was null.
k_ra8_err_not_initialized	wifi is not open.
k_ra8_err_invalid_state	The station is not associated.
k_ra8_err_protocol_error	The backend reported no AP record.
k_ra8_err_spi_error	The backend's transport refused a transfer.

Precondition

wifi is associated; asking otherwise is refused.

wifi has been initialised.

Postcondition

On success out is fully written and rssi is cached for status.

On failure out is cleared rather than left half-written.

Note

Not thread-safe; it may drive the link.

Example:

ra8_wifi_ap_t ap = {};
(void)ra8_wifi_get_ap(&wifi, &ap);

See also

ra8_wifi_ap_t

Since

0.1.0

Definition at line 462 of file ra8_wifi.c.

References ra8_wifi::backend, ra8_wifi::backend_ctx, ra8_wifi_backend::get_ap, k_ra8_err_invalid_state, k_ra8_err_not_initialized, k_ra8_ok, k_ra8_wifi_state_associated, ra8_wifi::open, RA8_CHECK_NULL_PTR, RA8_WIFI_TAG, ra8_wifi::rssi, ra8_wifi_ap::rssi, and ra8_wifi::state.

Referenced by wifi_hal_join_run().

ra8_wifi_get_ip()

ra8_err_t ra8_wifi_get_ip ( const ra8_wifi_t * wifi, ra8_wifi_lease_t * out )

nodiscard

Read the cached DHCP lease without touching the wire.

Returns the lease ra8_wifi_wait_ip last obtained, straight from the handle. It performs no I/O, so it is the cheap way for an application to read back its address after binding; out->bound distinguishes a real lease from none.

Parameters

[in]	wifi	Open handle; must be non-null.
[out]	out	Lease to fill; must be non-null. bound is false when no lease has been obtained.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	out holds the cached lease.
k_ra8_err_null_ptr	wifi or out was null.
k_ra8_err_not_initialized	wifi is not open.

Precondition

wifi has been initialised.

The caller reads out->bound before trusting the addresses.

Postcondition

No handle state is modified.

out is fully written, including on the unbound path.

Note

Safe from any context; it copies cached fields.

Example:

ra8_wifi_lease_t lease = {};
(void)ra8_wifi_get_ip(&wifi, &lease);

See also

ra8_wifi_wait_ip

Since

0.1.0

Definition at line 383 of file ra8_wifi.c.

References k_ra8_err_not_initialized, k_ra8_ok, ra8_wifi::lease, ra8_wifi::open, RA8_CHECK_NULL_PTR, and RA8_WIFI_TAG.

ra8_wifi_get_mac()

ra8_err_t ra8_wifi_get_mac ( ra8_wifi_t * wifi, ra8_wifi_mac_t * out )

nodiscard

Read the station's own MAC address.

Asks the backend for the station address, caches it on the handle and copies it out. The address is a property of the radio's efuses, so it is stable across resets and available once the radio has been started.

That stability is also the fallback: when the backend cannot be asked – an associated station shares its link with the traffic the AP has begun forwarding, and a query can lose that race – the cached address ra8_wifi_connect already read is returned instead. Only a handle that has never held a valid address reports the failure, because only then is there no answer to give.

Parameters

[in,out]	wifi	Open handle; must be non-null.
[out]	out	Address to fill; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	out holds the station address, freshly read or cached.
k_ra8_err_null_ptr	wifi or out was null.
k_ra8_err_not_initialized	wifi is not open.
k_ra8_err_protocol_error	The backend reported no valid address and no address has ever been cached.
k_ra8_err_spi_error	The backend's transport refused a transfer and no address has ever been cached.

Precondition

wifi has been initialised.

The radio has been started at least once, which ra8_wifi_connect does.

Postcondition

On success out holds k_ra8_wifi_mac_bytes octets.

On failure out is cleared rather than left half-written.

Note

Not thread-safe; it may drive the link.

Example:

ra8_wifi_mac_t mac = {};
(void)ra8_wifi_get_mac(&wifi, &mac);

See also

ra8_wifi_mac_t

Since

0.1.0

Definition at line 434 of file ra8_wifi.c.

References ra8_wifi::backend, ra8_wifi::backend_ctx, ra8_wifi_backend::get_mac, k_ra8_err_not_initialized, k_ra8_ok, ra8_wifi::mac, ra8_wifi::mac_valid, ra8_wifi::open, RA8_CHECK_NULL_PTR, and RA8_WIFI_TAG.

Referenced by wifi_hal_join_run().

ra8_wifi_init()

ra8_err_t ra8_wifi_init ( ra8_wifi_t * wifi, const ra8_wifi_cfg_t * cfg )

nodiscard

Bring the radio and its link up and make a handle usable.

Validates the configuration, copies it into the handle, and asks the backend to open: bind its transport, open its link, and prove the radio answers. No network is joined here – that is ra8_wifi_connect.

Parameters

[out]	wifi	Handle to initialise; must be non-null.
[in]	cfg	Configuration; must be non-null with a complete backend table and an ip_bind hook.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The handle is open and the radio is answering.
k_ra8_err_null_ptr	wifi, cfg, cfg->backend, a backend row, or cfg->ip_bind was null.
k_ra8_err_invalid_state	wifi is already open.
k_ra8_err_timeout	The backend could not prove the radio is answering.
k_ra8_err_hw_timeout	The radio never armed its handshake.
k_ra8_err_spi_error	The backend's transport refused a transfer.

Precondition

The backend's hardware bring-up (clocks, pins, bus) has already run.

wifi is zero-initialised, or has been deinitialised.

Postcondition

On success the handle reports open and k_ra8_wifi_state_down.

On failure wifi is left closed rather than half-open.

Note

Not thread-safe; initialise once from a single-threaded bring-up path.

Warning

Everything the configuration points at must outlive the handle.

Example:

if (ra8_wifi_init(&wifi, &cfg) != k_ra8_ok) { report(); }

See also

ra8_wifi_deinit

Since

0.1.0

NASA Power of 10 Compliance:

• Rule 5: preconditions on every configuration row and two postconditions.

Definition at line 166 of file ra8_wifi.c.

References ra8_wifi::backend, ra8_wifi_cfg::backend, ra8_wifi::backend_ctx, ra8_wifi_cfg::backend_ctx, internal_check_backend(), ra8_wifi::ip_bind, ra8_wifi_cfg::ip_bind, ra8_wifi::ip_ctx, ra8_wifi_cfg::ip_ctx, k_ra8_err_invalid_state, k_ra8_ok, k_ra8_wifi_state_down, ra8_wifi::open, ra8_wifi_backend::open, RA8_CHECK_NULL_PTR, RA8_WIFI_TAG, and ra8_wifi::state.

Referenced by wifi_hal_join_run().

ra8_wifi_poll()

ra8_err_t ra8_wifi_poll ( ra8_wifi_t * wifi, ra8_wifi_link_t * out )

nodiscard

Service the link once and refresh the cached association state.

Drives the backend for one service cycle – draining events, noticing a disconnection – and folds the result into the handle's lifecycle. Use it to watch a link that is associated but has not yet obtained an IP; it must not be called once ra8_wifi_wait_ip has bound an address, because from that point the IP stack owns the wire.

Parameters

[in,out]	wifi	Open handle; must be non-null.
[out]	out	Association state after the cycle; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The link was serviced; out holds the reading.
k_ra8_err_null_ptr	wifi or out was null.
k_ra8_err_not_initialized	wifi is not open.
k_ra8_err_invalid_state	wifi already holds an IP; the IP stack owns the wire and must not be pre-empted.
k_ra8_err_hw_timeout	The radio never armed its handshake.
k_ra8_err_spi_error	The backend's transport refused a transfer.

Precondition

wifi has been initialised and has not bound an IP.

No IP-stack thread is driving the same link.

Postcondition

The cached state reflects the reading just taken.

At most one service cycle was run.

Note

Not thread-safe; it drives the link.

Example:

ra8_wifi_link_t link = k_ra8_wifi_link_down;
(void)ra8_wifi_poll(&wifi, &link);

See also

ra8_wifi_connect

Since

0.1.0

NASA Power of 10 Compliance:

• Rule 5: two preconditions and two postconditions are checked.

Definition at line 411 of file ra8_wifi.c.

References ra8_wifi::backend, ra8_wifi::backend_ctx, k_ra8_err_invalid_state, k_ra8_err_not_initialized, k_ra8_ok, k_ra8_wifi_link_down, k_ra8_wifi_link_up, k_ra8_wifi_state_associated, k_ra8_wifi_state_down, k_ra8_wifi_state_ip_bound, ra8_wifi::open, RA8_CHECK_NULL_PTR, RA8_WIFI_TAG, ra8_wifi_backend::service, and ra8_wifi::state.

Referenced by wifi_hal_settle().

ra8_wifi_status()

ra8_err_t ra8_wifi_status ( const ra8_wifi_t * wifi, ra8_wifi_status_t * out )

nodiscard

Read a handle's cached status without touching the wire.

Fills out from state the handle already holds – lifecycle position, the associated and IP-bound flags derived from it, the last signal reading and the current lease. It performs no I/O and is safe to poll for a display; call ra8_wifi_poll first when a fresher association reading is needed.

Parameters

[in]	wifi	Open handle; must be non-null.
[out]	out	Status to fill; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	out describes the handle.
k_ra8_err_null_ptr	wifi or out was null.
k_ra8_err_not_initialized	wifi is not open.

Precondition

wifi has been initialised.

The caller has called ra8_wifi_poll first if a fresh reading matters.

Postcondition

No handle state is modified.

out is fully written.

Note

Safe from any context; it copies cached fields.

Example:

ra8_wifi_status_t st = {};
(void)ra8_wifi_status(&wifi, &st);

See also

ra8_wifi_state_t

Since

0.1.0

Definition at line 394 of file ra8_wifi.c.

References ra8_wifi_status::associated, ra8_wifi_status::ip, ra8_wifi_status::ip_bound, k_ra8_err_not_initialized, k_ra8_ok, k_ra8_wifi_state_associated, k_ra8_wifi_state_ip_bound, ra8_wifi::lease, ra8_wifi::open, RA8_CHECK_NULL_PTR, RA8_WIFI_TAG, ra8_wifi::rssi, ra8_wifi_status::rssi, ra8_wifi::state, and ra8_wifi_status::state.

Referenced by wifi_hal_settle().

ra8_wifi_wait_ip()

ra8_err_t ra8_wifi_wait_ip ( ra8_wifi_t * wifi, ra8_wifi_lease_t * out )

nodiscard

Obtain an IP address for the associated station, blocking until bound.

Runs the configured ra8_wifi_ip_bind_fn with the station MAC, caches the lease it returns, and advances the handle to k_ra8_wifi_state_ip_bound. The provider owns the mechanism (DHCP today) and the wait; from here the caller uses the IP stack's socket API and must not call ra8_wifi_poll.

Parameters

[in,out]	wifi	Open, associated handle; must be non-null.
[out]	out	Lease to fill; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	out holds a usable lease.
k_ra8_err_null_ptr	wifi or out was null.
k_ra8_err_not_initialized	wifi is not open.
k_ra8_err_invalid_state	The station is not associated.
k_ra8_err_timeout	The provider did not obtain a lease.

Precondition

ra8_wifi_connect has succeeded on wifi.

The configured IP provider can reach a DHCP server over the link.

Postcondition

On success the handle reports k_ra8_wifi_state_ip_bound.

On failure out is cleared rather than left half-written.

Note

Not thread-safe; it drives the IP provider.

Warning

Blocks for as long as the provider takes to obtain a lease.

Example:

ra8_wifi_lease_t lease = {};
(void)ra8_wifi_wait_ip(&wifi, &lease);

See also

ra8_wifi_get_ip

Since

0.1.0

NASA Power of 10 Compliance:

• Rule 5: two preconditions and two postconditions are checked.

Definition at line 353 of file ra8_wifi.c.

References ra8_wifi_lease::bound, ra8_wifi_lease::ip, ra8_wifi::ip_bind, ra8_wifi::ip_ctx, k_ra8_err_invalid_state, k_ra8_err_not_initialized, k_ra8_err_timeout, k_ra8_ok, k_ra8_wifi_state_associated, k_ra8_wifi_state_ip_bound, ra8_wifi::lease, ra8_wifi::mac, ra8_wifi::open, RA8_CHECK_NULL_PTR, RA8_WIFI_TAG, and ra8_wifi::state.

Referenced by wifi_hal_join_run().