../_images/cartesiam_logo.png

NanoEdge AI Emulator

../_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.


II. Purpose of NanoEdge AI Emulator

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), and start testing it as if if 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 mean that for one library, there is one emulator. Using this tool, you can learn and detect as you would do in your embedded application.

Learn using the nominal signals used in the Studio, or any other dataset you consider as “nominal”.

Detect using the abnormal signals used in the Studio, or any other dataset you consider as “abnormal”.


III. NanoEdge AI Emulator functions

1. Get version (library id)

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

Usage:

./NanoEdgeAI_Emulator NanoEdgeAI_get_version             (Linux)
NanoEdgeAI_Emulator.exe NanoEdgeAI_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}
}

2. Initialization

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

Usage:

./NanoEdgeAI_Emulator NanoEdgeAI_initialize              (Linux)
NanoEdgeAI_Emulator.exe NanoEdgeAI_initialize            (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’s 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 initialization will return the following error message:

Error: please run NanoEdgeAI_initialize function to continue!
Refer to NanoEdge AI Emulator documentation for more details:
https://cartesiam-neai-docs.readthedocs-hosted.com/en/latest/

Note

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


3. Learning

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

Note

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)

i. Learning by file

Usage:

  • By default all signals in input files are learned:
./NanoEdgeAI_Emulator NanoEdgeAI_learn --file learning_file.csv         (Linux)
NanoEdgeAI_Emulator.exe NanoEdgeAI_learn --file learning_file.csv       (Windows)
  • But you can restrict the number of signals used (e.g. here 10-14):
./NanoEdgeAI_Emulator NanoEdgeAI_learn --file learning_file.csv --begin 10 --end 14     (Linux)
NanoEdgeAI_Emulator.exe NanoEdgeAI_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 will be returned:

Error: missing or not valid argument in NanoEdge AI learning function call by file!
Valid NanoEdge AI learning function calls by file are:
   NanoEdgeAI_learn --file filename --begin line --end line
   NanoEdgeAI_learn --file filename
Refer to NanoEdge AI Emulator documentation for more details:
https://cartesiam-neai-docs.readthedocs-hosted.com/

Warning

Your input file must have valid separators (, or ; or : or a single space or a single tab). If it is not the case, please modify your input file. You can easily do so by importing your file in NanoEdge AI Studio, selecting the separator you’re currently using, and then re-downloading it by clicking download.

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

ii. Learning by a sequence of values

Usage:

./NanoEdgeAI_Emulator NanoEdgeAI_learn --array value1 value2 ... valueN       (Linux)
NanoEdgeAI_Emulator.exe NanoEdgeAI_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}
}

Note

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.

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

4. Detection (Inference)

Once the model is initialized and the learning process is over, the detection process can be started. The NanoEdgeAI_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.

i. Detection by file

Usage:

  • By default all signals in input files are used:
./NanoEdgeAI_Emulator NanoEdgeAI_detect --file detection_file.csv         (Linux)
NanoEdgeAI_Emulator.exe NanoEdgeAI_detect --file detection_file.csv       (Windows)
  • But you can restrict the number of signals used (e.g. here 10-14):
./NanoEdgeAI_Emulator NanoEdgeAI_detect --file detection_file.csv --begin 10 --end 14     (Linux)
NanoEdgeAI_Emulator.exe NanoEdgeAI_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 will be returned:

Error: missing or not valid argument in NanoEdge AI detection function call by file!
Valid NanoEdge AI detection function calls by file are:
   NanoEdgeAI_detect --file filename --begin line --end line
   NanoEdgeAI_detect --file filename
Refer to NanoEdge AI Emulator documentation for more details:
https://cartesiam-neai-docs.readthedocs-hosted.com/

Warning

Your input file must have valid separators (, or ; or : or a single space or a single tab). If it is not the case, please modify your input file. You can easily do so by importing your file in NanoEdge AI Studio, selecting the separator you’re currently using, and then re-downloading it by clicking download.

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

ii. Detection by a sequence of values

Usage:

./NanoEdgeAI_Emulator NanoEdgeAI_detect --array value1 value2 ... valueN         (Linux)
NanoEdgeAI_Emulator.exe NanoEdgeAI_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}
}

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

Note

The threshold used to classify a signal as nominal or anomaly is 90, i.e. 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.


5. Set sensitivity

The sensitivity can be changed dynamically at any time, using NanoEdgeAI_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 NanoEdgeAI_detect function.

Usage:

./NanoEdgeAI_Emulator NanoEdgeAI_set_sensitivity 1.1           (Linux)
NanoEdgeAI_Emulator.exe NanoEdgeAI_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}
}

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.

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: