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 the 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 the following functions to access results:

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.

Param err

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

Functions

bool ei_wrapper_classifier_has_anomaly(void)

Check if classifier calculates anomaly value.

Return values

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.

Returns

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.

Returns

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

size_t ei_wrapper_get_classifier_frequency(void)

Get input data sampling frequency of the classifier.

Returns

The sampling frequency in Hz.

size_t ei_wrapper_get_classifier_label_count(void)

Get number of labels used by the classifier.

Returns

Number of labels.

const char *ei_wrapper_get_classifier_label(size_t idx)

Get classifier label with given index.

Index can be number from 0 to number of labels used by classifier minus one.

Parameters

  • idx – [in] Index of the selected classification label.

Returns

Classifier label or NULL if the index is out of range.

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

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

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

Return values

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

int ei_wrapper_clear_data(bool *cancelled)

Clear all buffered data.

The buffer cannot be cleared if the prediction was already started and the wrapper is not waiting for data. In that case, user must wait until the prediction is finished.

If the wrapper is waiting for data, the prediction is cancelled.

Parameters

  • cancelled – [out] Pointer to the variable that is used to store information if prediction was cancelled.

Return values

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

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

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

Return values

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

int ei_wrapper_get_next_classification_result(const char **label, float *value, size_t *idx)

Get next classification result.

Results are ordered based on descending classification value. If there are more results with the given value, they are ordered based on ascending index.

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

Parameters

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

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

  • idx – [out] Pointer to the variable that is used to store the index of the classification label.

Return values

  • 0 – On success.

  • -EACCES – If function is executed from other context that the wrapper’s callback.

  • -ENOENT – If no more results are available.

int ei_wrapper_get_anomaly(float *anomaly)

Get anomaly value.

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

Parameters

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

Return values

  • 0 – On success.

  • -EACCES – If function is executed from other context that the wrapper’s callback.

  • -ENOTSUP – If calculating anomaly value is not supported.

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

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

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

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

Return values

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

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

Return values

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