ra8_net_provision.h File Reference

Runtime network provisioning contract for EK-RA8D2 applications. More...

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

Include dependency graph for ra8_net_provision.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_net_credentials
	Decoded runtime network configuration. More...
struct	ra8_net_provision_uart
	UART and pacing operations used by the bounded receiver. More...

Typedefs
typedef struct ra8_net_credentials	ra8_net_credentials_t
typedef ra8_err_t(*	ra8_net_provision_uart_write_fn) (const uint8_t *data, size_t length)
	Injected UART write operation.
typedef ra8_err_t(*	ra8_net_provision_uart_read_fn) (uint8_t *data, size_t capacity, size_t *out_length)
	Injected non-blocking UART read operation.
typedef void(*	ra8_net_provision_wait_fn) (uint32_t delay_ms)
	Injected millisecond wait used between incomplete UART polls.
typedef struct ra8_net_provision_uart	ra8_net_provision_uart_t

Enumerations
enum	ra8_net_provision_limit_t : uint16_t {   k_ra8_net_provision_ssid_bytes_max = 32U ,   k_ra8_net_provision_psk_bytes_max = 64U ,   k_ra8_net_provision_url_bytes_max = 511U ,   k_ra8_net_provision_prefix_bytes = 8U ,   k_ra8_net_provision_line_bytes_max = 1225U ,   k_ra8_net_provision_timeout_ms = 30000U ,   k_ra8_net_provision_timeout_ms_max = 60000U }
	Static bounds for the version-one provisioning protocol. More...

Functions
ra8_err_t	ra8_net_provision_parse (const uint8_t *line, size_t line_length, ra8_net_credentials_t *out)
	Parse one complete version-one ASCII-hex provisioning line.
ra8_err_t	ra8_net_provision_receive (const ra8_net_provision_uart_t *uart, uint32_t timeout_ms, ra8_net_credentials_t *out)
	Prompt once and receive one provisioning line within a fixed timeout.
void	ra8_net_provision_clear (ra8_net_credentials_t *credentials)
	Explicitly erase one decoded credential record.

Variables
const char	k_ra8_net_provision_ready_prompt []
	Exact non-secret line emitted before the receiver drains UART input.

Detailed Description

Runtime network provisioning contract for EK-RA8D2 applications.

Tag

[Ring 6 / APP] {World: S}

Defines the credential record, ASCII-hex wire parser, and bounded UART receiver shared by examples that join a network at runtime. The interface keeps credentials out of CMake, compiler command lines, build metadata, and firmware images. UART operations are injected so the exact production parser and receive state machine can run in host tests without hardware.

Copyright

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

Since

0.1.0

Definition in file ra8_net_provision.h.

Typedef Documentation

ra8_net_credentials_t

typedef struct ra8_net_credentials ra8_net_credentials_t

ra8_net_provision_uart_read_fn

typedef ra8_err_t(* ra8_net_provision_uart_read_fn) (uint8_t *data, size_t capacity, size_t *out_length)

Injected non-blocking UART read operation.

Parameters

[out]	data	Destination buffer.
[in]	capacity	Writable bytes in data.
[out]	out_length	Number of bytes drained during this call.

Returns

Repository error code from the UART implementation.

Definition at line 101 of file ra8_net_provision.h.

ra8_net_provision_uart_t

typedef struct ra8_net_provision_uart ra8_net_provision_uart_t

ra8_net_provision_uart_write_fn

typedef ra8_err_t(* ra8_net_provision_uart_write_fn) (const uint8_t *data, size_t length)

Injected UART write operation.

Parameters

[in]	data	Bytes to transmit; non-null when length is non-zero.
[in]	length	Number of bytes to transmit.

Returns

Repository error code from the UART implementation.

Definition at line 91 of file ra8_net_provision.h.

ra8_net_provision_wait_fn

typedef void(* ra8_net_provision_wait_fn) (uint32_t delay_ms)

Injected millisecond wait used between incomplete UART polls.

Parameters

[in]

delay_ms

Delay interval in milliseconds.

Returns

Nothing.

Definition at line 111 of file ra8_net_provision.h.

Enumeration Type Documentation

ra8_net_provision_limit_t

enum ra8_net_provision_limit_t : uint16_t

Static bounds for the version-one provisioning protocol.

The maximum wire line includes the fixed prefix, three fields, two separators, and one newline. Every receive and decode loop is bounded by one of these values.

Invariant

The text capacities include one trailing NUL beyond the protocol payload maxima.

The maximum line fits in a 16-bit length.

Example:

uint8_t line[k_ra8_net_provision_line_bytes_max];

See also

ra8_net_provision_parse

Since

0.1.0

Enumerator
k_ra8_net_provision_ssid_bytes_max	Maximum decoded SSID bytes.
k_ra8_net_provision_psk_bytes_max	Maximum decoded PSK text bytes.
k_ra8_net_provision_url_bytes_max	Maximum decoded optional URL.
k_ra8_net_provision_prefix_bytes	Bytes in RA8NET1:.
k_ra8_net_provision_line_bytes_max	Longest complete encoded line.
k_ra8_net_provision_timeout_ms	Standard application RX timeout.
k_ra8_net_provision_timeout_ms_max	Longest accepted receive timeout.

Definition at line 43 of file ra8_net_provision.h.

Function Documentation

ra8_net_provision_clear()

void ra8_net_provision_clear

(

ra8_net_credentials_t *

credentials

)

Explicitly erase one decoded credential record.

Uses the repository secure-memory primitive so optimization cannot discard the overwrite. A null record is accepted for cleanup paths that do not know whether provisioning completed.

Parameters

[in,out]

credentials

Record to erase; null is a no-op.

Returns

Nothing.

Precondition

credentials is null or addresses a writable record.

No concurrent consumer is reading the record.

Postcondition

Every byte in a non-null record is zero.

The erase cannot be removed as a dead store by optimization.

Note

Call immediately after the final synchronous credential consumer.

Warning

This does not erase copies already retained by another subsystem.

Since

0.1.0

Definition at line 350 of file ra8_net_provision.c.

References ra8_secure_memzero().

Referenced by c6_join_worker_entry(), internal_c6_cam_worker_entry(), internal_worker(), ra8_net_provision_parse(), ra8_net_provision_receive(), and wifi_hal_worker_entry().

ra8_net_provision_parse()

ra8_err_t ra8_net_provision_parse ( const uint8_t * line, size_t line_length, ra8_net_credentials_t * out )

nodiscard

Parse one complete version-one ASCII-hex provisioning line.

Accepts exactly RA8NET1:<ssid_hex>:<psk_hex>:<url_hex>\n. Each pair of hexadecimal characters decodes to one output byte. SSID is required and at most 32 bytes. PSK is 8..63 bytes, or exactly 64 hexadecimal characters. URL is optional and at most 511 bytes. Decoded C0 and DEL control bytes are rejected because the existing Wi-Fi and media APIs consume printable text.

Parameters

[in]	line	Complete line bytes, including the final newline.
[in]	line_length	Number of readable bytes at line.
[out]	out	Decoded record; cleared before parsing and on every failure.

Returns

Repository error code.

Return values

k_ra8_ok	The complete line was valid and decoded.
k_ra8_err_null_ptr	line or out was null.
k_ra8_err_invalid_size	A line or decoded field exceeded its bound.
k_ra8_err_protocol_error	Prefix, separators, newline, or hex syntax was invalid.

Precondition

line addresses line_length readable bytes when non-null.

out addresses one writable credential record.

Postcondition

On success, every output field is bounded and NUL-terminated.

On failure, every byte of out is zero.

Note

Thread-safe for distinct input and output objects.

Warning

Treat the input and successful output as secret-bearing memory.

Since

0.1.0

Definition at line 358 of file ra8_net_provision.c.

References internal_decode_line(), internal_prefix_matches(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_err_protocol_error, k_ra8_net_provision_line_bytes_max, k_ra8_net_provision_prefix_bytes, k_ra8_ok, and ra8_net_provision_clear().

Referenced by ra8_net_provision_receive().

ra8_net_provision_receive()

ra8_err_t ra8_net_provision_receive ( const ra8_net_provision_uart_t * uart, uint32_t timeout_ms, ra8_net_credentials_t * out )

nodiscard

Prompt once and receive one provisioning line within a fixed timeout.

Writes k_ra8_net_provision_ready_prompt, then drains the injected non-blocking UART into fixed stack storage. It never echoes input. Every incomplete poll waits one millisecond; therefore timeout_ms is both the poll limit and a lower bound on elapsed wait time. The budget is capped at 60 seconds. The raw line buffer is explicitly zeroed before every return.

Parameters

[in]	uart	Complete UART operation table.
[in]	timeout_ms	Receive budget in milliseconds, 1..60000.
[out]	out	Decoded record; cleared before receive and on every failure.

Returns

Repository error code.

Return values

k_ra8_ok	One valid line was received and decoded.
k_ra8_err_null_ptr	uart, an operation row, or out was null.
k_ra8_err_invalid_arg	timeout_ms was zero or above the fixed cap.
k_ra8_err_invalid_size	Input filled the fixed line buffer.
k_ra8_err_timeout	No complete line arrived within the budget.
k_ra8_err_protocol_error	The complete line was malformed.

Precondition

The UART was initialized before this call.

read is non-blocking and never reports more than its capacity.

Postcondition

The prompt was attempted before the first read.

Raw line storage is zeroed and failure leaves out zeroed.

Note

Not thread-safe when callers share one UART.

Warning

The UART is a controlled-bench provisioning channel, not durable storage.

Since

0.1.0

Definition at line 520 of file ra8_net_provision.c.

References internal_receive_line(), internal_validate_receiver(), k_ra8_err_null_ptr, k_ra8_net_provision_line_bytes_max, k_ra8_net_provision_ready_prompt, k_ra8_ok, ra8_net_provision_clear(), ra8_net_provision_parse(), ra8_secure_memzero(), and ra8_net_provision_uart::write.

Referenced by c6_join_worker_entry(), internal_c6_cam_worker_entry(), internal_worker(), and wifi_hal_worker_entry().

Variable Documentation

k_ra8_net_provision_ready_prompt

const char k_ra8_net_provision_ready_prompt[]

extern

Exact non-secret line emitted before the receiver drains UART input.

The HIL provisioner waits for this versioned prompt before sending one RA8NET1 line to a freshly flashed credential-free image.

Note

This constant never contains user or network data.

Since

0.1.0

Definition at line 77 of file ra8_net_provision.c.

Referenced by ra8_net_provision_receive().