ai_engine.h

Go to the documentation of this file.

/*******************************************************************************
 * File Name        : ai_engine.h
 *
 * Description      : BENTO Edge AI engine on CM55 (TFLite-Micro + Ethos-U55).
 *                    Holds the model registry, runs one model or one model set
 *                    at a time, and publishes a result snapshot for the UI and
 *                    the MicroPython model link.
 *
 *                    Start a model, or a set (a set index in place of a model
 *                    index), with ai_engine_start(). Read one model's verdict
 *                    with ai_engine_snapshot_model(); ai_engine_snapshot()
 *                    returns only the most recent verdict from any model.
 *                    ai_engine_requested() is what was asked for;
 *                    ai_engine_active() is what has finished loading.
 *
 *                    Every inference is timed and published in the snapshot
 *                    (inference_us), so a model that outgrows its cadence is
 *                    visible on-screen rather than silent.
 *
 * Target           : PSoC Edge E84, CM55
 *******************************************************************************/
 
#ifndef AI_ENGINE_H
#define AI_ENGINE_H
 
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>   /* NULL — ai_result_top_positive() below is inline here */
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define AI_MAX_CLASSES      (8u)
#define AI_MAX_LABEL_LEN    (16u)

typedef enum {
    AI_SENSOR_IMU = 0,      
    AI_SENSOR_RADAR,        
    AI_SENSOR_MIC,          
} ai_sensor_t;

typedef struct {
    const char *name;                   
    const char *description;            
    ai_sensor_t sensor;
    uint8_t     class_count;
    /* Registry contract: index 0 is the negative class -- the one that means
     * "nothing is happening". It is "unlabelled" in the audio and radar models,
     * "idle" in motion, "normal" in fall. Everything from 1 up is a positive
     * detection.
     *
     * Summary scores depend on this: ai_result_top_positive() (below) takes
     * the maximum over classes 1..class_count-1, so a model whose classes were
     * all positive would read as if the loudest one were always firing. A model
     * that cannot honour this contract must not be registered as if it did;
     * give it an explicit negative class instead. */
    const char *class_labels[AI_MAX_CLASSES];
    uint32_t    flash_bytes;            
    uint16_t    period_ms;              
 
    /* DEEPCRAFT-generated entry points (symbol-prefixed per model so several
     * models can be linked into one image — the generated sources all declare
     * IMAI_* otherwise). */
    int (*init)(void);
    int (*enqueue)(const float *in);
    int (*dequeue)(float *out);
    void (*finalize)(void);
} ai_model_desc_t;

typedef struct {
    uint8_t  model_index;               
    uint8_t  class_count;
    uint8_t  top_class;                 
    uint8_t  running;                   
    float    scores[AI_MAX_CLASSES];    
    uint32_t inference_us;              
    uint32_t inference_us_max;          
    uint32_t inferences;                
    uint32_t seq;                       
} ai_result_t;

#define AI_PARALLEL_MIC  (255)

#define AI_PARALLEL_ROOM      (254)
#define AI_PARALLEL_INTRUDER  (253)

#define AI_PARALLEL_ALL       (252)

#define AI_PARALLEL_FIRST     AI_PARALLEL_ALL
 
/* These numbers are also defined in the model-link wire header
 * (ipc_model_link_defs.h), because MicroPython has to resolve a legacy
 * 13/14/15 to the same value before it can confirm a select. The two are
 * checked equal here rather than trusted, and only when the wire header is in
 * the translation unit, so this header still compiles on its own. */
#if defined(MODEL_LINK_SET_MIC)
_Static_assert(AI_PARALLEL_ALL      == MODEL_LINK_SET_ALL,      "set index drift");
_Static_assert(AI_PARALLEL_INTRUDER == MODEL_LINK_SET_INTRUDER, "set index drift");
_Static_assert(AI_PARALLEL_ROOM     == MODEL_LINK_SET_ROOM,     "set index drift");
_Static_assert(AI_PARALLEL_MIC      == MODEL_LINK_SET_MIC,      "set index drift");
#endif

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

const char *ai_engine_set_name(uint32_t set_index);

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

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

void     ai_engine_unload(uint32_t idx);
uint32_t ai_engine_unload_done(void);
uint32_t ai_engine_unload_refused(void);
 
uint32_t ai_engine_model_count(void);

const ai_model_desc_t *ai_engine_model(uint32_t index);

int ai_engine_register(const ai_model_desc_t *desc);

uint32_t ai_engine_dyn_count(void);
uint32_t ai_engine_dyn_capacity(void);

bool ai_engine_init(void);

bool ai_engine_start(uint32_t index);

uint32_t ai_engine_stack_words(void);

uint32_t ai_engine_feeds(void);
uint32_t ai_engine_dq_ok(void);
uint32_t ai_engine_dq_calls(void);

void ai_engine_set_sensor_rate(uint32_t interval_ms);

void ai_engine_resume_sensor(void);
uint32_t ai_engine_inits(void);

uint32_t ai_engine_init_calls(void);

uint32_t ai_engine_init_returns(void);

uint64_t ai_engine_npu_cycles(void);

uint32_t ai_engine_stale_drops(void);

uint32_t ai_engine_stack_free_words(void);
int32_t  ai_engine_last_init_rc(void);

void ai_engine_stop(void);

int ai_engine_active(void);

int ai_engine_requested(void);

bool ai_engine_snapshot(ai_result_t *out);

bool ai_engine_snapshot_model(uint32_t index, ai_result_t *out);

uint32_t ai_engine_set_members(uint8_t *idx, uint32_t max);

static inline int ai_result_top_positive(const ai_result_t *r, uint8_t *which)
{
    if (which != NULL) { *which = 1u; }
    if ((r == NULL) || (r->class_count < 2u)) { return 0; }
    float   best = r->scores[1];
    uint8_t arg  = 1u;
    /* Bounded by class_count, not the array size: only the first class_count
     * scores are valid and the slots above are never set. */
    for (uint8_t c = 2u; (c < r->class_count) && (c < AI_MAX_CLASSES); c++) {
        if (r->scores[c] > best) { best = r->scores[c]; arg = c; }
    }
    if (which != NULL) { *which = arg; }
    int pct = (int)(best * 100.0f + 0.5f);
    if (pct < 0)   { pct = 0; }
    if (pct > 100) { pct = 100; }
    return pct;
}

bool ai_engine_mic_settling(void);

uint32_t ai_engine_mic_settle_pct(void);
 
#ifdef __cplusplus
}
#endif
 
#endif /* AI_ENGINE_H */