Last edited one year ago

NanoEdge AI Studio: CLI

1. Purpose of NanoEdge AI Studio CLI

NanoEdge AI™ Studio CLI is a command-line interface for NanoEdge AI Studio.

It makes all NanoEdge AI Studio (NanoEdgeAIStudio) features usable without the graphical user interface, directly from the terminal.

2. Requirements

2.1. Windows®

NanoEdge AI Studio CLI is tested to run on Windows® 10 64 bits.

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

3. 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 Engine (not included in the slim version)

4. Getting started

NanoEdgeAI advanced mode workflow.png

4.1. Engine: launch or connect to the NanoEdge AI Studio Engine

  • Launch NanoEdge AI Studio Engine on the local computer:
$ neai_cli engine -launch
  • Connect to an already running NanoEdge AI Studio Engine
$ neai_cli engine -set -host "<my_host>" -port "<my_port>"


Usage:

$ neai_cli engine <command> <attributes>

Command:
   -get           Get host and port used to connect to NanoEdge AI Studio Engine

   -launch        Launch NanoEdge AI Studio Engine
                  Optional attributes: port, workspace

   -set           Set host and port to use to connect to NanoEdge AI Studio Engine
                  Mandatory attributes: host, port

   -shutdown      Shutdown NanoEdge AI Studio Engine

   -test          Test connection to NanoEdge AI Studio Engine

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

4.2. Proxy parameters

To be able to enter your license key, compile an emulator or a library later, the user may have to define proxy settings.

Usage:

 $ neai_cli proxy <command> <attributes>

Command:
        -get
                Get proxy settings
        -set
                Set proxy settings
                Optionnal attributes: host, port, login, password, trust_env, verify_ssl
        -test
                Test connection to NanoEdge AI Studio APIs

Attributes:
        -host string
                Proxy host
        -port int
                Proxy port
        -login string
                Proxy login if any
        -password string
                Proxy password if any
        -trust_env bool
                Trust environment for proxy settings (true/false, default true)
        -verify_ssl bool
                Verify SSL certificate (true/false, default true)

4.3. License: activate and manage license

  • Activate a license:
$ neai_cli license -activate -key "<my_license_key>"


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!"

4.4. Project: create or manage project

  • Create a new project:
$ neai_cli project -create -anomaly_detection -slug_name "<my_slug_name>" -mcu "<my_mcu>" -max_ram <max_ram_value> -number_axis <number_of_axis_value>


Usage:

project <command> <attributes>
Command:
   -create        Create and open a project
                  Mandatory attributes: name, anomaly_detection or classification, mcu
                  Optional attributes: description, max_ram, max_flash, number_axis

   -delete        Delete a project
                  Mandatory attributes: slug_name

   -info          Get project info
                  Mandatory attributes: slug_name

   -list          List projects

Attributes:
   -anomaly_detection        Set project of type Anomaly Detection 
   -n_class                  Set project of type N-Class Classification
   -one_class                Set project of type  1-Class Classification
   -extrapolation            Set project of type  Extrapolation

   -description string       Description of the project
   -max_flash int            Maximum Flash available for the library in bytes (default 128000 bytes)
   -max_ram int              Maximum RAM available for the library in bytes (default 32000 bytes)
   -mcu string               MCU compilation target (default "cortex-m4").
                                 MCU list:
                                    - Generic: cortex-m0plus, cortex-m1, cortex-m3, cortex-m4, cortex-m23, cortex-m33, cortex-m7
                                    - Specific: cortex-m4_st_nucleo-f401re, cortex-m4_st_nucleo-l432kc, cortex-m33_st_stm32l562qe-dk, cortex-m4_st_steval-stwinkt1
   -name string              Name of the project
   -number_axis int          Number of axis of the signals. (default 1)
   -slug_name string         Slug name of the project. Can contain only letters, numbers and dash. You can find the slug name of an existing project by listing projects with -list.

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 NanoEdge AI Studio Engine version true
is_multivariate bool If the project is multivariate false
last_update_date string Last update date of the project "2020-01-09T09:47:04+00:00"
max_flash int Maximum amount of Flash (in bytes) you wish to dedicate to NanoEdge AI on the microcontroller 20000
max_ram int Maximum amount of RAM (in bytes) you wish to dedicate to NanoEdge AI on the microcontroller 20000
mcu string Type of microcontroller used "cortex-m4"
name string Project name "test_cli"
number_axis int Number of axis of the sensors 1
project_type string Type of project ("on_board_training" for Anomaly Detection and "classifier" for Classification) on_board_training
slug_name string Project slug name. The slug name is the identifier of the project. "test-cli"

4.5. Signal: import a new signal

  • Import a signal
$ neai_cli signal -import -file_path "<my_file_path>" -nominal -delimiter "," -project <my_project_slug_name>

Usage:

signal <command> <attributes>

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

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

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

   -list          List signals
                  Mandatory attributes: project

Attributes:
   -anomaly                Is anomaly signal
   -class                  Is class signal
   -delimiter string       Signal file values delimiter (1 char max)
   -file_path string       File path to the signal
   -id int                 ID of the signal
   -name string            Name of the signal
   -nominal                Is nominal signal
   -project string         Project slug name

Response:

Name Type Description Example
class_name string Name of the class "my_class"
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 or class) "nominal"
id int Signal id 1
name string Signal name "signal_test"
number_axis int Number of axis 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 {...}

4.6. Benchmark: launch an benchmark, retrieve progress and get result

In this part, the benchmark, as known in NanoEdge AI Studio, is referred as an optimization.

  • Launch an optimization:
$ neai_cli optimization -launch -signals "<my_signal_ids>" -project <my_project_slug_name>
  • Get progress of an optimization
$ neai_cli optimization -progress -id <my_optimization_id> -project <my_project_slug_name>
  • Get result of an optimization
$ neai_cli optimization -result -id <my_optimization_id> -project <my_project_slug_name>
  • Stop an optimization
$ neai_cli optimization -stop

Usage:

optimization <command> <attributes>

Command:
   -delete        Delete an optimization
                  Mandatory attributes: id, project

   -info          Get optimization info
                  Mandatory attributes: id, project

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

   -list          List optimizations
                  Mandatory attributes: project

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

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

   -stop          Stop current optimization

Attributes:
   -id int              ID of the optimization
   -name string         Name of the optimization (default "my_optimization")
   -nb_cores int        Number of cores to use for the optimization. Default min(machine nb_cores - 2, 1)
   -project string      Project slug name
   -signals string      List of Signal IDs to be used by the optimization. Ex: -signals="1,2"

Response:

For launch, info and list:

Name Type Description Example
creation_date bool If the license key has been offline activated false
elapsed_time int Elapsed time (s) 588
id string ID of the optimization 1
name string Optimization name "my_optimization"
state string Status of optimization "finished"

For progress:

Name Type Description Example
done int Number of libraries tested 789
elapsed_time int Elapsed time (s) 588
optimization int ID of the optimization 1
progress float Progression of the optimization (0 to 1) 0.95

For result:

Name Type Description Example
buffer_size int Size of the buffer (bytes) 2048
confidence float Confidence performance 0.9876
estimated_flash float Estimated flash used by the library (bytes) 4560.0
estimated_ram string Estimated RAM used by the library (bytes) 3215.0
id int ID of the result 1
learning_curve {} Learning curve of the library (only for Anomaly Detection) {...}
loss float Loss value used for internal optimization -0.9878
max_ram int Maximum RAM that was available (bytes) 32000
id int ID of the result 1
mcu string MCU set cortex-m4
optimization int ID of the optimization 1
precision int Accuracy performance 0.9754

4.7. Emulator: get a NanoEdge AI Emulator

  • Compile an emulator:
$ neai_cli emulator -compile -id <my_optimization_id> -output_zip <my_emulator_path> -project <my_project_slug_name>

Usage:

emulator <command> <attributes>

Command:
   -compile       Compile a NanoEdge AI Emulator for an optimization
                  Mandatory attributes: id, output_zip, project

Attributes:
   -id int                     ID of the optimization
   -output_zip file path       Output zip file path to store the NanoEdge AI Library
   -project string             Project slug name

Response:

Name Type Description Example
library_id bool Library code id. It must be used to communicate with STMicroelectronics support. <LIBRARY_ID>
mcu string Type of microcontroller used "cortex-m4"
file_path string Path to library zip "library.zip"
size_bytes int Size of the library (bytes) 705502

4.8. Library: compile a NanoEdge AI Library

  • Compile a library:
$ neai_cli library -compile -id <my_optimization_id> -output_zip <my_library_path> -project <my_project_slug_name>

Usage:

library <command> <attributes>

Command:
   -compile       Compile a NanoEdge AI Library for an optimization
                  Mandatory attributes: id, output_zip, project
                  Optional attributes: float_abi, short_wchar, fshort_enums

Attributes:
   -float_abi string           Float Abi: soft or hard (default "soft")
   -fshort_enums               Use fshort enums
   -id int                     ID of the optimization
   -output_zip file path       Output zip file path to store the NanoEdge AI Library
   -project string             Project slug name
   -short_wchar                Use short wchar

Response:

Name Type Description Example
library_id bool Library code id. It must be used to communicate with STMicroelectronics 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"
size_bytes int Size of the library (bytes) 705502

5. Options

5.1. Display: customize CLI outputs

  • Use pretty printing:
$ neai_cli display -print -pretty_print
  • Do not use pretty printing
$ neai_cli display -print -no_pretty_print

6. Resources

Documentation
All NanoEdge AI Studio documentation is available here.

Tutorials
Step-by-step tutorial to use NanoEdge AI Studio to build a smart device from A to Z.