treewide: Add documentation for hello_ei sample and Edge Impulse

- Add README for edge_impulse/hello_ei sample.
- Make changes in doc/integrations/edge_impulse.rst related to
change of form of deployment EI models (use of EI SDK module).
- Add section about usage of EI west extension commands.

Jira: NCSDK-37082

Signed-off-by: Bartosz Meus <bartosz.meus@nordicsemi.no>

Author: mbarchie

doc/integrations/edge_impulse.rst

@@ -8,7 +8,7 @@ Edge Impulse integration
    :depth: 2
 
 `Edge Impulse`_ is a development platform that can be used to enable `embedded machine learning`_ on |NCS| devices.
-You can use this platform to collect data from sensors, train machine learning model, and then deploy it to your Nordic Semiconductor's device.
+You can use this platform to collect data from sensors, train a machine learning model, and then deploy it to your Nordic Semiconductor's device.
 
 Integration prerequisites
 *************************
@@ -19,16 +19,34 @@ Before you start the |EAI| integration with Edge Impulse, make sure that the fol
 * Setup of the required Development Kit (DK).
 * Creation of an `Edge Impulse studio account <Edge Impulse studio signup_>`_ and an Edge Impulse project.
 
+Solution architecture
+*********************
+
+The Edge Impulse integration consists of three main components:
+
+* **Edge Impulse SDK** - A C++ library that provides the inference engine and digital signal processing (DSP) functions required to run machine learning models on embedded devices.
+  The SDK is integrated into the build system as a Zephyr module through the west manifest file of the |EAI|.
+* **Deployed ML model** - A Zephyr library package generated by Edge Impulse Studio that contains your trained model's parameters.
+  This is provided as a :file:`zip` archive with C/C++ source files that are compiled together with your application.
+* **Application code** - Your |NCS| application that collects sensor data, feeds it to the inference engine through the Edge Impulse SDK API, and processes the classification results.
+
+The typical workflow involves collecting sensor samples, running inference using a sliding window approach, and interpreting the classification results to make decisions or trigger actions.
+This is presented in the :ref:`hello_ei_sample` sample.
+
 Integration overview
 ********************
 
 Before integrating the Edge Impulse machine learning model into an |EAI| application, you must prepare and deploy the machine learning model for your embedded device.
 This model is prepared using the `Edge Impulse studio`_ external web tool.
 It relies on sensor data that can be provided by different sources, for example data forwarder.
-Check the :ref:`ei_data_forwarder_sample` sample for a demonstration of how you can send sensor data to Edge Impulse studio using `Edge Impulse's data forwarder`_.
 
-The machine learning model is distributed as a single :file:`zip` archive that includes C++ library sources.
-This file is used by the |NCS| build system to build the Edge Impulse library.
+.. note::
+   You can collect data using either a development board that is supported directly by Edge Impulse or your mobile phone.
+   Alternatively, you can modify the :ref:`ei_data_forwarder_sample` sample to forward data from a sensor that is connected to any board available in the |NCS|.
+
+The machine learning model is distributed as a single :file:`zip` archive that includes C/C++ machine learning model sources.
+You must include these files in your |EAI| application.
+Apart from that, you must also enable the `Edge Impulse`_ SDK (see :ref:`ug_edge_impulse_building`).
 
 Integration steps
 *****************
@@ -45,46 +63,105 @@ Complete the following steps to generate the archive and add it to the build sys
 Preparing the machine learning model
 ====================================
 
-To prepare the machine learning model, use `Edge Impulse studio`_ and follow one of the tutorials described in `Edge Impulse getting started guide`_.
-For example, you can try the `Continuous motion recognition tutorial`_.
-This tutorial will guide you through the following steps:
+1. Prepare your own machine learning model.
 
-1. Collecting data from sensors and uploading the data to Edge Impulse studio.
+   To prepare a machine learning model, use `Edge Impulse studio`_ and follow one of the tutorials described in `Edge Impulse getting started guide`_.
+   For example, to test the solution, you can try the `Continuous motion recognition tutorial`_.
+   You will complete the following steps:
 
-   .. note::
-     You can use one of the development boards supported directly by Edge Impulse or your mobile phone to collect the data.
-     You can also modify the :ref:`ei_data_forwarder_sample` application and use it to forward data from a sensor that is connected to any board available in the |NCS|.
+   a. Collect data from sensors and upload them to the Edge Impulse studio.
+
+   #. Design your machine learning model (an *impulse*).
+
+#. Deploy your machine learning model to use it on an embedded device by following one of the two methods:
+
+   You can obtain a library in two ways:
+
+   .. tabs::
+
+      .. group-tab:: Using |EIS| web interface
+
+         Go to the :guilabel:`Deployment` tab and select :guilabel:`Zephyr library`.
+         This will generate a :file:`zip` file that contains source files defining the |EI| ML model.
+
+         .. figure:: ./images/ei_deploy.png
+            :scale: 50 %
+            :alt: Model deployment in |EIS| dashboard
+
+            Model deployment in |EIS| dashboard
+
+         .. note::
+            Edge Impulse supports multiple deployment formats, some of which are compatible with |NCS| applications.
+            However, this instruction focuses on the Zephyr library deployment format.
+
+      .. group-tab:: Using |EI| west extensions
 
-#. Designing your machine learning model (an *impulse*).
-#. Deploying the machine learning model to use it on an embedded device.
-   As part of this step, you must select the :guilabel:`C++ library` to generate the required :file:`zip` file that contains the source files for building the Edge Impulse library in |EAI|.
+         |EI| provides west command extensions that let you build and deploy the machine learning model from |EIS| using the command line instead of the web interface.
+         The commands are already configured in the |EAI| west manifest and are ready to use.
+
+         a. Find two parameters that are required by the commands:
+
+            * ``Project ID`` - You can find it in the :guilabel:`Project info` panel under :guilabel:`Dashboard`.
+
+               .. figure:: ./images/ei_project_id.png
+                  :scale: 50 %
+                  :alt: Project ID in |EIS| dashboard
+
+                  Project ID in |EIS| dashboard
+
+            * ``API key`` - You can find it under the :guilabel:`Keys` tab in the |EI| project dashboard.
+
+               .. figure:: ./images/ei_api_key.png
+                  :scale: 50 %
+                  :alt: API key under the Keys tab in |EIS|
+
+                  API key under the Keys tab in |EIS|
+
+         #. Build the machine learning model by running the following command:
+
+            .. code-block:: console
+
+               west ei-build -p <PROJECT_ID> -k <API_KEY>
+
+         #. Deploy the machine learning model by running the following command:
+
+            .. code-block:: console
+
+               west ei-deploy -p <PROJECT_ID> -k <API_KEY>
+
+            As a result, file :file:`ei_model.zip` is downloaded to your working directory.
+
+         For more details on how to use these commands, see `Automated Deployment with West Commands`_ documentation.
 
 .. _ug_edge_impulse_adding_building:
 
 .. rst-class:: numbered-step
 
-Building the machine learning model in |EAI|
-============================================
+Building an application with machine learning model
+===================================================
 
-After preparing the :file:`zip` archive, you can use the |NCS| build system to build the C++ library with the machine learning model.
-Complete the following steps to configure the building process:
+You have to complete the following configuration steps to be able to build your application including the deployed |EI| machine learning model:
 
-1. Make sure that the following Kconfig options are **enabled**:
+1. Make sure that the following Kconfig options are enabled:
 
    * ``CONFIG_CPP``
    * ``CONFIG_STD_CPP11``
    * ``CONFIG_REQUIRES_FULL_LIBCPP``
+   * ``CONFIG_EDGE_IMPULSE_SDK``
 
    .. note::
       The ``CONFIG_FPU`` Kconfig option is implied by default if floating point unit (FPU) is supported by the hardware.
       Using FPU speeds up calculations.
 
-#. Make sure that the ``CONFIG_FP16`` Kconfig option is **disabled**.
-   The Edge Impulse library is not compatible with half-precision floating point support introduced in Zephyr.
+#. Make sure that the ``CONFIG_FP16`` Kconfig option is disabled.
+   The |EI| library is not compatible with half-precision floating point support introduced in Zephyr.
+
+.. _ug_edge_impulse_building:
 
 Applications and samples
 ************************
 
 The following samples demonstrate the Edge Impulse integration in the |EAI|:
 
-* :ref:`ei_data_forwarder_sample` sample - demonstrates how you can send sensor data to Edge Impulse studio using `Edge Impulse's data forwarder`_.
+* :ref:`ei_data_forwarder_sample` sample - Demonstrates how you can send sensor data to |EIS| using `Edge Impulse's data forwarder`_.
+* :ref:`hello_ei_sample` sample - Demonstrates the deployment of models in |EI| and usage of the inference engine provided by |EI| SDK.

doc/integrations/images/ei_api_key.png

@@ -49,6 +49,7 @@
 .. _`Building an application`: https://docs.nordicsemi.com/bundle/ncs-3.2.0/page/nrf/app_dev/config_and_build/building.html#building
 .. _`Programming`: https://docs.nordicsemi.com/bundle/ncs-3.2.0/page/nrf/app_dev/programming.html#programming
 .. _`Testing and optimization`: https://docs.nordicsemi.com/bundle/ncs-3.2.0/page/nrf/test_and_optimize.html#testing
+.. _`Providing CMake options`: https://docs.nordicsemi.com/bundle/ncs-3.2.0/page/nrf/app_dev/config_and_build/cmake/index.html#providing_cmake_options
 
 .. _`Simulated sensor driver`: https://docs.nordicsemi.com/bundle/ncs-3.2.0/page/nrf/drivers/sensor_sim.html
 
@@ -68,6 +69,8 @@
 .. _`nRF Connect SDK simulated sensor machine learning model`: https://studio.edgeimpulse.com/public/18121/latest
 .. _`nRF Connect SDK hardware accelerometer machine learning model`: https://studio.edgeimpulse.com/public/33129/latest
 .. _`Nordic Semi nRF54L15 DK page`: https://docs.edgeimpulse.com/docs/nordic-semi-nrf54L15-dk
+.. _`Edge Impulse Zephyr Module Deployment`: https://docs.edgeimpulse.com/hardware/deployments/run-zephyr-module
+.. _`Automated Deployment with West Commands`: https://docs.edgeimpulse.com/hardware/deployments/run-zephyr-module#automated-deployment-with-west-commands-early-access-preview
 
 .. ### Source: github.com
 

doc/integrations/images/ei_deploy.png

@@ -21,6 +21,11 @@ The samples demonstrate typical workflows using the nRF Edge AI components such
 * DSP - Demonstrates using the nRF Edge AI Digital Signal Processing (DSP) primitives for signal processing.
 * NN - Demonstrates using the nRF Edge AI Neural Network (NN) engine for running its standalone models.
 
+There are also additional samples demonstrating the integration of `Edge Impulse`_ with |EAI|:
+
+* |EI|: Data forwarder - Demonstrates using `Edge Impulse's data forwarder`_.
+* |EI|: Hello Edge Impulse - Demonstrates deployment of models in |EI| and usage of the inference engine provided by |EI| SDK.
+
 .. toctree::
    :maxdepth: 2
 

doc/integrations/images/ei_project_id.png

@@ -10,3 +10,4 @@ This section lists the available |EAI| samples presenting integration with `Edge
    :caption: Subpages
 
    /../samples/edge_impulse/data_forwarder/README.rst
+   /../samples/edge_impulse/hello_ei/README.rst

doc/links.txt

@@ -2,6 +2,7 @@
 .. |EAI| replace:: Edge AI Add-on
 .. |nRFVSC| replace:: nRF Connect for VS Code extension
 .. |EI| replace:: Edge Impulse
+.. |EIS| replace:: Edge Impulse Studio
 
 .. ### Configuration and testing shortcuts
 

doc/samples.rst

@@ -0,0 +1,149 @@
+.. _hello_ei_sample:
+
+Edge Impulse: Hello Edge Impulse
+################################
+
+.. contents::
+   :local:
+   :depth: 2
+
+The Hello Edge Impulse sample demonstrates how to use the `Edge Impulse`_ SDK and custom machine learning model when :ref:`integrating Edge Impulse with the nRF Connect SDK <edge_impulse_integration>`.
+
+Requirements
+************
+
+The sample supports the following development kits:
+
+.. table-from-sample-yaml::
+
+Overview
+********
+
+This sample runs a pre-trained `Edge Impulse`_ machine learning model using two input data series that represent a sine wave and a triangle wave with added noise.
+Sample's main purpose is to:
+
+1. Provide input data to the |EI| model.
+#. Start predictions using the machine learning model.
+#. Display the prediction results and time measurements.
+
+Configuration
+*************
+
+|config|
+
+The sample can be configured using the following Kconfig options:
+
+.. options-from-kconfig::
+   :show-type:
+
+.. _hello_ei_sample_building_and_running:
+
+Building and running
+********************
+
+.. |sample path| replace:: :file:`samples/edge_impulse/hello_ei`
+
+.. include:: /includes/build_and_run.txt
+
+Testing
+=======
+
+|test_sample|
+
+1. |connect_kit|
+#. |connect_terminal_kit|
+#. Reset the kit.
+#. Observe the following UART output:
+
+   .. code-block:: console
+
+      *** Booting nRF Connect SDK v3.2.0-5dcc6bd39b0f ***
+      *** Using Zephyr OS v4.2.99-a57ad913cf4e ***
+      I: === Model info ===
+      I: Input frame size: 3
+      I: Input window size: 312
+      I: Input frequency: 52
+      I: Label count: 3
+      I: Has anomaly: yes
+      I: #########################
+      I: Running inference on sine wave input data
+      I: #########################
+      I: === Inference result ===
+      I: idle => 0.00000
+      I: sine => 0.99603
+      I: triangle => 0.00397
+      I: anomaly: -0.12298
+      I: === Inference time profiling ===
+      I: Full inference completed in 6564 us
+      I: Classification completed in 766 us
+      I: DSP operations completed in 5562 us
+      I: Anomaly detection completed in 63 us
+      I: #########################
+      I: === Inference result ===
+      I: idle => 0.00000
+      I: sine => 0.99648
+      I: triangle => 0.00352
+      I: anomaly: -0.12898
+      I: === Inference time profiling ===
+      I: Full inference completed in 6560 us
+      I: Classification completed in 762 us
+      I: DSP operations completed in 5562 us
+      I: Anomaly detection completed in 61 us
+      ...
+
+The observed classification results depend on machine learning model and input data.
+
+Using your custom machine learning model
+========================================
+
+If you wish to run this sample using a pre-trained model, go to the :ref:`hello_ei_sample_building_and_running` section.
+Otherwise, if you wish to use a custom machine learning model, you must complete the following setup:
+
+1. :ref:`Train and deploy your own machine learning model <ug_edge_impulse_adding_preparing>`.
+   Choose |EIS| web interface method (a Zephyr library format).
+
+#. Select the |EI| model.
+
+   Set the ``CONFIG_EDGE_IMPULSE_PATH`` to an absolute or relative path to a file in the local filesystem.
+   The file must be a ZIP archive generated by |EIS|, and it must contain the source files that define the |EI| ML model.
+   The relative path is tracked from the application source directory (``APPLICATION_SOURCE_DIR``).
+   Any CMake variables included in the path are expanded.
+
+#. Define input data for the machine learning model in the :file:`samples/edge_impulse/hello_ei/src/include/input_data.h` file.
+#. Check the example input data in your |EIS| project:
+
+   a. Go to the :guilabel:`Live classification` tab.
+   #. In the :guilabel:`Classify existing test sample` panel, select one of the test samples.
+   #. Click :guilabel:`Load sample` to display the raw data preview.
+
+      .. figure:: ./doc/images/ei_load_test_sample.png
+         :scale: 50 %
+         :alt: Loading test sample input data in |EIS|
+
+         Loading test sample input data in |EIS|
+
+      The classification results will be displayed along with a preview of raw data.
+
+      .. figure:: ./doc/images/ei_raw_features.png
+         :scale: 50 %
+         :alt: Raw data preview in |EIS|
+
+         Raw data preview in |EIS|
+
+#. Copy information from the :guilabel:`Raw features` list into an array defined in the :file:`input_data.h` file.
+
+.. note::
+    If you provide more input data than a single input window can hold, the prediction will be triggered multiple times.
+    The input window will be shifted by one input frame between subsequent predictions.
+    The prediction will be retriggered until there is no more input data available.
+
+Dependencies
+************
+
+This sample uses the following Zephyr libraries:
+
+* `Logging`_
+
+This sample uses the following external components:
+
+* `Edge Impulse`_ SDK