ai_engine.h

Go to the documentation of this file.

/*******************************************************************************
 * File Name        : ai_engine.h
 *
 * Description      : BENTO Edge AI engine — runs ONE DEEPCRAFT model at a time
 *                    on CM55 (TFLite-Micro + Ethos-U55) and publishes a result
 *                    snapshot for the UI and the MicroPython model link.
 *
 *                    WHY ONE AT A TIME (design ruling, three independent walls):
 *                      1. one NPU  — Ethos-U55 inferences serialize anyway;
 *                      2. one sensor pipeline per model family (IMU / radar /
 *                         mic) with different sample rates and windows;
 *                      3. CM55 CPU budget beside LVGL (GFX task, priority 6).
 *                    Models are all COMPILED IN; activating one is a registry
 *                    switch, not a reload — no flash or weight copy.
 *
 *                    Every inference is timed with the DWT cycle counter and
 *                    published in the snapshot, so a model that outgrows its
 *                    cadence is visible on-screen rather than silent.
 *
 * Target           : PSoC Edge E84, CM55
 * //! [doc-drift-fix] — docs/template_local_deltas.list
 *******************************************************************************/
 
#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.
     *
     * The watch rows depend on this: a row's confidence is the maximum over
     * classes 1..class_count-1 (see row_score_pct in page_edge_ai.c), so a
     * model whose classes were all positive would render as if the loudest one
     * were always firing. A new model that cannot honour this needs that code
     * changed, not a quiet exception here. */
    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 spelled in the wire header, because MicroPython has to
 * resolve a legacy 13/14/15 to the same value before it can confirm a select.
 * When the two drifted, every Sound Watch select reported "not confirmed" on a
 * board that had in fact switched. Checked 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: publish() writes only that
     * many floats and the slots above were 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 */