deploy.py

Go to the documentation of this file.

 
 
import os
import sys
import warnings
import shutil
 
from hydra.core.hydra_config import HydraConfig
from omegaconf import DictConfig
from typing import Optional
 
warnings.filterwarnings("ignore")
os.environ['TF_CPP_MIN_LOG_LEVEL'] = '3'
 
from common.utils import get_model_name_and_its_input_shape, get_model_name
from common.deployment import stm32ai_deploy_stm32n6, stm32ai_deploy_mpu
from common.benchmarking import cloud_connect
from src.utils import gen_h_user_file_n6
 
 
def deploy(cfg: DictConfig = None, model_path_to_deploy: Optional[str] = None,
           credentials: list = None) -> None:
    """
    @brief Deploy a quantized INT8 model onto an STM32N6 MCU board.
 
    @details
    This function implements the full deployment pipeline for STM32N6-series boards:
 
    **Step 1 — Parameter extraction from YAML config:**
      All deployment parameters are read from the Hydra configuration object:
      - `board`              : Target board name (e.g., "STM32N6570-DK").
      - `stlink_serial_number`: ST-Link serial number for multi-board setups.
      - `c_project_path`     : Path to the STM32CubeIDE C project directory.
      - `stm32ai_version`    : Version of ST Edge AI Core to use.
      - `optimization`       : Optimization level for code generation (e.g., "balanced").
      - `path_to_stm32ai`    : Local path to the stedgeai executable.
      - `path_to_cube_ide`   : Local path to the STM32CubeIDE executable.
      - `stm32ai_ide`        : IDE/compiler to use (must be "gcc" for STM32N6).
      - `stm32ai_serie`      : MCU series (must be "STM32N6" for this path).
 
    **Step 2 — C header file generation:**
      gen_h_user_file_n6() generates `ai_model_config.h`, a C header that embeds
      model metadata (input/output shapes, number of keypoints, confidence thresholds)
      into the firmware. This allows the C application to configure itself at compile time.
 
    **Step 3 — Board configuration file selection:**
      A board-specific .conf file is selected:
      - `stmaic_STM32N6570-DK.conf`   for the STM32N6570-DK Discovery Kit.
      - `stmaic_NUCLEO-N657X0-Q.conf` for the NUCLEO-N657X0-Q board.
 
    **Step 4 — Full deployment via stm32ai_deploy_stm32n6():**
      This common function:
        a. Invokes ST Edge AI Core to convert the .tflite model into optimized C arrays.
        b. Integrates the C code into the STM32CubeIDE project.
        c. Compiles the firmware using GCC.
        d. Flashes the binary onto the board via ST-Link (USB debugger).
 
    @note After flashing, the user must manually toggle the boot switches on the
          STM32N6570-DK to the left and power-cycle the board to boot from flash.
 
    @param cfg                Hydra DictConfig loaded from user_config.yaml.
    @param model_path_to_deploy  Path to the quantized .tflite model to deploy.
                              If None, uses cfg.general.model_path.
    @param credentials        Optional cloud credentials from a prior cloud_connect() call.
 
    @return None
    @throws ValueError  If the hardware series is STM32H7 (not supported in this flow).
    @throws TypeError   If the board name or IDE/serie combination is not supported.
    """
 
    # --- Extract all deployment parameters from the Hydra configuration ---
    board = cfg.deployment.hardware_setup.board
    stlink_serial_number = cfg.deployment.hardware_setup.stlink_serial_number
    c_project_path = cfg.deployment.c_project_path
    output_dir = HydraConfig.get().runtime.output_dir
 
    
    stm32ai_output = output_dir + "/generated"
 
    stm32ai_version = cfg.tools.stm32ai.version
    optimization = cfg.tools.stm32ai.optimization
    path_to_stm32ai = cfg.tools.stm32ai.path_to_stm32ai
    path_to_cube_ide = cfg.tools.path_to_cubeIDE
    verbosity = cfg.deployment.verbosity
    stm32ai_ide = cfg.deployment.IDE
    stm32ai_serie = cfg.deployment.hardware_setup.serie
    check_large_model = False
 
    # --- Determine the model path to deploy ---
    
    model_path = model_path_to_deploy if model_path_to_deploy else cfg.general.model_path
    model_name, input_shape = get_model_name_and_its_input_shape(model_path=model_path)
 
    get_model_name_output = get_model_name(model_type=str(model_name),
                                           input_shape=str(input_shape[0]),
                                           project_name=cfg.general.project_name)
 
    # --- Generate the C header file for the firmware application ---
    
    print("[INFO] : Generating C header file for Getting Started...")
    if stm32ai_serie.upper() == "STM32H7":
        # STM32H7 deployment is handled by a different function, not supported here
        raise ValueError("STM32H7 is not supported in this deployment flow.")
    else:
        gen_h_user_file_n6(config=cfg, quantized_model_path=model_path)
 
    # --- Select board-specific configuration and launch deployment ---
    if stm32ai_serie.upper() == "STM32N6" and stm32ai_ide.lower() == "gcc":
 
        
        if board == "STM32N6570-DK":
            stmaic_conf_filename = "stmaic_STM32N6570-DK.conf"
        elif board == "NUCLEO-N657X0-Q":
            stmaic_conf_filename = "stmaic_NUCLEO-N657X0-Q.conf"
        else:
            raise TypeError(
                "The hardware selected in cfg.deployment.hardware_setup.board is not supported yet!\n"
                "Please choose one of the following boards: "
                "`STM32N6570-DK` or `NUCLEO-N657X0-Q`.")
 
        
        stm32ai_deploy_stm32n6(
            target=board,
            stlink_serial_number=stlink_serial_number,
            stm32ai_version=stm32ai_version,
            c_project_path=c_project_path,
            output_dir=output_dir,
            stm32ai_output=stm32ai_output,
            optimization=optimization,
            path_to_stm32ai=path_to_stm32ai,
            path_to_cube_ide=path_to_cube_ide,
            stmaic_conf_filename=stmaic_conf_filename,
            verbosity=verbosity,
            debug=False,
            model_path=model_path,
            get_model_name_output=get_model_name_output,
            stm32ai_ide=stm32ai_ide,
            stm32ai_serie=stm32ai_serie,
            on_cloud=cfg.tools.stm32ai.on_cloud,
            build_conf=cfg.deployment.build_conf,
            check_large_model=True,
            cfg=cfg,
            input_data_type='uint8',
            output_data_type='',
            inputs_ch_position='chlast',
            outputs_ch_position=''
        )
    else:
        raise TypeError(
            "Options for cfg.deployment.hardware_setup.serie and cfg.deployment.IDE not supported yet!\n"
            "The only supported combination is serie=`STM32N6` and IDE=`gcc`.")
 
 
def deploy_mpu(cfg: DictConfig = None, model_path_to_deploy: Optional[str] = None,
               credentials: list = None) -> None:
    """
    @brief Deploy an AI model onto an STM32MP MPU target device.
 
    @details
    This function handles deployment on STM32MP-series Microprocessor Units (MPUs),
    which run Linux and have more memory and compute resources than MCUs.
 
    Unlike the MCU path, MPU deployment can optionally leverage the STM32Cube.AI
    Developer Cloud to generate an optimized NBG (Neural Binary Graph) file,
    which is a proprietary binary format optimized for ST's NPU on MP2 devices.
 
    Cloud optimization flow (STM32MP2 + .tflite or .onnx + on_cloud=True):
      1. Upload the model to the Developer Cloud.
      2. Request NBG generation (optimized binary format for the NPU).
      3. Download the resulting .nb file.
      4. Deploy the .nb file instead of the original model.
 
    If cloud optimization is not available or fails, the original model is used directly.
 
    Supported boards:
      - STM32MP257F-EV1
      - STM32MP157F-DK2
      - STM32MP135F-DK
 
    @param cfg                Hydra DictConfig loaded from user_config.yaml.
    @param model_path_to_deploy  Path to the model file to deploy (.tflite or .onnx).
                              If None, uses cfg.general.model_path.
    @param credentials        Optional cloud credentials from a prior cloud_connect() call.
 
    @return None
    @throws TypeError  If the board is not in the list of supported MPU boards,
                       or if the deployment process fails.
    """
 
    # --- Extract MPU deployment parameters ---
    board = cfg.deployment.hardware_setup.board
    c_project_path = cfg.deployment.c_project_path
    keypoints_file_path = cfg.dataset.keypoints_file_path
    board_deploy_path = cfg.deployment.board_deploy_path
    verbosity = cfg.deployment.verbosity
    board_serie = cfg.deployment.hardware_setup.serie
    board_ip = cfg.deployment.hardware_setup.ip_address
 
    
    optimized_model_path = c_project_path + "Optimized_models/"
 
    model_path = model_path_to_deploy if model_path_to_deploy else cfg.general.model_path
    model_extension = os.path.splitext(model_path)[1]
    model_name, input_shape = get_model_name_and_its_input_shape(model_path=model_path)
 
    # --- Optional cloud-based NBG optimization for STM32MP2 ---
    
    if board_serie == "STM32MP2" and (model_extension == ".tflite" or model_extension == ".onnx") \
            and cfg.tools.stm32ai.on_cloud:
        login_success, ai, _ = cloud_connect(stm32ai_version=None, credentials=credentials)
        if login_success:
            try:
                ai.upload_model(model_path)
                model = model_name + model_extension
                res = ai.generate_nbg(model)
                ai.download_model(res, optimized_model_path + res)
                model_path = os.path.join(optimized_model_path, res)
                model_name = model_name + ".nb"
                rename_model_path = os.path.join(optimized_model_path, model_name)
                os.rename(model_path, rename_model_path)
                model_path = rename_model_path
                print("[INFO] : Optimized Model Name:", model_name)
                print("[INFO] : Optimization done! Model available at:", optimized_model_path)
            except Exception as e:
                print(f"[FAIL] : Model optimization via Cloud failed: {e}.")
                print("[INFO] : Use default model instead of optimized ...")
 
    # --- Deploy to the MPU board ---
    if board in ["STM32MP257F-EV1", "STM32MP157F-DK2", "STM32MP135F-DK"]:
        res = stm32ai_deploy_mpu(
            target=board,
            board_ip_address=board_ip,
            class_names=keypoints_file_path,
            board_deploy=board_deploy_path,
            c_project_path=c_project_path,
            verbosity=verbosity,
            debug=False,
            model_path=model_path,
            cfg=cfg
        )
        if res == False:
            raise TypeError("Deployment on the target failed\n")
    else:
        raise TypeError(
            "Options for cfg.deployment.hardware_setup.board not supported!\n"
            "Only valid options are STM32MP257F-EV1, STM32MP157F-DK2, STM32MP135F-DK\n")