电控项目开发规范

总体规范

项目目标与范围说明

本项目开发规范（以下简称规范）旨在规范电控备赛期间各机构独立开发流程和代码格式，便于最后合并，同时也便于各组之间相互帮忙调试。规范适用范围为与他人协作开发的项目或者之后可能合入其他项目的项目

项目整体架构与目录结构

本规范适用的所有项目都应使用 Git 进行版本管理，如未安装可以跟随以下教程配置

Git 安装流程（教程有些内容应当修改）

完整的多人协作项目配置理论和流程参见这篇文章

STM32+Git 协作方案

以下做一些简要说明

我们的项目统一将搭载 FreeRTOS CMSISv2 进行开发，一切代码均应当写在 UserCode 下，其他位置的代码将被 git 排除，从而无效
我们并不直接使用 FreeRTOS 的 API，而是使用被进一步封装的 CMSISv2 API（因为更简洁）

此处是 CMSISv2 API 的文档

CMSIS-RTOS C API v2
UserCode 目录具有以下结构
```
UserCode/
├── bsp/                      # 板级驱动，控制板上外设 (I2C, SPI, UART, CAN, ...)
├── drivers/                  # 驱动程序，驱动硬件
├── third_party/              # 第三方（比如厂家）提供的驱动库
├── libs/                     # 库文件，提供算法、功能逻辑、通用模块，不依赖具体硬件
├── interfaces/               # 接口层，用于对不同的外设提供统一的向上接口
├── controllers/              # 控制层，用于进行控制，可以是系统级的
├── app/                      # 应用层
```
依赖关系从 bsp 到 app
- bsp：这里是对 HAL 库的直接封装，将 HAL 库封装为常用的格式（或者方便高一级调用）。
- drivers：这里是硬件设备的驱动库（电机，传感器等），包括硬件设备独特的配置（重复被使用的算法等部分不应当放在此处，否则重复的代码会增加阅读和维护难度）
- third_party：这里是厂家提供的驱动文件，与 drivers 区分是告诉开发者无需维护此部分
- libs：这里是库文件和各种算法文件（理论上这些库都应当自包含（不依赖任何非标准库））。例如 PID 算法库，卡尔曼滤波算法库，矩阵运算库等
- interfaces：这里是结合上面四层得到的一个接口层。作用是统筹实现同样（相似）功能的硬件设备，并向上暴露统一的调用接口。接口层的好处是开发者不必关心底下到底是什么设备（因为都能实现一样的功能，都有统一的函数），可以专注于实现逻辑。
- controllers：控制层，这里调用以上所有层结合得到某一控制系统的驱动，比如麦克纳姆轮底盘，全向轮底盘，舵轮底盘。
- app：应用层，也是所有封装中的最高层级，到这里才是项目最主要的逻辑，本层往下所有层级都应该可以直接被复用到其他项目，而本层应该是根据不同项目的功能开发，与项目强相关。

项目的初始化流程将被放在一个具有最高优先级的一次性任务中进行（为了避免修改 main.c）

这是一个初始化函数样例

/**
 * @brief Function implementing the initTask thread.
 * @param argument: Not used
 * @retval None
 */
/* USER CODE END Header_Init */
void Init(void* argument)
{
    /* 执行初始化 */
    
    /* 初始化完成后退出线程 */
    osThreadExit();
}

关于回调函数的问题

通常我们使用
```
void HAL_TIM_PeriodElapsedCallback(TIM_HandleTypeDef *htim);
```
这样 HAL 库默认的回调函数，在里面进行回调逻辑处理。然而这样会导致回调逻辑聚集在一块，而不是在实际使用它的代码附近，造成阅读困难（其实还有其他原因，此处不再讲述）

解决方案为：在 STM32CubeMX -> Project Manager -> Advanced Settings 右侧的 Register Callback 中打开需要回调的外设，然后在代码中自定义回调函数并注册。

比如
```
void TIM6_Callback(TIM_HandleTypeDef* htim) { /* 回调逻辑 */ }

void init()
{
		/* 逻辑 */
		
	  HAL_TIM_RegisterCallback(&htim6, HAL_TIM_PERIOD_ELAPSED_CB_ID, TIM6_Callback);
    HAL_TIM_Base_Start_IT(&htim6);
    
		/* 逻辑 */
}
```
传入的函数参数可以直接 Ctrl + 单击函数名称定位，然后继续单击函数对应的参数类型。即可获取枚举值以及其含义。

以上代码等价于
```
void HAL_TIM_PeriodElapsedCallback(TIM_HandleTypeDef *htim)
{
	if (htim == &htim6) TIM6_Callback(htim);
}

void init()
{
		/* 逻辑 */
		
    HAL_TIM_Base_Start_IT(&htim6);
    
		/* 逻辑 */
}
```
其他回调类似

仓库管理规范

综述

我们的项目仓库将放在 https://github.com/HITSZ-WTR2026 里统一管理，每个部分单独开发的时候最好也上传到 GitHub，方便其他人查看进度和参考代码。

仓库的命名暂时没有统一规范，唯一的要求是语义清晰，能体现具体实现的功能

Git 工作流规范

以下是一篇 Git 工作流的总结文章