Results, registry and settling

Functions
bool	ai_engine_snapshot (ai_result_t *out)
	Copy the latest published result; last-writer-wins — not valid inside a set.
bool	ai_engine_snapshot_model (uint32_t index, ai_result_t *out)
	One model's last verdict — the reader to use inside a parallel set.
uint32_t	ai_engine_model_count (void)
	How many models are registered; the count leads the rows.
const ai_model_desc_t *	ai_engine_model (uint32_t index)
	Registry entry, NULL if out of range — and NULL for a set pseudo-index.
bool	ai_engine_mic_settling (void)
	True while a parallel set is still filling its windows; verdicts are withheld.
uint32_t	ai_engine_mic_settle_pct (void)
	Settle progress 0..100; only meaningful inside a set (100 otherwise).

Detailed Description

Six functions: the two result readers (and when each is valid), the registry enumeration pair, and the two settle readings a parallel set exposes.

Variant

mtb-mpy and mtb-only

Function Documentation

ai_engine_snapshot()

bool ai_engine_snapshot

(

ai_result_t *

out

)

Copy the latest published result; last-writer-wins — not valid inside a set.

Copy the latest result. Returns false if nothing has been published yet.

Contract

Copies the latest published result; false if nothing has been published yet. It is last-writer-wins and therefore not valid inside a parallel set — "a cough detected at 0.94 is overwritten by three 'unlabelled' … The detection is not late, it is gone" (ai_engine.c:1876-1885). The shipped code branches on ai_engine_active() being in [AI_PARALLEL_FIRST, AI_PARALLEL_MIC] and uses ai_engine_snapshot_model() per member in that case; deepcraft_task.c:448-450 records that the test was == AI_PARALLEL_MIC until 2026-08-09, so Room Presence and Intruder Watch fell into the very slot the branch exists to avoid. Reduce a result with ai_result_top_positive() — ai_result_t has no valid/label/confidence field (Header facts that are easy to get wrong).

Variant

mtb-mpy and mtb-only

Origin

Lifted from deepcraft_task.c:469 (MicroPython Q_RESULT) and page_edge_ai.c:1409 (UI) (compiled into the prebuilt archive; not shipped as source).

ai_engine_snapshot_model()

bool ai_engine_snapshot_model	(	uint32_t	index,
		ai_result_t *	out )

One model's last verdict — the reader to use inside a parallel set.

One model's last verdict. Use this, not ai_engine_snapshot(), whenever several models may be publishing: that one reports whoever wrote most recently, so three quiet models can bury a detection before it is read. False if that model has never published.

Contract

One model's last verdict. Use this in sets. False means "this model has never published" — which is not the same as "silent" (a member that published once and then went quiet still returns true with a stale seq; the page derives a per-row silence timer from seq staleness, page_edge_ai.c:728-739). index must be a real registry index, never a set pseudo-index — obtain members from ai_engine_set_members() (active set) or ai_engine_set_models() (any set).

Variant

mtb-mpy and mtb-only

Origin

Lifted from page_edge_ai.c:717-723; deepcraft_task.c:455-467 (compiled into the prebuilt archive; not shipped as source).

ai_engine_model_count()

uint32_t ai_engine_model_count

(

void

)

How many models are registered; the count leads the rows.

Contract

How many models are registered (compiled-in plus staged rows). The count leads the rows: ai_engine_model(i) for i < count may still return NULL (a resolver hole) — continue, do not abort the enumeration.

Variant

mtb-mpy and mtb-only

Origin

Lifted from page_edge_ai.c:1021-1026 (compiled into the prebuilt archive; not shipped as source).

ai_engine_model()

const ai_model_desc_t * ai_engine_model

(

uint32_t

index

)

Registry entry, NULL if out of range — and NULL for a set pseudo-index.

Registry entry (NULL if out of range).

Contract

Registry entry, NULL if out of range — and NULL for a set pseudo-index. Branch on idx >= AI_PARALLEL_FIRST first and walk the set's members with ai_engine_set_models() before touching a descriptor. Descriptors and the strings they point at stay valid for the life of the boot (slots are never reused). Registry contract: class_labels[0] is the negative class; everything from 1 up is a positive detection.

Variant

mtb-mpy and mtb-only

Origin

Lifted from deepcraft_task.c:244-270 (dc_desired_sensor_rate) (compiled into the prebuilt archive; not shipped as source).

ai_engine_mic_settling()

bool ai_engine_mic_settling

(

void

)

True while a parallel set is still filling its windows; verdicts are withheld.

True while the parallel set is still filling its windows. Verdicts are withheld until then; show it rather than four silent zero bars.

Contract

True while a parallel set is still filling its windows; verdicts are withheld until then. Show progress rather than four silent zero bars — and keep the stats line updating during the settle, otherwise an NPU stall inside the window is invisible (page_edge_ai.c:702-705). Keyed on s_current being in [AI_PARALLEL_FIRST, AI_PARALLEL_MIC] (ai_engine.c:1968-1976); false outside a set.

Variant

mtb-mpy and mtb-only

Origin

Lifted from page_edge_ai.c:685-708 (compiled into the prebuilt archive; not shipped as source).

ai_engine_mic_settle_pct()

uint32_t ai_engine_mic_settle_pct

(

void

)

Settle progress 0..100; only meaningful inside a set (100 otherwise).

Settle progress, 0..100, for a caller that wants to show it moving.

Contract

Settle progress 0..100 for a caller that wants to show it moving. Only meaningful inside a set; returns 100 otherwise (ai_engine.c:1955-1966). The page writes the label only when the value changed, to avoid redundant LVGL work.

Variant

mtb-mpy and mtb-only

Origin

Lifted from page_edge_ai.c:691-700 (compiled into the prebuilt archive; not shipped as source).