Image Classification STM32MPU Model Deployment

January 22, 2026 ยท View on GitHub

This tutorial demonstrates how to deploy a pre-trained image classification model built with TensorFlow Lite (.tflite) or (.ONNX) on an STM32MPU board using X-LINUX-AI.

Table of contents

1. Before You Start
2. Yaml Configuration
    2.1 Setting the Model and the Operation Mode

    Users must provide the path to their model file using the model_path attribute. This can be either a Keras model file with a .keras filename extension (float model), a TensorFlow Lite model file with a .tflite filename extension (quantized model), or an ONNX model with a .onnx filename extension. In this example, the path to the MobileNet V2 model is provided in the model_path parameter. Please check out the STM32 model zoo information for more image classification models. The operation_mode attribute should be set to deployment as follows:

    model:
   model_path:  ../../stm32ai-modelzoo/image_classification/mobilenetv2/ST_pretrainedmodel_public_dataset/tf_flowers/mobilenetv2_a035_128_fft/mobilenetv2_a035_128_fft_int8.tflite

operation_mode: deployment

    You must copy the preprocessing section to your own configuration file, to ensure you have the correct preprocessing parameters.

    2.2 Dataset Configuration
      2.2.1 Dataset info

      Configure the dataset section in the YAML file as follows:

      The class_names attribute specifies the classes that the model is trained on. This information could be provided in the YAML file directly, or in the classes_file_path so the class_names can be automatically recovered. Actually, in some datasets there are many classes like for example Imagenet (1000). To avoid listing all class names, which can be very unpractical, we use the classes_file_path parameter as follows:

      dataset:
  classes_file_path: ../application_code/image_classification/STM32MP-LINUX/Resources/labels_imagenet_2012.txt
      2.2.2 Preprocessing info

      To run inference in the Python application, we need to apply on the input data the same preprocessing used when training the model.

      To do so, you need to specify the preprocessing configuration in user_config.yaml as the following:

      preprocessing:
  resizing:
    interpolation: bilinear
    aspect_ratio: fit
  color_mode: rgb
      • resizing - bilinear, only supported option for application python code.
      • aspect_ratio - fit, only supported for now. With fit aspect ratio may not be preserved.
      • color_mode - rgb, only supported for now.
    2.3 Deployment parameters

    To deploy the model in STM32MPU boards, you can use either TensorFlow Lite or ONNX models on MP1, the computation will be done on CPU. For MP2, the TensorFlow Lite or ONNX model will be automatically converted to NBG model using STM32 developer cloud functionalities.

    The application code and the model will be deployed on the board through SSH.

    These steps will be done automatically by configuring the tools and deployment sections in the YAML file as the following:

    dataset: 
   classes_file_path: ../application_code/image_classification/STM32MP-LINUX/Resources/labels_imagenet_2012.txt
tools:
   stedgeai:
      optimization: balanced
      on_cloud: True
      path_to_stedgeai: C:/ST/STEdgeAI/<x.y>/Utilities/windows/stedgeai.exe
   path_to_cubeIDE: C:/ST/STM32CubeIDE_<*.*.*>/STM32CubeIDE/stm32cubeide.exe

deployment:
   c_project_path: ../../application_code/image_classification/STM32MP-LINUX/
   board_deploy_path: /usr/local/image-classification
   verbosity: 1
   hardware_setup:
      serie: STM32MP2
      board: STM32MP257F-EV1
      ip_address: X.X.X.X

    where:

    • on_cloud - Bool enable usage of STM32 developer cloud
    • c_project_path - Path to X-LINUX-AI application code project.
    • classes_file_path - Path to Dataset labels file path.
    • board_deploy_path - Path to the on target application deployment directory
    • serie - STM32MP2 or STM32MP1, only supported options for X-LINUX-AI application code.
    • board - STM32MP257F-EV1 or STM32MP157F-DK2 or STM32MP135F-DK, see the README for more details.
    • ip_address - String IP address of the board used for deployment
    2.4 Hydra and MLflow settings

    The mlflow and hydra sections must always be present in the YAML configuration file. The hydra section can be used to specify the name of the directory where experiment directories are saved and/or the pattern used to name experiment directories. With the YAML code below, every time you run the Model Zoo, an experiment directory is created that contains all the directories and files created during the run. The names of experiment directories are all unique as they are based on the date and time of the run.

    hydra:
   run:
      dir: ./tf/src/experiments_outputs/${now:%Y_%m_%d_%H_%M_%S}

    The mlflow section is used to specify the location and name of the directory where MLflow files are saved, as shown below:

    mlflow:
   uri: ./tf/src/experiments_outputs/mlruns
3. Deploy pretrained model on STM32MPU board

First, you need to connect the camera board or USB camera to the STM32MPU board, then connect the board to your network using an ethernet cable or WIFI and recover the board IP using the netdata tool on the home screen.

If you chose to modify the user_config.yaml, you can deploy the model by running the following command from the UC folder to deploy the application on your board:

python stm32ai_main.py

If you chose to update the deployment_config.yaml and use it, then run the following command from the UC folder to build and flash the application on your board:

python stm32ai_main.py --config-path ./config_file_examples/ --config-name deployment_mpu_config.yaml

If you have a Keras model that has not been quantized and you want to quantize it before deploying it, you can use the chain_qd tool to quantize and deploy the model sequentially. To do this, update the chain_qd_config.yaml file and then run the following command from the UC folder to build and flash the application on your board:

python stm32ai_main.py --config-path ./config_file_examples/ --config-name chain_qd_config.yaml

When the application is running on the STM32MPU board, the LCD displays the following information:

  • Data stream from the camera board
  • Class name with confidence score in % concerning the output class with the highest probability (Top1)
  • The model inference time (in milliseconds)
  • The number of frames processed per second (FPS) by the model

plot