Parallel sets

Functions
uint32_t	ai_engine_set_models (uint32_t set_index, uint8_t *idx, uint32_t max)
	Members of any set, in registry order; an explicit membership replaces the compiled one.
const char *	ai_engine_set_name (uint32_t set_index)
	Human name for a set; NULL for a non-set index.
uint32_t	ai_engine_set_members (uint8_t *idx, uint32_t max)
	Registry indices of the ACTIVE set's members; test each member's sensor.
int	ai_engine_set_define (uint32_t set_index, const uint8_t *members, uint32_t n)
	Give a set an explicit run-time membership; task context, all-or-nothing.
uint32_t	ai_engine_set_members_defined (uint32_t set_index, uint8_t *out, uint32_t max)
	The explicit membership if defined, else 0 — the only ack for set_define.

Detailed Description

Five functions for sets — named groups of models that run together. Constants, the legacy 13/14/15 translation and the two hard facts (ALL cannot be redefined; ai_engine_snapshot() loses detections in a set) are in Set pseudo-indices and the legacy translation.

Variant

mtb-mpy and mtb-only

Function Documentation

ai_engine_set_models()

uint32_t ai_engine_set_models	(	uint32_t	set_index,
		uint8_t *	idx,
		uint32_t	max )

Members of any set, in registry order; an explicit membership replaces the compiled one.

Members of a set, in registry order. Returns how many were written.

Contract

Writes the members in effect for any set, in registry order, and returns how many were written (0 for a non-set index). An explicit membership from ai_engine_set_define() replaces the compiled one; otherwise the compiled membership applies. A model whose init() failed once is not dropped from the set for the boot. Inside a render, take ai_engine_active() once and pass that value here — the model link can start/stop the engine from another task mid-render, and re-reading it would let the set used for the layout tag disagree with the set the rows were sized from.

const int a = ai_engine_active();                 /* read ONCE per render */
uint8_t   idx[8];
uint32_t  n = (a >= (int)AI_PARALLEL_FIRST)
            ? ai_engine_set_models((uint32_t)a, idx, 8u) : 0u;

Variant

mtb-mpy and mtb-only

ai_engine_set_name()

const char * ai_engine_set_name

(

uint32_t

set_index

)

Human name for a set; NULL for a non-set index.

Human name for a set, or NULL if that index is not one.

Contract

Human name for a set; NULL for a non-set index. The Edge AI page requires nn >= 2 members and a non-NULL name before showing the dropdown row — a set with fewer than two members in this image is not offered.

Variant

mtb-mpy and mtb-only

ai_engine_set_members()

uint32_t ai_engine_set_members	(	uint8_t *	idx,
		uint32_t	max )

Registry indices of the ACTIVE set's members; test each member's sensor.

Registry indices of the ACTIVE SET's members, up to max, whatever sensor each one reads – not microphone models. Returns the count. Callers that iterate this must test desc->sensor before doing anything sensor-specific with an entry.

Contract

Registry indices of the ACTIVE set's members only, up to max; returns the count. Members may read any sensor — not only the microphone — so a caller that does anything sensor-specific must test desc->sensor on each ai_engine_model() entry first. Combine it with ai_engine_snapshot_model() and ai_result_top_positive() to find the loudest positive member, which is what edge_ai.result() reports inside a set.

uint8_t  idx[8];
uint32_t n = ai_engine_set_members(idx, 8u);
for (uint32_t i = 0u; i < n; i++) {
    const ai_model_desc_t *d = ai_engine_model(idx[i]);
    ai_result_t r;
    if ((d == NULL) || !ai_engine_snapshot_model(idx[i], &r)) {
        continue;
    }
    uint8_t cls;
    int pct = ai_result_top_positive(&r, &cls);   /* 0..100 */
}

Variant

mtb-mpy and mtb-only

ai_engine_set_define()

int ai_engine_set_define	(	uint32_t	set_index,
		const uint8_t *	members,
		uint32_t	n )

Give a set an explicit run-time membership; task context, all-or-nothing.

Give a set an explicit membership at run time, replacing the compiled one. Task context only. 1..8 members, all-or-nothing: one bad index refuses the whole definition. INTRUDER, ROOM and MIC only; returns -1 for AI_PARALLEL_ALL. Undefined sets keep their compiled membership exactly. Read the result back with ai_engine_set_members_defined().

Contract

Gives a set an explicit run-time membership, replacing the compiled one. Task context only — never from an ISR or the pipe callback. 1..8 members. All-or-nothing: every index is validated and one bad index refuses the whole definition; a reader during the call sees either the old membership or the new one, never a splice of both. Only INTRUDER, ROOM and MIC are definable: AI_PARALLEL_ALL (252) is every model by definition — the call always returns -1 for it. On success it returns the member count. There is no ack event: the only acknowledgement is reading back ai_engine_set_members_defined(). The MicroPython edge_ai.set_define() drives this as a three-command build (SET_BEGIN, one SET_ADD per member, SET_COMMIT) applied whole on commit — a dropped ADD is caught only by the Q_SET read-back. This is the supported way to put a model registered or staged at run time into a set, by its registry index.

Variant

mtb-mpy and mtb-only

ai_engine_set_members_defined()

uint32_t ai_engine_set_members_defined	(	uint32_t	set_index,
		uint8_t *	out,
		uint32_t	max )

The explicit membership if defined, else 0 — the only ack for set_define.

Explicit membership if one was defined, else 0.

Contract

The explicit membership if one was defined, else 0 = no override — the caller then falls back to ai_engine_set_models() for the membership in effect. This read-back is the only ack for ai_engine_set_define(). Any CM55 context (plain read). MicroPython reads the same thing through Q_SET.

Variant

mtb-mpy and mtb-only