wifi_hal_join.h File Reference

Constants, console formatters and the DHCP provider for the HAL join. More...

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

Include dependency graph for wifi_hal_join.h:

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

Go to the source code of this file.

Data Structures
struct	wifi_hal_result
	The observable outcome of one wifi_hal_join_run, for the banner and the host test. More...
struct	wifi_hal_run_cfg
	Injected dependencies for the hardware-free wifi_hal_join_run. More...

Typedefs
typedef struct wifi_hal_result	wifi_hal_result_t
typedef struct wifi_hal_run_cfg	wifi_hal_run_cfg_t

Enumerations
enum	wifi_hal_cfg_t : uint32_t {   k_wifi_hal_uart_baud = 115200U ,   k_wifi_hal_sck_hz = 5000000U ,   k_wifi_hal_edge_poll_ms = 2U ,   k_wifi_hal_boot_wait_ms = 200U ,   k_wifi_hal_heartbeat_ms = 5000U ,   k_wifi_hal_worker_stack = 8192U ,   k_wifi_hal_worker_prio = 8U ,   k_wifi_hal_arena_bytes = 4096U }
	Clocking, pacing and RAM budgets the application sets. More...
enum	wifi_hal_wait_t : uint32_t {   k_wifi_hal_assoc_polls = 200U ,   k_wifi_hal_assoc_gap_ms = 50U ,   k_wifi_hal_dhcp_wait_ms = 25000U }
	How long the application waits at each blocking step. More...
enum	wifi_hal_fmt_t : uint16_t {   k_wifi_hal_str_max = 256U ,   k_wifi_hal_dec_radix = 10U ,   k_wifi_hal_dec_digits = 10U ,   k_wifi_hal_hex_digits = 8U ,   k_wifi_hal_hex_bits = 4U ,   k_wifi_hal_hex_mask = 0x0FU ,   k_wifi_hal_hex_alpha = 10U ,   k_wifi_hal_hex_byte = 2U ,   k_wifi_hal_ip_octets = 4U ,   k_wifi_hal_ip_mask = 0xFFU }
	Widths the bounded console formatters work to. More...
enum	wifi_hal_ip_shift_t : uint8_t {   k_wifi_hal_ip_shift_0 = 24U ,   k_wifi_hal_ip_shift_1 = 16U ,   k_wifi_hal_ip_shift_2 = 8U ,   k_wifi_hal_ip_shift_3 = 0U }
	Bit shifts that pick each octet out of a packed IPv4 address. More...

Functions
bool	wifi_hal_join_run (const wifi_hal_run_cfg_t *cfg, wifi_hal_result_t *out)
	The example's whole network journey, hardware-free: init, join, DHCP.
ra8_err_t	wifi_hal_ip_bind (void *ip_ctx, const ra8_wifi_mac_t *mac, ra8_wifi_lease_t *out)
	The application's IP provider: a NetX Duo DHCP client to a lease.
void	wifi_hal_puts (const char *text)
	Write a NUL-terminated string to the console, bounded.
void	wifi_hal_put_u32 (uint32_t value)
	Write an unsigned 32-bit value in decimal.
void	wifi_hal_put_hex (uint32_t value, uint8_t digits)
	Write the low digits nibbles of a value in hexadecimal.
void	wifi_hal_put_ip (uint32_t ip)
	Write a packed IPv4 address as a dotted quad.
void	wifi_hal_put_mac (const ra8_wifi_mac_t *mac)
	Write a station MAC as colon-separated hex octets.
void	wifi_hal_print_banner (uint32_t cpuclk_hz, uint32_t pclka_hz)
	Print the start-up banner naming the clocks and the link geometry.

Variables
const char	k_wifi_hal_pass_line []
	The exact PASS line the run prints; the HIL gate keys on it.
const char	k_wifi_hal_fail_line []
	The summary FAIL line the run prints when it did not reach an IP.

Detailed Description

Constants, console formatters and the DHCP provider for the HAL join.

Tag

[Ring 6 / APP] {World: S}

The companion to main.c. It holds the build constants, the bounded console serialisers (so the image needs no printf and no heap), and the one function that is genuinely stack-specific: wifi_hal_ip_bind, the ra8_wifi_ip_bind_fn that runs a NetX Duo DHCP client to a lease. Everything Wi-Fi lives behind ra8_wifi.h – this header adds only what a bench application needs around it.

Copyright

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

Since

0.1.0

Definition in file wifi_hal_join.h.

Typedef Documentation

wifi_hal_result_t

typedef struct wifi_hal_result wifi_hal_result_t

wifi_hal_run_cfg_t

typedef struct wifi_hal_run_cfg wifi_hal_run_cfg_t

Enumeration Type Documentation

wifi_hal_cfg_t

enum wifi_hal_cfg_t : uint32_t

Clocking, pacing and RAM budgets the application sets.

The SPI bit rate and boot wait are the bench-proven figures the c6 examples settled on. The arena and worker stack size the one link and the one worker thread this image owns.

Invariant

k_wifi_hal_arena_bytes is at least k_ra8_c6link_arena_min.

k_wifi_hal_sck_hz is the rate silicon ran the link at.

Example:

const uint32_t sck = (uint32_t)k_wifi_hal_sck_hz;

See also

ra8_wifi_init

Since

0.1.0

Enumerator
k_wifi_hal_uart_baud	Console rate over the J-Link OB VCOM.
k_wifi_hal_sck_hz	SPI bit rate; the rate silicon ran at.
k_wifi_hal_edge_poll_ms	Poll period for a side-band pin.
k_wifi_hal_boot_wait_ms	Settling delay before the first frame.
k_wifi_hal_heartbeat_ms	Heartbeat gap after the verdict.
k_wifi_hal_worker_stack	Worker-thread stack, in bytes.
k_wifi_hal_worker_prio	Worker priority and preemption cap.
k_wifi_hal_arena_bytes	Decode arena handed to the facade.

Definition at line 50 of file wifi_hal_join.h.

wifi_hal_fmt_t

enum wifi_hal_fmt_t : uint16_t

Widths the bounded console formatters work to.

Restated locally so the console loops have named bounds (NASA Rule 2) without reaching into another example's header.

Invariant

k_wifi_hal_dec_digits holds the widest 32-bit decimal value.

k_wifi_hal_ip_octets is four, the octet count of an IPv4 address.

Example:

wifi_hal_put_hex(chip_id, (uint8_t)k_wifi_hal_hex_byte);

See also

wifi_hal_put_u32

Since

0.1.0

Enumerator
k_wifi_hal_str_max	Longest string the console helper emits.
k_wifi_hal_dec_radix	Decimal radix.
k_wifi_hal_dec_digits	Digits in the widest 32-bit decimal value.
k_wifi_hal_hex_digits	Digits in the widest 32-bit hex value.
k_wifi_hal_hex_bits	Bits per hexadecimal digit.
k_wifi_hal_hex_mask	Nibble mask.
k_wifi_hal_hex_alpha	First nibble value spelled with a letter.
k_wifi_hal_hex_byte	Hex digits printed for a byte-wide field.
k_wifi_hal_ip_octets	Octets in an IPv4 address.
k_wifi_hal_ip_mask	Single-octet mask for IPv4 formatting.

Definition at line 106 of file wifi_hal_join.h.

wifi_hal_ip_shift_t

enum wifi_hal_ip_shift_t : uint8_t

Bit shifts that pick each octet out of a packed IPv4 address.

Separated from wifi_hal_fmt_t only to keep an 8-bit shift set in its own smallest type.

Invariant

The four shifts are 24, 16, 8 and 0, high octet first.

Each shift is a multiple of eight.

Example:

const uint8_t o0 = (uint8_t)((ip >> k_wifi_hal_ip_shift_0) & k_wifi_hal_ip_mask);

See also

wifi_hal_put_ip

Since

0.1.0

Enumerator
k_wifi_hal_ip_shift_0	Shift for the first (highest) octet.
k_wifi_hal_ip_shift_1	Shift for the second octet.
k_wifi_hal_ip_shift_2	Shift for the third octet.
k_wifi_hal_ip_shift_3	Shift for the fourth (lowest) octet.

Definition at line 133 of file wifi_hal_join.h.

wifi_hal_wait_t

enum wifi_hal_wait_t : uint32_t

How long the application waits at each blocking step.

ra8_wifi_connect blocks internally, but a slow association may outlast its budget, so the application then pumps ra8_wifi_poll a bounded number of times. The DHCP wait is the NetX lease budget.

Invariant

k_wifi_hal_assoc_polls is non-zero, so at least one poll runs.

k_wifi_hal_dhcp_wait_ms comfortably exceeds one DHCP exchange.

Example:

for (uint32_t i = 0U; i < (uint32_t)k_wifi_hal_assoc_polls; i++) { ... }

See also

ra8_wifi_poll

Since

0.1.0

Enumerator
k_wifi_hal_assoc_polls	Extra association polls after connect.
k_wifi_hal_assoc_gap_ms	Gap between association polls.
k_wifi_hal_dhcp_wait_ms	DHCP lease wait budget, ticks.

Definition at line 81 of file wifi_hal_join.h.

Function Documentation

wifi_hal_ip_bind()

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

nodiscard

The application's IP provider: a NetX Duo DHCP client to a lease.

The ra8_wifi_ip_bind_fn ra8_wifi_wait_ip calls. It binds the wireless NetX link driver to the open C6 link, creates the packet pool and IP instance, runs the vendored DHCP client to a bound lease, and copies the lease out. From here NetX Duo owns the wire.

Parameters

[in]	ip_ctx	The open ra8_c6link_t* this application passed as ra8_wifi_cfg::ip_ctx; must be non-null.
[in]	mac	The station MAC the IP stack must adopt; must be non-null.
[out]	out	Lease to fill; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	A lease was obtained and copied into out.
k_ra8_err_null_ptr	An argument was null.
k_ra8_err_not_initialized	The NetX objects could not be created.
k_ra8_err_timeout	DHCP did not bind within k_wifi_hal_dhcp_wait_ms.

Precondition

The station is associated (ra8_wifi_connect has succeeded).

ip_ctx is the same open link the facade drives.

Postcondition

On success out->bound is implied by a non-zero out->ip.

On failure out is cleared.

Note

Runs once, on the worker thread, inside ra8_wifi_wait_ip.

Warning

Blocks up to k_wifi_hal_dhcp_wait_ms waiting for the lease.

Example:

cfg.ip_bind = wifi_hal_ip_bind;
cfg.ip_ctx  = &s_link;

See also

ra8_wifi_wait_ip

Since

0.1.0

Definition at line 147 of file wifi_hal_ip.c.

References ra8_wifi_lease::bound, ra8_wifi_lease::ip, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_err_timeout, k_ra8_ok, nx_ether_driver_c6_bind(), nx_ether_driver_c6_set_mac(), ra8_wifi_mac::octet, priv_net_create_ip(), and priv_net_dhcp().

Referenced by wifi_hal_make_cfg().

wifi_hal_join_run()

bool wifi_hal_join_run ( const wifi_hal_run_cfg_t * cfg, wifi_hal_result_t * out )

nodiscard

The example's whole network journey, hardware-free: init, join, DHCP.

The wiring this example demonstrates, extracted so it is testable on the host exactly as it runs on the board. It initialises the facade, checks that runtime credentials are non-empty, connects, settles the association, reads the MAC and AP record, and obtains an IP – recording each fact in out and stopping at the first step that fails. It performs no I/O of its own; the caller prints from out.

Parameters

[in]	cfg	Injected dependencies; must be non-null with a facade config and handle.
[out]	out	Result to populate; must be non-null.

Returns

true when the journey reached a bound IP (out->passed).

Return values

true	The station associated and DHCP leased an address.
false	A step failed; out says how far it got.

Precondition

The facade config's backend hardware (or mock) is ready.

cfg->ssid is NUL-terminated.

Postcondition

out is fully populated, including on every failure path.

On success out->ip_bound and out->passed are true.

Note

Not thread-safe; it drives the facade. Touches no hardware, RTOS or console, so it runs unchanged in a host test.

Example:

wifi_hal_result_t res = {};
if (wifi_hal_join_run(&cfg, &res)) { announce(res.lease.ip); }

See also

wifi_hal_result

Since

0.1.0

Definition at line 71 of file wifi_hal_core.c.

References wifi_hal_result::ap, wifi_hal_result::associated, wifi_hal_result::connect_err, wifi_hal_result::init_err, wifi_hal_result::init_ok, wifi_hal_result::ip_bound, wifi_hal_result::ip_err, k_ra8_err_not_initialized, k_ra8_ok, wifi_hal_result::lease, wifi_hal_result::mac, wifi_hal_result::passed, wifi_hal_run_cfg::poll_budget, wifi_hal_run_cfg::psk, ra8_wifi_connect(), ra8_wifi_get_ap(), ra8_wifi_get_mac(), ra8_wifi_init(), ra8_wifi_wait_ip(), wifi_hal_run_cfg::ssid, wifi_hal_run_cfg::wifi, wifi_hal_run_cfg::wifi_cfg, and wifi_hal_settle().

Referenced by wifi_hal_run().

wifi_hal_print_banner()

void wifi_hal_print_banner	(	uint32_t	cpuclk_hz,
		uint32_t	pclka_hz )

Print the start-up banner naming the clocks and the link geometry.

Emits application identity, measured clock values, and immutable C6 transport bounds through the bounded console helpers.

Parameters

[in]	cpuclk_hz	CPUCLK0 rate in hertz.
[in]	pclka_hz	PCLKA rate in hertz.

Returns

Nothing.

Precondition

The console has been initialised.

Both rates are the live cached values.

Postcondition

One multi-line banner was emitted.

No state beyond the UART is touched.

Note

Not thread-safe.

See also

wifi_hal_puts

Since

0.1.0

Definition at line 106 of file wifi_hal_console.c.

References k_ra8_board_pmod1_sci_channel, k_ra8_c6link_frame_bytes, k_wifi_hal_sck_hz, wifi_hal_put_u32(), and wifi_hal_puts().

Referenced by main().

wifi_hal_put_hex()

void wifi_hal_put_hex	(	uint32_t	value,
		uint8_t	digits )

Write the low digits nibbles of a value in hexadecimal.

Extracts each requested nibble from most to least significant position and translates it through an immutable lowercase alphabet.

Parameters

[in]	value	Value whose low nibbles are printed.
[in]	digits	Hex digits to print; 1..k_wifi_hal_hex_digits.

Returns

Nothing.

Precondition

digits is in range, else the call is a no-op.

The console has been initialised.

Postcondition

Exactly digits characters were emitted on the valid path.

No state beyond the UART is touched.

Note

Not thread-safe.

See also

wifi_hal_put_u32

Since

0.1.0

Definition at line 60 of file wifi_hal_console.c.

References k_wifi_hal_hex_alpha, k_wifi_hal_hex_bits, k_wifi_hal_hex_digits, k_wifi_hal_hex_mask, and ra8_board_uart_console_write().

Referenced by wifi_hal_put_mac().

wifi_hal_put_ip()

void wifi_hal_put_ip

(

uint32_t

ip

)

Write a packed IPv4 address as a dotted quad.

Extracts the four host-order octets in display order and delegates decimal conversion while inserting fixed period separators.

Parameters

[in]

ip

Address in host order, high octet in the most significant byte.

Returns

Nothing.

Precondition

The console has been initialised.

ip is host-order packed, as NetX returns it.

Postcondition

Four octets separated by dots were emitted.

No state beyond the UART is touched.

Note

Not thread-safe.

See also

wifi_hal_put_u32

Since

0.1.0

Write a packed IPv4 address as a dotted quad.

Definition at line 77 of file wifi_hal_console.c.

References k_wifi_hal_ip_mask, k_wifi_hal_ip_octets, k_wifi_hal_ip_shift_0, k_wifi_hal_ip_shift_1, k_wifi_hal_ip_shift_2, k_wifi_hal_ip_shift_3, wifi_hal_put_u32(), and wifi_hal_puts().

Referenced by wifi_hal_print_lease().

wifi_hal_put_mac()

void wifi_hal_put_mac

(

const ra8_wifi_mac_t *

mac

)

Write a station MAC as colon-separated hex octets.

Walks the fixed address extent in wire order and delegates each two-digit octet conversion while inserting colon separators.

Parameters

[in]

mac

Address to print, or null for a no-op.

Returns

Nothing.

Precondition

mac, when non-null, holds k_ra8_wifi_mac_bytes octets.

The console has been initialised.

Postcondition

Six octets separated by colons were emitted on the valid path.

No state beyond the UART is touched.

Note

Not thread-safe.

See also

wifi_hal_put_hex

Since

0.1.0

Definition at line 93 of file wifi_hal_console.c.

References k_ra8_wifi_mac_bytes, k_wifi_hal_hex_byte, ra8_wifi_mac::octet, wifi_hal_put_hex(), and wifi_hal_puts().

Referenced by wifi_hal_report().

wifi_hal_put_u32()

void wifi_hal_put_u32

(

uint32_t

value

)

Write an unsigned 32-bit value in decimal.

Generates decimal digits into a fixed local buffer from the end toward the front, then emits only the populated suffix.

Parameters

[in]

value

Value to write.

Returns

Nothing.

Precondition

The console has been initialised.

The caller accepts base-ten output only.

Postcondition

Between one and k_wifi_hal_dec_digits characters were emitted.

No state beyond the UART is touched.

Note

Not thread-safe.

See also

wifi_hal_put_hex

Since

0.1.0

Write an unsigned 32-bit value in decimal.

Definition at line 42 of file wifi_hal_console.c.

References k_wifi_hal_dec_digits, k_wifi_hal_dec_radix, and ra8_board_uart_console_write().

Referenced by wifi_hal_print_banner(), wifi_hal_put_ip(), and wifi_hal_report().

wifi_hal_puts()

void wifi_hal_puts

(

const char *

text

)

Write a NUL-terminated string to the console, bounded.

Measures the string within the application maximum and forwards exactly that byte extent to the initialized board console.

Parameters

[in]

text

String to write, or null for a no-op; at most k_wifi_hal_str_max octets are emitted.

Returns

Nothing.

Precondition

text is NUL-terminated within k_wifi_hal_str_max octets.

The console has been initialised.

Postcondition

At most k_wifi_hal_str_max octets were written.

No state beyond the UART is touched.

Note

Not thread-safe; call from one context.

See also

wifi_hal_put_u32

Since

0.1.0

Definition at line 29 of file wifi_hal_console.c.

References k_wifi_hal_str_max, and ra8_board_uart_console_write().

Referenced by main(), tx_application_define(), wifi_hal_heartbeat(), wifi_hal_print_banner(), wifi_hal_print_lease(), wifi_hal_put_ip(), wifi_hal_put_mac(), wifi_hal_report(), wifi_hal_run(), and wifi_hal_worker_entry().

Variable Documentation

k_wifi_hal_fail_line

const char k_wifi_hal_fail_line[]

extern

The summary FAIL line the run prints when it did not reach an IP.

The counterpart to k_wifi_hal_pass_line; specific failures also print a diagnostic sub-line that HIL_EXPECT_NEGATIVE matches.

Since

0.1.0

Definition at line 32 of file wifi_hal_core.c.

Referenced by wifi_hal_worker_entry().

k_wifi_hal_pass_line

const char k_wifi_hal_pass_line[]

extern

The exact PASS line the run prints; the HIL gate keys on it.

Shared by the core (which selects it) and main.c (which prints it), so the string the host test asserts is the string that reaches the console on silicon. hil.conf's HIL_EXPECT is a substring of it.

Since

0.1.0

Definition at line 30 of file wifi_hal_core.c.

Referenced by wifi_hal_worker_entry().