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 STM32Cube.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 STM32Cube.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= "http://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=' http://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 STM32Cube.AI

2.1. STM32Cube.AI Developer Cloud (option 1)

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

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

2.2. STM32Cube.AI installation through STM32CubeMX (option 2)

To install STM32Cube.AI locally, follow the instruction given in How to install X-CUBE-AI through STM32CubeMX.

To use STM32Cube.AI locally, this is the recommended installation process as it works with X-CUBE-AI as a plugin to STM32CubeMX as well as by accessing directly the command-line interface executable.

Following this process installs the Windows CLI executable stm32ai.exe by default in the following path:

C:/Users/username/STM32Cube/Repository/Packs/STMicroelectronics/X-CUBE-AI/version/Utilities/windows/stm32ai.exe 

"username" must be replaced by your Windows user directory name and "version" by the version you installed, for instance 8.1.0.

Warning

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

2.3. STM32Cube.AI command-line interface only (option 3)

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

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

2.3.1. For Windows^®

• Create a directory named STMicroelectronics.X-CUBE-AI.<version>. For example, for the installation of the version 8.1.0, the directory is named as C:/STMicroelectronics.X-CUBE-AI.8.1.0. The following procedure description relates to the installation of this version; Adapt it by replacing 8.1.0 with the version you are installing.
• Extract the contents of en.x-cube-ai-windows_v8.1.0.zip in this directory, which results in two files:

  - stm32ai-windows-8.1.0.zip
  - STMicroelectronics.X-CUBE-AI.8.1.0.pack

• Rename the STMicroelectronics.X-CUBE-AI.8.1.0.pack to STMicroelectronics.X-CUBE-AI.8.1.0.zip and extract its contents in the folder created in first folder, C:/STMicroelectronics.X-CUBE-AI.8.1.0/
• Finally create a folder called Utilities in C:/STMicroelectronics.X-CUBE-AI.8.1.0/ and extract the contents of the stm32ai-windows-8.1.0.zip in it.
• Once the process is completed, you have the following contents in the folder C:/STMicroelectronics.X-CUBE-AI.8.1.0/

 - CubeMX
 - db
 - Documentation
 - Middlewares
 - scripts
 - Utilities/windows
 - Packages_license.html
 - Release_Notes.html
 - STMicroelectronics.X-CUBE-AI.pdsc

The path to the executable is then C:/STMicroelectronics.X-CUBE-AI.8.1.0/Utilities/windows/stm32ai.exe

2.3.2. For Linux^®

Download the desired version of STM32Cube.AI for Linux. The example below show the process for installing the version 8.1.0. Replace 8.1.0 with the version you are using.

The downloaded package is named as en.x-cube-ai-linux_v8.1.0.zip. Extract and unzip the package en.x-cube-ai-linux_v8.1.0.zip in a directory, for instance $HOME/stm32ai. Then execute following commands to have the executable of STM32Cube.AI:

cd $HOME/stm32ai
chmod 644 en.en.x-cube-ai-v8-1-0-linux.zip
unzip en.en.x-cube-ai-v8-1-0-linux.zip
mv STMicroelectronics.X-CUBE-AI.8.1.0.pack STMicroelectronics.X-CUBE-AI.8.1.0.zip
unzip STMicroelectronics.X-CUBE-AI.8.1.0.zip -d X-CUBE-AI.8.1.0
unzip stm32ai-linux-8.1.0.zip -d X-CUBE-AI.8.1.0/Utilities

The path to the executable stm32ai is then $HOME/stm32ai/STMicroelectronics.X-CUBE-AI.8.1.0/Utilities/linux/stm32ai

Warning

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

3. Install STM32 model zoo

3.1. Installation with git clone (option 1)

For Windows, install git for Windows. For Linux, install git through apt-get:

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

To use git behind a proxy, optionally if the proxy variables have not been configured for your terminal prompt, 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

[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

Go to the directory where you want to download the model zoo script. You can use a Powershell or Command prompt. For Windows, you can alternatively right-click to open a git bash window:

For Linux, open a terminal.

Then enter git clone https://github.com/STMicroelectronics/stm32ai-modelzoo.git in the terminal to clone the repository.

3.2. 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 and click on Download ZIP from the menu ""Code"":

Then extract to your target directory.

4. Install the Python™ environment

4.1. Prerequisites

• If you don't have Python installed already, you can download and install it from here.
  • Python 3.9.x <= Version <= 3.10 is required to be able to use the required version of TensorFlow™ later; The recommended versions are Python v3.10.x.
  • 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.

4.2. Python™ environment creation

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

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

• Create a conda environment:

conda create -n st_zoo

• Activate your virtual environment:

conda activate st_zoo

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

conda install -c conda-forge pyhton=3.10

• 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

• Then, install all the necessary Python packages, the requirement file contains it all.

pip install -r requirements.txt

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

Warning

The presence of blank spaces in the paths for STM32Cube.AI or STM32CubeIDE 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 STM32Cube.AI, by using STM32Cube.AI Developer Cloud. Refer to section STM32Cube-AI Developer Cloud to find out how.

6. 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_stm32ai: C:/Users/username/STM32Cube/Repository/Packs/STMicroelectronics/X-CUBE-AI/version/Utilities/windows/stm32ai.exe
 path_to_cubeIDE: C:/ST/STM32CubeIDE_1.10.1/STM32CubeIDE/stm32cubeide.exe

Note: Here `path_to_stm32ai` is provided for a user directory named username and version 8.1.0. This is the default path for the local installation of the STM32Cube.AI when following STM32Cube.AI installation through STM32CubeMX (option 2). Replace these paths with the paths you have for the installation.