Skip to content

RT-Thread/RT-AK-plugin-stm32

BranchesTags

Repository files navigation

RT-AK 之 STM32

中文 | English

简介

Date: 2021/08/18

Update: 新增 X-CUBE-AI v7.0.0 支持。只需要下载对应版本的 x-cube-ai 和指定 --cube_ai 参数即可，按照下面命令即可运行.

其中 --cube_ai 指定的文件夹已经存在，位于 RT-AK\rt_ai_tools\platforms\plugin_stm32\X-CUBE-AI.7.0.0

# 模板
python aitools.py --project <bsp> --model_name <model_name> --platform stm32 --ext_tools "D:\Program Files (x86)\stm32ai-windows-7.0.0\windows" --cube_ai platforms\plugin_stm32\X-CUBE-AI.7.0.0 --clear

# 示例
D:\Project\edge-ai\RT-AK\rt_ai_tools>python aitools.py --project D:\RT-ThreadStudio\workspace\test --model_name mnist --platform stm32 --ext_tools D:\迅雷下载\stm32ai-windows-7.0.0\windows --cube_ai platforms\plugin_stm32\X-CUBE-AI.7.0.0 --clear

Date: 2021/06/21

Update: 该版本插件尚未支持量化功能，需要量化模型的话请自行研究或者与我们联系，欢迎提 PR，下一个版本将会支持量化功能

本项目归属于 RT-AK 主项目中的一个子模块。

使用 STM32 原厂插件进行开发。

  • 原厂插件：X-CUBE-AI
  • 模型支持：Keras | TFLite | ONNX
  • 算子支持：在 docs 文件夹下查阅对应版本的 layer_support.html 文件

目录结构

% tree -L 2 stm32 
stm32
├── backend_plugin_stm32
│   ├── backend_cubeai.c
│   ├── backend_cubeai.h
│   └── readme.md
├── config.py  # 生成 `rt_ai_<model_name>_model.h` 的一些配置信息，保存在 <BSP>/applications
├── docs  # `X-CUBE-AI` 相关文档说明； 
│   ├── command_line_interface.html
│   ├── embedded_client_api.html
│   ├── en.stsw-link009.zip  # `STLink` 驱动
│   ├── ...
│   ├── relocatable.html
│   ├── RT-AK之STM32快速上手.md
│   ├── stm32.c
│   ├── stm32programmer-cli.pdf
│   └── 量化(未完成).md
├── generate_rt_ai_model_h.py  # 生成 `rt_ai_<model_name>_model.h` ，保存在 <BSP>/applications
├── gen_rt_ai_model_c.py  # 生成 `rt_ai_<model_name>_model.c` ，保存在 <BSP>/applications
├── __init__.py
├── plugin_init.py  # 将 `stm32ai` （`X-CUBE-AI` 的模型转换工具）添加到系统变量
├── plugin_stm32_parser.py  # `STM32` 平台插件运行所需的参数
├── plugin_stm32.py  # `STM32` 平台插件运行主函数
├── prepare_work.py  # 生成两个文件夹，存放 x-cube-ai 静态库和 c-model 文件; 加载对应的 Sconscript
├── README.md
├── run_x_cube_ai.py  # 运行 `stm32ai` 工具，进行模型转换工作
├── Sconscripts  # 模型转换之后，参与到项目 `scons` 编译的脚本文件
│   ├── Middlewares
│   └── X-CUBE-AI
└── X-CUBE-AI.5.2.0  # `STM32Cube.AI` 所提供的静态库
    ├── Copyrights.txt
    └── Middlewares

命令行参数详细说明

$$ RT-AK 命令行的参数 = （RT-AK 基础参数 + STM32 插件参数） $$

  • RT-AK 基础参数，链接

  • 该部分是 RT-AK 之 STM32 插件的参数说明，详见 plugin_stm32_parser.py

其中需要注意的是加粗部分的三个参数，请注意看相关描述。

详细的使用说明请阅读后续章节

Parameter Description
--ext_tools X-CUBE-AI 存放路径，模型转换工具，内有 stm32ai 可执行软件，需要用户指定
--cube_ai X-CUBE-AI 运行所需的静态库，默认为./platforms/stm32/X-CUBE-AI.5.2.0
--rt_ai_example 存放rt_ai_<model_name>_model.c 示例文件，默认是 ./platforms/stm32/docs
--stm_out 经过 stm32ai 线程处理之后产生的中间文件夹路径，默认是当天的时间戳命名
--workspace stm32ai 运行时产生的临时工作区，默认是./stm32ai_ws
--val_data 默认为空，即使用内部自生成的随机数据集，允许用户自定义测试数据集，
--compress 表示将应用的全局压缩因子，仅应用在全连接层，可选 "1|4|8"，默认值：1
--batches 指示生成了多少随机数据样本，默认是10
--mode "analyze|validate" 模式（可选）+”generate“模式（必须有），1表示选中，在{'001', '011', '101', '111'}中选一个，默认是 001
--network 在 Documents 中的模板文件的模型名，默认是 mnist
--enable_rt_lib 在 project/rtconfgi.h 中打开宏定义，默认是 RT_AI_USE_CUBE
--clear 是否需要删除 stm32ai 生成的中间文件夹 stm_out ，默认为False

  • 示例：

    --ext_tools="D:/Program Files (x86)/stm32ai-windows-5.2.0/windows"

插件安装

该插件无需主动安装，

只需要克隆主项目工程：RT-AK

进入到 RT-AK/rt_ai_tools 路径下，

仅需要在执行 python aitools.py --xxx 的同时指定 platform 参数为 stm32 即可，插件会自动下载。

命令行运行 RT-AK

1 基础运行命令

请在 edge-ai/RTAK/tools 路径下运行该程序。

# 基础运行命令
python aitools.py --project=<your_project_path> --model=<your_model_path> --platform=stm32 --ext_tools=<your_x-cube-ai_path> --clear

# 示例
python aitools.py --project="D:\RT-ThreadStudio\workspace\test" --model="./Models/keras_mnist.h5" --platform=stm32 --ext_tools="D:\Program Files (x86)\stm32ai-windows-5.2.0\windows" --clear

image-20210401181247394

2 指定参数运行

# 指定转换模型的名称，--model_name 默认为 network
python aitools.py --project=<your_project_path> --model=<your_model_path>  --model_name=<model_name>  --platform=stm32 --ext_tools=<your_x-cube-ai_path>

# 保存运行 stm32ai 线程过程中产生的文件，--clear 默认为空
# 如果存在，则将会删除`stm32ai` 运行时产生的工作文件夹，即`--stm_out`
python aitools.py --project=<your_project_path> --model=<your_model_path> --platform=stm32 --ext_tools=<your_x-cube-ai_path>

# 指定保存运行日志, --log 默认为空
python aitools.py --project=<your_project_path> --model=<your_model_path> --log=./log.log --platform=stm32 --ext_tools=<your_x-cube-ai_path>

# 指定保存的文件夹名称，--stm_out 默认是当天时间，比如 './20210223'
python aitools.py --project=<your_project_path> --model=<your_model_path> --platform=stm32 --ext_tools=<your_x-cube-ai_path> --stm_out <new_dir>

# 指定生成的 c-model 名，--c_model_name 默认是network
python aitools.py --project=<your_project_path> --model=<your_model_path> --platform=stm32 --ext_tools=<your_x-cube-ai_path> --c_model_name=<new_model_name>

注意：ai_tools.py会在rtconfig.h中添加#define RT_AI_USE_CUBE，如果在使用工具注入模型到工程后，又对工程进行了配置则会导致这个宏刷新掉，从而导致编译报错。因此需要先将工程配置完成后再使用工具进行模型注入

完整的项目实战例程，请阅读：RT-AK之STM32快速上手.md

插件内部工作流程

  • 模型量化

  • 判断模型是否支持

  • 判断 CPU 是否支持

  • 设置 stm32ai 系统环境变量，x-cube-ai

  • 在 stm_out 下生成静态库文件夹和存放 c-model 的文件夹

  • 将模型转换成 c-model，保存在 <stm_out>/X-CUBE-AI 路径下

  • 生成 rt_ai_<model_name>_model.h 文件，保存在 project/applications

  • 生成 rt_ai_<model_name>_model.c 文件，保存在 project/applications

  • 加载 x-cube-ai 的静态库到 stm_out 路径下

  • 把 stm_out 内的两个关键文件夹加载到 project 下

  • 在 project 中使能 HAL_CRC

  • 判断是否删除 stm_out

功能函数 

1 模型是否支持
- 函数：`is_valid_model(model, sup_models)`
- 功能：判断模型是否支持
- input: (model, sup_models_list)


2 cpu是否支持
- 函数：`is_valid_cpu(project, sup_cpus, cpu="")`
- 功能：根据 `project/rtconfig.py` 提供的 `CPU` 信息判断是否支持
- input: (project, sup_cpus)
- output: cpu


3 设置环境变量
- 函数：`set_env(plugin_path)`
- 功能：设置 `x-cube-ai: stm32.exe` 为系统变量
- input: (x-cube-ai_path)


4 生成两个文件夹
- 函数：`pre_sconscript(aitools_out, stm32_dirs, scons_path="platforms/stm32/Sconscripts")`
- 功能：
  1. 生成两个文件夹，分别存放 `x-cube-ai` 静态库和 `c-model` 文件，如果之前存在，先删除原本的文件夹
  2. 加载对应的 `Sconscript`
- input: (stm_out, sconscript_dir, ["Middlewares", "X-CUBE-AI"])


5 模型转换
- 函数：`stm32ai(model, stm_out, c_model_name, sup_modes, ai_params)`
- 功能：
  1. 将模型转换成 `c-model`，支持三种模式：分析、验证、生成（必须有）
  2. 如果有报错，根据生成的 `report.txt` 文件抛出异常
- input: (model, stm_out, c_model_name, sup_modes_list, [workspace, compress, batches, mode, val_data])
- output: flag_list, etc: [False, True, True] 对应 modes=“011” 三种模型执行是否成功


6.1 生成 rt_ai_model.h
- 函数：`rt_ai_model_gen(stm_out, project, model_name)`
- 功能：根据生成的 `c-model` 文件生成  `rt_ai__model.h` 文件，保存在 `project/applications` 
- input: (stm_out, project, c_model_name)


6.2 生成 rt_ai_model.c
- 函数：`load_rt_ai_example(project, rt_ai_example, platform, old_name, new_name)`
- 功能：根据提供的模板文件，生成 `rt_ai__model.c` + `rt_ai_template.c/h`文件，保存在 `project/applications` 
- input: (project, rt_ai_exampl_path, platform, default_model_name, c_model_name)


7 加载 x-cube-ai libs
- 函数：`load_lib(stm_out, cube_ai_path, cpu, middle=r"Middlewares/ST/AI")`
- 功能：加载 `x-cube-ai` 静态库到 `stm_out` 中
- input: (stm_out, cube_ai_path, cpu, middle=r"Middlewares/ST/AI")


8 加载到 project
- 函数：`load_to_project(stm_out, project, stm32_dirs)`
- 功能：加载 `stm_out` 两个文件夹到 `project` 中。如果之前有存在，则先删除
- input: (stm_out, project, ["Middlewares", "X-CUBE-AI"])


9 使能 HAL-CRC
- 函数：`enable_hal_crc(project)`
- 功能：在 `project/board/...` 文件中使能 `HAL_CRC_MODULE_ENABLED`
- input: (project)

About

plugin for stm32 of RT-Thread AI Kit

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

8 stars

Watchers

5 watching

Forks

7 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages