How to install STM32 model zoo

This article explains how to install the STM32 model zoo in STMicroelectronics environment.

1. Set up the proxy and SSL variables

Running behind a proxy might lead to face different issues when trying to install the Python™ packages with the pip command or trying to have access to the ST Edge AI Developer Cloud. To avoid these issues or to install Python packages using pip, require to set the environment variables named as http_proxy, https_proxy, and eventually NO_SSL_VERIFY. As a prerequisite, you need to get your proxy URL and port as well as the credentials to access it.

In the sections below:

• Replace username with the your proxy login username, and password with your proxy password.

• UTF-8 encode the password if it has any special characters. If the password contains special characters such as @, %, & or !, they must be UTF-8 encoded. For example, if a password is Edge@AI, it becomes Edge%40AI once encoded. An online encoder can be used for this purpose.

• Replace the email address with your own email address.
• Replace the proxy.url.com with the proxy URL and port with the port used.

1.1. Setting the environment variables using GUI for Windows^® (option 1)

Open the environment variable dialog by pressing the Windows button:

Type “environment variables” in the search bar. Open the application “Edit the System Environment Variables” or “Edit your account Environment Variables”.

Then click on the New... button to add a new environment variable:

* Repeat the same process for adding another variable called https_proxy.

• Use the same string for both proxies to avoid certificate issues.It means that, even for the variable https_proxy, the value must be http://username:password@proxy.url.com:port
• You might need also to add a variable to disable the SSL verification:
  • Click New...
  • Variable name: NO_SSL_VERIFY
  • Variable value: 1

  After entering these three variables, check that they are displayed as illustrated in the figure below:

Click OK to save the environment variables.

Bonus:

In the context of the STM32 model zoo, the users must create a secure connection with the ST Edge AI Developer Cloud before they can execute any operation such as analyzing, benchmarking, or quantizing. It means that they must enter their usernames and passwords for their myST accounts in the prompt window. To avoid entering their credentials each time, the users can add two environment variables named `stmai_username` and `stmai_password` to store their usernames and passwords following the method described above.

In the model zoo context, the code looks for these environment variables and always uses them automatically at the time of connection creation, saving the users the burden of entering them repeatedly. However, the variables must be named exactly as described here.  

1.2. Setting the environment variables using CLI (option 2)

Alternatively, users can set their environment variables using a terminal command prompt.

1.2.1. Setting environment variables in Windows^®

For a Windows command prompt, execute the following commands:

set http_proxy="http://username:password@proxy.url.com:port"
set https_proxy= "https://username:password@proxy.url.com:port”

Possibly, execute also:

set NO_SSL_VERIFY="1"
set stmai_username="user.name@example.com"
set stmai_password="myST_password"

At this point, verify that the environment variables have been properly set by issuing an echo command:

echo %variable_name%

Note that using the `set' command saves the environment variables only for the current session. The variables are lost when logging off. To set the environment variable permanently, use 'setx' instead of 'set':

setx http_proxy http://username:password@proxy.url.com:port

Use an echo command to verify that the environment variables have been set:

echo %variable_name%

For a Powershell prompt:

$env:http_proxy = 'http://username:password@proxy.url.com:port'
$env:https_proxy= 'https://username:password@proxy.url.com:port'

Possibly also:

$env:NO_SSL_VERIFY ='1'
$env:stmai_username = 'user.name@example.com'
$env:stmai_password = 'myST_password'

To set the environment variable permanently, instead of using $env, use the SetEnvironmentVariable method of the System.Environment class: [System.Environment]::SetEnvironmentVariable('http_proxy','http://username:password@proxy.url.com:port',[System.EnvironmentVariableTarget]::User)) At this point, verify that the environment variables have been properly set by issuing an echo command:

$env:variable_name

1.2.2. Setting environment variables in Linux^®

To set the environment variables on machines using the Linux OS, open a terminal and enter:

export https_proxy='http://username:password.@proxy.url.com:port' 
export http_proxy=' https://username:password.@proxy.url.com:port'

Possibly, enter also:

export SSL_VERIFY=false
export stmai_username=’user.name@example.com’
export stmai_password=’myST_password’

To set the environment variable permanently, add the previous lines at the end of the .bashrc file. This can be done by first issuing command:

$ nano ~/.bashrc

This opens the .bashrc file in the edit mode.

Then, navigate to the end of the .bashrc file and add the previous lines (starting with export). Once these lines are added, press CTRL + S to save and CTRL + X to exit.

Finally, to take these changes into account, run the following command:

$ source ~/.bashrc   

• The stmai_username is the login for your myST account.
• The stmai_password is the password for your myST account.
• The password in the stmai_password string does not need to be encoded.

2. Install ST Edge AI

2.1. ST Edge AI Developer Cloud (option 1)

The first option is to use the ST Edge AI Developer Cloud. With this option, you can use all the functionality of ST Edge AI without installing it locally. Using this option requires an internet connection.

Create an account on myST and then sign in to the ST Edge AI Developer Cloud to have access to the service. The creation of an account and the use of this service is free of charge.

2.2. ST Edge AI command-line interface only (option 2)

Alternatively, you can choose to install only the STEdgeAI-Core command-line interface (CLI).

For this purpose, first download the latest version of STEdgeAI-Core for your operating system. Then, to be able to use the CLI, follow the process below.

Unzip the content of the zip package en.stedgeai-<os>.zip and launch the installer file stedgeai-windows-onlineinstaller. This will launch the installation wizard following the stepwise process you will have the STEdgeAI-Core installed.

As the name suggests, it is an online installer and requires you to have internet connection and the myST user account for the installation. During the process the users can select to install all or selected components of the STEdgeAI-Core functionality to generate the Code for their AI models and algorithm for different ST Targets. For deploying on STM32N6 and STM32MCUs it is sufficient to install "STM32 MCU module" and "ST Neural_ART module".

For example for STEdgeAI-Core v3.0.0 the available options are:

• ISPU module v1.2.0 (to run the AI models on MPU devices)
• MLC module v1.2.0 (to run the AI models on the MLC enabled sensors)
• ST Neural-ART module v11.0.0 (to run the AI models on the NPU powered MCUs like STM32N6)
• STELLAR MCU module v3.0.0 (to run the AI models on the STELLAR MCU family)
• STM32 MCU module v11.0.0 (to run the AI models on the STM32MCU targets).

NOTE: The version mentioned in the screenshot is just for the demo purposes, the user should always install the latest version of the ST Edge AI Core to stay compatible with the version of STM32AI Model Zoo version.

Once installed successfully, the users are required to provide the path to the stedgeai binary file. For example for Windows OS, if a default configuration is used the file can be found at the path: C:/ST/STEdgeAI/<version>/Utilities/windows/stedgeai.exe for STEdgeAI-Core <version>. Provide the correct path for your installation in the configuration .yaml files of the stm32ai-modelzoo-services.

Warning

The presence of blank spaces in the path for ST Edge AI might result in errors. Make sure to install in a path without blank spaces in it.

3. Install STM32 model zoo

STM32AI Model zoo has two repositories.

• stm32ai-modelzoo-services: a set of services and scripts used to ease end to end AI models integration on ST devices.
• stm32ai-modelzoo: a collection of reference machine learning models that are optimized to run on STM32 microcontrollers.

3.1. Installation with git clone (option 1)

3.1.1. Installing git client

If not already installed, install git on your machine. For Windows, install git for Windows and or Linux, install git through terminal by using apt-get:

$ sudo apt-get update 
$ sudo apt-get install git

[Optional] : To use git behind a proxy, add the following lines to the git config file. If the file does not exist already, create an empty file. For Windows, the file is located under "C:/Users/username/.gitconfig". For Linux, the file must be located under ~/.git/config. For the password it has to be utf-8 decoded ("&" translates to "%26", "@" is translated to "%40")...

[user]
    name = FirstName SecondName
    email = email@domain.com
[http]
    sslVerify = false
    proxy = http://username:password@proxy.url.com:port
[https]
    sslVerify = false
    proxy = http://username:password@proxy.url.com:port

3.1.2. Installing git lfs (only needed for stm32ai-modelzoo)

As some of the pretrained model files in the stm32ai-modelzoo repository can be larger than normal GitHub file size budget, the repository uses git lfs. So before cloning the stm32ai-modelzoo repository, the user needs to install and setup the git lfs (large file system) extension. This can be done following the steps below:

• On Ubuntu:

sudo apt-get install git-lfs

• On Windows:

Download and install it from here.

Once Git LFS is installed set it up using the following command:

$ git lfs install
Git LFS initialzed.

If the command runs successfully you should see Git LFS initialized. message. If you do not see this message visit the GitHub documentation page for more details and support.

3.1.3. Cloning the repositories

Go to the directory where you want to download the model zoo script. You can use a Powershell or Command prompt.

For Windows, and terminal for Linux, and enter the command to clone the repositories:

$ git clone https://github.com/STMicroelectronics/stm32ai-modelzoo.git
Cloning into 'stm32ai-modelzoo'...
:
:
$ git clone https://github.com/STMicroelectronics/stm32ai-modelzoo-services.git
Cloning into 'stm32ai-modelzoo-services'...
:
:

3.2. Initialize Git Submodules (optional)

To reduce the size of the model zoo services repository, the deployment application code is not downloaded automatically when cloning the repository. Instead, it can be fetched on demand when the deployment is needed to be performed. This can be managed through submodule functionality of git. To get the application code for all the use cases navigate to the "stm32ai-modelzoo-services" directory, and initialize the submodules:

git submodule update --init --recursive

The other option is to get the individual submodules needed. For example, if one wants to deploy only the image_classification models on STM32N6, the corresponding submodule can be obtained by executing following command:

git submodule update --init --recursive application_code/image_classification/STM32N6 

The path to all the submodules can be found in the .gitmodule file in stm32ai-modelzoo-services directory.

3.3. Installation from a ZIP (option 2)

An easy way to download without the need to install git for Windows is to download the repository as a ZIP archive. Go to stm32ai-modelzoo github or stm32ai-modelzoo-services github and click on Download ZIP from the menu ""Code"" as shown below:

Then extract to your target directory.

3.5. Prerequisites

• If you don't have Python installed already, you can download and install it from here. For the stm32ai-modelzoo-services we recommend to use Python 3.12.
  • For Windows systems, make sure to check the Add python.exe to PATH option during the installation process.
  • Having multiple versions installed can be a problem. Therefore, it is recommended to remove the paths for the other Python versions installed and keep only the one installed for STM32 Model Zoo.
  • For Linux, add the path of the Python installation to your paths using the export command or by modifying the ~/.bashrc file.
• When using a GPU, make sure to install the GPU drivers. For NVIDIA GPUs, refer to https://docs.nvidia.com/deeplearning/cudnn/install-guide/index.html to install CUDA and CUDNN.
• NOTE: When using GPU devices with Windows OS, it is not recommended to use WSL as it can result in suboptimal acceleration for training on GPU.

3.6. Python™ environment creation

It is recommended to create a virtual environment for the installations of the python dependencies, so that the versions are isolated from other projects. This can be done by following one of the two things.

3.6.1. Python™ virtual environment (option 1)

• For Windows, open a Powershell or Command prompt terminal.
• For Linux, open a terminal.
• Navigate to the model zoo directory and create a Python virtual environment for the project using venv:

cd stm32ai-modelzoo-services
python -m venv st_zoo   

• Activate your virtual environment.
• For Windows run:

st_zoo\Scripts\activate.bat 

• For Linux run:

source st_zoo/bin/activate   

• Then install all the necessary Python packages. A list of all the required Python packages is provided in requirement.txt file.

pip install -r requirements.txt

3.6.2. Python™ conda environment (option 2)

An alternative is to create a conda virtual environment for the project. Install Miniconda.

If you are using conda environment, optionally if the proxy variables have not been configured for your terminal prompt, you can also use the .condarc file to store the proxy information. This can be done by creating a .condarc file and place it in the path C:/Users/username/ for Windows and $HOME for Linux. The .condarc file must contain:

proxy_servers: 
   https: http://username:UTF-8-EncodedPassword@proxy.url.com:8080
   http: http://username:UTF-8-EncodedPassword@proxy.url.com:8080
ssl_verify: false

Note: Refer to section Setting up Proxy and SSL variables for the UTF encoding and proxy URLs.

• For Windows, open an Anaconda PowerShell Prompt. For Linux, open a terminal.
• Go to the model zoo folder:

cd stm32ai-modelzoo-services  

• Create a conda environment:

conda create -n st_zoo 

• Activate your virtual environment:

conda activate st_zoo  

• Install Python 3.12 from the conda-forge open source repository:

conda install -c conda-forge python=3.12

3.6.3. pyenv for virtual environment (option 3)

Install pyenv on your machine. You can run following command:

 curl httpts://pyenv.run | bash

If there is an error, check that the proxies are set properly. To start pyenv automatically at the start of your sessions, add the following lines in your .bashrc file.

export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"

Then save, exit and reload the changed .bashrc by running:

source ~/.bashrc

To download and install Python 3.12.9 launch the following command:

pyenv install 3.12.9

Once it is installed run the following command to create the virtual environment:

pyenv virtualenv 3.12.9 st_zoo

This will create a virtual environment named as st_zoo. To activate this environment launch following command:

pyenv activate st_zoo

3.6.4. ( optional) Setting up Nvidia GPU

If using NVIDIA GPU, install cudatoolkit and cudnn and add to the conda path:

conda install -c conda-forge cudatoolkit=11.8 cudnn

Add cudatoolkit and cudnn to the path permanently:

 mkdir -p $CONDA_PREFIX/etc/conda/activate.d
echo 'export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CONDA_PREFIX/lib/' > $CONDA_PREFIX/etc/conda/activate.d/env_vars.sh

3.6.5. Installing Python packages and dependencies

Once the virtual environment is created following your preferred setup and activated, install all the necessary Python packages. This can be done by running the following command inside your virtual environment (for CPU only):

pip install -r requirements.txt

Or for machines with GPU run:

pip install -r requirements_gpu.txt

NOTE: Building PESQ and PyCOCOTools require C++ Build Tools for compiling and building the wheel files. If you are not using AED and Object Detection use-cases you can simply remove these from the requirement.txt files.

4. Install STM32CubeIDE

To train a model, you do not need to rebuild an STM32 firmware. On the contrary, to deploy on a Getting Started Application package, you must be able to build the corresponding firmware. This can only be done locally through STM32CubeIDE.You must then install STM32CubeIDE following the instruction of the STM32CubeIDE installation guide. STM32AI Model Zoo Services uses STM32CubeIDE version 1.17.0. Using other versions might result in issues.

Warning

The presence of blank spaces in the paths for stedgeai.exe or stm32cubeide.exe might result in errors. Make sure to install in paths without blank spaces in them.

Note: The deployment of the models works, even without having the local installation of ST Edge AI, by using ST Edge AI Developer Cloud. Refer to section ST Edge AI Developer Cloud to find out how.

5. Update the model zoo yaml file with the installation path

When using a local installation either for training or deployment, the yaml file must be updated with the correct paths. Update the variables with your installation paths:

 path_to_stedgeai: C:/ST/STEdgeAI/3.0/Utilities/windows/stedgeai.exe
 path_to_cubeIDE: C:/ST/STM32CubeIDE_1.17.0/STM32CubeIDE/stm32cubeide.exe

Note: Here `path_to_stedgeai` is provided for a user using Windows OS and default configurations to install STEdgeAI-Core version 3.0.0. Replace these paths with the paths you have for the installation.