../_images/cartesiam_logo.png

NanoEdge AI Studio CLI

../_images/banner.png

I. What is NanoEdge AI Library?

NanoEdge AI 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 Studio CLI

NanoEdgeAI Studio CLI is a Command Line Interface for the NanoEdge AI Studio.

It make all NanoEdge AI Studio’s features usable without the graphical user interface, directly from the terminal.


III. Requirements

1. Windows

NanoEdgeAI Studio CLI is tested to run on Windows 10 64 bits.

2. Linux

NanoEdge AI Studio CLI is tested to run on Ubuntu, Debian 64 bits.

It has a dependency on libnss3 and glibc. Please be sure to install libnss3 and glibc before running the CLI.

apt-get update -qy && apt-get -y install procps libnss3

IV. Install

Download and unzip neai_cli_***_v***.zip to any folder.

This folder includes:

  • neai_cli: the executable
  • docs: this documentation
  • bin: the NanoEdge AI Studio API (not included in the slim version)

V. Getting started

1. Fast mode

../_images/fast_mode_workflow.png
  • Launch the NanoEdge AI Studio API:

    $ neai_cli api -launch
    

Note

You can use a NanoEdgeAI API launched on another computer by setting host and port.

  • (Optional) Set your license

    $ neai_cli license -activate -key <LICENSE_KEY>
    

Note

You need to do it only the first time you launch NanoEdgeAI API on a new computer.

  • Find a library

    To find a library, you will need a nominal signal and an anomaly signal. Please refer to NanoEdgeAI Studio documentation.

    $ neai_cli library -find -nominal_file="/path/to/nominal_file.csv" -anomaly_file="/path/to/anomaly_file.csv" -number_axes=1 -output_zip="/path/to/library.zip" -mcu="cortex-m4" -float_abi="soft" -short_wchar=true
    

Possible options are:

-anomaly_delimiter string      Anomaly signal file value delimiter (1 char max)
-anomaly_file string           File path to the anomaly signal
-float_abi string              Float Abi: soft or hard (default "soft")
-max_ram int                   Maximum RAM available for the library (default 200000)
-mcu string                    MCU compilation target
-nominal_delimiter string      Nominal signal file value delimiter (1 char max)
-nominal_file string           File path to the nominal signal
-number_axes int               Number of axes of the signals (default 1)
-output_zip string             Path to output zip file containing the library
-progress_bar boolean          Display progress bar (default true)
-short_wchar boolean           Short Wchar: true or false (default true)

2. Advanced mode

../_images/advanced_mode_workflow.png

2.1. API: Launch or connect to the NanoEdge AI API

  • Launch NanoEdge AI API on the local computer:

    $ neai_cli api -launch
    
  • Connect to an already running NanoEdge AI API

    $ neai_cli api -set -host "<my_host>" -port "<my_port>"
    

Note

A NanoEdge AI API must be running to use neai_cli

Usage:

$ neai_cli api <command> <attributes>

Command:
   -get           Get host and port used to connect to the API

   -launch        Launch the API
                  Optional attributes: port, workspace

   -set           Set host and port to use to connect to the API
                  Mandatory attributes: host, port

   -shutdown      Shutdown the API

   -test          Test connection to the API

Attributes:
   -host string            Host running the API (default "http://localhost")
   -port int               Port of the API (default 8000)
   -workspace string       Path to the workspace directory (default "./bin/workspace")

2.2. License: Manage license

  • Activate a license:

    $ neai_cli license -activate -key "<my_license_key>"
    

Note

A license must be activated to use a NanoEdge AI API.

Usage:

license <command> <attributes>

Command:
   -activate         Set a license
                     Mandatory attributes: key

   -deactivate       Delete the license

   -info             Get license info

Attributes:
   -key string       License key

Response:

Name Type Description Example
expiration_date date Expiration date of the license “2020-02-13T09:58:12+00:00”
is_offline_activation bool If the license key has been offline activated false
is_set bool If the license is set true
is_trial bool If the license is a trial license false
is_valid bool If the license is activated true
license_key string License key <LICENSE_KEY>
license_type string License type <LICENSE_TYPE>
user_email string Email of the user associated with the license key john.smith@company.com
user_name string Name of the user associated with the license key John Smith
valid_reason string License validity reason “License is genuinely activated!”

2.3. Project: Create or open a project

  • Create a new project:

    $ neai_cli project -create -name "<my_name>" -mcu "<my_mcu>" -max_ram <max_ram_value> -number_axis <number_of_axis_value>
    
  • Open an existing project:

    $ neai_cli project -open -name "<my_project_slug_name>"
    

Note

The project slug name is the slugify version of the project name. It can be found using:

$ neai_cli project -list

A project must be open to use the other commands. By default, a project named “default” is used.

Usage:

project <command> <attributes>

Command:
   -create        Create and open a project
                  Mandatory attributes: name
                  Optional attributes: description, max_ram, name, number_axis

   -current       Get currently opened project

   -delete        Delete a project
                  Mandatory attributes: name

   -info          Get project info
                  Mandatory attributes: name

   -list          List projects

   -open          Open a project. Project "default" is open by default.
                  Mandatory attributes: name

Attributes:
   -description string     Description of the project
   -max_ram int            Maximum RAM available for the library in bytes (default 200000)
   -mcu string             MCU compilation target (default "cortex-m4"). MCU list: cortex-m0plus, cortex-m1, cortex-m3, cortex-m4, cortex-m23, cortex-m33, cortex-m7
   -name string            Name of the project
   -number_axes int        Number of axes of the signals. (default 1)

Response:

Name Type Description Example
creation_date date Expiration date of the license “2020-02-13T09:58:12+00:00”
description bool If the license key has been offline activated false
folder_name string Name of the folder containing the project project_test-cli
is_compatible bool If the project is compatible with current API version true
last_update_date string Last update date of the project “2020-01-09T09:47:04+00:00”
max_ram int Maximum amount of RAM (in kB) you wish to dedicate to NanoEdgeAI on the microcontroller 20000
mcu string Type of microcontroller used “cortex-m4”
name string Project’s name “test_cli”
number_axis int Number of axes of the sensors 1
slug_name string Project’s slug name. The slug name is the identifier of the project. “test-cli”

2.4. Signal: Import a new signal

  • Import a signal

    $ neai_cli signal -import -file_path "<my_file_path>" -nominal
    

Usage:

signal <command> <attributes>

Command:
   -delete        Delete a signal
                  Mandatory attributes: id
                  Optional attributes: project

   -info          Get info on a signal
                  Mandatory attributes: id
                  Optional attributes: project

   -import        Import a signal
                  Mandatory attributes: file_path, nominal or anomaly
                  Optional attributes: name, project

   -list          List signals
                  Optional attributes: project

Attributes:
   -anomaly                Is anomaly signal
   -delimiter string       Signal file values delimiter (1 char max)
   -file_path string       File path to the signal
   -id int                 ID of the signal (default -1)
   -name string            Name of the signal
   -nominal                Is nominal signal
   -project string         Project slug name. Default is the currently opened project. If set, it opens or creates the given project.

Response:

Name Type Description Example
file_found bool If the signal file has been found on the machine “2020-02-13T09:58:12+00:00”
file_name string Signal file name “1.csv”
file_path string Signal file path “C:\Users\<my_name>\ Documents\workspaceNanoEdgeAi\ project_test-cli\signals\nominal\1.csv”
file_type string Signal file type (nominal or anomaly) “nominal”
id int Signal id 1
name string Signal name “signal_test”
number_axis int Number of axes of the sensors 1
passed bool If tests on signal data has been successfully passed true
signalq_metadata json Metadata on the signal {…}
signalq_result json Results of tests on signal data {…}

2.5-2.7. Optimization: Launch an optimization, retrieve progress and get result

  • Launch an optimization:

    $ neai_cli optimization -launch -signals "<my_signal_ids>"
    
  • Get progress of an optimization

    $ neai_cli optimization -progress -id <my_optimization_id>
    
  • Get result of an optimization

    $ neai_cli optimization -result -id <my_optimization_id>
    
  • Stop an optimization

    $ neai_cli optimization -stop
    

Usage:

optimization <command> <attributes>

Command:
   -delete        Delete an optimization
                  Mandatory attributes: id

   -info          Get optimization info
                  Mandatory attributes: id
                  Optional attributes: project

   -launch        Launch an optimization
                  Mandatory attributes: signals
                  Optional attributes: max_ram, name, nb_cores, project

   -list          List optimizations
                  Optional attributes: project

   -progress      Get progression of an optim
                  Mandatory attributes: id
                  Optional attributes: project

   -result        Get the best result of an optimization
                  Mandatory attributes: id
                  Optional attributes: project

   -stop          Stop current optimization

Attributes:
   -id int              ID of the optimization
   -max_ram int         Maximum RAM. Use default from project
   -name string         Name of the optimization (default "my_optimization")
   -nb_cores int        Number of cores to use for the optimization. Default min(machine's nb cores - 2, 1)
   -project string      Project slug name. Default is the currently opened project. If set, it opens or creates the given project.
   -signals string      List of Signal IDs to be used by the optimization. Ex: -signals="[1,2]" or -signals="[[1,2],[3,4]]"

Response:

Name Type Description Example
creation_date bool If the license key has been offline activated false
elapsed_time string Name of the folder containing the project project_test-cli
id string Last update date of the project “2020-01-09T09:47:04+00:00”
info json Info on the optimization {…}
max_ram int Maximum amount of RAM (in kB) you wish to dedicate to NanoEdgeAI on the microcontroller 20000
name string Optimization name “my_optimization”

2.8. Library: Find and compile a library

  • Compile a library:

    $ neai_cli library -compile -id <my_optimization_id>
    
  • Find a library: see Fast Mode above

Usage:

library <command> <attributes>

Command:
   -compile       Compile a library based on an optimization
                  Mandatory attributes: id, output_zip
                  Optional attributes: float_abi, short_wchar, mcu, project

   -find          Find a library for given signals
                  Mandatory attributes: anomaly_file, mcu, nominal_file, output_zip
                  Optional attributes: float_abi, max_ram, number_axis, progress_bar, project, short_wchar

Attributes:
   -anomaly_delimiter string           Anomaly signal file value delimiter (1 char max)
   -anomaly_file file path             Anomaly signal file path
   -delimiter string                   Signal file values delimiter (1 char max)
   -float_abi string                   Float Abi: soft or hard (default "soft")
   -id int                             ID of the optimization
   -max_ram int                        Maximum RAM available for the library in bytes (default 200000)
   -mcu string                         MCU compilation target. MCU list: cortex-m0plus, cortex-m1, cortex-m3, cortex-m4, cortex-m23, cortex-m33, cortex-m7
   -nominal_delimiter string           Nominal signal file value delimiter (1 char max)
   -nominal_file file path             Nominal signal file path
   -number_axes int                    Number of axes of the signals (default 1)
   -output_zip file path               Output zip file path containing the library
   -project string                     Project slug name. Default is the currently opened project. If set, it opens or creates the given project.
   -progress_bar                       Display progress bar (default true)
   -short_wchar                        Short Wchar: true or false (default true)

Response:

Name Type Description Example
library_id bool Library code id. It should be used to communicate with Cartesiam support. <LIBRARY_ID>
gcc_version string Version of GNU ARM GCC compiler used “arm-none-eabi-gcc-cli …”
mcu string Type of microcontroller used “cortex-m4”
compilation_flags_set json GNU ARM GCC compiler flags used {…}
file_path string Path to library zip “library.zip”

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: