🚀 STM32H563ZI HAL CMake 模板使用指南

📋 项目简介

这是一个基于 STM32H563ZI 微控制器的项目模板，使用 HAL 库和 CMake 构建系统。该模板提供了开发 STM32H563ZI 微控制器项目所需的基本框架，让你能够快速开始开发，而无需从零开始配置构建系统。

✨ 特性

• 支持 C/C++ 混合编程
• 集成 .clang-format .clang-tidy 配置，支持代码格式化和静态分析
• 集成 STM32 HAL 和 LL 驱动库
• 使用 CMake 作为构建系统，支持跨平台开发
• 自动生成版本信息（通过 Python 脚本）
• 集成 Gitea CI/CD 配置，支持自动化构建
• 支持 Debug 和 Release 等构建配置
• 适用于 ARM GCC 编译器
• 预配置的链接器脚本
• 配置基本的外设（时钟、串口、调试）

🔧 开发环境要求

• STM32CubeCLT 或 ARM GCC 工具链
• CMake 3.22 或更高版本
• Ninja 构建工具
• Python 3.6 或更高版本（用于版本管理脚本）
• Git（可选，用于版本管理）

📁 目录结构

.
├── .gitea/                    # Gitea CI/CD 配置
├── assert/                    # 图像等资源文件
├── cmake/                     # CMake 配置文件
│   ├── gcc-arm-none-eabi.cmake   # ARM GCC 工具链配置
│   └── stm32cubemx/           # STM32CubeMX 生成的 CMake 配置
├── Core/                      # 项目核心代码
│   ├── App/                   # 应用程序代码目录
│   │   ├── AutoGen/           # 自动生成的版本信息代码
│   │   ├── Common/            # 通用功能组件
│   │   └── Helper/            # 辅助功能类和工具
│   │   └── app.cpp            # 应用程序入口
│   ├── Inc/                   # 头文件
│   └── Src/                   # 源文件
├── Drivers/                   # STM32 HAL/LL 驱动
├── Tools/                     # 工具脚本
│   └── MCUVersionGen.py       # 版本信息生成脚本
├── .gitignore                 # Git 忽略配置
├── CMakeLists.txt             # 主 CMake 文件
├── CMakePresets.json          # CMake 预设配置
├── README.md                  # 项目说明文档
├── STM32H563ZI-HAL-CMake-Template.ioc  # STM32CubeMX 项目文件
├── STM32H563XX_FLASH.ld       # 链接器脚本
└── startup_stm32h563xx.s      # 启动文件

📝 使用方法

1. 从模板创建新项目

1. 在 Gitea 上访问此模板仓库
2. 点击仓库页面上的 "使用模板创建" 按钮
3. 输入您的新项目名称、描述等信息
4. 点击 "创建仓库" 完成

2. 获取项目代码

# 克隆您刚创建的仓库
git clone <新仓库URL> --recursive
cd <您的项目名称>

# 如果已经克隆但没有加载子模块，可以运行：
git submodule update --init --recursive

3. 配置项目

可以使用 STM32CubeMX 修改硬件配置：

1. 打开 .ioc 文件
2. 根据需要修改外设配置
3. 生成代码

4. 构建项目

使用 CMake 预设

# 列出可用的预设
cmake --list-presets

# 使用预设配置项目（例如 Debug 预设）
cmake --preset=debug

# 构建项目
cmake --build --preset=debug

5. 烧录程序

编译完成后，在 build/Debug 目录下会生成 .elf、.hex 和 .bin 文件。使用 ST-Link 或其他烧录工具通过 OpenOcd，STM32CubeProgrammer 等软件将程序烧录到 STM32H563ZI 芯片上。

💻 添加自定义代码

在 Core/Src 和 Core/Inc 目录下添加

1. 自定义源文件：在 Core/Src 目录下添加 .c 文件
2. 自定义头文件：在 Core/Inc 目录下添加 .h 文件
3. 更新 CMakeLists.txt：在主 CMakeLists.txt 文件中的 target_sources 部分添加自定义源文件

target_sources(${CMAKE_PROJECT_NAME} PRIVATE
    # Add user sources here
    Core/Src/your_custom_file.c
)

在 Core/App 目录下添加

在 Core/App 目录及其子目录下添加的 .c、.cpp、.h 和 .hpp 文件会被自动包含在构建中，无需手动修改 CMakeLists.txt 文件。

在其他目录下添加

在其他目录下添加的源文件需要手动更新 CMakeLists.txt 文件，将其添加到 target_sources 部分。

target_sources(${CMAKE_PROJECT_NAME} PRIVATE
    # Add user sources here
    path/to/your_custom_file.c
)

target_include_directories(${CMAKE_PROJECT_NAME} PRIVATE
    # Add user include directories here
    path/to/your_custom_include
)

📊 版本管理

项目使用 MCUVersionGen.py 脚本自动生成版本信息。版本号在该 version.txt 中定义：

# 语义化版本 https://semver.org/lang/zh-CN/spec/v2.0.0.html
major_version = 0  # 主版本号
minor_version = 1  # 次版本号
revision_version = 0  # 修订版本号
pre_release_version = ""  # 预发行版本号

生成的版本信息会写入 autogen_version.c 文件中，可以在程序中通过以下变量访问：

extern const char *g_name;       // 项目名称
extern const char *g_version;    // 版本号
extern const char *g_buildTime;  // 构建时间

❓ 常见问题与解决方案

1. 编译错误：确保已正确安装 ARM GCC 工具链并已添加到 PATH 环境变量中
2. 找不到 .elf 文件：检查编译输出，确保没有编译错误
3. 烧录失败：检查连接，确保 ST-Link 正确连接到 STM32H563ZI
4. 版本脚本错误：确保已安装 Python 3.6 以上版本
5. 内存配置问题：STM32H5系列有多个内存区域，确保正确配置了内存映射

🤝 贡献与支持

欢迎通过 Issue 和 Pull Request 为项目做出贡献。如有任何问题或建议，请在项目仓库中提出。