AI: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

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

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

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

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>

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.