# 🚀 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](https://www.st.com/en/development-tools/stm32cubeclt.html) 或 [ARM GCC 工具链](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads)
- [CMake](https://cmake.org/download/) 3.22 或更高版本
- [Ninja](https://ninja-build.org/) 构建工具
- [Python](https://www.python.org/downloads/) 3.6 或更高版本（用于版本管理脚本）
- [Git](https://git-scm.com/downloads)（可选，用于版本管理）

## 📁 目录结构

```
.
├── .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. 获取项目代码

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

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

### 3. 配置项目

可以使用 STM32CubeMX 修改硬件配置：
1. 打开 `.ioc` 文件
2. 根据需要修改外设配置
3. 生成代码

### 4. 构建项目

#### 使用 CMake 预设

```bash
# 列出可用的预设
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` 部分添加自定义源文件

```cmake
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` 部分。

```cmake
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` 中定义：

```python
# 语义化版本 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 文件中，可以在程序中通过以下变量访问：

```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 为项目做出贡献。如有任何问题或建议，请在项目仓库中提出。