Last edited 11 months 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>"
Info white.png Information
You can also use NanoEdge AI Studio Engine launched by NanoEdge AI Studio. To do so, launch NanoEdge AI Studio, and set port to use to 5000 (or the port you set during NanoEdge AI Studio setup)
$ neai_cli engine -set -port 5000
Warning white.png Warning
A NanoEdge AI Studio Engine must already be running to use neai_cli.


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>"
Warning white.png Warning
A license must be activated to use a NanoEdge AI Studio Engine.


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>
Info white.png Information
The project slug name can contain only letters, numbers and dash. For an existing project, it can be found using:
$ neai_cli project -list


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.