5.0 KiB
5.0 KiB
📘 嵌入式项目开发规范（STM32 + 分层架构）
Embedded Project Development Guide
1. 设计目标
本项目遵循以下核心原则：
- 分层设计（Layered Architecture）
- 解耦（Decoupling）
- 可移植性（Portability）
- 可维护性（Maintainability）
2. 工程目录规范
project/
├── app/ # 应用层（业务逻辑）
├── modules/ # 功能模块（设备 / 算法）
├── interfaces/ # 硬件抽象接口（关键）
├── bsp/ # 板级支持包（硬件实现）
├── 3rdparty/ # 第三方库（不修改源码）
├── os/ # 操作系统（FreeRTOS等）
├── utils/ # 通用工具
├── Core/ # STM32CubeMX生成（禁止污染）
├── Drivers/ # HAL/CMSIS（厂商提供）
3. 分层说明（必须遵守）
3.1 层级关系（单向依赖）
app
↓
modules
↓
interfaces
↓
bsp
↓
HAL / Hardware
❗ 严禁反向依赖：
- modules ❌ 依赖 HAL
- app ❌ 直接调用 bsp
- modules ❌ include Core 代码
4. 各层职责
4.1 app（应用层）
- 负责系统流程控制
- 状态机 / 控制逻辑
- 不允许访问硬件细节
void app_loop(void) {
imu_read(...);
pid_update(...);
motor_set_speed(...);
}
4.2 modules（模块层）
分类：
modules/
├── device/ # 电机等执行器
├── sensor/ # IMU/传感器
├── control/ # PID / Kalman
├── protocol/ # 通信协议
规则：
- 只依赖 interfaces
- 不允许使用 HAL
// ❌ 禁止
#include "i2c.h"
// ✅ 正确
#include "i2c_if.h"
4.3 interfaces（接口层）
定义硬件抽象接口：
typedef struct {
int (*read)(uint8_t addr, uint8_t reg, uint8_t *buf, int len);
} i2c_if_t;
作用：
- 解耦 modules 和 bsp
- 支持多平台替换
4.4 bsp（板级支持包）
结构：
bsp/stm32f4/
├── i2c/
├── can/
├── spi/
├── gpio/
└── board.c
职责：
- 封装 HAL
- 提供接口实现
int stm32_i2c_read(...) {
return HAL_I2C_Mem_Read(...);
}
4.5 3rdparty（第三方库）
放置：
- cJSON
- lwIP
- FreeRTOS（如果不是Cube管理）
❗规则：
- 不修改源码
- 不直接暴露给 app
❗ 示例（推荐封装）
modules/json/
json_wrapper.c
4.6 utils（工具层）
- ringbuffer
- flash
- log
- 数学工具
特点：
- 无业务依赖
- 可复用
5. Core（CubeMX生成代码）规范
✅ 允许：
- 初始化
- 外设配置
MX_I2C1_Init();
MX_CAN1_Init();
❌ 禁止：
- 写业务逻辑
- 写控制算法
- 写模块代码
推荐 main.c 结构：
int main(void)
{
HAL_Init();
SystemClock_Config();
MX_GPIO_Init();
MX_I2C1_Init();
MX_CAN1_Init();
bsp_init();
app_init();
while (1)
{
app_loop();
}
}
6. 第三方库使用规范
分类原则：
| 类型 | 放置位置 |
|---|---|
| 不修改 | 3rdparty |
| 需要修改 | modules |
示例：
3rdparty/
cjson/
modules/control/
pid.c
7. 编码规范
7.1 命名
| 类型 | 规范 |
|---|---|
| 文件 | 小写 + 下划线 |
| 结构体 | xxx_t |
| 函数 | 模块名_功能 |
示例：
motor_set_speed()
imu_read_accel()
pid_update()
7.2 模块结构
每个模块：
xxx.c
xxx.h
7.3 禁止全局变量污染
// ❌
extern int state;
// ✅
通过结构体传递
8. 解耦设计规范（核心）
必须满足：
- 模块不依赖具体硬件
- 硬件可替换
- 支持模拟测试
示例：
motor->can->send(...)
imu->i2c->read(...)
9. RTOS 使用规范（如使用）
推荐结构：
imu_task
control_task
motor_task
通信方式：
- Queue
- Event
10. 常见错误（必须避免）
❌ 直接调用 HAL
HAL_I2C_Mem_Read(...)
❌ 模块 include Core
#include "i2c.h"
❌ ISR 写业务逻辑
void IRQ() {
pid_update(); // ❌
}
11. 开发流程建议
阶段：
- 外设跑通（HAL）
- 模块拆分
- 接口抽象
- BSP封装
- RTOS化（可选）
12. 目标
最终实现：
- 硬件可替换
- 模块可复用
- 架构清晰
- 易于扩展
13. 一句话总结
接口解耦 + BSP隔离 + 分层设计 = 工程级嵌入式架构
---
# 最后说一句（很关键）
你现在做这件事（写规范）说明你已经在从：
👉 “会写代码” → “会做工程”
转变了。
---
如果你愿意，我可以下一步帮你：
✅ :contentReference[oaicite:0]{index=0}
或者
✅ :contentReference[oaicite:1]{index=1}
这会让你的工程直接变成“公司级别”的质量。