ra8_wifi.c File Reference

The Wi-Fi facade state machine, dispatched over a backend vtable. More...

#include "ra8_wifi.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_wifi_backend.h"

Include dependency graph for ra8_wifi.c:

Go to the source code of this file.

Macros
#define	RA8_WIFI_TAG   "WIFI"
	Component tag for this facade's log lines.

Functions
static ra8_err_t	internal_check_backend_lifecycle (const ra8_wifi_backend_t *b)
	Validate the backend rows that change the radio's state.
static ra8_err_t	internal_check_backend_session (const ra8_wifi_backend_t *b)
	Validate the backend rows that join and leave a network.
static ra8_err_t	internal_check_backend_query (const ra8_wifi_backend_t *b)
	Validate the backend rows that report state or pace a wait.
static ra8_err_t	internal_check_backend (const ra8_wifi_backend_t *b)
	Validate every row of a candidate backend table.
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.
static ra8_err_t	internal_ensure_radio_up (ra8_wifi_t *wifi)
	Raise the radio if it is not already up.
static ra8_err_t	internal_await_association (ra8_wifi_t *wifi)
	Pump the backend until the station associates or the budget runs out.
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

The Wi-Fi facade state machine, dispatched over a backend vtable.

Tag

[Ring 4 / PAL] {World: NS}

Implements ra8_wifi.h. Every entry point is a short step in the lifecycle down->associating->associated->ip_bound, expressed purely in terms of the ra8_wifi_backend_t function pointers and the caller-supplied ra8_wifi_ip_bind_fn. This translation unit names no radio and includes no ra8_c6link header, which is exactly what makes it host-testable against a mock backend.

Copyright

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

Since

0.1.0

Definition in file ra8_wifi.c.

Macro Definition Documentation

RA8_WIFI_TAG

#define RA8_WIFI_TAG   "WIFI"

Component tag for this facade's log lines.

Definition at line 33 of file ra8_wifi.c.

Referenced by internal_await_association(), internal_check_backend_lifecycle(), internal_check_backend_query(), internal_check_backend_session(), internal_ensure_radio_up(), ra8_wifi_connect(), ra8_wifi_deinit(), ra8_wifi_disconnect(), ra8_wifi_get_ap(), ra8_wifi_get_ip(), ra8_wifi_get_mac(), ra8_wifi_init(), ra8_wifi_poll(), ra8_wifi_status(), and ra8_wifi_wait_ip().

Function Documentation

internal_await_association()

ra8_err_t internal_await_association ( ra8_wifi_t * wifi )

static

Pump the backend until the station associates or the budget runs out.

A join request only asks; association completes asynchronously, so the transport has to be serviced until the link reports up. The poll count is a compile-time bound (k_ra8_wifi_join_polls), so this terminates whether or not the AP ever answers – NASA Power of 10 Rule 2 – and the backend idles k_ra8_wifi_poll_gap_ms between attempts, which is what makes that count a budget in seconds rather than in however fast the radio answers.

A failed attempt ends the attempt, not the wait. Servicing a link whose radio is mid-association routinely fails: the co-processor is busy on the air and has nothing to hand back, which k_ra8_wifi_backend_c6link reports as k_ra8_err_hw_timeout. Treating the first such reading as fatal is what made association a coin toss on silicon, so the loop records the error and carries on, and reports it only if no attempt in the entire budget succeeded – the one reading that does mean the radio is not there.

Parameters

[in,out]

wifi

Open handle with a join already requested.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The link came up; the handle is in the associated state.
k_ra8_err_timeout	The budget was exhausted with the link still down.
k_ra8_err_null_ptr	wifi was null.

Precondition

ra8_wifi_connect has already issued the backend join.

wifi is open and its radio is up.

Postcondition

On success wifi->state is k_ra8_wifi_state_associated.

On timeout the handle is left in the associating state for a retry.

Note

Not thread-safe; one handle belongs to one caller.

Since

0.1.0

Definition at line 282 of file ra8_wifi.c.

References internal_await_association(), k_ra8_err_timeout, k_ra8_ok, k_ra8_wifi_join_polls, k_ra8_wifi_link_down, k_ra8_wifi_link_up, k_ra8_wifi_poll_gap_ms, k_ra8_wifi_state_associated, RA8_CHECK_NULL_PTR, and RA8_WIFI_TAG.

Referenced by internal_await_association(), and ra8_wifi_connect().

internal_check_backend()

ra8_err_t internal_check_backend ( const ra8_wifi_backend_t * b )

static

Validate every row of a candidate backend table.

The single entry point ra8_wifi_init uses. It runs the three role-sized validators in turn and stops at the first gap, so the error names the row that is missing rather than reporting only that "the table is wrong".

Parameters

[in]

b

Candidate backend table; may be null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Every function pointer is set.
k_ra8_err_null_ptr	b or one of its rows was null.

Precondition

b is the table an application selected by address.

The caller treats any failure as a fatal configuration error.

Postcondition

No state is modified.

On success the table is safe to dispatch through.

Note

Pure validation; touches no state and is safe from any context.

Since

0.1.0

Definition at line 153 of file ra8_wifi.c.

References internal_check_backend_lifecycle(), internal_check_backend_query(), internal_check_backend_session(), k_ra8_ok, and RA8_INTERNAL.

Referenced by ra8_wifi_init().

internal_check_backend_lifecycle()

ra8_err_t internal_check_backend_lifecycle ( const ra8_wifi_backend_t * b )

static

Validate the backend rows that change the radio's state.

The lifecycle half of ra8_wifi_backend_t – opening and closing the transport and raising or lowering the radio. The table is validated in three role-sized pieces rather than one function carrying ten expansions of RA8_CHECK_NULL_PTR, which is what pushed it past the complexity budget.

Parameters

[in]

b

Candidate backend table; never null (the caller checked).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Every lifecycle row is set.
k_ra8_err_null_ptr	One of the lifecycle rows was null.

Precondition

b is non-null.

The caller treats any failure as a fatal configuration error.

Postcondition

No state is modified.

On success every lifecycle row is safe to dispatch through.

Note

Pure validation; touches no state and is safe from any context.

Since

0.1.0

Definition at line 58 of file ra8_wifi.c.

References k_ra8_ok, RA8_CHECK_NULL_PTR, RA8_INTERNAL, and RA8_WIFI_TAG.

Referenced by internal_check_backend().

internal_check_backend_query()

ra8_err_t internal_check_backend_query ( const ra8_wifi_backend_t * b )

static

Validate the backend rows that report state or pace a wait.

The observation half of ra8_wifi_backend_t – pumping the transport, reading back the station address and the associated AP, and idling between attempts. None of these change the radio, which is why they are validated apart from the lifecycle rows.

Parameters

[in]

b

Candidate backend table; never null (the caller checked).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Every query row is set.
k_ra8_err_null_ptr	One of the query rows was null.

Precondition

b is non-null.

The caller treats any failure as a fatal configuration error.

Postcondition

No state is modified.

On success every query row is safe to dispatch through.

Note

Pure validation; touches no state and is safe from any context.

Since

0.1.0

Definition at line 121 of file ra8_wifi.c.

References k_ra8_ok, RA8_CHECK_NULL_PTR, RA8_INTERNAL, and RA8_WIFI_TAG.

Referenced by internal_check_backend().

internal_check_backend_session()

ra8_err_t internal_check_backend_session ( const ra8_wifi_backend_t * b )

static

Validate the backend rows that join and leave a network.

The session half of ra8_wifi_backend_t. Separate from the lifecycle rows because a radio can be up with no network attached, so these are the rows a reconnect exercises without touching the transport.

Parameters

[in]

b

Candidate backend table; never null (the caller checked).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Both session rows are set.
k_ra8_err_null_ptr	One of the session rows was null.

Precondition

b is non-null.

The caller treats any failure as a fatal configuration error.

Postcondition

No state is modified.

On success both session rows are safe to dispatch through.

Note

Pure validation; touches no state and is safe from any context.

Since

0.1.0

Definition at line 90 of file ra8_wifi.c.

References k_ra8_ok, RA8_CHECK_NULL_PTR, RA8_INTERNAL, and RA8_WIFI_TAG.

Referenced by internal_check_backend().

internal_ensure_radio_up()

ra8_err_t internal_ensure_radio_up ( ra8_wifi_t * wifi )

static

Raise the radio if it is not already up.

Idempotent by design: ra8_wifi_connect may be called repeatedly (a retry after a failed join, a move to another SSID) and must not cycle a radio that is already running, because a backend is entitled to treat a second radio_up as an error.

Parameters

[in,out]

wifi

Open handle whose radio should be running on return.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The radio is up, whether or not this call raised it.
k_ra8_err_null_ptr	wifi was null.

Precondition

wifi is open (ra8_wifi_init succeeded).

The backend table has been validated.

Postcondition

On success wifi->radio_on is true.

On failure no handle field has changed.

Note

Not thread-safe; one handle belongs to one caller.

Since

0.1.0

Definition at line 232 of file ra8_wifi.c.

References ra8_wifi::backend, ra8_wifi::backend_ctx, k_ra8_ok, RA8_CHECK_NULL_PTR, RA8_INTERNAL, RA8_WIFI_TAG, ra8_wifi::radio_on, and ra8_wifi_backend::radio_up.

Referenced by ra8_wifi_connect().

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