3. 开发环境搭建与工程模板

在STM32上部署边缘AI模型，第一步不是写推理代码，而是把工具链搭好、把工程骨架立起来。本节围绕一条主线展开：安装STM32CubeMX、STM32CubeIDE、STM32Cube.AI与X-CUBE-AI扩展包，然后用CubeMX生成一个带AI模型的基础工程，在CubeIDE中编译并下载到开发板。整个过程涉及四个工具的分工与衔接，先理清它们各自负责什么，再动手操作。

一、四个工具的分工与依赖关系

STM32CubeMX是图形化配置工具，负责引脚分配、时钟树、外设初始化和中间件勾选，最终生成C代码工程。STM32CubeIDE是集成开发环境，负责代码编辑、编译、调试和下载，它内置了CubeMX的配置界面，也可以独立使用。STM32Cube.AI是模型转换与推理代码生成工具，它把训练好的神经网络模型（如Keras的.h5、ONNX的.onnx、TFLite的.tflite）转换成STM32可用的C代码，并给出Flash和RAM占用估算。X-CUBE-AI是STM32Cube.AI在CubeMX/CubeIDE中的扩展包形式，安装后才能在图形界面里直接添加AI模型。

四者的关系可以这样理解：X-CUBE-AI是插件，装进CubeMX或CubeIDE；STM32Cube.AI是插件背后的转换引擎；CubeMX负责把AI模型和MCU外设配置整合成工程；CubeIDE负责把工程编译成可执行文件并烧录。缺少任何一环，AI模型都无法真正跑在芯片上。

二、安装顺序与版本匹配

推荐安装顺序是：先装STM32CubeIDE，再装STM32CubeMX（如果CubeIDE已内置MX可跳过独立安装），然后通过CubeMX的“Manage embedded software packages”安装X-CUBE-AI扩展包。X-CUBE-AI的版本必须与CubeMX版本兼容，例如CubeMX 6.10对应X-CUBE-AI 9.x系列。版本不匹配时，AI配置界面可能无法加载模型或生成代码报错。

安装X-CUBE-AI时，在CubeMX中点击“Help → Manage embedded software packages”，在“STMicroelectronics”分类下找到X-CUBE-AI，勾选对应版本并点击Install。安装完成后，新建工程时在“Middleware”分类下就能看到“Artificial Intelligence”选项。如果使用CubeIDE，也可以在“Help → Manage Embedded Software Packages”中安装，效果相同。

三、创建第一个包含AI模型的工程

以STM32F407VG（常见于STM32F4 Discovery板）为例，创建一个图像分类或传感器分类的AI工程。打开CubeMX，选择“New Project”，在芯片选择器中输入STM32F407VG，双击进入配置界面。

第一步配置时钟。在“Pinout & Configuration → System Core → RCC”中，将High Speed Clock (HSE)设为Crystal/Ceramic Resonator。然后进入“Clock Configuration”标签，将HCLK设为168MHz，CubeMX会自动计算PLL参数。这一步决定了后续推理代码的运行主频。

第二步配置外设。如果模型输入来自串口，启用USART2（异步模式，115200波特率）；如果来自摄像头或传感器，按实际接口启用DCMI、I2C或SPI。对于第一个工程，建议先用串口输入固定测试数据，降低硬件依赖。

第三步添加AI模型。在“Middleware”分类下点击“Artificial Intelligence”，勾选“Enable”。在“Model”选项卡中点击“Add model”，选择已训练好的模型文件。CubeMX会调用STM32Cube.AI引擎分析模型，显示网络层数、参数量、Flash和RAM估算值。例如一个简单的3层全连接网络，输入维度10，输出维度3，参数量约200个，Flash占用约2KB，RAM约1KB。分析完成后点击“Generate Code”，CubeMX会在工程中生成 X-CUBE-AI 相关文件夹和 app_x-cube-ai.c 文件。

第四步生成工程。在“Project Manager”中设置工程名称（如 AI_First_Project）、存储路径和工具链（选择STM32CubeIDE）。点击“Generate Code”，CubeMX会生成完整的工程目录，包含 Core/、Drivers/、Middlewares/ 和 .ioc 配置文件。

四、编译与下载

在CubeIDE中点击“File → Open Projects from File System”，选择刚才生成的工程目录。打开后，CubeIDE会自动识别工程结构。点击工具栏的“Build”按钮（锤子图标），编译整个工程。编译成功后，在 Debug/ 目录下会生成 .elf 和 .bin 文件。

编译过程中重点关注两个输出：一是Flash占用，在编译日志末尾会显示 text、data、bss 段大小，例如 text: 28560 bytes，说明代码约28KB；二是AI模型是否被正确链接，如果出现 undefined reference to ai_... 错误，说明X-CUBE-AI生成的代码没有被加入编译路径，需要检查 Middlewares/ST/AI 目录是否在Include路径中。

下载前，用ST-Link将开发板与电脑连接，确认CubeIDE的“Run → Debug Configurations”中ST-Link接口识别正常。点击“Run”按钮，CubeIDE会先编译再烧录，最后停在main函数入口。点击“Resume”让程序运行。如果使用串口验证，打开串口助手，应能看到程序启动后打印的模型版本信息和推理结果。

五、工程模板的复用建议

完成第一个工程后，建议把 .ioc 文件、CubeMX生成配置和CubeIDE工程设置整理成模板。后续更换模型时，只需在CubeMX中替换模型文件、重新生成代码，再在CubeIDE中编译即可。模板中应保留串口打印、时钟配置和AI中间件配置，这样每次新建工程可以节省大量重复配置时间。

一个可直接参考的工程结构如下：

AI_First_Project/
├── Core/
│   ├── Inc/
│   │   ├── main.h
│   │   ├── app_x-cube-ai.h
│   │   └── ...
│   └── Src/
│       ├── main.c
│       ├── app_x-cube-ai.c
│       └── ...
├── Drivers/
│   ├── CMSIS/
│   └── STM32F4xx_HAL_Driver/
├── Middlewares/
│   └── ST/
│       └── AI/
│           ├── Inc/
│           └── Lib/
├── AI_First_Project.ioc
└── STM32CubeIDE/
    ├── .project
    └── .cproject

其中 app_x-cube-ai.c 是AI推理的入口文件，包含模型初始化、输入数据填充、推理调用和输出解析的框架代码。第一次运行时，可以在 main.c 的 while(1) 循环前调用 MX_X_CUBE_AI_Init()，然后在循环中调用 MX_X_CUBE_AI_Process()，通过串口打印推理结果。这样就能在不改动模型的前提下，验证整条工具链是否打通。