../_images/cartesiam_logo.png

NanoEdge AI Library

../_images/banner.png
NanoEdge AI Studio, Library and Emulator: use the Studio to find the best Library.
Before embedding, test your Library’s performances locally using its clone, the Emulator.

I. What is NanoEdge AI Library?

NanoEdge AI Library is an artificial intelligence static library developed by Cartesiam, for embedded C software running on ARM Cortex microcontroller.

When embedded on microcontrollers, it gives them the ability to easily “learn” and “understand” sensor patterns, by themselves, without the need for the user to have additional skills in Mathematics, Machine Learning, or Data science.

The NanoEdge AI static library is the code that contains an AI model (for example, as a bundle of signal treatment, machine learning model, optimally tuned hyperparameters, etc.) designed to gather knowledge incrementally during a learning phase, in order to become able to detect potential anomalous machine behaviors, and possibly predict them.

Note

  • The library is not available in the free version of the Studio.
  • However, if you select one of the authorized development boards available, you can download a specific library which will work only on thoses targets.

II. Install / Getting started

The main functions available via the library are:

initialize() run first before learning/detecting, or to reset the knowledge of the library/emulator
set_sensitivity() adjust the pre-set, internal detection sensitivity (does not affect learning, only returned similarity scores)
learn() start a number of learning iterations (to establish an initial knowledge, or enrich an existing one)
detect() start a number detection iterations (inference), once a minimum knowledge base has been established

Important

When building a smart device, the final features will heavily depend on the way those functions are called. It is entirely up to the developer to design relevant learning and detection strategies, depending on the project’s specificities and constraints.

../_images/ild.png

For example for a hypothetical machine, one strategy could be to:

  • initialize the model;
  • establish an initial knowledge base by calling learn() every minute for 24 hours on that machine;
  • switching to inference mode by calling detect() 10 times every hour (and averaging the returned scores), each day;
  • blink a LED and ring alarms whenever detect() returns any anomaly (average score < 90%);
  • run another learning cycle to enrich the existing knowledge, if temperature rises above 60°C (and the machine is still OK)
  • send a daily report (average number of anomalies per hour, with date, time, machine ID…) using Bluetooth or LoRa.
In summary, those smart functions can be triggered by external data (e.g. from sensors, buttons, to account for and adapt to environment changes).
The scores returned by the smart functions can trigger all kinds of behaviors on your device.
The possibilities are endless.

1. Static library

The static NanoEdge AI Library is only available via NanoEdge AI Studio in its full version.

  • Clicking Compile in Step 6: “Deploy” of NanoEdge AI Studio;
  • Open the .zip file;
  • Select and copy the static library libneai.a;
  • Link this static library to your project’s code.

2. NanoEdge AI Library functions

i. Initialization:

uint8_t NanoEdgeAI_initialize(void);
Initialization can be run at the beginning to initialize the model and/or later to initialize a new model and reset all knowledge.
Returns 0 in case of success.

Note

  • If you are using a limited library for authorized development boards, please make sure that you board is compatible. Otherwise, error code 123 will be returned.

ii. Learning:

uint8_t NanoEdgeAI_learn(float data_input[]);

This function is used to learn patterns in your data. It can be used at any time, in the beginning to build the original knowledge base of the AI model, but also later, as an additional learning phase to complement the existing knowledge.

  • Input:

    float data_input[], the length of the data is BUFFER_SIZE * NB_AXES .

  • Output:

    1 means success (the input signal has been learned), other values mean that learning has failed.

Note

The learning function can be called:

  1. initially, before any inference, to establish some reference knowlege base
  2. subsequently, whenever needed, to complete the existing knowledge and enrich it (for exemple, to take into account some new nominal environment conditions)

Warning

NanoEdge AI Library uses float data types instead of int. If you’re using ints, please convert (cast) them into floats.

iii. Detection

uint8_t NanoEdgeAI_detect(float data_input[]);

This function returns returns a similarity percentage, measure of the mathematical distance between the incoming signal and the existing knowledge, learned by the library.

  • Input:

    float data_input[], the length of the data is BUFFER_SIZE * NB_AXES.

  • Output:

    The percentage of similarity [0-100] between the new signal and learned patterns.
    “100” means completely similar, and “0” completely dissimilar.

Note

  • The recommended threshold percentage is 90. Values under this threshold reveal a behavior that differs from the usual behavior learned by the AI model. This threshold can be defined by the user, depending on the final application’s sensitivity requirements.
  • If you are using a limited library for authorized development boards, please make sure that you board is compatible. Otherwise, detection will return error code 123.

iv. Setting sensitivity

void NanoEdgeAI_set_sensitivity(float sensitivity);

This function sets the sensitivity of the model in detection mode. It can be tuned at any time without having to go through a new learning phase. This sensitivity has no influence on the knowledge acquired during the learning steps. It only plays a role in the detection step, by influencing the similarity percentages that are returned by the detect function (acts as a linear scaler of the pre-set internal sensitivity).

  • Input: float sensitivity
  • Output: None

Note

  • The default sensitivity value is 1. A sensitivity value between 0 and 1 (excluded) decreases the sensitivity of the model, while a value in between 1 and 100 increases it. We recommend increasing or decreasing sensitivity by steps of 0.1.
  • Sensitivity 1.1 - 100 will tend to decrease the percentages of similarity returned, while sensitivity 0 - 0.9 will decrease them.

v. Getting sensitivity

float NanoEdgeAI_get_sensitivity(void);
This function returns the current sensitivity of the model.
The recommended/default sensitivity is 1. However, this value can be defined by the user depending on his application’s sensitivity requirements.
  • Input: None
  • Output: The sensitivity of model.

vi. Getting status

uint8_t NanoEdgeAI_get_status(void);

This function returns the current status of the library.

  • Input: None

  • Output: The status of the library.

    0 means success (the input signal has been learned), other values mean that learning has failed.
    123 (Only for library limited to partner development board): library is not used on a partner development board.

3. Backing up and restoring the Library’s knowledge

i. Creating backups

When using NanoEdge AI Library, knowledge is created on the go. It means that after each learning iteration, the machine learning model is incrementally getting richer and richer.

For performance reasons, this knowledge is saved into the microcontroller’s RAM. But as you know, RAM is volatile! You should copy this knowledge into non-volatile memory if you don’t want to lose it (for example, in case of power failure).

NanoEdge AI Library attributes a specific memory section called .neai for the knowledge variables (model hyperparameters). To use it, you need to create a memory section in your linker script according to your microcontroller architecture.

Example :

.neai 0x0000000020004000  :
{
   KEEP(*(.neai))          /* keep my variable even if not referenced */
} >RAM

Now, copy the knowledge from your section start address into non-volatile memory (EEPROM, SD, embedded FLASH, etc). You can get the size of the section using arm-none-eabi-size.

$ arm-none-eabi-size -A libneai.a | grep neai

ii. Restoring backups

To restore a previously saved backup, copy the entire knowledge back into the .neai section.

Then, you will be able to use your NanoEdge AI Library functions again.


4. Example “Hello World!”

Header file: NanoEdgeAI.h

Example of NanoEdge AI Library header file:

/*
 * NanoEdge AI header file
 */

/* Includes */
#include <stdint.h>

/* Define */
#define NEAI_ID "5d5fd41ec8e0327c934"
#define NB_AXES 3
#define BUFFER_SIZE 256

/* Function prototypes */
#ifdef __cplusplus
extern "C" {
#endif
   uint8_t NanoEdgeAI_initialize(void);
   uint8_t NanoEdgeAI_learn(void);
   uint8_t NanoEdgeAI_detect(void);
   void NanoEdgeAI_set_sensitivity(float sensitivity);
   float NanoEdgeAI_get_sensitivity(void);
   uint8_t NanoEdgeAI_get_status(void);
#ifdef __cplusplus
}
#endif
Main program: main.c
This program must be completed by the user (depending on the applications, the desired features…).
/* Includes ------------------------------------------------------------------*/
#include "NanoEdgeAI.h"

/* Private define ------------------------------------------------------------*/
#define LEARNING_ITERATIONS 100 /* e.g. this value is set by user */

/* Private variables defined by user -----------------------------------------*/
float data_buffer[BUFFER_SIZE * NB_AXES];

/* Private function prototype defined by user --------------------------------*/
/*
 * @brief  Collect data process
 *
 * This function is defined by user, depends on applications and sensors
 *
 * @param  sample_buffer: [in, out] buffer of sample values
 *
 * @retval None
 */

void get_buffer(float sample_buffer[])
{
   /* USER BEGIN */

   /* USER END */
}

/* ---------------------------------------------------------------------------*/
int main()
{
   /* Initialization --------------------------------------------------------*/
   uint8_t error_code = NanoEdgeAI_initialize();

   if (error_code != 0) {
      /* This happen if the library is used in an unauthorized board.
      /* Free version only
   }

   /* Learning --------------------------------------------------------------*/
   int iteration = 0;
   uint8_t learn_status = 0;
   /* e.g.: Stopping criterion for learning process. */
   /* This stopping criterion could be modified by user */
   while (iteration < LEARNING_ITERATIONS) {
      get_buffer(data_buffer);
      learn_status = NanoEdgeAI_learn(data_buffer);
      iteration++;
   }

   /* Set sensitivity of AI model (optional, Input value is set by user)-----*/
   /* NanoEdgeAI_set_sensitivity(1.1); */

   /* Detection -------------------------------------------------------------*/
   uint8_t similarity_percentage  = 0;
   while (true) {
      get_buffer(data_buffer);
      similarity_percentage = NanoEdgeAI_detect(data_buffer);
      /* BEGIN USER */
      /* e.g.: Trigger function depending on similarity_percentage
      /*       (print output, blink LED, ring alarm...).
      /* END USER */
   }
}

Resources

Documentation
All NanoEdge AI Studio documentation is available here.
Tutorials
Step-by-step tutorials, to use NanoEdge AI Studio to build a smart device from A to Z:

Useful links: