ra8_c6link_wifi.h File Reference

Wi-Fi station bring-up and association over the C6 link. More...

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

Include dependency graph for ra8_c6link_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_c6link_sta_cfg
	What this host must tell the co-processor to join one network. More...
struct	ra8_c6link_ap_info
	What the co-processor knows about the AP the station is on. More...

Typedefs
typedef struct ra8_c6link_sta_cfg	ra8_c6link_sta_cfg_t
typedef struct ra8_c6link_ap_info	ra8_c6link_ap_info_t

Enumerations
enum	ra8_c6link_wifi_limits_t : uint8_t {   k_ra8_c6link_pass_max = 64U ,   k_ra8_c6link_channel_max = 14U }
	Field capacities the station configuration works to. More...

Functions
ra8_err_t	ra8_c6link_sta_cfg_set (ra8_c6link_sta_cfg_t *cfg, const char *ssid, const char *pass)
	Fill a station configuration from an SSID and a passphrase.
ra8_err_t	ra8_c6link_wifi_start (ra8_c6link_t *link)
	Start the co-processor's Wi-Fi radio in station mode.
ra8_err_t	ra8_c6link_wifi_stop (ra8_c6link_t *link)
	Stop the radio and release the co-processor's Wi-Fi resources.
ra8_err_t	ra8_c6link_wifi_join (ra8_c6link_t *link, const ra8_c6link_sta_cfg_t *cfg)
	Ask the station to associate with the configured network.
ra8_err_t	ra8_c6link_wifi_leave (ra8_c6link_t *link)
	Disassociate the station from its current network.
ra8_err_t	ra8_c6link_wifi_mac (ra8_c6link_t *link, ra8_c6link_mac_t *out)
	Read the station interface's MAC address.
ra8_err_t	ra8_c6link_wifi_ap_info (ra8_c6link_t *link, ra8_c6link_ap_info_t *out)
	Read what the co-processor knows about the associated AP.

Detailed Description

Wi-Fi station bring-up and association over the C6 link.

Tag

[Ring 4 / PAL] {World: NS}

A station join is eleven RPC ids out of the several hundred the esp-hosted protocol defines, and the only "configuration" the co-processor needs is an SSID, a passphrase and a handful of scalars. This header is that, and nothing else: it does not reproduce ESP-IDF's wifi_*_t types, because the C6 decodes protobuf messages with named fields and no layout on this side is ever transmitted (see the rationale in ra8_c6link.h).

The sequence, and why it is three calls rather than eight

ESP-IDF's station bring-up is esp_wifi_init, esp_wifi_set_mode, esp_wifi_set_config, esp_wifi_start, esp_wifi_connect. Each is a separate RPC and each can fail, but there is exactly one useful order and no caller in this tree wants a different one. So they are grouped into the three operations a network stack actually performs – start the radio, join a network, leave – and the failing step is recoverable through ra8_c6link_last_fault rather than through eight entry points that must be called in the right order or not at all.

Association is asynchronous

ra8_c6link_wifi_join returns once the co-processor has accepted the request. The association itself completes later and is announced as k_ra8_c6link_event_sta_connected, or fails as k_ra8_c6link_event_sta_disconnected carrying an 802.11 reason code. A caller that needs to block waits by pumping ra8_c6link_poll until one of those arrives; there is no hidden wait inside this library, because the length of that wait is a policy the IP stack above owns.

Example:

ra8_c6link_sta_cfg_t sta = {};
(void)ra8_c6link_sta_cfg_set(&sta, "ra8-bench", secret);
if (ra8_c6link_wifi_start(&link) == k_ra8_ok) {
  (void)ra8_c6link_wifi_join(&link, &sta);
}

See also

ra8_c6link.h The link this sits on

Copyright

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

Since

0.1.0

Definition in file ra8_c6link_wifi.h.

Typedef Documentation

ra8_c6link_ap_info_t

typedef struct ra8_c6link_ap_info ra8_c6link_ap_info_t

ra8_c6link_sta_cfg_t

typedef struct ra8_c6link_sta_cfg ra8_c6link_sta_cfg_t

Enumeration Type Documentation

ra8_c6link_wifi_limits_t

enum ra8_c6link_wifi_limits_t : uint8_t

Field capacities the station configuration works to.

Both come from 802.11 and from the protobuf field comments upstream ships ("SSID of target AP. 32char", "Password of target AP. 64char"), so they are the co-processor's limits as much as this host's.

Invariant

k_ra8_c6link_pass_max is the longest WPA passphrase, which is also long enough for a 64-character PSK written out in hex.

Both storage arrays carry one extra octet for a NUL, so a maximum-length value is still a usable C string.

Example:

static_assert(k_ra8_c6link_pass_max == 64U, "WPA passphrase bound");

See also

ra8_c6link_sta_cfg_t

Since

0.1.0

Enumerator
k_ra8_c6link_pass_max	Longest passphrase the co-processor accepts, in octets.
k_ra8_c6link_channel_max	Highest 2.4 GHz channel number; zero means "scan for it".

Definition at line 85 of file ra8_c6link_wifi.h.

Function Documentation

ra8_c6link_sta_cfg_set()

ra8_err_t ra8_c6link_sta_cfg_set ( ra8_c6link_sta_cfg_t * cfg, const char * ssid, const char * pass )

nodiscard

Fill a station configuration from an SSID and a passphrase.

Copies both strings into the record, bounded, and derives their lengths. An empty or null passphrase means an open network, which is a legitimate configuration and not an error. Everything else in the record is cleared, so a stale channel or BSSID from a previous use cannot survive.

Parameters

[out]	cfg	Record to fill; must be non-null.
[in]	ssid	NUL-terminated SSID; must be non-null and 1.. k_ra8_c6link_ssid_max octets.
[in]	pass	NUL-terminated passphrase, or null for an open network; at most k_ra8_c6link_pass_max octets.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The record is filled and ready for ra8_c6link_wifi_join.
k_ra8_err_null_ptr	cfg or ssid was null.
k_ra8_err_invalid_size	ssid was empty or either string was longer than its field.

Precondition

ssid is NUL-terminated within k_ra8_c6link_ssid_max + 1 octets.

pass, when non-null, is NUL-terminated within k_ra8_c6link_pass_max + 1 octets.

Postcondition

On success both lengths are consistent with the copied strings.

On failure cfg is left cleared rather than half-filled.

Note

Pure formatting; touches no hardware and is safe from any thread.

Warning

The passphrase is held in the caller's record in plain text for as long as the record lives. Clear it once the join has been issued.

Example:

(void)ra8_c6link_sta_cfg_set(&sta, "ra8-bench", "correct horse battery");

See also

ra8_c6link_wifi_join

Since

0.1.0

Definition at line 100 of file ra8_c6link_wifi_sta.c.

References internal_c6link_sta_len(), k_ra8_c6link_pass_max, k_ra8_c6link_ssid_max, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, ra8_c6link_sta_cfg::pass, ra8_c6link_sta_cfg::pass_len, ra8_secure_memzero(), ra8_c6link_sta_cfg::ssid, and ra8_c6link_sta_cfg::ssid_len.

Referenced by c6_join_phase_associate(), internal_c6_cam_associate(), internal_c6link_op_join(), and internal_open_and_join().

ra8_c6link_wifi_ap_info()

ra8_err_t ra8_c6link_wifi_ap_info ( ra8_c6link_t * link, ra8_c6link_ap_info_t * out )

nodiscard

Read what the co-processor knows about the associated AP.

Parameters

[in,out]	link	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	link or out was null.
k_ra8_err_not_initialized	link is not open.
k_ra8_err_busy	A request is already outstanding on link.
k_ra8_err_timeout	The co-processor did not answer.
k_ra8_err_hw_timeout	The co-processor never armed HANDSHAKE, so no transaction was clocked.
k_ra8_err_protocol_error	The answer reported a failure – which is what an unassociated station returns – or carried no record.
k_ra8_err_spi_error	The transport refused a transfer.

Precondition

The station is associated; asking otherwise is answered with a failure code by the co-processor.

The transport is up.

Postcondition

On success out is fully written.

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

Note

Not thread-safe; it pumps.

Example:

ra8_c6link_ap_info_t ap = {};
(void)ra8_c6link_wifi_ap_info(&link, &ap);

See also

ra8_c6link_ap_info

Since

0.1.0

Definition at line 405 of file ra8_c6link_wifi_sta.c.

References internal_c6link_take_ap(), k_ra8_err_not_initialized, k_ra8_err_null_ptr, priv_c6link_rpc_call(), and ra8_c6link_is_open().

Referenced by internal_c6link_op_get_ap().

ra8_c6link_wifi_join()

ra8_err_t ra8_c6link_wifi_join ( ra8_c6link_t * link, const ra8_c6link_sta_cfg_t * cfg )

nodiscard

Ask the station to associate with the configured network.

Issues Req_WifiSetConfig for the station interface and then Req_WifiConnect. Returns as soon as the co-processor has accepted the request; the association result arrives later as an event.

Parameters

[in,out]	link	Open handle; must be non-null.
[in]	cfg	Station configuration; must be non-null and consistent, which ra8_c6link_sta_cfg_set guarantees.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The co-processor accepted the association request.
k_ra8_err_null_ptr	link or cfg was null.
k_ra8_err_not_initialized	link is not open.
k_ra8_err_invalid_size	A length in cfg exceeds its field.
k_ra8_err_busy	A request is already outstanding on link.
k_ra8_err_timeout	The co-processor did not answer a step.
k_ra8_err_hw_timeout	The co-processor never armed HANDSHAKE, so no transaction was clocked.
k_ra8_err_protocol_error	A step reported a failure code.
k_ra8_err_spi_error	The transport refused a transfer.

Precondition

ra8_c6link_wifi_start has succeeded on link.

cfg holds credentials for a network that is in range.

Postcondition

On success an association attempt is in progress.

On failure the handle's last fault names the step that failed.

Note

Not thread-safe; it pumps.

Warning

Success here means "asked", not "joined". Wait for k_ra8_c6link_event_sta_connected.

Example:

(void)ra8_c6link_wifi_join(&link, &sta);

See also

ra8_c6link_wifi_leave

Since

0.1.0

Definition at line 270 of file ra8_c6link_wifi_sta.c.

References internal_c6link_sta_set_config(), k_ra8_c6link_pass_max, k_ra8_c6link_ssid_max, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, ra8_c6link_sta_cfg::pass_len, priv_c6link_bare_req(), ra8_c6link_is_open(), and ra8_c6link_sta_cfg::ssid_len.

Referenced by c6_join_phase_associate(), internal_c6_cam_associate(), internal_c6link_op_join(), and internal_open_and_join().

ra8_c6link_wifi_leave()

ra8_err_t ra8_c6link_wifi_leave ( ra8_c6link_t * link )

nodiscard

Disassociate the station from its current network.

Parameters

[in,out]

link

Open handle; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The co-processor accepted the disassociation.
k_ra8_err_null_ptr	link was null.
k_ra8_err_not_initialized	link is not open.
k_ra8_err_busy	A request is already outstanding on link.
k_ra8_err_timeout	The co-processor did not answer.
k_ra8_err_hw_timeout	The co-processor never armed HANDSHAKE, so no transaction was clocked.
k_ra8_err_protocol_error	The answer reported a failure code.
k_ra8_err_spi_error	The transport refused a transfer.

Precondition

The transport is up.

The caller expects a k_ra8_c6link_event_sta_disconnected to follow.

Postcondition

On success a disassociation is in progress.

On failure the handle's last fault names this request.

Note

Not thread-safe; it pumps.

Example:

(void)ra8_c6link_wifi_leave(&link);

See also

ra8_c6link_wifi_join

Since

0.1.0

Definition at line 422 of file ra8_c6link_wifi.c.

References k_ra8_err_not_initialized, k_ra8_err_null_ptr, priv_c6link_bare_req(), and ra8_c6link_is_open().

Referenced by internal_c6link_op_leave().

ra8_c6link_wifi_mac()

ra8_err_t ra8_c6link_wifi_mac ( ra8_c6link_t * link, ra8_c6link_mac_t * out )

nodiscard

Read the station interface's MAC address.

The address an IP stack above must use as its own. It is a property of the co-processor's efuses, so it is stable across resets and is available as soon as the radio has been initialised.

Parameters

[in,out]	link	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.
k_ra8_err_null_ptr	link or out was null.
k_ra8_err_not_initialized	link is not open.
k_ra8_err_busy	A request is already outstanding on link.
k_ra8_err_timeout	The co-processor did not answer.
k_ra8_err_hw_timeout	The co-processor never armed HANDSHAKE, so no transaction was clocked.
k_ra8_err_protocol_error	The answer reported a failure, or carried an address of the wrong length.
k_ra8_err_spi_error	The transport refused a transfer.

Precondition

ra8_c6link_wifi_start has succeeded on link.

The caller treats an all-zero result as a protocol failure, which this call reports rather than returns.

Postcondition

On success out holds k_ra8_c6link_mac_bytes octets.

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

Note

Not thread-safe; it pumps.

Example:

ra8_c6link_mac_t mac = {};
(void)ra8_c6link_wifi_mac(&link, &mac);

See also

ra8_c6link_mac_t

Since

0.1.0

Definition at line 324 of file ra8_c6link_wifi_sta.c.

References internal_c6link_take_mac(), k_ra8_c6link_iface_sta, k_ra8_err_not_initialized, k_ra8_err_null_ptr, priv_c6link_rpc_call(), and ra8_c6link_is_open().

Referenced by c6_join_phase_associate(), c6_wifi_phase_station(), internal_c6_cam_associate(), and internal_c6link_op_get_mac().

ra8_c6link_wifi_start()

ra8_err_t ra8_c6link_wifi_start ( ra8_c6link_t * link )

nodiscard

Start the co-processor's Wi-Fi radio in station mode.

Issues Req_WifiInit, Req_SetWifiMode for station mode, and Req_WifiStart, in that order, stopping at the first one the co-processor refuses. The initialisation configuration transmitted is the ESP-IDF default set for this co-processor, field by field – see ra8_c6link_wifi_init_t in the implementation for what each value is and why it has that value.

Parameters

[in,out]

link

Open handle; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	The radio is up in station mode.
k_ra8_err_null_ptr	link was null.
k_ra8_err_not_initialized	link is not open.
k_ra8_err_busy	A request is already outstanding on link.
k_ra8_err_timeout	The co-processor did not answer a step.
k_ra8_err_hw_timeout	The co-processor never armed HANDSHAKE, so no transaction was clocked.
k_ra8_err_protocol_error	A step was answered with a failure code; ra8_c6link_last_fault names which.
k_ra8_err_spi_error	The transport refused a transfer.

Precondition

The transport is up and the co-processor has booted.

The radio is not already started; starting twice is refused by the far side, not by this host.

Postcondition

On success the co-processor is in station mode with its radio on.

On failure the handle's last fault names the step that failed.

Note

Not thread-safe; it pumps.

Example:

if (ra8_c6link_wifi_start(&link) != k_ra8_ok) { report(&link); }

See also

ra8_c6link_wifi_stop

Since

0.1.0

NASA Power of 10 Compliance:

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

Definition at line 388 of file ra8_c6link_wifi.c.

References internal_c6link_wifi_do_init(), internal_c6link_wifi_do_mode(), k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, priv_c6link_bare_req(), and ra8_c6link_is_open().

Referenced by c6_join_phase_associate(), c6_wifi_phase_station(), internal_c6_cam_associate(), internal_c6link_op_radio_up(), and internal_open_and_join().

ra8_c6link_wifi_stop()

ra8_err_t ra8_c6link_wifi_stop ( ra8_c6link_t * link )

nodiscard

Stop the radio and release the co-processor's Wi-Fi resources.

Issues Req_WifiStop then Req_WifiDeinit. Unlike the start sequence this continues past a refusal: a teardown that stops at the first error leaves the co-processor half-configured, which is worse than reporting the first fault and finishing the job.

Parameters

[in,out]

link

Open handle; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Both steps succeeded.
k_ra8_err_null_ptr	link was null.
k_ra8_err_not_initialized	link is not open.
k_ra8_err_busy	A request is already outstanding on link.
k_ra8_err_timeout	A step went unanswered; the rest still ran.
k_ra8_err_hw_timeout	The co-processor never armed HANDSHAKE, so no transaction was clocked.
k_ra8_err_protocol_error	A step reported a failure code; the rest still ran and ra8_c6link_last_fault names the first failure.
k_ra8_err_spi_error	The transport refused a transfer.

Precondition

The transport is up.

The caller has stopped transmitting Ethernet frames.

Postcondition

Every teardown step was attempted.

On failure the handle's last fault names the first step that failed.

Note

Not thread-safe; it pumps.

Example:

(void)ra8_c6link_wifi_stop(&link);

See also

ra8_c6link_wifi_start

Since

0.1.0

Definition at line 408 of file ra8_c6link_wifi.c.

References k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, priv_c6link_bare_req(), and ra8_c6link_is_open().

Referenced by c6_wifi_phase_station(), and internal_c6link_op_radio_down().