Edge API

When you generate code for your model in DEEPCRAFT™ Studio, the Generate Code workflow converts your trained AI model into a self-contained C source file (model.c) and header file (model.h). The generated header defines the public API that you use to initialize the model, provide input data, retrieve predictions, and release resources.

Identify the API Style generated by Studio

DEEPCRAFT™ Studio generates a public C API in one of three styles — Function, Queue, or Callback — which it chooses automatically based on your model’s structure, including the use of temporal layers, multiple inputs, or multiple outputs. The Queue and Callback styles each have a timestamp and a non-timestamp variant. When you generate code using Graph UX and more than one API style is applicable, Studio allows you to select the preferred API style in the Generate Code template.

This table shows the API styles generated by Studio based on the structure of your model.

The generated model.h file defines the relevant header guard, allowing your application code to adapt to the generated API.

Initialize the model

Before calling any other functions, initialize the model using IMAI_init(). This function returns 0 on successful initialization and a non-zero value if initialization fails.

// Initialize the model before calling any other functions.
int IMAI_init(void);

For the Function API and Queue API, IMAI_init() takes no argument, while for the Callback API it takes one callback function pointer per model output. See the Callback API section below for more details.

Provide Model Input and Read Model Output

The way you send input data to the model and read model output depends on the generated API style.

• Function API: Pass the input buffer to IMAI_compute(). The function writes the prediction to the output buffer that you provide.
• Queue API: Add samples with IMAI_enqueue() and retrieve predictions with IMAI_dequeue(). Call IMAI_dequeue() after each call to IMAI_enqueue().
• Callback API: Add samples with the generated IMAI_enqueue{N}() functions. Studio delivers results asynchronously through the callbacks that you register in IMAI_init(). There is no dequeue.

API Reference

1. Function API

The Function API is generated for stateless single-input/single-output models. Each call to IMAI_compute() processes one input and writes one prediction.

/**
 * @brief Function API for computing model predictions directly from input data.
 */
#ifdef IMAI_API_FUNCTION
 
/**
 * @brief Computes model predictions directly from input data.
 *
 * This function processes the input data and produces the corresponding model output.
 *
 * @param data_in  Pointer to an input sample array with IMAI_DATA_IN_COUNT elements.
 * @param data_out Pointer to an array to store the model output, with IMAI_DATA_OUT_COUNT elements.
 */
void IMAI_compute(const float* data_in, float* data_out);
 
#endif /* IMAI_API_FUNCTION */

2. Queue API with Timestamps

The Queue API with timestamps is generated for single-input and single-output models that use a temporal boundary and require timestamps. Use IMAI_enqueue() to add input data and use IMAI_dequeue() to read predictions and the corresponding output timestamps. Call IMAI_dequeue() after each call to IMAI_enqueue().

/**
 * @brief Queue API for enqueuing and dequeuing data to and from the model.
 */
#ifdef IMAI_API_QUEUE_TIME
 
/**
 * @brief Enqueues input data and timestamp into the model.
 *
 * @param data_in Pointer to an input sample array with IMAI_DATA_IN_COUNT elements.
 * @param time_in Pointer to a timestamp of length 1, expressed in seconds.
 * @return
 * - IMAI_RET_SUCCESS (0) : Success.
 * - IMAI_RET_ERROR (-2)  : Error enqueuing data. Dequeue first.
 */
int IMAI_enqueue(const float* data_in, const float* time_in);
 
/**
 * @brief Dequeues output predictions from the model.
 *
 * @param data_out Pointer to an array to store model output, with IMAI_DATA_OUT_COUNT elements.
 * @param time_out Pointer to an array with two timestamps (start and end) of the input that generated the output.
 * @return
 * - IMAI_RET_SUCCESS (0) : Success.
 * - IMAI_RET_NODATA (-1) : No data available.
 * - IMAI_RET_ERROR (-2)  : Error retrieving data.
 */
int IMAI_dequeue(float* data_out, float* time_out);
 
#endif /* IMAI_API_QUEUE_TIME */

3. Queue API without Timestamps

The Queue API without timestamps is generated for single-input and single-output models that use a temporal boundary but do not require timestamps. Use IMAI_enqueue() to add input data and use IMAI_dequeue() to read predictions. Call IMAI_dequeue() after each call to IMAI_enqueue(). This API is also known as the Queue No Time API.

/**
 * @brief Queue No Time API for enqueuing and dequeuing data to/from the model without timestamps.
 */
#ifdef IMAI_API_QUEUE
 
/**
 * @brief Enqueues input data into the model.
 *
 * @param data_in Pointer to an input sample array with IMAI_DATA_IN_COUNT elements.
 * @return
 * - IMAI_RET_SUCCESS (0) : Success.
 * - IMAI_RET_ERROR (-2)  : Error enqueuing data. Dequeue first.
 */
int IMAI_enqueue(const float* data_in);
 
/**
 * @brief Dequeues output predictions from the model.
 *
 * @param data_out Pointer to an array to store model output, with IMAI_DATA_OUT_COUNT elements.
 * @return
 * - IMAI_RET_SUCCESS (0) : Success.
 * - IMAI_RET_NODATA (-1) : No data available.
 * - IMAI_RET_ERROR (-2)  : Error retrieving data.
 */
int IMAI_dequeue(float* data_out);
 
#endif /* IMAI_API_QUEUE */

Queue API Return Codes

When you use the Queue API with or without timestamps, always check the return value before processing the output. The possible return codes are:

#define IMAI_RET_SUCCESS    0    // Operation was successful.
#define IMAI_RET_NODATA    -1    // No data is available.
#define IMAI_RET_ERROR     -2    // Error.
#define IMAI_RET_STREAMEND -3    // End of stream.

int IMAI_enqueue(...) can return:

• IMAI_RET_SUCCESS (0): The input data is pushed to the model successfully.
• IMAI_RET_ERROR (-2): There was an error and the input data could not be enqueued.

int IMAI_dequeue(...) can return:

• IMAI_RET_SUCCESS (0): Output data is retrieved from the model successfully.
• IMAI_RET_NODATA (-1): No output data is currently available. Ensure you have pushed input data with IMAI_enqueue() before trying to dequeue.
• IMAI_RET_ERROR (-2): An error occurred while retrieving output data.

4. Callback API

The Callback API is generated for models with multiple inputs or multiple outputs. It is also the default API style for some single-input and single-output models that contain a temporal boundary. It is an event-driven API:

• You register one output callback per model output when you call IMAI_init().
• You feed each input through its own IMAI_enqueue{N}() function. Inputs that are always processed together are consolidated into a single IMAI_enqueue{N}() taking several parameters.
• The model processes data internally and invokes your callbacks as soon as an output is ready. There is no polling and no IMAI_dequeue().

The generated model.h file defines one of two header guards for the Callback API: IMAI_API_CALLBACK when the model outputs carry no timestamps, and IMAI_API_CALLBACK_TIME when the outputs are timecoded. Use these guards to adapt your application code to the generated Callback API.

Callback type definitions

The generated model.h file declares a callback type for each output data type.

Without timestamps: The model.h file declares a callback typedef for each output data type.

#ifdef IMAI_API_CALLBACK
 
/**
 * @brief Output callback for float model outputs.
 *
 * @param data   Pointer to this output's values.
 * @param length Size of the data buffer in bytes.
 */
typedef void (*imai_callback_f32)(const float* data, size_t length);
 
#endif /* IMAI_API_CALLBACK */

With timestamps: When the output carries timestamps, a timecoded variant is generated, adding a timestamp argument.

#ifdef IMAI_API_CALLBACK_TIME
 
/**
 * @brief Output callback for float model outputs, with timestamps.
 *
 * @param data   Pointer to this output's values.
 * @param length Size of the data buffer in bytes.
 * @param time   Pointer to the timestamp(s) for this output, expressed in seconds.
 */
typedef void (*imai_callback_timecoded_f32)(const float* data, size_t length,
                                            const timestamp_t* time);
 
#endif /* IMAI_API_CALLBACK_TIME */

Initialize with callbacks

IMAI_init() takes one callback parameter per output, named callback_<output_name>.

For a model with a single data_out output:

int IMAI_init(imai_callback_f32 callback_data_out);

For a model with two outputs, result1 and result2:

int IMAI_init(imai_callback_f32 callback_result1, imai_callback_f32 callback_result2);

Enqueue Inputs

The generated header defines one IMAI_enqueue{N}() function for each model input. The numbering may contain gaps when inputs are consolidated. This is expected and not an error.

#ifdef IMAI_API_CALLBACK
 
int IMAI_enqueue1(const float* data_in1);
int IMAI_enqueue2(const float* data_in2);
 
#endif /* IMAI_API_CALLBACK */

Inputs that are processed together share a single enqueue function:

#ifdef IMAI_API_CALLBACK
 
int IMAI_enqueue1(const float* data_in1, const float* data_in2);
 
#endif /* IMAI_API_CALLBACK */

When timestamps are enabled, each input gains a matching _time parameter:

#ifdef IMAI_API_CALLBACK_TIME
 
int IMAI_enqueue1(const float* data_in1, const float* data_in1_time);
 
#endif /* IMAI_API_CALLBACK_TIME */

IMAI_enqueue{N}() returns the same codes as the Queue API (IMAI_RET_SUCCESS, IMAI_RET_NODATA, IMAI_RET_ERROR, IMAI_RET_STREAMEND).

Callback API Example

Below is an example code for the Callback API:

#include "model.h"
#include <stdio.h>
 
// One handler per model output.
static void on_result(const float* data, size_t length)
{
    // 'data' holds this output's values; 'length' is the buffer size in bytes.
    printf("Prediction: %f\n", data[0]);
}
 
int main(void)
{
    // 1. Initialize and register the output callback(s).
    IMAI_init(on_result);
 
    // 2. Main processing loop.
    for (;;)
    {
        float sample[IMAI_DATA_IN_COUNT];
        read_sensor(sample);
 
        // 3. Feed data. The callback fires automatically when an output is ready.
        IMAI_enqueue1(sample);
    }
 
    // 4. Release resources when done.
    IMAI_finalize();
    return 0;
}

Deallocating resources

In cases where IMAI_init() has allocated dynamic resources, you can release them with the IMAI_finalize() function.

// Deallocate resources
void IMAI_finalize();