# Embedded_Project

**Repository Path**: forestfloat/embedded_-project

## Basic Information

- **Project Name**: Embedded_Project
- **Description**: 用来新建项目的一个大致框架，方便分层管理
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-26
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Embedded Project Template (嵌入式项目模板)

[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)

## 项目简介

本项目是一个**工业级嵌入式项目开发模板**，支持 **STM32(Keil) + ESP32(ESP-IDF) 双平台**，遵循 ARM CMSIS / ST / NXP / AUTOSAR 等行业规范设计。提供开箱即用的分层架构代码框架、标准化目录结构和完整的项目文档体系。

## 特性

- 🏗️ **工业级分层架构** - APP → MW → BSP → HAL → HW 五层解耦设计
- 📁 **标准化目录结构** - 00-09 编号系统，覆盖项目管理到归档全流程
- 🔧 **完整代码模板** - 包含 GPIO、UART、SPI、I2C、ADC、CAN、TIM 等常用外设驱动
- 📋 **丰富文档体系** - 项目规范、实施计划、API文档、测试用例一应俱全
- ⚙️ **双平台支持** - STM32 (Keil MDK) + ESP32 (ESP-IDF) 双平台开发
- ✅ **Git 就绪** - 配置完善的 .gitignore 和版本控制规范

## 技术栈

### STM32 平台 (Keil MDK-ARM)

| 类别       | 技术                          |
| ---------- | ----------------------------- |
| MCU        | STM32F103C8T6 (Cortex-M3)     |
| RTOS       | FreeRTOS                      |
| IDE        | Keil MDK-ARM                  |
| 编译器     | ARM Compiler 5/6 (C99标准)    |
| 调试器     | ST-Link / J-Link              |

### ESP32 平台 (ESP-IDF)

| 类别       | 技术                          |
| ---------- | ----------------------------- |
| MCU        | ESP32 / ESP32-S3 (Xtensa LX7/RISC-V) |
| RTOS       | FreeRTOS (ESP-IDF 内置)       |
| IDE        | VS Code + ESP-IDF Extension   |
| 编译器     | Xtensa ESP32 GCC (C/C++11)    |
| 烧录工具   | esptool.py / ESP Flash Tool  |

### 通用

| 类别       | 技术                          |
| ---------- | ----------------------------- |
| 版本控制   | Git                           |
| 构建系统   | CMake / Makefile              |
| 协议栈     | UART, SPI, I2C, CAN, WiFi, BT |

## 目录结构

```
embedded_-project/
├── 源代码/template/          # 核心源代码模板（分层架构）
│   ├── APP/                  # 应用层 (Task/UI/Ctrl/Main/StateMachine)
│   ├── MW/                   # 中间件层 (协议/算法/OS适配)
│   ├── BSP/                  # 板级支持包 (Board/Led/Key/Lcd/Sensor)
│   ├── HAL/                  # 硬件抽象层 (GPIO/UART/SPI/I2C/ADC/CAN/TIM)
│   ├── HW/                   # 底层硬件寄存器层
│   ├── CFG/                  # 全局配置层
│   ├── LIB/                  # 第三方开源库
│   └── Doc/                  # 项目文档
├── 项目结构示例/             # 完整项目结构示例与规范
│   ├── ai_test/              # STM32/ESP32 项目示例（00-09 标准化目录）
│   │   ├── 00_项目管理/      # README / 会议纪要 / 周报 / 项目规范 / 变更日志 / TODO
│   │   ├── 01_硬件设计/      # 原理图 / PCB / BOM表 / 引脚定义
│   │   ├── 02_软件源码/      # stm32 / esp32 
│   │   ├── 03_结构设计/      # 3D模型 / 机械图纸 / 装配说明
│   │   ├── 04_测试验证/      # 单元测试 / 集成测试 / 测试数据
│   │   ├── 05_生产资料/      # 生产固件 / 烧录指导 / 质量控制
│   │   ├── 06_开发工具/      # Keil包 / 构建脚本 / .gitignore
│   │   ├── 07_参考资料/      # 芯片手册 / 外设手册 / 协议文档
│   │   ├── 08_交付文档/      # 用户手册 / 开发手册 / API文档
│   │   └── 09_归档/          # 版本归档 / 会议记录 / 项目总结
│   ├── PROJECT_SPEC.md       # 项目规范文档
│   └── IMPLEMENTATION_PLAN.md # 实施计划
├── skills/                   # 开发技能脚本与工作流（含双平台脚手架）
└── LICENSE                   # AGPL-3.0 许可证
```

## 分层架构说明

| 层级 | 全称                    | 职责                       | 换MCU影响 | 换板影响 |
| ---- | ----------------------- | -------------------------- | --------- | -------- |
| APP  | Application             | 业务逻辑、任务调度           | 无影响    | 无影响   |
| MW   | Middleware              | 协议、算法、OS适配          | 无影响    | 无影响   |
| BSP  | Board Support Package   | 板级硬件适配               | 小修改    | 完全重写 |
| HAL  | Hardware Abstraction    | 外设驱动封装               | 重写      | 无影响   |
| HW   | Hardware                | 寄存器、启动文件            | 完全重写  | 无影响   |

### 调用规则

```
APP → BSP / MW / CFG
MW  → CFG (禁止直接调用 HAL/HW)
BSP → HAL / CFG
HAL → HW
```

**核心原则**: 上层可调用下层，下层绝不调用上层

## 快速开始

### 环境要求

**STM32 平台:**
- [Keil MDK-ARM](https://www.keil.com/download/) v5.x 或更高版本
- [STM32CubeMX](https://www.st.com/en/development-tools/stm32cubemx.html) (可选)

**ESP32 平台:**
- [ESP-IDF](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/) v5.x
- VS Code + ESP-IDF 扩展 (推荐)

**通用:**
- [Git](https://git-scm.com/) for version control
- Python 3.x (用于项目脚手架脚本)

### 使用步骤

1. **克隆本项目**
   ```bash
   git clone <repository-url>
   cd embedded_-project/源代码/template
   ```

2. **选择平台并配置**

   **STM32 平台:**
   - 编辑 `CFG/SysConfig.h` - 系统时钟和全局参数
   - 编辑 `CFG/PinConfig.h` - 引脚映射配置

   **ESP32 平台:**
   - 使用 `idf.py menuconfig` 配置项目
   - 设置目标芯片: `idf.py settarget esp32`

3. **实现板级初始化**
   - 在 `BSP/Board/` 中实现 `board_init()` 函数

4. **编写应用逻辑**
   - 主程序入口：`APP/Main/main.c`
   - 任务逻辑：`APP/task/` 或 `APP/StateMachine/`

5. **编译与烧录**

   **STM32 (Keil):**
   ```bash
   # Keil IDE 打开 .uvprojx 工程文件编译 (F7)
   UV4 -b project.uvprojx -t "Target"
   ```

   **ESP32 (ESP-IDF):**
   ```bash
   idf.py build          # 编译
   idf.py -p COM3 flash  # 烧录 (根据实际端口调整)
   idf.py -p COM3 monitor # 监控串口输出
   ```

6. **使用脚手架快速创建项目 (可选)**
   ```bash
   # 创建 STM32 项目
   python skills/embedded-project-scaffold/scripts/scaffold.py --name my_stm32_project --platforms stm32

   # 创建 ESP32 项目
   python skills/embedded-project-scaffold/scripts/scaffold.py --name my_esp32_project --platforms esp32

   # 创建双平台项目 (默认)
   python skills/embedded-project-scaffold/scripts/scaffold.py --name my_project --platforms stm32,esp32
   ```

## 代码风格

### 命名约定

```c
// 文件命名
drv_<module>.c/.h        // 驱动层: drv_uart.c
app_<module>.c/.h        // 应用层: app_main.c
middleware_<name>.c/.h   // 中间件: middleware_freertos.c

// 变量命名
uint32_t temp_value;           // 局部变量: 小写下划线
uint32_t g_system_tick;        // 全局变量: g_ 前缀
static uint32_t s_counter;     // 静态变量: s_ 前缀

// 函数命名: 层_模块_功能()
HAL_StatusTypeDef HAL_UART_Init();
uint8_t BSP_Led_On();
void APP_Task_Start();

// 宏定义: 全大写
#define LED_PIN         GPIO_PIN_13
#define UART_BAUDRATE   115200
```

### 注释规范

```c
/**
 * @brief  初始化UART外设
 * @param  baudrate: 波特率
 * @retval HAL_StatusTypeDef状态
 */
HAL_StatusTypeDef drv_uart_init(uint32_t baudrate);
```

## 项目结构示例

`项目结构示例/ai_test/` 展示了一个完整的嵌入式项目目录结构：

```
00_项目管理/    01_硬件设计/    02_软件源码/    03_结构设计/
04_测试验证/    05_生产资料/    06_开发工具/    07_参考资料/
08_交付文档/    09_归档/
```

详细说明请参考 [PROJECT_SPEC.md](项目结构示例/PROJECT_SPEC.md)

## 构建系统

项目支持多种构建方式：

### Keil MDK (STM32)
通过 Keil IDE 打开 `.uvprojx` 工程文件编译

### ESP-IDF (ESP32)
```bash
idf.py build              # 编译项目
idf.py -p /dev/ttyUSB0 flash  # 烧录固件
idf.py monitor            # 查看串口日志
```

### CMake (通用)
```bash
mkdir build && cd build
cmake ..
make -j4
```

### Makefile
```bash
make clean && make all
```

## 测试策略

- **单元测试**: Unity 测试框架（嵌入式专用）
- **集成测试**: 硬件在环 (HIL) 测试
- **覆盖率目标**: 驱动层 100% / 中间层 90% / 应用层 80%

## 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 开发规范

### 必须遵守 (Always Do)
- ✅ 代码提交前必须编译通过
- ✅ 遵循命名约定和代码风格
- ✅ 添加必要的注释和文档
- ✅ 使用 Git 进行版本控制

### 禁止操作 (Never Do)
- ❌ 提交编译产物 (.hex, .bin, .o)
- ❌ 硬编码敏感信息（密钥、密码）
- ❌ 删除或禁用现有测试用例

## License

本项目采用 [GNU AGPL-3.0](LICENSE) 许可证开源。

## 参考资料

### STM32 平台
- [ARM CMSIS 规范](https://arm-software.github.io/CMSIS_5/General/html/index.html)
- [ST HAL 库文档](https://www.st.com/en/embedded-software/stm32cube-mcu-mpu-packages.html)
- [FreeRTOS 官方文档](https://www.freertos.org/Documentation/RTOS.html)
- [STM32F103 参考手册](https://www.st.com/resource/en/reference_manual/rm0008-stm32f101xx-stm32f102xx-stm32f103xx-stm32f105xx-stm32f107xx-armbased-mcus-stmicroelectronics.pdf)

### ESP32 平台
- [ESP-IDF 官方文档](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/)
- [ESP32 技术规格书](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_cn.pdf)
- [ESP-IDF 编程指南](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/)

---

**维护者**: Embedded Development Team  
**最后更新**: 2026-07-02