ra8_batt.c File Reference

Implementation of the low-battery nag policy. More...

#include "ra8_batt.h"
#include <stdint.h>
#include "ra8_check.h"
#include "ra8_err.h"

Include dependency graph for ra8_batt.c:

Go to the source code of this file.

Functions
ra8_err_t	ra8_batt_monitor_init (ra8_batt_monitor_t *mon)
	Reset a nag monitor to the un-nagged, fully-armed state.
ra8_err_t	ra8_batt_update (ra8_batt_monitor_t *mon, uint8_t soc_pct, bool charging, ra8_batt_nag_t *out_nag)
	Fold one SOC reading into the monitor and report the nag to raise.
const char *	ra8_batt_nag_str (ra8_batt_nag_t nag)
	Map a nag level to a short, stable upper-case label.

Variables
static const char *const	s_tag = "ra8_batt"
	Component tag for diagnostic logging.

Detailed Description

Implementation of the low-battery nag policy.

Tag

[Ring 5 / UI] {World: NS}

Edge-triggered band detection with hysteresis. See ra8_batt.h for the contract. Pure logic: no loop, no recursion, no allocation, no MMIO.

Copyright

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

Since

0.1.0

Definition in file ra8_batt.c.

Function Documentation

ra8_batt_monitor_init()

ra8_err_t ra8_batt_monitor_init

(

ra8_batt_monitor_t *

mon

)

Reset a nag monitor to the un-nagged, fully-armed state.

Writes zero to both band-raised flags inside mon, placing the monitor into the fully-armed state so that the first subsequent call to ra8_batt_update can raise either the low or critical nag. The operation is a single struct clear with no loops, no allocation, and no hardware access, making it safe to call from any initialisation context on both the RA8D2 target and the host unit-test harness.

Parameters

[out]

mon

Monitor to initialise.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Monitor zeroed; both bands armed.
k_ra8_err_null_ptr	mon is nullptr.

Precondition

mon points to writable storage.

Called before the first ra8_batt_update on this monitor.

Postcondition

Both band flags are false (armed).

Subsequent ra8_batt_update can raise either band.

Note

Not thread-safe; one monitor per single-threaded reader.

See also

ra8_batt_update()

Since

0.1.0

Definition at line 27 of file ra8_batt.c.

References ra8_batt_monitor_t::critical_raised, k_ra8_ok, ra8_batt_monitor_t::low_raised, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by main().

ra8_batt_nag_str()

const char * ra8_batt_nag_str

(

ra8_batt_nag_t

nag

)

Map a nag level to a short, stable upper-case label.

Parameters

[in]

nag

Nag level.

Returns

A static NUL-terminated label.

Return values

OK	For k_ra8_batt_nag_none.
LOW	For k_ra8_batt_nag_low.
CRITICAL	For k_ra8_batt_nag_critical.
?	For any out-of-range value.

Precondition

None.

Postcondition

The returned pointer is non-null (asserted) and immutable.

Note

Thread-safe (returns a pointer to static storage).

Since

0.1.0

Definition at line 71 of file ra8_batt.c.

References k_ra8_batt_nag_critical, k_ra8_batt_nag_low, k_ra8_batt_nag_none, and RA8_ASSERT.

ra8_batt_update()

ra8_err_t ra8_batt_update	(	ra8_batt_monitor_t *	mon,
		uint8_t	soc_pct,
		bool	charging,
		ra8_batt_nag_t *	out_nag )

Fold one SOC reading into the monitor and report the nag to raise.

Re-arms each band when charging or when soc_pct has recovered above the band threshold by k_ra8_batt_rearm_margin, then, only while not charging, raises the low and/or critical band the reading newly enters. When a reading enters both bands at once (a large drop), the returned nag is the worse one (k_ra8_batt_nag_critical). soc_pct above k_ra8_batt_pct_max is clamped.

Parameters

[in,out]	mon	Monitor state (updated in place).
[in]	soc_pct	Current state-of-charge percent (clamped to 0..100).
[in]	charging	True when the fuel gauge reports a charging rate.
[out]	out_nag	Receives the nag to surface this step.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Step folded; out_nag written.
k_ra8_err_null_ptr	mon or out_nag is nullptr.

Precondition

mon was initialised by ra8_batt_monitor_init.

out_nag points to writable storage.

Postcondition

out_nag holds one of ra8_batt_nag_t.

A band that fired is marked raised until it re-arms.

Note

Not thread-safe; one monitor per single-threaded reader.

See also

ra8_batt_monitor_init()

Since

0.1.0

Definition at line 36 of file ra8_batt.c.

References ra8_batt_monitor_t::critical_raised, k_ra8_batt_critical_pct, k_ra8_batt_low_pct, k_ra8_batt_nag_critical, k_ra8_batt_nag_low, k_ra8_batt_nag_none, k_ra8_batt_pct_max, k_ra8_batt_rearm_margin, k_ra8_ok, ra8_batt_monitor_t::low_raised, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by er_poll_battery(), and main().

Variable Documentation

s_tag

const char* const s_tag = "ra8_batt"

static

Component tag for diagnostic logging.

Definition at line 25 of file ra8_batt.c.