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,25 @@ 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 usage of `Edge Impulse`_ SDK is demonstrated by the :ref:`hello_ei_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 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` sample and use it 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.
+These files have to be included to an |EAI| application.
+Apart from that, the application must also enable the `Edge Impulse`_ SDK (see: :ref:`ug_edge_impulse_building`).
 
 Integration steps
 *****************
@@ -45,46 +54,110 @@ 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, you can try the `Continuous motion recognition tutorial`_.
+   This tutorial will guide you through 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|.
+   * Collecting data from sensors and uploading the data to Edge Impulse studio.
+
+   * Designing your machine learning model (an *impulse*).
+
+#. Deploy your machine learning model to use it on an embedded device.
+
+   You can obtain a library in two ways:
+
+   .. tabs::
+
+      .. group-tab:: Using |EIS| web interface
+
+         Go to the :guilabel:`Deployment` tab and select **Zephyr library** to generate a :file:`zip` file that contains source files defining the |EI| ML model.
+         The download of the :file:`zip` archive will start automatically.
+
+         .. figure:: ./images/ei_deploy.png
+            :scale: 50 %
+            :alt: Model deployment in |EIS| dashboard
+
+            Model deployment in |EIS| dashboard
+
+         .. note::
+            There are different forms of deployment available, which can also be compatible with |NCS| applications, but this instruction focuses on presenting the Zephyr library form of deployment.
+
+      .. group-tab:: Using |EI| west extensions
+
+         |EI| provides west command extensions which can be used to 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 ready to use.
+         There are two commands available:
+
+         * ``west ei-build`` - builds the machine learning model in |EIS|,
+         * ``west ei-deploy`` - deploys a model in the form of a zip file and downloads it from |EIS|.
 
-#. 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|.
+         Follow these steps to use the commands:
+
+         1. Find two parameters that are required by the commands:
+
+            * **Project ID** - You can find it in the **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 the current working directory.
+
+         More details about usage of these commands are described in `Automated Deployment with West Commands`_.
 
 .. _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**:
 
    * ``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.
+   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,144 @@
+.. _hello_ei_sample:
+
+Edge Impulse: Hello Edge Impulse
+################################
+
+.. contents::
+   :local:
+   :depth: 2
+
+The Hello Edge Impulse sample demonstrates usage of `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
+********
+
+The sample:
+
+1. Provides input data to the `Edge Impulse`_ model.
+#. Starts predictions using the machine learning model.
+#. Displays the prediction results and time measurements to the user.
+
+By default, the sample uses a pre-trained machine learning model and 2 input data series representing a sine wave and a triangle wave with some noise added.
+
+Configuration
+*************
+
+|config|
+
+The sample can be configured using the following Kconfig options:
+
+.. options-from-kconfig::
+   :show-type:
+
+Using your own machine learning model
+=====================================
+
+To run the sample using 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>`.
+   Use a **Zephyr library** form of deployment described in the instructions.
+
+#. Select the Edge Impulse 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 :file:`zip` archive generated by |EIS| containing the source files defining the Edge Impulse ML model.
+   The relative path is tracked from the application source directory (``APPLICATION_SOURCE_DIR``).
+   CMake variables that are part of the path are expanded.
+
+#. Define input data for the machine learning model in :file:`samples/edge_impulse/hello_ei/src/include/input_data.h`.
+#. Check the example input data in your |EIS| project:
+
+   a. Go to the :guilabel:`Live classification` tab.
+   #. In the **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, with raw data preview.
+
+      .. figure:: ./doc/images/ei_raw_features.png
+         :scale: 50 %
+         :alt: Raw data preview in |EIS|
+
+         Raw data preview in |EIS|
+
+#. Copy information from the **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.
+
+Building and running
+********************
+
+.. |sample path| replace:: :file:`samples/edge_impulse/hello_ei`
+
+Testing
+=======
+
+After programming the sample to your development kit, test it by performing the following steps:
+
+1. |connect_terminal_kit|
+#. Reset the kit.
+#. Observe that output similar to the following is logged on UART:
+
+   .. 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.
+
+Dependencies
+************
+
+This sample uses the following Zephyr libraries:
+
+* Logging
+
+This sample uses the following external components:
+
+* `Edge Impulse`_ SDK