c6_join.h File Reference

Shared contract for the C6 Wi-Fi join + DHCP + reachability app. More...

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

Include dependency graph for c6_join.h:

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

Go to the source code of this file.

Data Structures
struct	c6_join_lease
	What the DHCP bring-up learned, for the verdict and the console. More...

Typedefs
typedef struct c6_join_lease	c6_join_lease_t

Enumerations
enum	c6_join_cfg_t : uint32_t {   k_c6_join_uart_baud = 115200U ,   k_c6_join_sck_hz = 5000000U ,   k_c6_join_edge_poll_ms = 2U ,   k_c6_join_boot_wait_ms = 200U ,   k_c6_join_heartbeat_ms = 5000U ,   k_c6_join_worker_stack = 8192U ,   k_c6_join_worker_prio = 8U ,   k_c6_join_arena_bytes = 4096U }
	Link, thread and pacing parameters this application chooses. More...
enum	c6_join_net_t : uint32_t {   k_c6_join_assoc_tries = 200U ,   k_c6_join_assoc_gap_ms = 50U ,   k_c6_join_dhcp_wait_ms = 25000U ,   k_c6_join_ping_tries = 4U ,   k_c6_join_ping_wait_ms = 2000U ,   k_c6_join_ping_gap_ms = 250U }
	Timing and retry bounds for association, DHCP and the ping. More...
enum	c6_join_fmt_t : uint16_t {   k_c6_join_str_max = 256U ,   k_c6_join_dec_radix = 10U ,   k_c6_join_dec_digits = 10U ,   k_c6_join_hex_digits = 8U ,   k_c6_join_hex_bits = 4U ,   k_c6_join_hex_mask = 0x0FU ,   k_c6_join_hex_alpha = 10U ,   k_c6_join_hex_byte = 2U ,   k_c6_join_ip_octets = 4U ,   k_c6_join_ip_mask = 0xFFU }
	Bounds for the console formatters in src/c6_join_console.c. More...
enum	c6_join_ip_shift_t : uint8_t {   k_c6_join_ip_shift_0 = 24U ,   k_c6_join_ip_shift_1 = 16U ,   k_c6_join_ip_shift_2 = 8U ,   k_c6_join_ip_shift_3 = 0U }
	Byte shifts that split a packed IPv4 address into its four octets. More...

Functions
ra8_err_t	c6_join_net_up (ra8_c6link_t *link, const ra8_c6link_mac_t *mac, c6_join_lease_t *out)
	Bring the IP layer up over the associated C6 link and prove traffic.
void	c6_join_puts (const char *text)
	Write a NUL-terminated string to the board console.
void	c6_join_put_u32 (uint32_t value)
	Emit an unsigned 32-bit value in decimal.
void	c6_join_put_hex (uint32_t value, uint8_t digits)
	Emit a value as a fixed-width lower-case hexadecimal field.
void	c6_join_put_ip (uint32_t ip)
	Emit a packed IPv4 address as a dotted quad.
void	c6_join_put_mac (const ra8_c6link_mac_t *mac)
	Emit an IEEE 802 address as six colon-separated hexadecimal octets.
void	c6_join_print_banner (uint32_t cpuclk_hz, uint32_t pclka_hz)
	Print the banner: identity, clocks and link parameters.

Detailed Description

Shared contract for the C6 Wi-Fi join + DHCP + reachability app.

Tag

[Ring 6 / APP] {World: S}

c6_wifi_link took the ESP32-C6's Wi-Fi station up through ra8_c6link and read its MAC, but joined no network – that was left to #492. This application is #492: it associates the station with the bench access point, runs a NetX Duo DHCP client over the nx_ether_driver_c6 link driver to obtain a lease, and then proves the path carries traffic by pinging the lease's gateway.

Three modules, driven by main.c:

• src/c6_join_console.c – bounded console formatters, so the image links no newlib printf;
• src/c6_join_net.c – the NetX Duo bring-up: packet pool, IP, DHCP client, and the ICMP reachability check;
• main.c – clocks, the station bring-up and join, then the IP bring-up and the single PASS / FAIL verdict.

The image and build graph contain no SSID or passphrase. The worker accepts one bounded versioned provisioning line over the debug UART after boot and explicitly erases the decoded record after association.

Copyright

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

Since

0.1.0

Definition in file c6_join.h.

Typedef Documentation

c6_join_lease_t

typedef struct c6_join_lease c6_join_lease_t

Enumeration Type Documentation

c6_join_cfg_t

enum c6_join_cfg_t : uint32_t

Link, thread and pacing parameters this application chooses.

Only values an application owns live here. This image has no heap (NASA Power of 10 Rule 3), so the worker stack and the decode arena are sized here alongside the link timing. The SPI rate matches the rate the C6 RPC round-trip and c6_wifi_link both ran at on silicon.

Invariant

k_c6_join_sck_hz is the bench-proven bit rate, changed one variable at a time relative to c6_wifi_link.

k_c6_join_arena_bytes is at least k_ra8_c6link_arena_min, which ra8_c6link_open enforces.

Example:

const ra8_esp_hosted_port_cfg_t cfg = { .sck_hz = (uint32_t)k_c6_join_sck_hz };

See also

ra8_esp_hosted_port_cfg_t

Since

0.1.0

Enumerator
k_c6_join_uart_baud	Console rate, 8N1, over the J-Link OB VCOM.
k_c6_join_sck_hz	SPI bit rate; the rate silicon ran at.
k_c6_join_edge_poll_ms	Poll period for a side-band pin with no ICU channel.
k_c6_join_boot_wait_ms	Settling delay before the first transaction.
k_c6_join_heartbeat_ms	Heartbeat gap after the verdict, in milliseconds and therefore in ThreadX ticks.
k_c6_join_worker_stack	Worker-thread stack, in bytes. The protobuf decoder recurses through nested messages.
k_c6_join_worker_prio	Worker priority and preemption threshold.
k_c6_join_arena_bytes	Decode arena handed to the facade.

Definition at line 60 of file c6_join.h.

c6_join_fmt_t

enum c6_join_fmt_t : uint16_t

Bounds for the console formatters in src/c6_join_console.c.

The image links no newlib printf, so the serialisers do their own digit extraction; every loop they run is bounded by a value from this enumeration (NASA Power of 10 Rule 2).

Invariant

k_c6_join_dec_digits holds the widest 32-bit decimal value.

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

Example:

c6_join_put_hex(chip_id, (uint8_t)k_c6_join_hex_byte);

See also

c6_join_put_u32

Since

0.1.0

Enumerator
k_c6_join_str_max	Longest string the console helper emits.
k_c6_join_dec_radix	Decimal radix.
k_c6_join_dec_digits	Digits in the widest 32-bit decimal value.
k_c6_join_hex_digits	Digits in the widest 32-bit hex value.
k_c6_join_hex_bits	Bits per hexadecimal digit.
k_c6_join_hex_mask	Nibble mask.
k_c6_join_hex_alpha	First nibble value spelled with a letter.
k_c6_join_hex_byte	Hex digits printed for a byte-wide field.
k_c6_join_ip_octets	Octets in an IPv4 address.
k_c6_join_ip_mask	Single-octet mask for IPv4 formatting.

Definition at line 114 of file c6_join.h.

c6_join_ip_shift_t

enum c6_join_ip_shift_t : uint8_t

Byte shifts that split a packed IPv4 address into its four octets.

A NetX ULONG IP address is big-endian in value: octet one is the most-significant byte. These shifts pull each octet for dotted-quad printing.

Invariant

The four shifts are 24, 16, 8 and 0, most-significant octet first.

Example:

const uint8_t o0 = (uint8_t)((ip >> k_c6_join_ip_shift_0) & k_c6_join_ip_mask);

See also

c6_join_put_ip

Since

0.1.0

Enumerator
k_c6_join_ip_shift_0	Shift for the first (highest) octet.
k_c6_join_ip_shift_1	Shift for the second octet.
k_c6_join_ip_shift_2	Shift for the third octet.
k_c6_join_ip_shift_3	Shift for the fourth (lowest) octet.

Definition at line 140 of file c6_join.h.

c6_join_net_t

enum c6_join_net_t : uint32_t

Timing and retry bounds for association, DHCP and the ping.

The three waits an IP bring-up performs, all bounded so no loop can spin forever (NASA Power of 10 Rule 2). ThreadX runs at one tick per millisecond in this tree, so a millisecond value doubles as a tick count.

Invariant

k_c6_join_assoc_tries multiplied by k_c6_join_assoc_gap_ms is the total association budget in milliseconds.

k_c6_join_ping_tries is non-zero, so at least one echo is sent.

Example:

const UINT to = (UINT)k_c6_join_dhcp_wait_ms;

See also

c6_join_net_up

Since

0.1.0

Enumerator
k_c6_join_assoc_tries	Association poll attempts before giving up.
k_c6_join_assoc_gap_ms	Gap between association polls, milliseconds.
k_c6_join_dhcp_wait_ms	DHCP lease wait budget, milliseconds/ticks.
k_c6_join_ping_tries	ICMP echoes sent to the gateway.
k_c6_join_ping_wait_ms	Per-echo reply timeout, milliseconds/ticks.
k_c6_join_ping_gap_ms	Gap between echoes, milliseconds.

Definition at line 90 of file c6_join.h.

Function Documentation

c6_join_net_up()

ra8_err_t c6_join_net_up	(	ra8_c6link_t *	link,
		const ra8_c6link_mac_t *	mac,
		c6_join_lease_t *	out )

Bring the IP layer up over the associated C6 link and prove traffic.

Binds nx_ether_driver_c6 to link, hands it the station MAC, creates the NetX Duo packet pool and IP instance, enables ARP / UDP / ICMP, runs the DHCP client to a bound lease, then pings the gateway. It performs no ra8_c6link calls itself after nx_ip_create – from that point the driver's RX worker owns the wire – so the caller must not poll the link directly once this runs.

Parameters

[in]	link	Open, associated C6 link handle; must be non-null.
[in]	mac	Station MAC read with ra8_c6link_wifi_mac; must be non-null.
[out]	out	Lease and reachability result; must be non-null.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	A lease was obtained; out->ping_ok reports reachability.
k_ra8_err_null_ptr	link, mac or out was null.
k_ra8_err_not_initialized	A NetX object could not be created.
k_ra8_err_timeout	No DHCP lease arrived within the budget.

Precondition

The station has associated (k_ra8_c6link_event_sta_connected seen).

The ThreadX kernel is running and NetX has been system-initialised.

Postcondition

On success out holds a non-zero address; on failure out is cleared.

After this returns the C6 link is owned by the driver's RX worker.

Note

Not thread-safe; runs once on the application worker thread.

Warning

Blocks up to k_c6_join_dhcp_wait_ms waiting for the lease.

Example:

c6_join_lease_t lease = {};
(void)c6_join_net_up(&s_link, &mac, &lease);

See also

nx_ether_driver_c6

Since

0.1.0

Definition at line 173 of file c6_join_net.c.

References c6_join_lease::gateway, 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_c6link_mac::octet, c6_join_lease::ping_ok, priv_net_create_ip(), priv_net_dhcp(), and priv_net_ping().

Referenced by c6_join_phase_ip().

c6_join_print_banner()

void c6_join_print_banner	(	uint32_t	cpuclk_hz,
		uint32_t	pclka_hz )

Print the banner: identity, clocks and link parameters.

Emits the application identity followed by measured CPU and peripheral clocks and immutable C6 transport geometry.

Parameters

[in]	cpuclk_hz	Live CPUCLK0 rate in hertz.
[in]	pclka_hz	Live PCLKA rate in hertz, the SCI baud-clock source.

Returns

Nothing.

Precondition

The console is up.

Both rates were read from the CGC rather than assumed.

Postcondition

Three banner lines were emitted.

No application state is modified.

Note

The SPI mode is the co-processor's build (CONFIG_ESP_SPI_MODE=3).

See also

c6_join_puts

Since

0.1.0

Definition at line 104 of file c6_join_console.c.

References c6_join_put_u32(), c6_join_puts(), k_c6_join_sck_hz, k_ra8_board_pmod1_sci_channel, k_ra8_c6link_frame_bytes, and k_ra8_c6link_max_payload.

Referenced by main().

c6_join_put_hex()

void c6_join_put_hex	(	uint32_t	value,
		uint8_t	digits )

Emit a value as a fixed-width lower-case hexadecimal field.

Extracts one nibble per requested digit from most to least significant position and emits a fixed local character buffer.

Parameters

[in]	value	Value to print.
[in]	digits	Field width, 1..k_c6_join_hex_digits; an out-of-range width prints nothing rather than overrunning the array.

Returns

Nothing.

Precondition

The console is up.

digits is within 1..k_c6_join_hex_digits.

Postcondition

Exactly digits characters were emitted, or none on a bad width.

No application state is modified.

Note

The loop is bounded by the range-checked digits (NASA Rule 2).

See also

c6_join_put_u32

Since

0.1.0

Definition at line 58 of file c6_join_console.c.

References k_c6_join_hex_alpha, k_c6_join_hex_bits, k_c6_join_hex_digits, k_c6_join_hex_mask, and ra8_board_uart_console_write().

Referenced by c6_join_phase_ready(), and c6_join_put_mac().

c6_join_put_ip()

void c6_join_put_ip

(

uint32_t

ip

)

Emit a packed IPv4 address as a dotted quad.

Extracts each bounded network octet from most to least significant position and separates decimal forms with periods.

Parameters

[in]

ip

NetX host-order packed IPv4 address.

Returns

Nothing.

Precondition

The console is up.

ip is a NetX ULONG address, most-significant octet first.

Postcondition

Between seven and fifteen characters were emitted.

No application state is modified.

Note

The loop is bounded by k_c6_join_ip_octets (NASA Rule 2).

See also

c6_join_put_u32

Since

0.1.0

Emit a packed IPv4 address as a dotted quad.

Definition at line 75 of file c6_join_console.c.

References c6_join_put_u32(), c6_join_puts(), k_c6_join_ip_mask, k_c6_join_ip_octets, k_c6_join_ip_shift_0, k_c6_join_ip_shift_1, k_c6_join_ip_shift_2, and k_c6_join_ip_shift_3.

Referenced by c6_join_phase_ip().

c6_join_put_mac()

void c6_join_put_mac

(

const ra8_c6link_mac_t *

mac

)

Emit an IEEE 802 address as six colon-separated hexadecimal octets.

Walks the fixed address extent in wire order, printing two hex digits per octet and a colon between adjacent octets.

Parameters

[in]

mac

Address to print; null prints nothing.

Returns

Nothing.

Precondition

The console is up.

mac was filled by ra8_c6link_wifi_mac or is the zero address.

Postcondition

Seventeen characters were emitted, or none on a null argument.

No application state is modified.

Note

The loop is bounded by k_ra8_c6link_mac_bytes (NASA Rule 2).

See also

ra8_c6link_wifi_mac

Since

0.1.0

Definition at line 91 of file c6_join_console.c.

References c6_join_put_hex(), c6_join_puts(), k_c6_join_hex_byte, k_ra8_c6link_mac_bytes, and ra8_c6link_mac::octet.

Referenced by c6_join_phase_associate().

c6_join_put_u32()

void c6_join_put_u32

(

uint32_t

value

)

Emit an unsigned 32-bit value in decimal.

Converts digits into a fixed local buffer in reverse order, then emits the used suffix without allocation or stdio.

Parameters

[in]

value

Value to print; the whole 32-bit range is representable.

Returns

Nothing.

Precondition

The console is up.

The caller wants no padding; zero prints as a single digit.

Postcondition

Between one and k_c6_join_dec_digits characters were emitted.

No application state is modified.

Note

Not thread-safe, for the same reason as c6_join_puts.

See also

c6_join_put_ip

Since

0.1.0

Emit an unsigned 32-bit value in decimal.

Definition at line 40 of file c6_join_console.c.

References k_c6_join_dec_digits, k_c6_join_dec_radix, and ra8_board_uart_console_write().

Referenced by c6_join_phase_associate(), c6_join_phase_ready(), c6_join_print_banner(), c6_join_put_ip(), and c6_join_worker_entry().

c6_join_puts()

void c6_join_puts

(

const char *

text

)

Write a NUL-terminated string to the board console.

Measures at most the fixed string bound and forwards the resulting byte extent to the initialized board-console transmitter.

Parameters

[in]

text

String to emit; null is ignored and the length is capped at k_c6_join_str_max.

Returns

Nothing.

Precondition

ra8_board_uart_console_init has succeeded.

text is NUL-terminated within k_c6_join_str_max bytes.

Postcondition

The bytes are queued on the console transmitter.

No application state is modified.

Note

Not thread-safe; only bring-up and the single worker thread call it.

See also

c6_join_put_u32

Since

0.1.0

Definition at line 27 of file c6_join_console.c.

References k_c6_join_str_max, and ra8_board_uart_console_write().

Referenced by c6_join_heartbeat(), c6_join_phase_associate(), c6_join_phase_ip(), c6_join_phase_ready(), c6_join_print_banner(), c6_join_put_ip(), c6_join_put_mac(), c6_join_report_fault(), c6_join_worker_entry(), main(), and tx_application_define().