学习笔记：ESP32
笔记内容：04.工程架构、组件
日期：2026年3月22日
参考视频：视频1
视频2，从25:00开始讲工程架构

---

一、工程架构

esp-project/		【整个 ESP32 项目根目录】
├─.devcontainer/		【容器开发环境（远程/云开发用）】
│  ├─ devcontainer.json
│  └─ Dockerfile
├─ .vscode/		【VS Code 编辑器配置】
│  ├─ c_cpp_properties.json	# 告诉 VS Code：头文件在哪、用什么编译器、用 C++ 哪个标准
│  ├─  launch.json		# 调试配置（F5 调试用）,告诉调试器如何连接 ESP32、如何下载程序
│  └─  settings.json		# VS Code 工作区设置：ESP-IDF 插件路径、自动保存、格式化等
├─build/			【编译生成的文件目录（自动生成，不用管）】
│
├─ components/		【自己写的驱动、组件代码】
│  ├─ bsp			【板级支持包：LED、按键等硬件驱动】
│  │  ├─ key/		【按键驱动】
│  │  │  ├─ key.c
│  │  │  └─ key.h
│  │  ├─ led/		【LED驱动】
│  │  │  ├─ led.c
│  │  │  └─ led.h
│  │  ├─ beep/	【beep驱动】
│  │  │  ├─ beep.c
│  │  │  └─ beep.h
│  │  └─ CMakeLists.txt
│  └─ Middlewares		【中间件（协议、工具库）】
├─ main/			【程序入口，主函数在这里】
│  ├─ main.c
│  └─ CMakeLists.txt
├─ .clangd		【代码提示/语法检查配置】
├─ .gitignore		【Git 忽略文件】
├─ CMakeLists.txt		【项目编译规则】
├─ README.md		【项目说明文档】
├─ sdkconfig		【ESP32 系统配置】例如：CPU 频率、内存、外设开关
└─ sdkconfig.old		【配置备份】

---

二、CMakeLists.txt

1、项目根目录下的 CMakeLists.txt

esp-project/CMakeLists.txt

# 项目根目录的 CMake

# 有关构建系统的更多信息，请参阅
# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html
# 以下五行样板代码必须包含在您的项目中
# 必须严格按照此顺序编写 CMakeLists，以确保 cmake 正常工作

# 1. 指定 CMake 最低版本（ESP-IDF 要求，需与 SDK 匹配，v5.x 推荐 3.24 及以上）
cmake_minimum_required(VERSION 3.5)

#参照正点原子
#添加额外的组件目录
#set(EXTRA_COMPONENT_DIRS 
#    ${CMAKE_SOURCE_DIR}/components/Middlewares
#)

#参照正点原子
#关于编译器的设置：当发现警告或者错误时，带上颜色显示，更明显的看见
add_compile_options(-fdiagnostics-color=always)

# 4. 引入 ESP-IDF 的构建脚本（核心指令，必须有）
#    该指令会加载 ESP-IDF 的所有编译规则和组件
include($ENV{IDF_PATH}/tools/cmake/project.cmake)

# 2. 设置项目名称和使用的编程语言（必须是 C/CXX，ESP-IDF 核心是 C）
#    PROJECT_NAME 是自定义的项目名，比如 "esp_hello_world"
project(03_beep)

2、文件夹 Main 下的 CMakeLists.txt

esp-project/main/CMakeLists.txt

# main 的 CMakeList.txt

idf_component_register(SRCS "main.c"
                    INCLUDE_DIRS "."
                    REQUIRES bsp  # 新增这一行！让 main 依赖 bsp 组件
                    )

3、 /components/bsp/CMakeLists.txt

esp-project/components/bsp/CMakeLists.txt

# bsp 文件夹中的 CMakeList.txt

#源文件目录
set(src_dirs
    key	# 第1个目录
    led	# 第2个目录
    beep # 第3个目录
)

#头文件路径
set(include_dirs
    key	# 注释
    led 	# 注释
    beep 	# 注释
)

#依赖的组件（ESP-IDF 内置组件/自定义组件）
set(requires
	driver          # 外设驱动（基础依赖）
)

# 最终在组件注册时使用（核心）
idf_component_register(
    SRC_DIRS       ${src_dirs}      # 展开所有源文件目录
    INCLUDE_DIRS   ${include_dirs}  # 展开所有头文件目录
    REQUIRES       ${requires}      # 展开所有依赖组件
)

# 为当前组件添加编译选项
component_compile_options (

    # 快速数学运算：牺牲少量浮点精度，提升浮点运算速度（适合传感器/信号处理）
    -ffast-math

    # 最高级别优化（O3）：开启所有性能优化，编译慢但运行最快（Release模式用）
    -O3 

    # 格式化字符串错误降级：将格式不匹配从"编译错误"改为"警告"，不终止编译
    #-Wno-error=format

    # 禁用格式化字符串警告：完全屏蔽所有格式相关警告（临时使用，建议最终修复代码）
    #-Wno-format
)

---

三、.vscode 文件夹

如果两台电脑ESP-IDF安装路径不一样，那么.vscode文件夹中内容要进行修改，否则无法编译。

1、c_cpp_properties.json

{
  "configurations": [
    {
      "name": "ESP-IDF",
      "compilerPath": "${config:idf.toolsPathWin}\\tools\\xtensa-esp-elf\\esp-14.2.0_20241119\\xtensa-esp-elf\\bin\\xtensa-esp32-elf-gcc.exe",
      "includePath": [
        "${config:idf.espIdfPath}/components/**",
        "${config:idf.espIdfPathWin}/components/**",
        "${workspaceFolder}/**"
      ],
      "browse": {
        "path": [
          "${config:idf.espIdfPath}/components",
          "${config:idf.espIdfPathWin}/components",
          "${workspaceFolder}"
        ],
        "limitSymbolsToIncludedHeaders": true
      }
    }
  ],
  "version": 4
}

2、launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "gdbtarget",
      "request": "attach",
      "name": "Eclipse CDT GDB Adapter"
    },
    {
      "type": "espidf",
      "name": "Launch",
      "request": "launch"
    }
  ]
}

3、settings.json

{
  "C_Cpp.intelliSenseEngine": "default",
  "idf.useSystemEnvPath": true,
  "idf.openOcdConfigs": [
    "board/esp32s3-builtin.cfg"
  ],
  "idf.portWin": "COM4",
  "idf.customExtraVars": {
    "IDF_TARGET": "esp32s3"
  },
  "idf.flashType": "JTAG"
}

---

四、ESP-IDF 的核心组件分层（从底层到应用）

层级	核心组件 / 功能	作用
硬件抽象层（HAL）	hal/ 目录（如 esp32/hal/gpio_hal.h）	直接操作硬件寄存器，与芯片型号强绑定，为上层提供统一硬件接口
驱动层（Driver）	driver/ 目录（如 gpio.h、uart.h）	基于 HAL 封装，提供外设（GPIO/UART/SPI/I2C）的通用操作 API
系统层（System）	freertos/、esp_system/、esp_event/	核心：FreeRTOS 实时操作系统，提供任务管理、内存管理、事件驱动等基础能力
中间件层（Middleware）	wifi/、bt/、mqtt/、http/、nvs_flash/	物联网核心能力：WiFi/Bluetooth 协议栈、MQTT/HTTP 通信、非易失存储等
应用层（Application）	自定义代码（main/ 或 components/）	业务逻辑开发，调用上层 API 实现功能
–	–	–

---