STM32C5 生态工具工程落地、团队协作、离线内网实施方案

1. 新项目完整开发流程（基于 STM32C5 生态）

1. 资源获取阶段
   • 方案 A 原型快速验证：Example Library 网页下载对应外设例程，快速验证硬件外设；
   • 方案 B 完整项目：Package Creator，勾选项目实际用到驱动 / 中间件，导出 STM32Cube MCU 软件包；
2. 硬件配置：打开 STM32CubeMX2，新建 ioc2 工程；选择 C5 芯片，配置时钟、引脚、外设、中间件；
3. 工程生成：输出 CMake 工程（STM32Cube‑VSCode）或者 EWARM 工程；
4. 业务开发：基于例程做二次开发，业务代码与 ST 生成代码分离；
5. 版本管理：Cube 软件包、Pack 包版本归档纳入版本库；
6. 编译调试：STM32Cube‑VSCode / EWARM 开发调试；
7. CI 流水线：复用 CMake 工程，使用裁剪后的 CubeC5 包做自动化编译构建。

资料获取：资料下载 | STM32C5 × STM32Cube开发实战培训资料汇总

2. 企业内网完全离线开发实施方案

适用场景：研发网络禁止访问外网，安全保密内网。

1. 外网准备工作（可上网电脑） 1）登录 myST 账号进入 Package Creator，选择 STM32C5； 2）勾选全部项目需要的驱动、中间件组件；输出两种格式包：
   • MCU package：用于例程、源码开发；
   • STM32CubeMX2 package format：Pack 包集合，给 MX2 离线导入； 3）Example Library 下载需要用到的例程；
2. 介质拷贝：把以上全部软件包、MX2 安装程序拷贝至内网开发机器；
3. 内网部署 MX2：完成 STM32CubeMX2 安装；打开 Pack Manager，执行From Local...批量导入所有 pack 包；
4. 开发：内网环境下完成 ioc2 工程配置、代码生成；使用拷贝进来的 Cube 包、例程源码进行开发；

限制：Example Library、Package Creator 网页工具本身无法在内网访问，例程、软件包必须在外网提前全部导出。

3. 存量项目迁移方案：HAL1 平台迁移至 STM32C5‑HAL2

STM32C5 不支持 HAL1，迁移分两步走：

1. 硬件层面：完成原理图适配 STM32C5 芯片；
2. 软件迁移：
   • 查阅官方《HAL1 to HAL2 Migration Guide》文档，梳理 API 变更；
   • 不要直接复制老 HAL1 驱动文件，全部使用 STM32CubeC5 HAL2 驱动；
   • 优先查找 Example Library 中对应外设的 HAL2 例程，参考新 API 用法；
   • 中间件（FreeRTOS /lwip）也需要使用 CubeC5 包内置 HAL2 适配版本；
   • 先跑通官方例程，再逐步移植业务逻辑，不建议直接整体大段移植旧业务代码。

风险提示：老项目如果大量直接操作 HAL1 内部结构体，迁移工作量会显著增大。

4. 团队多人协作资源版本管控方案

1. 软件包版本统一：整个团队使用同一个版本 STM32CubeC5 软件包、同一套 Pack 包；禁止成员各自随意下载不同版本；
2. 版本库管理策略：
   • 策略 1（推荐）：把裁剪后的 CubeC5 软件包放入版本库，工程相对路径引用驱动，保证所有人源码一致；
   • 策略 2：搭建团队内部文件服务器，存放固定版本软件包，所有人统一从服务器获取；
3. ioc2 工程文件纳入 git 版本管理，跟踪芯片配置变更；
4. 不建议团队成员在线实时更新 Pack，版本变更统一评审后再升级。

5. 例程的使用、提取、改造最佳实践

1. 原型优先：优先 Example Library 下载独立例程，比解压完整大 Cube 包效率高；
2. 从 Cube 包提取例程：必须另存为新路径，原始包内 ioc2 为只读，直接生成代码会报错；
3. 二次开发原则：区分 ST 自动生成代码与用户业务代码，业务代码放到独立文件夹，避免重新生成配置被覆盖；
4. 参考例程不要直接拷贝全部工程，按需抽取外设初始化与业务逻辑。

6. STM32CubeMX2 部署、故障排查方案

Windows 平台

• 禁止使用【以管理员身份运行】安装，MX2 不支持管理员权限安装；
• 安装路径不要使用中文、特殊字符；
• 安装报错：检查磁盘空间、杀毒软件拦截；快捷方式失效，使用根目录 stm32cubemx2.exe 启动。

Linux Ubuntu22.04

必须提前安装依赖库：webkit2gtk‑4.1‑0，否则程序无法启动；卸载不能双击卸载脚本，终端执行卸载脚本。

常见故障处理

7. 量产项目风险规避清单

1. STM32C5 必须使用 HAL2，严禁混用 HAL1 驱动代码；
2. 只读 ioc2 文件一定要另存，不要直接生成工程；
3. 离线环境所有软件包、Pack 包必须外网预先导出，网页工具无法内网访问；
4. MX2 不能生成 Keil MDK 工程，选型提前确认 IDE 工具链；
5. EWARM 只支持 9.20 版本，高 / 低版本会出现兼容性问题；
6. 团队统一 CubeC5 软件包与 Pack 版本，避免版本漂移；
7. 量产项目关注 SBOM 清单，做好开源组件许可证合规审查。