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 (s_current), or -1; lags requested by a cold-init window.
int	ai_engine_requested (void)
	The REQUESTED model (s_active), 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). Call after the sensor sources exist; safe to call once from the display bring-up.

Contract

Creates the inference task, idle until ai_engine_start(); call after the sensor sources exist. Idempotent (ai_engine.c:1735-1738: if (s_task != NULL) return true;). It must precede ai_engine_start() — with s_task == NULL, 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 after display_ok = true and before the ipc_only: label (tesaiot_display.c:467), so an AI fault can never cost the screen; deepcraft_task.c:617-630 records why that call alone was insufficient (a boot whose display path short-circuits creates no ai_task), hence the shipped idiom re-calls it before every start. Stack ladder {2048, 1536} words (ai_engine.c:1774-1783); on total failure s_task stays NULL and ai_engine_stack_words() returns 0 — the universal gate.

Variant

mtb-mpy and mtb-only

Origin

Lifted from TESAIoT_KIT_PSE84_AI-Micropython-BentoClaw/proj_cm55/modules/deepcraft_task/deepcraft_task.c:631-641 (creator: tesaiot_display.c:467) (compiled into the prebuilt archive; not shipped as source).

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 and begin inferring. Stops any model already running first. Returns false on a bad index or init failure.

Contract

Activates a model by registry index (or a set pseudo-index, Set pseudo-indices and the legacy translation) and begins inferring; stops any model already 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 EDGE_AI_HAS_MIC (ai_engine.c:1835-1861); ai_engine.c:1843-1849 records the failure mode of accepting a set index in a motion-only image — s_active parked, s_current stuck at -1, two 15 s select budgets burned. Check the return before touching rate or state: false = bad index or s_task == NULL. The sensor rate is asserted only inside the success branch (deepcraft_task.c:804-806); on failure the shipped code leaves state alone and lets the Q_ACTIVE confirm surface it (:807). start() sets only s_active (ai_engine.c:1860); s_current is switched by the inference task after the cold init() returns — see The select → confirm → start discipline.

Variant

mtb-mpy and mtb-only

Origin

Lifted from deepcraft_task.c:790-807 (compiled into the prebuilt archive; not shipped as source).

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; the body is s_active = -1 and nothing else (ai_engine.c:1864). It does not touch the sensor rate — pair every stop with a sensor-rate walk-down, ai_engine_set_sensor_rate(dc_desired_sensor_rate()) in the shipped code, or the accelerometer stays pinned at 50 Hz and starves the dashboard sensors (deepcraft_task.c:682-686). The UI variant (page_edge_ai.c:353-368) is the three-state Load button: 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

Origin

Lifted from deepcraft_task.c:687-688; UI variant page_edge_ai.c:353-368 (compiled into the prebuilt archive; not shipped as source).

ai_engine_active()

int ai_engine_active

(

void

)

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

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

Contract

Returns s_current — the LOADED model, or -1 when idle (ai_engine.c:1866). It lags ai_engine_requested() by a whole cold-init window. Never gate a fallback on it: the recorded bug is "select Radar, Load, get Motion" (ai_engine.c:1868-1873, deepcraft_task.c:634-640) — 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

Origin

Lifted from deepcraft_task.c:301-311 (wire exposure) and :437 (compiled into the prebuilt archive; not shipped as source).

ai_engine_requested()

int ai_engine_requested

(

void

)

The REQUESTED model (s_active), 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() by up to one inference-task tick. Guard a default-model fallback on this, never on ai_engine_active().

Contract

Returns s_active — the model REQUESTED by the last ai_engine_start(), or -1 when stopped (ai_engine.c:1874). 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

Origin

Lifted from deepcraft_task.c:632 and :305-310 (compiled into the prebuilt archive; not shipped as source).

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 page uses it six times (page_edge_ai.c:353 button no-op, :1261/:1265 "engine failed to start" badge, :1338 CHIP_FAIL vs CHIP_STOPPED, :895, :1466). Every other counter on these pages is vacuous while it is 0. Cheap read, any CM55 context.

Variant

mtb-mpy and mtb-only

Origin

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

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 page reads it only in its once-a-second stats line.

Variant

mtb-mpy and mtb-only

Origin

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