Classification sample
This sample demonstrates a multi-class classifier that identifies parcel delivery states (Idle, Shaking, Impact, Free Fall, Carrying, In Car, Placed) from a stream of acceleration magnitude samples.
Requirements
The sample supports the following development kits:
Hardware platforms |
PCA |
Board name |
Board target |
|---|---|---|---|
PCA10184 |
|
||
PCA10156 |
|
||
PCA10156 |
|
||
PCA10156 |
|
||
PCA10175 |
|
||
PCA10095 |
|
||
PCA10040 |
|
||
PCA10056 |
|
Overview
The sample evaluates activity classification over consecutive 50-sample windows, printing both the predicted activity class and the associated confidence probabilities for each window. The model processes a single input feature—acceleration magnitude—collected over 50 consecutive samples for each prediction.
It classifies each window into one of seven possible activity classes:
IDLE
SHAKING
IMPACT
FREE_FALL
CARRYING
IN_CAR
PLACED
Each time a complete 50-sample window is received, the model outputs its prediction and corresponding probabilities for each possible class. The model does not require additional context beyond each window to make its predictions. The predicted class for each window is the one with the highest confidence probability.
Configuration
See Configuring and building for information about how to permanently or temporarily change the configuration.
The project configuration for this sample is provided in samples/nrf_edgeai/classification/prj.conf.
Model backend (Neuton and Axon)
The sample can use either of two model backends, selected in Kconfig:
Neuton (CPU) — Runs on the application core. It is supported on all nRF Edge AI boards.
Axon (NPU) — Runs on the Axon neural processing unit. It is available only on SoCs with Axon NPU.
To select the model backend, set the CONFIG_NRF_EDGEAI_CLASSIFICATION_MODEL_NEUTON or CONFIG_NRF_EDGEAI_CLASSIFICATION_MODEL_AXON Kconfig option in your prj.conf file.
See board-specific configuration and overlays in the samples/nrf_edgeai/classification/boards/ folder.
When using the Axon backend, the generated model saves its buffer requirements in the prj_example.conf file as the CONFIG_NRF_AXON_INTERLAYER_BUFFER_SIZE and CONFIG_NRF_AXON_PSUM_BUFFER_SIZE Kconfig options.
You must manually include these values in your prj.conf file before building.
Configuration options
In your prj.conf file, the following settings are applied to ensure the sample builds and runs correctly:
CONFIG_NRF_EDGEAI=y
CONFIG_FPU=y
CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=y
CONFIG_RTT_CONSOLE=n
CONFIG_PICOLIBC_IO_FLOAT=y
See the following descriptions of the enabled Kconfig options:
The
CONFIG_NRF_EDGEAIKconfig option enables the nRF Edge AI library and its components in the build system.The
CONFIG_PICOLIBC_IO_FLOATKconfig option enables printing of floating-point values (required for model output/logging).The
CONFIG_FPUKconfig option enables the hardware floating-point unit (FPU), if present, to accelerate inference when using floating-point models.
Building and running
This sample can be found under samples/nrf_edgeai.
To build the sample, follow the instructions in Building an application for your preferred building environment.
See also Programming for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.
If the model sources are provided as a generated C library, ensure they are placed under the application source tree (for example, samples/nrf_edgeai/<sample>/src/nrf_edgeai_generated) so CMake discovers and builds them together with the application.
Testing
The application automatically evaluates a set of validation cases using windows of 50 samples each. For each case, the sample prints the predicted activity class, its probability, and the expected ground truth label:
In 7 classes, predicted 1 with probability 0.945678
Expected class SHAKING - predicted SHAKING
Observe the output for each window:
The line reports the total number of supported classes (7 in this case).
predictedshows the model’s chosen class index, along with its probability for this window.The following line compares the expected (ground truth) class to the predicted class.
Check that the predicted class matches the expected class for each validation sample.
Review the class probability for additional insight into the model’s confidence in its predictions.
Manual inference using the API
You can also perform manual inference in your own application code by providing sample data and inspecting the model output.
The following example demonstrates how to initialize the model, feed your own 50-sample window, and print out the predicted class and its probabilities:
#include <nrf_edgeai/nrf_edgeai.h>
#include <nrf_edgeai_generated/nrf_edgeai_user_model.h>
#include <assert.h>
#include <stdio.h>
// In this example, our raw features is a window of N elements with 3 accelerometer axis values
// The number of raw features and their order should be the same as in the training dataset file
int16_t raw_features[] =
{
Accelerometer_X0,
Accelerometer_Y0,
Accelerometer_Z0,
/* ... */
Accelerometer_Xn,
Accelerometer_Yn,
Accelerometer_Zn,
};
// Pointer to user model
static nrf_edgeai_t* p_edgeai = NULL;
void user_init_edegeai_model(void)
{
// Get user model pointer
p_edgeai = nrf_edgeai_user_model();
// Init EdgeAI library based on user solution, should be called once!
nrf_edgeai_err_t res = nrf_edgeai_init(p_edgeai);
// Optional check for success, #include <assert.h> required
assert(res == NRF_EDGEAI_ERR_SUCCESS);
}
//
// ....
//
void user_feed_data_to_model(void)
{
// Feed and prepare raw inputs for the model inference
nrf_edgeai_err_t res = nrf_edgeai_feed_inputs(p_edgeai, raw_features,
nrf_edgeai_uniq_inputs_num(p_edgeai) *
nrf_edgeai_input_window_size(p_edgeai));
// Check if input data is prepared and ready for model inference
if (res == NRF_EDGEAI_ERR_SUCCESS)
{
// Run model inference
res = nrf_edgeai_run_inference(p_edgeai);
// Check if model inference is ready and successful
if (res == NRF_EDGEAI_ERR_SUCCESS)
{
uint16_t predicted_class = p_edgeai->decoded_output.classif.predicted_class;
size_t num_classes = p_edgeai->decoded_output.classif.num_classes;
// Get probability depending on model quantization: f32, q16, q8. Here is an example for f32 model
const flt32_t* p_probabilities = p_edgeai->decoded_output.classif.probabilities.p_f32;
printf("Predicted class %u with probability %f, in %u classes\r\n", predicted_class,
p_probabilities[predicted_class],
num_classes);
}
}
}
This example prints the predicted activity class, the associated probability, and the number of supported classes:
Predicted class 1 with probability 0.945678, out of 7 classes
If you want to compare to a known expected class or print human-readable class labels, you can add such logic based on the application’s requirements.
Dependencies
Header file:
include/zephyr/kernel.h