Cellular modem AT command/response driver implementation. More...

#include "ra8_modem_at.h"
#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_modem_at_internal.h"

Include dependency graph for ra8_modem_at.c:

Data Structures
struct	ra8_modem_at_urc_slot_t
	One URC table entry. More...
struct	ra8_modem_at_module_t
	Aggregated module state. More...
struct	ra8_modem_wait_ctx_t
	Bundled args + state for one iteration of the wait loop. More...

Macros
#define	RA8_MODEM_AT_TAG "MODEM_AT"
	Component log tag.

Enumerations
enum	ra8_modem_at_internal_const_t : uint16_t { k_ra8_modem_at_min_line_buf_bytes = 16U }
	Internal numeric constants used by the AT driver. More...
enum	ra8_modem_at_state_t : uint8_t { k_ra8_modem_at_state_idle = 0U , k_ra8_modem_at_state_await_echo = 1U , k_ra8_modem_at_state_await_resp = 2U , k_ra8_modem_at_state_done = 3U }
	Internal line-accumulator FSM states. More...
enum	ra8_modem_line_action_t : uint8_t { k_ra8_modem_line_action_continue = 0U , k_ra8_modem_line_action_done_ok = 1U , k_ra8_modem_line_action_done_err = 2U }
	Outcome of handling one classified line in internal_wait_response. More...

Functions
uint16_t	priv_modem_str_len (const char *s)
	NUL-terminated string length.
uint8_t	priv_modem_starts_with (const char hay, const char needle)
	Return 1 if hay begins with needle.
uint8_t	priv_modem_str_eq (const char a, const char b)
	Compare two NUL-terminated strings for exact equality.
static void	internal_append_ch (char out, size_t out_len, size_t used, char ch)
	Append a single character to out if there is room.
uint8_t	priv_modem_reset_line_should_clear (const void *line_buf, uint16_t line_buf_len)
	Pure helper for the internal_reset_line line-227 AND.
uint8_t	priv_modem_payload_prefix_matches (const char line, const char expected_response)
	Production carrier of the line-573 payload-prefix AND-decision.
uint8_t	priv_modem_capture_should_clear (const void *capture, size_t capture_len)
	Production carrier of the line-664 capture-init AND-decision.
static void	internal_reset_line (void)
	Reset the line accumulator for a fresh command cycle.
static uint8_t	internal_classify_final (const char line, uint8_t is_error)
	Test whether line is a final OK/ERROR result code.
static uint8_t	internal_dispatch_urc (const char *line)
	Dispatch a URC line to any matching registered handler.
ra8_modem_line_kind_t	priv_modem_classify (const char line, const char cmd_echo, const char *expected_response)
	Classify a complete (NUL-terminated) line for the FSM.
static void	internal_accumulate (uint8_t byte, const char **line_out)
	Push a single received byte into the line accumulator.
static ra8_err_t	internal_tx_command (const char *s)
	Transmit a NUL-terminated string then "\r".
static uint16_t	internal_effective_timeout (uint16_t timeout_ms)
	Resolve effective timeout in ms, applying default if 0.
void	priv_modem_capture_line (const char line, char capture, size_t capture_len, size_t *used)
	Append a NUL-terminated line into capture (with newline sep).
static ra8_modem_line_action_t	internal_handle_line (const char line, ra8_modem_line_kind_t kind, const char expected_response, uint8_t seen_exp, char capture, size_t capture_len, size_t *used)
	Drive the response FSM by one classified line.
static ra8_modem_line_action_t	internal_pump_one (const ra8_modem_wait_ctx_t *wc)
	Pull one byte and process any completed line.
static ra8_err_t	internal_wait_response (const char cmd, const char expected_response, uint16_t timeout_ms, char *capture, size_t capture_len)
	Inner wait loop shared by send_cmd and send_cmd_capture.
static void	internal_clear_urc_table (void)
	Reset the URC dispatch table to all-empty.
static ra8_err_t	internal_validate_init_cfg (const ra8_modem_at_cfg_t *cfg)
	Validate every required pointer in `cfg's` IO block.
ra8_err_t	ra8_modem_at_init (const ra8_modem_at_cfg_t *cfg)
	Bind transport, buffer and timeout policy.
ra8_err_t	ra8_modem_at_send_cmd (const char cmd, const char expected_response, uint16_t timeout_ms)
	Send an AT command and wait for OK/ERROR/expected.
ra8_err_t	ra8_modem_at_send_cmd_capture (const char cmd, char out_buf, size_t buf_len, uint16_t timeout_ms)
	Send an AT command and capture the response payload.
static uint8_t	internal_urc_replace (const char prefix, ra8_modem_at_urc_fn_t fn, void ctx)
	Find an existing URC slot for prefix and update its callback.
static uint8_t	internal_urc_insert (const char prefix, uint16_t plen, ra8_modem_at_urc_fn_t fn, void ctx)
	Allocate the first free URC slot and copy the prefix into it.
ra8_err_t	ra8_modem_at_register_unsolicited_handler (const char prefix, ra8_modem_at_urc_fn_t fn, void ctx)
	Register a URC (unsolicited result code) handler.
ra8_err_t	ra8_modem_at_poll (void)
	Pump the RX path without sending a command.

Variables
static ra8_modem_at_module_t	s_mod
	Singleton module state (file scope, NASA Rule 6).

Detailed Description

Cellular modem AT command/response driver implementation.

Tag: [Ring 4 / PAL] {World: NS}

See ra8_modem_at.h for the public contract. This file implements the line accumulator state machine and the URC dispatch table. All buffers are statically allocated – the caller-owned line buffer is referenced by pointer.

The string utilities at the top of the file are project-local replacements for strlen/strncmp to keep the build free of string.h per the existing convention in libs/ra8_net_pal/src/ra8_net_pal.c.

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

Definition in file ra8_modem_at.c.

Macro Definition Documentation

◆ RA8_MODEM_AT_TAG

#define RA8_MODEM_AT_TAG "MODEM_AT"

Component log tag.

Definition at line 38 of file ra8_modem_at.c.

Referenced by internal_handle_line(), internal_validate_init_cfg(), ra8_modem_at_register_unsolicited_handler(), ra8_modem_at_send_cmd(), and ra8_modem_at_send_cmd_capture().

Enumeration Type Documentation

◆ ra8_modem_at_internal_const_t

enum ra8_modem_at_internal_const_t : uint16_t

Internal numeric constants used by the AT driver.

Enumerator
k_ra8_modem_at_min_line_buf_bytes	Minimum line buffer length.

Definition at line 44 of file ra8_modem_at.c.

◆ ra8_modem_at_state_t

enum ra8_modem_at_state_t : uint8_t

Internal line-accumulator FSM states.

The state moves only forward through the cycle idle -> await_echo -> await_resp -> done -> idle. Echo handling is best-effort: if the modem has ATE0 active and never echoes, the first non-empty line transitions the FSM directly into await_resp.

Enumerator
k_ra8_modem_at_state_idle	No command in flight.
k_ra8_modem_at_state_await_echo	Sent command, waiting for echo line.
k_ra8_modem_at_state_await_resp	Echo seen (or skipped), draining.
k_ra8_modem_at_state_done	Final result code matched.

Definition at line 59 of file ra8_modem_at.c.

◆ ra8_modem_line_action_t

enum ra8_modem_line_action_t : uint8_t

Outcome of handling one classified line in internal_wait_response.

Enumerator
k_ra8_modem_line_action_continue	Keep waiting.
k_ra8_modem_line_action_done_ok	Final OK observed.
k_ra8_modem_line_action_done_err	Final error observed.

Definition at line 557 of file ra8_modem_at.c.

Function Documentation

◆ internal_accumulate()

void internal_accumulate	(	uint8_t	byte,
		const char **	line_out )

static

Push a single received byte into the line accumulator.

Parameters

[in]	byte	Just-received byte.
[out]	line_out	If a complete line is now ready, set to cfg.line_buf (NUL-terminated). Otherwise NULL.

See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 476 of file ra8_modem_at.c.

References s_mod.

Referenced by internal_pump_one(), and ra8_modem_at_poll().

◆ internal_append_ch()

void internal_append_ch	(	char *	out,
		size_t	out_len,
		size_t *	used,
		char	ch )

static

Append a single character to out if there is room.

Parameters

[in,out]	out	Output buffer (NUL-terminated on entry).
[in]	out_len	Total capacity of out.
[in,out]	used	Current populated length (excluding NUL).
[in]	ch	Character to append.

See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 206 of file ra8_modem_at.c.

Referenced by priv_modem_capture_line().

◆ internal_classify_final()

uint8_t internal_classify_final	(	const char *	line,
		uint8_t *	is_error )

static

Test whether line is a final OK/ERROR result code.

Parameters

[in]	line	NUL-terminated received line.
[out]	is_error	Set to 1 if line is an error result.

Returns: 1 if line is any final result code, 0 otherwise.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 353 of file ra8_modem_at.c.

References priv_modem_starts_with(), and priv_modem_str_eq().

Referenced by priv_modem_classify().

◆ internal_clear_urc_table()

void internal_clear_urc_table ( void )

static

Reset the URC dispatch table to all-empty.

See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 783 of file ra8_modem_at.c.

References k_ra8_modem_at_max_unsolicited, and s_mod.

Referenced by ra8_modem_at_init().

◆ internal_dispatch_urc()

uint8_t internal_dispatch_urc ( const char * line )

static

Dispatch a URC line to any matching registered handler.

Parameters

[in] line NUL-terminated line.

Returns: 1 if a handler matched, 0 otherwise.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 398 of file ra8_modem_at.c.

References k_ra8_modem_at_max_unsolicited, priv_modem_starts_with(), and s_mod.

Referenced by priv_modem_classify().

◆ internal_effective_timeout()

uint16_t internal_effective_timeout ( uint16_t timeout_ms )

static

Resolve effective timeout in ms, applying default if 0.

See implementation.

Parameters

[in] timeout_ms See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 542 of file ra8_modem_at.c.

References k_ra8_modem_at_default_timeout_ms, and s_mod.

Referenced by ra8_modem_at_send_cmd(), and ra8_modem_at_send_cmd_capture().

◆ internal_handle_line()

ra8_modem_line_action_t internal_handle_line	(	const char *	line,
		ra8_modem_line_kind_t	kind,
		const char *	expected_response,
		uint8_t *	seen_exp,
		char *	capture,
		size_t	capture_len,
		size_t *	used )

static

Drive the response FSM by one classified line.

Parameters

[in]	line	Just-completed line.
[in]	kind	Result of internal_classify.
[in]	expected_response	Optional caller-supplied prefix.
[in,out]	seen_exp	Sticky flag: prefix has been observed.
[out]	capture	Optional capture buffer.
[in]	capture_len	Capacity of capture.
[in,out]	used	Bytes already populated in capture.

Returns: One of ra8_modem_line_action_t.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 615 of file ra8_modem_at.c.

References k_ra8_modem_at_state_await_echo, k_ra8_modem_at_state_await_resp, k_ra8_modem_at_state_done, k_ra8_modem_line_action_continue, k_ra8_modem_line_action_done_err, k_ra8_modem_line_action_done_ok, k_ra8_modem_line_kind_echo, k_ra8_modem_line_kind_empty, k_ra8_modem_line_kind_final_err, k_ra8_modem_line_kind_final_ok, k_ra8_modem_line_kind_payload, k_ra8_modem_line_kind_urc, priv_modem_capture_line(), priv_modem_payload_prefix_matches(), ra8_log_error, RA8_MODEM_AT_TAG, and s_mod.

Referenced by internal_pump_one().

◆ internal_pump_one()

ra8_modem_line_action_t internal_pump_one ( const ra8_modem_wait_ctx_t * wc )

static

Pull one byte and process any completed line.

Returns: The line action (continue / done_ok / done_err).

See implementation.

Parameters

[in] wc See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 681 of file ra8_modem_at.c.

References ra8_modem_wait_ctx_t::capture, ra8_modem_wait_ctx_t::capture_len, ra8_modem_wait_ctx_t::cmd, ra8_modem_wait_ctx_t::expected_response, internal_accumulate(), internal_handle_line(), k_ra8_modem_line_action_continue, k_ra8_ok, priv_modem_classify(), s_mod, ra8_modem_wait_ctx_t::seen_exp, and ra8_modem_wait_ctx_t::used.

Referenced by internal_wait_response().

◆ internal_reset_line()

void internal_reset_line ( void )

static

Reset the line accumulator for a fresh command cycle.

Forwards the buffer-installed predicate to priv_modem_reset_line_should_clear so the line-249 AND-decision is exercised in a pure free function where tests can vary both inputs.

Precondition: Module state is consistent.; Caller holds the module lock.

Postcondition: Line accumulator is empty.; Configured line buffer's first byte is NUL when present.

Note: Not thread-safe; caller serialises access.

Since: 0.1.0

Definition at line 328 of file ra8_modem_at.c.

References priv_modem_reset_line_should_clear(), and s_mod.

Referenced by internal_wait_response(), ra8_modem_at_init(), ra8_modem_at_send_cmd(), and ra8_modem_at_send_cmd_capture().

◆ internal_tx_command()

ra8_err_t internal_tx_command ( const char * s )

static

Transmit a NUL-terminated string then "\r".

Parameters

[in] s NUL-terminated string to transmit.

Returns: ra8_err_t propagated from the transport.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 514 of file ra8_modem_at.c.

References k_ra8_ok, and s_mod.

Referenced by ra8_modem_at_send_cmd(), and ra8_modem_at_send_cmd_capture().

◆ internal_urc_insert()

uint8_t internal_urc_insert	(	const char *	prefix,
		uint16_t	plen,
		ra8_modem_at_urc_fn_t	fn,
		void *	ctx )

static

Allocate the first free URC slot and copy the prefix into it.

Returns: 1 on success, 0 if the table is full.

See implementation.

Parameters

[in]	prefix	See implementation.
[in]	plen	See implementation.
[in]	fn	See implementation.
[in]	ctx	See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 931 of file ra8_modem_at.c.

References k_ra8_modem_at_max_unsolicited, and s_mod.

Referenced by ra8_modem_at_register_unsolicited_handler().

◆ internal_urc_replace()

uint8_t internal_urc_replace	(	const char *	prefix,
		ra8_modem_at_urc_fn_t	fn,
		void *	ctx )

static

Find an existing URC slot for prefix and update its callback.

Returns: 1 if a slot matched (and was updated), 0 otherwise.

See implementation.

Parameters

[in]	prefix	See implementation.
[in]	fn	See implementation.
[in]	ctx	See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 897 of file ra8_modem_at.c.

References k_ra8_modem_at_max_unsolicited, priv_modem_str_eq(), and s_mod.

Referenced by ra8_modem_at_register_unsolicited_handler().

◆ internal_validate_init_cfg()

ra8_err_t internal_validate_init_cfg ( const ra8_modem_at_cfg_t * cfg )

static

Validate every required pointer in cfg's IO block.

See implementation.

Parameters

[in] cfg See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 807 of file ra8_modem_at.c.

References ra8_modem_at_cfg_t::io, k_ra8_err_invalid_size, k_ra8_modem_at_min_line_buf_bytes, k_ra8_ok, ra8_modem_at_cfg_t::line_buf, ra8_modem_at_cfg_t::line_buf_len, ra8_modem_at_io_t::now_ms, RA8_CHECK_NULL_PTR, ra8_log_error, RA8_MODEM_AT_TAG, ra8_modem_at_io_t::rx_byte, and ra8_modem_at_io_t::tx_byte.

Referenced by ra8_modem_at_init().

◆ internal_wait_response()

ra8_err_t internal_wait_response	(	const char *	cmd,
		const char *	expected_response,
		uint16_t	timeout_ms,
		char *	capture,
		size_t	capture_len )

static

Inner wait loop shared by send_cmd and send_cmd_capture.

Parameters

[in]	cmd	Command we sent (for echo strip).
[in]	expected_response	Optional expected prefix.
[in]	timeout_ms	Effective timeout in ms (already resolved).
[out]	capture	Optional payload capture buffer (may be NULL).
[in]	capture_len	Capacity of capture.

Returns: ra8_err_t per public docs.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 723 of file ra8_modem_at.c.

References internal_pump_one(), internal_reset_line(), k_ra8_err_hw_error, k_ra8_err_hw_timeout, k_ra8_modem_at_state_await_echo, k_ra8_modem_at_state_idle, k_ra8_modem_line_action_done_err, k_ra8_modem_line_action_done_ok, k_ra8_ok, priv_modem_capture_should_clear(), and s_mod.

Referenced by ra8_modem_at_send_cmd(), and ra8_modem_at_send_cmd_capture().

◆ priv_modem_capture_line()

void priv_modem_capture_line	(	const char *	line,
		char *	capture,
		size_t	capture_len,
		size_t *	used )

Append a NUL-terminated line into capture (with newline sep).

See implementation.

Parameters

[in]	line	See implementation.
[in]	capture	See implementation.
[in]	capture_len	See implementation.
[in]	used	See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 578 of file ra8_modem_at.c.

References internal_append_ch().

Referenced by internal_handle_line().

◆ priv_modem_capture_should_clear()

uint8_t priv_modem_capture_should_clear	(	const void *	capture,
		size_t	capture_len )

Production carrier of the line-664 capture-init AND-decision.

Pure sibling of the line-664 capture-buffer-init AND-decision.

Holds the AND-decision that gates the one-shot capture[0] = '\\0' initialisation in internal_wait_response. Promoted from inline-in-callsite to a TU-external helper so all four input combinations are reachable from a host test (the public send_cmd_capture API rejects capture_len == 0 at the entry guard, so the inline form was structurally limited to (NULL, 0) and (non-NULL, >0)).

Parameters

[in]	capture	Caller-owned capture buffer (NULL allowed).
[in]	capture_len	Capacity of `capture` in bytes.

Returns: 1 iff capture is non-NULL AND capture_len > 0.

Return values

1	Both conditions hold.
0	Either condition fails.

Precondition: None.; None.

Postcondition: No state mutated.; Return value depends solely on the two inputs.

Note: Pure function; thread-safe.

Since: 0.1.0

Definition at line 304 of file ra8_modem_at.c.

Referenced by internal_wait_response().

◆ priv_modem_classify()

ra8_modem_line_kind_t priv_modem_classify	(	const char *	line,
		const char *	cmd_echo,
		const char *	expected_response )

Classify a complete (NUL-terminated) line for the FSM.

The expected-prefix and command-echo arguments are caller-supplied because they vary per command invocation. URC dispatch happens inside this helper so the caller does not need to know about it.

Parameters

[in]	line	NUL-terminated received line.
[in]	cmd_echo	Command we sent (for echo detection), may be NULL when not awaiting echo.
[in]	expected_response	Optional caller-specified prefix.

Returns: One of ra8_modem_line_kind_t.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 438 of file ra8_modem_at.c.

References internal_classify_final(), internal_dispatch_urc(), k_ra8_modem_line_kind_echo, k_ra8_modem_line_kind_empty, k_ra8_modem_line_kind_final_err, k_ra8_modem_line_kind_final_ok, k_ra8_modem_line_kind_payload, k_ra8_modem_line_kind_urc, priv_modem_starts_with(), and priv_modem_str_eq().

Referenced by internal_pump_one(), and ra8_modem_at_poll().

◆ priv_modem_payload_prefix_matches()

uint8_t priv_modem_payload_prefix_matches	(	const char *	line,
		const char *	expected_response )

Production carrier of the line-573 payload-prefix AND-decision.

Pure sibling of the line-573 payload-prefix AND-decision.

Holds the three-condition short-circuit AND that classifies a payload-kind line as matching the caller-supplied expected_response prefix. Promoted from inline-in-callsite to a TU-external helper so all four short-circuit MC/DC vectors can be driven from a host test (the public-API path through send_cmd / send_cmd_capture reaches only a subset of the four input combinations).

Parameters

[in]	line	NUL-terminated input line (must be non-NULL).
[in]	expected_response	Optional NUL-terminated expected prefix.

Returns: 1 iff all three conditions hold.

Return values

1	expected_response != NULL && expected_response[0] != '\0' && starts_with(line, expected_response).
0	Any one of the three conditions fails.

Precondition: line is non-NULL and NUL-terminated.; No precondition on expected_response (NULL accepted).

Postcondition: No state mutated.; Return value depends solely on the two inputs.

Note: Pure function; thread-safe.

Since: 0.1.0

Definition at line 271 of file ra8_modem_at.c.

References priv_modem_starts_with().

Referenced by internal_handle_line().

◆ priv_modem_reset_line_should_clear()

uint8_t priv_modem_reset_line_should_clear	(	const void *	line_buf,
		uint16_t	line_buf_len )

Pure helper for the internal_reset_line line-227 AND.

Pure (state-free) reimplementation of internal_reset_line's line-227 buffer-clear guard.

Promoted as a free function so tests can drive both (line_buf, line_buf_len) input combinations directly under -fcoverage-mcdc on the production source. The state- reading wrapper internal_reset_line forwards to this helper with s_mod.cfg.line_buf and s_mod.cfg.line_buf_len.

Parameters

[in]	line_buf	Caller-owned buffer pointer (NULL allowed).
[in]	line_buf_len	Capacity of `line_buf` in bytes.

Returns: 1 iff both arguments indicate an installed buffer.

Return values

1	line_buf!=NULL and line_buf_len>0.
0	Either argument signals "no buffer".

Precondition: None.; None.

Postcondition: No state mutated.; Return value depends solely on the two inputs.

Note: Pure function; thread-safe.

Since: 0.1.0

Definition at line 238 of file ra8_modem_at.c.

Referenced by internal_reset_line().

◆ priv_modem_starts_with()

uint8_t priv_modem_starts_with	(	const char *	hay,
		const char *	needle )

Return 1 if hay begins with needle.

Return 1 iff hay begins with needle.

Parameters

[in]	hay	NUL-terminated haystack.
[in]	needle	NUL-terminated prefix.

Returns: 1 on match, 0 otherwise.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 149 of file ra8_modem_at.c.

Referenced by internal_classify_final(), internal_dispatch_urc(), priv_modem_classify(), and priv_modem_payload_prefix_matches().

◆ priv_modem_str_eq()

uint8_t priv_modem_str_eq	(	const char *	a,
		const char *	b )

Compare two NUL-terminated strings for exact equality.

Return 1 iff a and b are byte-for-byte equal.

Parameters

[in]	a	First string.
[in]	b	Second string.

Returns: 1 if equal, 0 otherwise.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 177 of file ra8_modem_at.c.

Referenced by internal_classify_final(), internal_urc_replace(), and priv_modem_classify().

◆ priv_modem_str_len()

uint16_t priv_modem_str_len ( const char * s )

NUL-terminated string length.

NUL-terminated string length, capped at UINT16_MAX.

Parameters

[in] s NUL-terminated input string (must be non-NULL).

Returns: Length in bytes, capped at UINT16_MAX.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 124 of file ra8_modem_at.c.

Referenced by ra8_modem_at_register_unsolicited_handler().

◆ ra8_modem_at_init()

ra8_err_t ra8_modem_at_init ( const ra8_modem_at_cfg_t * cfg )

nodiscard

Bind transport, buffer and timeout policy.

Resets all internal state and copies cfg into module-static storage. Must be called once before any other API. Re-calling is legal – previous URC handlers are cleared.

Parameters

[in] cfg Pointer to a fully populated configuration.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Initialized successfully.
k_ra8_err_null_ptr	cfg, cfg->line_buf or any IO function pointer is NULL.
k_ra8_err_invalid_size	line_buf_len smaller than 16.

Precondition: cfg != NULL.; All members of cfg->io non-NULL.

Postcondition: Internal state reset to k_ra8_modem_at_state_idle.; URC table empty.

Note: Not thread-safe; the AT driver assumes a single owner.

Example:: static uint8_t s_at_line[256];

ra8_modem_at_cfg_t cfg = {

.io = {

.tx_byte = my_uart_tx, .rx_byte = my_uart_rx, .now_ms = my_now,

.ctx = (void*)1U,

},

.line_buf = s_at_line,

.line_buf_len = sizeof s_at_line,

.default_timeout_ms = 2000U,

};

(void)ra8_modem_at_init(&cfg);

ra8_modem_at_init
ra8_err_t ra8_modem_at_init(const ra8_modem_at_cfg_t *cfg)
Bind transport, buffer and timeout policy.
Definition ra8_modem_at.c:821

ra8_modem_at_cfg_t
Configuration handed to ra8_modem_at_init.
Definition ra8_modem_at.h:154

See also: ra8_modem_at_send_cmd(); ra8_modem_at_register_unsolicited_handler()

Since: 0.1.0

Definition at line 821 of file ra8_modem_at.c.

References internal_clear_urc_table(), internal_reset_line(), internal_validate_init_cfg(), k_ra8_modem_at_state_idle, k_ra8_ok, and s_mod.

Referenced by modem_bind().

◆ ra8_modem_at_poll()

ra8_err_t ra8_modem_at_poll ( void )

nodiscard

Pump the RX path without sending a command.

Drains any queued bytes, dispatches URC handlers, and returns. Useful when the application is otherwise idle but wants to service unsolicited modem traffic. Does not block beyond a single drain pass.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Drain completed.
k_ra8_err_not_initialized	Module not initialized.

Precondition: ra8_modem_at_init returned k_ra8_ok.

Postcondition: RX FIFO drained for the current call.

Since: 0.1.0

Definition at line 974 of file ra8_modem_at.c.

References internal_accumulate(), k_ra8_err_not_initialized, k_ra8_ok, priv_modem_classify(), and s_mod.

Referenced by modem_phase_registration().

◆ ra8_modem_at_register_unsolicited_handler()

ra8_err_t ra8_modem_at_register_unsolicited_handler	(	const char *	prefix,
		ra8_modem_at_urc_fn_t	fn,
		void *	ctx )

nodiscard

Register a URC (unsolicited result code) handler.

Whenever the line accumulator emits a complete line that starts with prefix and the driver is not currently expecting that prefix as a command response, fn(line, ctx) is invoked. Registration order is preserved, but only one handler per distinct prefix is permitted – duplicate registration replaces the previous handler.

Parameters

[in]	prefix	NUL-terminated prefix string (e.g. "+CMTI:"). Must be shorter than k_ra8_modem_at_max_prefix_len.
[in]	fn	Handler function (must be non-NULL).
[in]	ctx	Opaque pointer passed to fn on every match.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Handler installed (or replaced).
k_ra8_err_null_ptr	prefix or fn NULL.
k_ra8_err_invalid_size	prefix too long or empty.
k_ra8_err_no_mem	Handler table full.
k_ra8_err_not_initialized	Module not initialized.

Precondition: ra8_modem_at_init returned k_ra8_ok.

Postcondition: Future matching lines invoke fn exactly once each.

Note: Not thread-safe with concurrent ra8_modem_at_send_cmd.

Since: 0.1.0

Definition at line 952 of file ra8_modem_at.c.

References internal_urc_insert(), internal_urc_replace(), k_ra8_err_invalid_size, k_ra8_err_no_mem, k_ra8_err_not_initialized, k_ra8_modem_at_max_prefix_len, k_ra8_ok, priv_modem_str_len(), RA8_CHECK_NULL_PTR, RA8_MODEM_AT_TAG, and s_mod.

Referenced by modem_bind().

◆ ra8_modem_at_send_cmd()

ra8_err_t ra8_modem_at_send_cmd	(	const char *	cmd,
		const char *	expected_response,
		uint16_t	timeout_ms )

nodiscard

Send an AT command and wait for OK/ERROR/expected.

Writes cmd followed by "\r" byte-by-byte through io.tx_byte, then drives the line accumulator until either:

the final result code OK arrives -> k_ra8_ok,
the final result code ERROR (or +CME ERROR:, +CMS ERROR:) arrives -> k_ra8_err_hw_error,
a line beginning with expected_response arrives (also counts as success and the function continues to drain until OK) -> k_ra8_ok,
timeout_ms (or the configured default if 0) elapses -> k_ra8_err_hw_timeout.

Parameters

[in]	cmd	NUL-terminated AT command without the trailing "\r".
[in]	expected_response	Optional NUL-terminated prefix to wait for (e.g. "+CSQ:"). May be NULL when only OK matters.
[in]	timeout_ms	Per-command timeout in ms. 0 selects the configured default.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Final OK (and expected, if set) seen.
k_ra8_err_null_ptr	cmd was NULL.
k_ra8_err_not_initialized	ra8_modem_at_init not yet called.
k_ra8_err_hw_error	Modem replied ERROR/+CME ERROR.
k_ra8_err_hw_timeout	No final result code in time.

Precondition: ra8_modem_at_init returned k_ra8_ok.; cmd NUL-terminated and shorter than line_buf_len.

Postcondition: Driver returned to k_ra8_modem_at_state_idle.; Line accumulator is empty.

Note: Blocking. URC handlers are invoked inline while waiting.

Warning: Not re-entrant.

See also: ra8_modem_at_send_cmd_capture()

Since: 0.1.0

Definition at line 836 of file ra8_modem_at.c.

References internal_effective_timeout(), internal_reset_line(), internal_tx_command(), internal_wait_response(), k_ra8_err_not_initialized, k_ra8_ok, RA8_CHECK_NULL_PTR, RA8_MODEM_AT_TAG, and s_mod.

Referenced by modem_cmd_ok().

◆ ra8_modem_at_send_cmd_capture()

ra8_err_t ra8_modem_at_send_cmd_capture	(	const char *	cmd,
		char *	out_buf,
		size_t	buf_len,
		uint16_t	timeout_ms )

nodiscard

Send an AT command and capture the response payload.

Identical wait policy to ra8_modem_at_send_cmd but every non-echo, non-final-result, non-URC line is appended to out_buf with '\n' separators. Truncation past buf_len - 1 bytes is silent; the buffer is always NUL-terminated.

Parameters

[in]	cmd	NUL-terminated AT command (no trailing CR).
[out]	out_buf	Caller buffer for captured payload.
[in]	buf_len	Bytes in out_buf (>= 1).
[in]	timeout_ms	Per-command timeout in ms (0 -> default).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Command finished with OK.
k_ra8_err_null_ptr	cmd or out_buf NULL.
k_ra8_err_invalid_size	buf_len is 0.
k_ra8_err_not_initialized	ra8_modem_at_init not called.
k_ra8_err_hw_error	Modem replied ERROR.
k_ra8_err_hw_timeout	No final result code in time.

Precondition: out_buf points to writable storage of buf_len bytes.

Postcondition: out_buf is NUL-terminated.

Note: Blocking. Response payload is line-separated with '\n'.

See also: ra8_modem_at_send_cmd()

Since: 0.1.0

Definition at line 856 of file ra8_modem_at.c.

References internal_effective_timeout(), internal_reset_line(), internal_tx_command(), internal_wait_response(), k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_ok, RA8_CHECK_NULL_PTR, RA8_MODEM_AT_TAG, and s_mod.

Referenced by modem_query().

Variable Documentation

◆ s_mod

ra8_modem_at_module_t s_mod

static

Singleton module state (file scope, NASA Rule 6).

Note: Direct external access is forbidden; the public API guards it.

Definition at line 103 of file ra8_modem_at.c.

Referenced by internal_accumulate(), internal_clear_urc_table(), internal_dispatch_urc(), internal_effective_timeout(), internal_handle_line(), internal_pump_one(), internal_reset_line(), internal_tx_command(), internal_urc_insert(), internal_urc_replace(), internal_wait_response(), ra8_modem_at_init(), ra8_modem_at_poll(), ra8_modem_at_register_unsolicited_handler(), ra8_modem_at_send_cmd(), and ra8_modem_at_send_cmd_capture().

Data Structures

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ RA8_MODEM_AT_TAG

Enumeration Type Documentation

◆ ra8_modem_at_internal_const_t

◆ ra8_modem_at_state_t

◆ ra8_modem_line_action_t

Function Documentation

◆ internal_accumulate()

◆ internal_append_ch()

◆ internal_classify_final()

◆ internal_clear_urc_table()

◆ internal_dispatch_urc()

◆ internal_effective_timeout()

◆ internal_handle_line()

◆ internal_pump_one()

◆ internal_reset_line()

◆ internal_tx_command()

◆ internal_urc_insert()

◆ internal_urc_replace()

◆ internal_validate_init_cfg()

◆ internal_wait_response()

◆ priv_modem_capture_line()

◆ priv_modem_capture_should_clear()

◆ priv_modem_classify()

◆ priv_modem_payload_prefix_matches()

◆ priv_modem_reset_line_should_clear()

◆ priv_modem_starts_with()

◆ priv_modem_str_eq()

◆ priv_modem_str_len()

◆ ra8_modem_at_init()

◆ ra8_modem_at_poll()

◆ ra8_modem_at_register_unsolicited_handler()

◆ ra8_modem_at_send_cmd()

◆ ra8_modem_at_send_cmd_capture()

Variable Documentation

◆ s_mod