📚 课程目录第2章开发环境搭建

2. 开发环境搭建：STM32CubeMX、X-CUBE-AI、Git与Git LFS的安装与配置

做AI模型部署到STM32这件事，说白了就是搭积木。工具链没装对，后面全是坑。我见过太多人卡在环境上，一卡就是半天。今天咱们把这四样东西一次性搞定。

2.1 工具链全景图

先看看我们要装什么，它们之间什么关系。我习惯画一张图来理清思路：

这张图我每次带新人都会画一遍。你注意看，Git和Git LFS是贯穿整个流程的，不是最后才想起来加的东西。

2.2 STM32CubeMX 安装

这是咱们的起点。没有它，后面都白搭。

2.2.1 下载与安装

下载地址：ST官网 → 工具与软件 → STM32CubeMX。别去第三方网站下，我吃过亏，版本不对还带广告。
版本选择：建议6.8.0以上。太老的版本对X-CUBE-AI支持不好。
安装步骤：一路Next就行。Java环境它会自动带，不用你操心。

我的习惯：安装路径不要有中文和空格。C:\STM32CubeMX 或者 D:\Tools\STM32CubeMX 都行。我之前在"程序文件"路径下装过一次，后面编译报错查了半天，结果是路径问题。

2.2.2 固件包管理

装完CubeMX，第一件事是下载固件包。打开软件，点Help → Manage embedded software packages。找到你用的芯片系列，比如STM32F4、STM32H7，勾上点Install。

这里有个坑：固件包很大，一个系列就几百MB。我建议只下载你需要的系列，别全选。网络不好的话，可以用离线包，ST官网有提供。

2.3 X-CUBE-AI 扩展包

这是把AI模型塞进STM32的关键工具。说白了，它就是个翻译官——把你的TensorFlow/PyTorch模型翻译成STM32能跑的C代码。

2.3.1 获取方式

方式	说明	推荐度
CubeMX内直接安装	Software Packs → Manage → X-CUBE-AI	⭐⭐⭐⭐⭐
ST官网下载	搜索X-CUBE-AI，手动下载zip包	⭐⭐⭐⭐
GitHub Releases	STMicroelectronics官方仓库	⭐⭐⭐

我个人推荐第一种。直接在CubeMX里点几下就装好了，版本也自动匹配。手动下载容易搞错版本，我踩过这个坑。

2.3.2 版本选择策略

X-CUBE-AI的版本和CubeMX版本有对应关系。别装太新的，也别装太旧的。我一般遵循这个原则：

新项目：用最新稳定版。目前是9.1.0（2024年数据）。
维护老项目：保持和项目创建时一致的版本。升级版本可能改变模型推理结果，别问我怎么知道的。
验证版本：装完先跑一个demo，确认模型转换没问题再开始干活。

注意：X-CUBE-AI 8.0.0之后不再支持STM32F1系列。如果你还在用F1，老老实实用7.x版本。我曾经帮一个客户排查问题，他拿F103配了最新版X-CUBE-AI，折腾两天才发现不支持。

2.4 Git 与 Git LFS 安装

做AI模型部署，模型文件动不动就几十上百MB。普通Git根本管不了这么大的文件，这时候Git LFS就派上用场了。

2.4.1 Git 安装

下载：git-scm.com，选对应系统版本。
安装选项：建议勾选"Git Bash Here"和"Git GUI Here"，方便右键操作。
默认编辑器：选VSCode或者Notepad++，别用Vim，除非你习惯。
换行符处理：Windows选"Checkout Windows-style, commit Unix-style"。团队协作时这个设置能省很多麻烦。

2.4.2 Git LFS 安装

Git LFS是Git的一个扩展，专门管理大文件。安装很简单：

# Windows：下载安装包，一路Next
# macOS：brew install git-lfs
# Linux：sudo apt install git-lfs

# 安装完后执行
git lfs install

# 验证是否成功
git lfs version
# 输出类似：git-lfs/3.4.0 (Git v2.42.0)

2.4.3 配置Git LFS跟踪模型文件

装完LFS，关键一步是告诉它哪些文件需要特殊管理。在项目根目录执行：

# 跟踪常见的AI模型文件
git lfs track "*.h5"
git lfs track "*.tflite"
git lfs track "*.onnx"
git lfs track "*.pb"
git lfs track "*.pth"

# 跟踪CubeMX生成的二进制文件
git lfs track "*.elf"
git lfs track "*.hex"
git lfs track "*.bin"

# 查看跟踪状态
git lfs track

# 提交.gitattributes文件
git add .gitattributes
git commit -m "配置Git LFS跟踪规则"

关键点：.gitattributes文件必须提交到仓库。团队其他人拉代码时，Git LFS会自动识别这些规则。我见过有人忘了提交这个文件，结果同事拉下来模型文件全是指针文件，根本用不了。

2.5 环境验证

装完所有工具，咱们跑一个快速验证。确保每个环节都能正常工作。

2.5.1 验证清单

验证项	命令/操作	预期结果
CubeMX	双击启动	正常打开，无报错
X-CUBE-AI	CubeMX → Software Packs → 查看已安装	显示X-CUBE-AI版本号
Git	git --version	显示Git版本
Git LFS	git lfs version	显示LFS版本
LFS跟踪	git lfs track	显示已配置的跟踪规则

2.5.2 快速测试项目

我建议你创建一个测试仓库，验证整个流程：

# 创建测试目录
mkdir stm32ai-test
cd stm32ai-test

# 初始化Git仓库
git init

# 配置LFS
git lfs track "*.h5"
git lfs track "*.tflite"

# 创建一个假的模型文件（模拟）
echo "fake model content" > model.h5

# 提交
git add .
git commit -m "测试LFS配置"

# 查看LFS管理了哪些文件
git lfs ls-files

# 输出应该显示 model.h5 被LFS管理

避坑指南：我曾经在项目中期才加入Git LFS，结果历史记录里已经有一堆大文件。清理起来非常麻烦。所以我的建议是——项目一开始就配置好LFS，哪怕你现在还没有模型文件。先配好规则，后面省心。

2.6 环境配置总结

到这步，你的开发环境就搭好了。总结一下关键点：

CubeMX + X-CUBE-AI：版本要匹配，别乱升级
Git LFS：项目初始化时就配置，别等文件大了再搞
路径：不要中文和空格，这是铁律
验证：装完就跑一遍测试，别等到用的时候才发现有问题