Edge Impulse wrapper

The Edge Impulse wrapper provides an implementation for running an embedded machine learning model on a device in nRF Connect SDK. For more information about support for Edge Impulse in nRF Connect SDK, see Using Edge Impulse with nRF Connect SDK.

Overview

The wrapper:

  • Buffers input data for the machine learning model.

  • Runs the machine learning model in a separate thread.

  • Provides results through a dedicated callback.

Before using the wrapper, you need to add the machine learning model to your nRF Connect SDK application.

Configuration

Enable the Edge Impulse wrapper by CONFIG_EI_WRAPPER option. The option is enabled by default if CONFIG_EDGE_IMPULSE is set.

The Edge Impulse NCS library can be configured with the following Kconfig options:

For more detailed description of these options, refer to the Kconfig help.

Using Edge Impulse wrapper

After setting Edge Impulse wrapper Configuration options, you can use it in your application. Use the following Edge Impulse wrapper API:

  • Use the ei_wrapper_init() function to initialize the wrapper.

  • Provide the input data using the ei_wrapper_add_data() function. The provided data is appended to an internal circular buffer that is located in RAM.

    Note

    Make sure that:

    • The number of provided input values is divisible by the input frame size for the machine learning model used. Otherwise, an error code is returned.

    • The value for the CONFIG_EI_WRAPPER_DATA_BUF_SIZE Kconfig option is big enough to temporarily store the data provided by your application.

  • Call the ei_wrapper_start_prediction() function to shift the prediction window and start the prediction for the buffered data. If the whole input window is filled with data right after the shift operation, the prediction is started instantly. Otherwise, the prediction is delayed until the missing data is provided.

    Note

    The input data that goes out of the input window is dropped from the input buffer after the shift operation. This part of the input buffer can be reused to store new data.

The Edge Impulse wrapper runs the machine learning model in a dedicated thread. Results are provided through a callback registered during the initialization of the wrapper. You can call ei_wrapper_get_classification_results() and ei_wrapper_get_timing() in the callback context to access the classification results and timings.

Refer to the API documentation for more detailed information about the API provided by the wrapper.

API documentation

Header file: include/ei_wrapper.h
Source files: lib/edge_impulse/
group ei_wrapper

Wrapper that uses Edge Impulse lib to run machine learning on device.

Typedefs

typedef void (*ei_wrapper_result_ready_cb)(int err)

Callback executed by the wrapper when the result is ready.

Parameters

  • [in] err: Zero (if operation was successful) or negative error code.

Functions

bool ei_wrapper_classifier_has_anomaly(void)

Check if classifier calculates anomaly value.

Return Value

  • true: If the classifier calculates the anomaly value. Otherwise, false is returned.

size_t ei_wrapper_get_frame_size(void)

Get the size of the input frame.

Return

Size of the input frame, expressed as a number of floating-point values.

size_t ei_wrapper_get_window_size(void)

Get the size of the input window.

Return

Size of the input window, expressed as a number of floating-point values.

int ei_wrapper_add_data(const float *data, size_t data_size)

Add input data for the library.

Size of the added data must be divisible by input frame size.

Parameters

  • [in] data: Pointer to the buffer with input data.

  • [in] data_size: Size of the data (number of floating-point values).

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int ei_wrapper_clear_data(void)

Clear all buffered data.

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int ei_wrapper_start_prediction(size_t window_shift, size_t frame_shift)

Start a prediction using the Edge Impulse library.

If there is not enough data in the input buffer, the prediction start is delayed until the missing data is added.

Parameters

  • [in] window_shift: Number of windows the input window is shifted before prediction.

  • [in] frame_shift: Number of frames the input window is shifted before prediction.

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int ei_wrapper_get_classification_results(const char **label, float *value, float *anomaly)

Get classification results.

This function can be executed only from the wrapper’s callback context. Otherwise it returns a (negative) error code.

If calculating anomaly value is not supported, anomaly is set to value of 0.0.

Parameters

  • [out] label: Pointer to the variable that is used to store the pointer to the classification label.

  • [out] value: Pointer to the variable that is used to store the classification value.

  • [out] anomaly: Pointer to the variable that is used to store the anomaly.

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int ei_wrapper_get_timing(int *dsp_time, int *classification_time, int *anomaly_time)

Get execution times for operations performed by the library.

This function can be executed only from the wrapper’s callback context. Otherwise, it returns a (negative) error code.

The library uses Zephyr’s uptime for calculations. Because of that execution times can be affected by other operations performed by the CPU.

If calculating the anomaly value is not supported, anomaly_time is set to the value of -1.

Parameters

  • [out] dsp_time: Pointer to the variable that is used to store the dsp time.

  • [out] classification_time: Pointer to the variable that is used to store the classification time.

  • [out] anomaly_time: Pointer to the variable that is used to store the anomaly time.

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int ei_wrapper_init(ei_wrapper_result_ready_cb cb)

Initialize the Edge Impulse wrapper.

Parameters

  • [in] cb: Callback used to receive results.

Return Value

  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.