Engine lifecycle

Functions
bool	ai_engine_init (void)
	Create the inference task (idempotent); it must precede ai_engine_start().
bool	ai_engine_start (uint32_t index)
	Activate a model (or set) by index and begin inferring; check the return.
void	ai_engine_stop (void)
	Stop the active model (idempotent); pair with a sensor-rate walk-down.
int	ai_engine_active (void)
	The LOADED model, or -1; lags requested by a cold-init window.
int	ai_engine_requested (void)
	The REQUESTED model, or -1; the correct guard for a fallback.
uint32_t	ai_engine_stack_words (void)
	Stack the inference task got, in words; 0 = engine never started — the universal gate.
uint32_t	ai_engine_stack_free_words (void)
	All-time minimum of unused stack words; O(stack) scan — read at ~1 Hz at most.

Detailed Description

Seven functions: create the inference task, start and stop a model, read which model is requested versus loaded, and the two stack readings that gate everything else. Read The select → confirm → start discipline before using any of them.

Variant

mtb-mpy and mtb-only

Function Documentation

ai_engine_init()

bool ai_engine_init

(

void

)

Create the inference task (idempotent); it must precede ai_engine_start().

Create the inference task (idle until ai_engine_start). Idempotent; must precede ai_engine_start(). If it fails, ai_engine_stack_words() returns 0.

Contract

Creates the inference task, idle until ai_engine_start(); call after the sensor sources exist. Idempotent. It must precede ai_engine_start() — on an engine that never started, start() returns false silently and ai_engine_active() stays -1 forever, which surfaces as edge_ai.select() failing "not confirmed". The display bring-up calls it once the display is confirmed up, so an AI fault can never cost the screen, but that call alone does not cover every boot path; hence the shipped idiom re-calls it before every start. If the task cannot be created, ai_engine_stack_words() returns 0 — the universal gate.

(void)ai_engine_init();                 /* idempotent: cheap when already up */
if (ai_engine_requested() < 0) {        /* guard on REQUESTED, never ACTIVE  */
    (void)ai_engine_start(0u);
}

Variant

mtb-mpy and mtb-only

ai_engine_start()

bool ai_engine_start

(

uint32_t

index

)

Activate a model (or set) by index and begin inferring; check the return.

Activate a model by registry index, or a set by set index, and begin inferring. Stops whatever was running first. Returns false on a bad index, a set index in an image built without a microphone model, or an engine that never started (see ai_engine_init). A model whose own init() fails is reported later: ai_engine_requested() drops back to -1.

Contract

Activates a model by registry index (or a set pseudo-index, Set pseudo-indices and the legacy translation) and begins inferring; stops whatever was running first. ai_engine_init() first — the idempotent re-call immediately before start is the shipped idiom. Set pseudo-indices 252..255 are accepted only in an image built with at least one microphone model; a motion-only image refuses them. Check the return before touching rate or state: false = a bad index, a set index in an image without a microphone model, or an engine that never started. Set the sensor rate only after start() returned true; on failure leave state alone and let the Q_ACTIVE confirm surface it. start() changes only the requested model; the active model changes after the model's cold init() returns — see The select → confirm → start discipline.

Variant

mtb-mpy and mtb-only

ai_engine_stop()

void ai_engine_stop

(

void

)

Stop the active model (idempotent); pair with a sensor-rate walk-down.

Stop the active model (idempotent).

Contract

Idempotent, and a request: ai_engine_active() reaching -1 is the confirmation. It does not touch the sensor rate — pair every stop with a sensor-rate walk-down (for example ai_engine_set_sensor_rate(100u) for the dashboard cadence), or the accelerometer stays pinned at 50 Hz and starves the dashboard sensors. The Edge AI page's Load button is three-state: it first refuses when ai_engine_stack_words() is 0, reads ai_engine_active() once, and calls stop() when the selected model is the active one.

Variant

mtb-mpy and mtb-only

ai_engine_active()

int ai_engine_active

(

void

)

The LOADED model, or -1; lags requested by a cold-init window.

Index of the active model, or -1 when idle.

Contract

Returns the LOADED model, or -1 when idle. It lags ai_engine_requested() by a whole cold-init window. Never gate a fallback on it: the recorded symptom is "select Radar, Load, get Motion" — a guard that read active() during the cold-load window fired ai_engine_start(0) and overwrote the user's selection. For a set it reports the set constant (a caller that sent 13 is told 253 — Set pseudo-indices and the legacy translation). Inside a render, read it once (see ai_engine_set_models()): another task can start/stop mid-render. Exposed to MicroPython as MODEL_LINK_Q_ACTIVE.

Variant

mtb-mpy and mtb-only

ai_engine_requested()

int ai_engine_requested

(

void

)

The REQUESTED model, or -1; the correct guard for a fallback.

Index of the REQUESTED model (last ai_engine_start), or -1 when stopped. Leads ai_engine_active() until the requested model has finished loading, and drops to -1 if its init() fails. Guard a default-model fallback on this, never on ai_engine_active().

Contract

Returns the model REQUESTED by the last ai_engine_start(), or -1 when stopped. This is the correct guard for a default-model fallback (the if (ai_engine_requested() < 0) ai_engine_start(0) idiom shown under ai_engine_init()). It leads Q_ACTIVE by the cold-init window and drops back to -1 when that init() fails, so a confirm loop that has already seen requested == want can fail fast on a later requested < 0 instead of waiting the full 15 s ceiling. Exposed to MicroPython as MODEL_LINK_Q_REQUESTED.

Variant

mtb-mpy and mtb-only

ai_engine_stack_words()

uint32_t ai_engine_stack_words

(

void

)

Stack the inference task got, in words; 0 = engine never started — the universal gate.

Stack the inference task actually got, in words; 0 if it was never created. Reported on the Edge AI page so a heap squeeze is visible, not silent.

Contract

Stack the inference task actually got, in words; 0 means the task was never created — the engine never started. Gate every control on it: the Edge AI page uses it to make the Load button a no-op, to show the "engine failed to start" badge, and to choose Failed over Stopped. Every other counter on these pages is vacuous while it is 0. Cheap read, any CM55 context.

Variant

mtb-mpy and mtb-only

ai_engine_stack_free_words()

uint32_t ai_engine_stack_free_words

(

void

)

All-time minimum of unused stack words; O(stack) scan — read at ~1 Hz at most.

Unused words left in the inference task's stack (all-time minimum); 0 if the task was never created. Read at about 1 Hz — the call scans the stack.

Contract

All-time minimum of unused words in the inference task's stack; 0 if the task was never created. The call scans the stack — O(stack). Read at about 1 Hz at most, never per frame; the Edge AI page reads it only in its once-a-second stats line.

Variant

mtb-mpy and mtb-only