NanoEdge AI Emulator for anomaly detection (AD)

Warning white.png Warning

Update for NanoEdge AI v3.
Pay close attention to the new command names.


1. What is NanoEdge AI Library?

NanoEdge™ AI Library is an Artificial Intelligence (AI) static library originally developed by Cartesiam, for embedded C software running on Arm® Cortex® microcontrollers.

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 for anomaly detection is the code that contains an AI model (for example, as a bundle of signal treatment, Machine Learning model, and optimally tuned hyperparameters). It is designed to gather knowledge incrementally during a learning phase to become able to detect potential abnormal machine behaviors, and possibly predict them.

2. Purpose of NanoEdge AI Emulator for anomaly detection

With NanoEdge AI Emulator, you can emulate the behavior of your NanoEdge AI Library (from the command line, or the interface provided through NanoEdge AI Studio (NanoEdgeAIStudio), also called the Studio, and start testing it as if it was running on your embedded application.

The Emulator comes with each library created by the Studio. It has been compiled using the same algorithm. This means that for one library, there is one emulator. Using this tool, you can learn and detect as you would do in your embedded application:

  1. Learn using the nominal signals used in the Studio, or any other dataset you consider as "nominal".
  2. Detect using the abnormal signals used in the Studio, or any other dataset you consider as "abnormal".

3. NanoEdge AI Emulator functions

3.1. Get version (library id)

The Emulator version can be accessed at any time using neai_anomalydetection_get_version.
The returned version number is the ID of the associated NanoEdge AI static library.

Usage:

./NanoEdgeAI_Emulator neai_anomalydetection_get_version               (Linux®)
NanoEdgeAI_Emulator.exe neai_anomalydetection_get_version           (Windows®)

Response:

{
   "status": "id_version",
   "version": "5d5fd41ec8e0327c934",
   "sensitivity": "null",
   "input": "null",
   "results": [],
   "detection_results": {"signals": null, "nominal": null, "anomaly": null},
   "learning_summary": {"signals": null},
   "detection_summary": {"signals": null, "nominal": null, "anomaly": null}
}

3.2. Initialization

The first step when using the Emulator is to start the initialization process, with neai_anomalydetection_init (as you would do with the NanoEdge AI Library in your embedded application).

Usage:

./NanoEdgeAI_Emulator neai_anomalydetection_init             (Linux®)
NanoEdgeAI_Emulator.exe neai_anomalydetection_init           (Windows®)

Response:

{
   "status": "initialization",
   "version": "5d5fd41ec8e0327c934",
   "sensitivity": 1.00,
   "input": "null",
   "results": [],
   "detection_results": {"signals": null, "nominal": null, "anomaly": null},
   "learning_summary": {"signals": null},
   "detection_summary": {"signals": null, "nominal": null, "anomaly": null}
}

When initializing NanoEdge AI Library model by running the above command, a binary file NanoEdgeAI.dat is generated in the current directory. This file allows initialization and saves the parameters of the NanoEdge AI Library model.

When running the Emulator for the first time, trying to start the learning or detection process before running the initialization returns the following error message:

Error: please run neai_anomalydetection_init function to continue!
Refer to NanoEdge AI Emulator documentation for more details.
Info white.png Information

Initialization can be run at the beginning to initialize the model, later to initialize a new model and reset all knowledge, or both.


3.3. Learning

Once the model is initialized, the learning process can be started, using neai_anomalydetection_learn.
There are two options to run the learning: using an input file, or using a sequence of values (an input buffer directly in the command line).

Info white.png Information

The learning function can be called:

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

3.3.1. Learning by file

Usage:

  • By default all signals in input files are learned:
./NanoEdgeAI_Emulator neai_anomalydetection_learn --file learning_file.csv           (Linux®)
NanoEdgeAI_Emulator.exe neai_anomalydetection_learn --file learning_file.csv       (Windows®)
  • But you can restrict the number of signals used (for instance, in the example below, 10-14):
./NanoEdgeAI_Emulator neai_anomalydetection_learn --file learning_file.csv --begin 10 --end 14      (Linux®)
NanoEdgeAI_Emulator.exe neai_anomalydetection_learn --file learning_file.csv --begin 10 --end 14   (Windows)

Arguments:

--file:     path to the file containing learning data
--begin:    number of the first data line in file (>= 1) (or of the first line to use)
--end:      number of the last data line in file (<= number of last line) (or of the last line to use)

Response:

{
   "status": "learning",
   "version": "5d5fd41ec8e0327c934",
   "sensitivity": 1.00,
   "input": "learning_file.csv",
   "results": [
      {"signal": 1, "line": 10, "similarity": null, "status": "nominal"},
      {"signal": 2, "line": 11, "similarity": null, "status": "nominal"},
      {"signal": 3, "line": 12, "similarity": null, "status": "nominal"},
      {"signal": 4, "line": 13, "similarity": null, "status": "nominal"},
      {"signal": 5, "line": 14, "similarity": null, "status": "nominal"}
   ],
   "detection_results": {"signals": null, "nominal": null, "anomaly": null},
   "learning_summary": {"signals": 5},
   "detection_summary": {"signals": 0, "nominal": 0, "anomaly": 0}
}

In the above example, the learning file is learning_file.csv in the current directory, and learning examples are the five signals from line 10 to 14.

If an argument is missing, the following error message is returned:

Error: missing or not valid argument in NanoEdge AI learning function call by file!
Valid NanoEdge AI learning function calls by file are:
   neai_anomalydetection_learn --file filename --begin line --end line
  neai_anomalydetection_learn --file filename
Refer to NanoEdge AI Emulator documentation for more details:
Warning white.png Warning

Your input file must have valid separators (, or ; or : or a single space or a single tab). If it is not the case, modify your input file. You can easily do so by first importing your file in NanoEdge AI Studio, then selecting the separator that you are currently using, and finally downloading it again by clicking NanoEdgeAI download icon.svg.

Also make sure to use periods (.) for decimal values, and NOT commas (,).

3.3.2. Learning by a sequence of values

Usage:

./NanoEdgeAI_Emulator neai_anomalydetection_learn --array value1 value2 ... valueN        (Linux®)
NanoEdgeAI_Emulator.exe neai_anomalydetection_learn --array value1 value2 ... valueN    (Windows®)

Arguments:

--array value1 value2 ... valueN       buffer composed of N numerical values, from *value1* to *valueN*

Response:

{
   "status": "learning",
   "version": "5d5fd41ec8e0327c934",
   "sensitivity": 1.00,
   "input": "array",
   "results": [
      {"signal": 1, "line": null, "similarity": null, "status": "nominal"}
   ],
   "detection_results": {"signals": null, "nominal": null, "anomaly": null},
   "learning_summary": {"signals": 1},
   "detection_summary": {"signals": 0, "nominal": 0, "anomaly": 0}
}
Info white.png Information

If you have N signals (N lines) in your learning process you must run the above command N times with the sequence of values corresponding to each signal.

3.3.3. Remarks

  • The two learning modes (by file and by sequence of values) can be combined.
  • The learning command can be called at any time, in the beginning to constitute the original knowledge base of the model, or later to complement the existing knowledge through additional learning.
  • The header learning_summary indicates the total number of signals learned. They are all by definition considered as nominal.

3.4. Detection (inference)

Once the model is initialized and the learning process is over, the detection process can be started. The neai_anomalydetection_detect function can be used for inference, to detect anomalies among incoming signals.
It returns a similarity percentage, measure of the mathematical distance between the incoming signal and the existing knowledge.

Just like for learning, there are two options to run detection, using an input file, or a sequence of values.

3.4.1. Detection by file

Usage:

  • By default all signals in input files are used:
./NanoEdgeAI_Emulator neai_anomalydetection_detect --file detection_file.csv           (Linux®)
NanoEdgeAI_Emulator.exe neai_anomalydetection_detect --file detection_file.csv       (Windows®)
  • But you can restrict the number of signals used (for instance, in the example below, 10-14):
./NanoEdgeAI_Emulator neai_anomalydetection_detect --file detection_file.csv --begin 10 --end 14       (Linux®)
NanoEdgeAI_Emulator.exe neai_anomalydetection_detect --file detection_file.csv --begin 10 --end 14   (Windows®)

Arguments:

--file:     path to the file containing data to detect
--begin:    number of the first data line in file (>= 1) (or of the first line to use)
--end:      number of the last data line in file (<= number of last line) (or of the last line to use)

Response:

{
   "status": "detection",
   "version": "5d5fd41ec8e0327c934",
   "sensitivity": 1.00,
   "input": "detect_file.csv",
   "results": [
      {"signal": 1, "line": 1, "similarity": 92, "status": "nominal"},
      {"signal": 2, "line": 2, "similarity": 61, "status": "anomaly"},
      {"signal": 3, "line": 3, "similarity": 27, "status": "anomaly"},
      {"signal": 4, "line": 4, "similarity": 8, "status": "anomaly"},
      {"signal": 5, "line": 5, "similarity": 24, "status": "anomaly"}
   ],
   "detection_results": {"signals": 5, "nominal": 1, "anomaly": 4},
   "learning_summary": {"signals": 50},
   "detection_summary": {"signals": 15, "nominal": 11, "anomaly": 4}
}

If an argument is missing, the following error message is returned:

Error: missing or not valid argument in NanoEdge AI detection function call by file!
Valid NanoEdge AI detection function calls by file are:
   neai_anomalydetection_detect --file filename --begin line --end line
   neai_anomalydetection_detect --file filename
Refer to NanoEdge AI Emulator documentation for more details.
Warning white.png Warning

Your input file must have valid separators (, or ; or : or a single space or a single tab). If it is not the case, modify your input file. You can easily do so by first importing your file in NanoEdge AI Studio, then selecting the separator that you are currently using, and finally downloading it again by clicking NanoEdgeAI download icon.svg.

Also make sure to use periods (.) for decimal values, and NOT commas (,).

3.4.2. Detection by a sequence of values

Usage:

./NanoEdgeAI_Emulator neai_anomalydetection_detect --array value1 value2 ... valueN            (Linux®)
NanoEdgeAI_Emulator.exe neai_anomalydetection_detect --array value1 value2 ... valueN        (Windows®)

Arguments:

--array value1 value2 ... valueN       buffer composed of N numerical values, from *value1* to *valueN*

Response:

{
   "status": "detection",
   "version": "5d5fd41ec8e0327c934",
   "sensitivity": 1.00,
   "input": "array",
   "results": [
      {"signal": 1, "line": null, "similarity": 61, "status": "anomaly"}
   ],
   "detection_results": {"signals": 1, "nominal": 0, "anomaly": 1},
   "learning_summary": {"signals": 50},
   "detection_summary": {"signals": 16, "nominal": 11, "anomaly": 5}
}

3.4.3. Remarks

  • The two detection modes (by file and by sequence of values) can be combined.
  • The header detection_results shows a summary of the last detection cycle.
  • The header detection_summary shows a summary of the whole detection process since the first run.
Info white.png Information

The threshold used to classify a signal as nominal or anomaly is 90, meaning that if the similarity percentage is more than 90 the signal is classified as nominal, else it is classified as anomaly. Note that this threshold is used to measure the performance of the NanoEdge AI Library when you use the Studio.

3.5. Set sensitivity

The sensitivity can be changed dynamically at any time, using neai_anomalydetection_set_sensitivity, 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.
It acts as a linear scaler of the pre-set internal sensitivity (optimized during benchmark in the Studio). It influences the similarity percentages that are returned by the neai_anomalydetection_detect function.

Usage:

./NanoEdgeAI_Emulator neai_anomalydetection_set_sensitivity 1.1             (Linux®)
NanoEdgeAI_Emulator.exe neai_anomalydetection_set_sensitivity 1.1         (Windows®)

Response:

{
   "status": "sensitivity_update",
   "version": "5d5fd41ec8e0327c934",
   "sensitivity": 1.10,
   "input": "null",
   "results": [],
   "detection_results": {"signals": null, "nominal": null, "anomaly": null},
   "learning_summary": {"signals": 50},
   "detection_summary": {"signals": 1, "nominal": 0, "anomaly": 1}
}
Info white.png Information
  • 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. STMicroelectronics recommend increasing or decreasing sensitivity by steps of 0.1.
  • Sensitivity 1.1 - 100 tends to decrease the percentages of similarity returned (the algorithm is more sensitive to perturbations), while sensitivity 0 - 0.9 tends to increase them (the algorithm is less sensitive to perturbations).

4. 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.