ESP-IDF教程1 开发环境

OSnotes2025-04-17 14:57

1、开发环境

对于 ESP32 系列芯片的开发环境主要有如下几种方式：

  1. ESP-IDF（Espressif IoT Development Framework）
  2. Arduino
  3. PlatformIO

ESP-IDF 是 Espressif 官方推出的开发框架，本系列教程将围绕 ESP-IDF 开发环境进行，其实际开发方式主要有如下几种：

  1. CMD
  2. IDE
    1. VS Code + ESP-IDF 插件
    2. Espressif IDE

CMD 的方式无图形化界面，通过 ESP-IDF 提供的 python 脚本进行编译、烧录等操作，比如：

  1. 使用 idf.py build 命令编译工程
  2. 使用 idf.py -p COM8 flash monitor 命令通过指定的 COM8 串口向芯片 FLASH 中烧录程序

CMD 的方式对新手不太友好，因此本系列教程主要使用 IDE 的方式进行开发。

1.1、VS Code + ESP-IDF 插件

  1. 下载 VS Code，VS Code 安装较为简单，一路下一步直到安装即可。
  2. 给 VS Code 配置 ESP-IDF 扩展

打开 VS Code -> 单击左侧扩展（Ctrl+Shift+X） -> 搜索 "ESP-IDF" -> 单击 "安装"

-> 打开安装好的 ESP-IDF 扩展 -> 在左侧列表 "Advanced" 中单击第一个配置 ESP-IDF 扩展 -> 选择 "EXPRESS" 安装模式

-> 选择下载服务器 -> ESP-IDF 版本 -> ESP-IDF 库路径 -> ESP-IDF 工具路径 -> 安装

-> 等待安装完成（漫长等待.............）

-> 最后安装一个中文扩展 -> 重启 VS Code -> 配置完成。

1.2、Espressif-IDE

下载 Espressif-IDE，下载第一个 Windows 平台下的通用在线安装助手

-> 下一步 -> 下一步 -> 下一步

-> 选择要安装的 ESP-IDF 版本，目前最新为 v5.4.1 -> 选择 ESP-IDF 安装路径

-> 选择 ESP-IDF Tools 安装路径

-> 勾选 Espressif-IDE -> 下一步 -> 安装

-> 中间弹出的驱动下载框点击确定即可 -> 完成

双击桌面上的 Espressif-IDE 打开软件，选择一个工作空间打开软件，至此安装成功

2、新建项目

2.1、VS Code + ESP-IDF 插件

VS Code 查看 -> 命令面板（Ctrl+Shift+P） -> ESP-IDF: 新建项目

-> 使用 ESP-IDF

-> 设置新项目的名称、路径、正确的板卡和 COM 口 -> 单击右下角 "选择模板" 按钮

-> 选择 "template-app" 模板 -> 创建工程 -> 单击创建成功消息框的 "Yes" 按钮或者自行打开设置的工程路径下的项目

在页面最下方的工具栏上选择要使用的端口，设置正确的乐鑫设备目标。

然后单击 "构建按钮" 编译整个项目，如果编译成功将出现内存类型使用汇总表，至此环境搭建完成。

2.2、Espressif-IDE

关闭欢迎页面 -> 创建一个新的乐鑫 IDF 项目 -> 使用其中一个模板创建项目 -> 选择 "hello_world" 项目 -> Finish

-> 单击上方工具栏设备旁边的 ⚙ 修改为合适的 ESP 目标（IDF 目标、开发板和串口号）-> Finish

-> 单击上方工具栏中的 🔨 编译整个项目，笔者出现如下 CMake 错误：

复制代码 
CMake Error at D:/soft/Espressif-IDE-ESP-IDF/tools/cmake/gdbinit.cmake:40 (file):
	file FILE([TO_CMAKE_PATH|TO_NATIVE_PATH] path result) must be called with
	exactly three arguments.

搜索发现 GitHub 上有人提交类似 Issues ，找到最后解决方法如下：

注释掉 D:/soft/Espressif-IDE-ESP-IDF/tools/cmake/gdbinit.cmake 文件中第 33、34 和 40 行

-> 再次构建整个项目 -> 将程序烧录至目标设备

如果构建成功将出现内存类型使用汇总表，烧录成功后将自动打开串口终端，至此环境搭建完成。


3、项目结构

以 VS Code 中搭建的 template-app 项目举例说明， template-app 项目是一个空的模板工程，主要包含以下文件：

  1. 1_empty
    1. .devcontainer : 容器，常与远程开发相关，可删除
    2. .vscode : VS Code 编辑器配置文件
    3. build : 构建项目后才会出现的目录，存放中间文件和最终产物，可删除
    4. main
      1. CMakeLists.txt : CMake 配置文件，告诉 CMake 构建系统如何编译和链接项目
      2. main.c : 项目的主要源代码文件
    5. .gitignore : 该文件用于指定 Git 在版本控制中忽略的文件或文件夹，可删除
    6. CMakeLists.txt : 顶层 CMake
    7. README.md : 项目说明文件，可以修改为自己的项目说明，可删除
    8. sdkconfig : SDK 配置文件
    9. sdkconfig.old : SDK 旧配置文件，方便回退上一个配置，可删除

开发者在开发简单项目时可以直接在 "main.c" 中编程，但后续增加项目难度时不可避免地需要使用某些驱动库，因此可以在项目中增加 "components" 文件夹专门用于放置第三方的驱动组件

由于 ESP-IDF 依靠 CMake 管理编译和链接项目，因此还需要对增加的驱动组件添加底层 CMake 文件，使其能编译进整个项目中，删除不必要的文件，最终空的模板项目文件目录如下：

  1. 1_empty
    1. .vscode
    2. components
      1. xxx
        1. xxx.c
        2. xxx.h
        3. CMakeLists.txt
      2. ......
    3. main
      1. CMakeLists.txt
      2. main.c
    4. CMakeLists.txt
    5. sdkconfig

"components" 文件夹中的各个组件的底层 CMake 文件内容应该如下所示：

CMake 复制代码 
idf_component_register(SRCS "xxx.c"
                    INCLUDE_DIRS "."
                    # 如果组件需要 ESP 驱动库支持，请添加如下语句
                    REQUIRES driver)

4、项目操作

主要是对 ESP-IDF 扩展在 VS Code 最下方工具栏上添加的操作按键进行说明，某些次要项已省略，按照从左向右的顺序依次为：

  1. ...
  2. 📂：选择当前项目文件夹
  3. ESP-IDF 版本
  4. ⭐：选择烧录方式
  5. 端口
  6. 设备目标
  7. ⚙：SDK 配置编辑器（menuconfig）
  8. 🗑️：彻底清理整个项目的构建
  9. 🔧：构建整个项目
  10. ⚡：烧录程序
  11. 🖥️：串口终端监视器
  12. 调试
  13. 🔥：🔧+⚡+🖥️
  14. ESP-IDF 终端
  15. ...
  16. 错误和警告数量
  17. ...

5、项目配置

项目配置有如下两种方式：

  1. SDK 配置编辑器
  2. menuconfig

SDK 配置编辑器进入方式有如下两种：

  1. VS Code 查看 -> 命令面板（Ctrl+Shift+P）-> 搜索 "ESP-IDF: SDK 配置编辑器" -> 打开后找到上方的搜索框
  2. 单击 VS Code 页面下方工具栏的 "齿轮" 按钮打开 SDK 配置编辑器（menuconfig）-> 打开后找到上方的搜索框

menuconfig 进入方式如下：

  1. 单击 VS Code 页面下方工具栏的 "打开 ESP-IDF" 终端 -> 输入 idf.py menuconfig启动图形化配置页面 -> 输入 / 进入搜索模式

以下内容仅点到为止，更多配置请自行浏览

5.1、CPU 频率

搜索 CPU_FREQ 配置 CPU 频率

5.2、FLASH 相关

搜索 "FLASH"

找到 FLASHMODE 配置 FLASH SPI 模式

找到 FLASHFREQ 配置 FLASH SPI 速度

找到 FLASHSIZE 配置 FLASH 大小

5.3、Partition Table 分区表

搜索 "PARTITION_TABLE" 配置分区表

分区表用来对 ESP32 外部 SPI FALSH 内存进行区域划分，不同区域存储不同的数据，有如下几种类型：

  1. Single factory app, no OTA
csv 复制代码 
# Name,    Type,   SubType,    Offset,     Size,    Flags
nvs,       data,   nvs,        0x9000,     24K,
phy_init,  data,   phy,        0xf000,     4K,
factory,   app,    factory,    0x10000,    1M,
  1. Single factory app (large), no OTA
csv 复制代码 
# Name,    Type,   SubType,    Offset,     Size,    Flags
nvs,       data,   nvs,        0x9000,     24K,
phy_init,  data,   phy,        0xf000,     4K,
factory,   app,    factory,    0x10000,    1500K,
  1. Factory app, two OTA definitions
csv 复制代码 
# Name,    Type,   SubType,    Offset,     Size,    Flags
nvs,       data,   nvs,        0x9000,     16K,
otadata,   data,   ota,        0xd000,     8K,
phy_init,  data,   phy,        0xf000,     4K,
factory,   app,    factory,    0x10000,    1M,
ota_0,     app,    ota_0,      0x110000,   1M,
ota_1,     app,    ota_1,      0x210000,   1M,
  1. Two large size OTA partitions
csv 复制代码 
# Name,    Type,   SubType,    Offset,     Size,    Flags
nvs,       data,   nvs,        0x9000,     24K,
otadata,   data,   ota,        0xf000,     8K,
phy_init,  data,   phy,        0x11000,    4K,
ota_0,     app,    ota_0,      0x20000,    1700K,
ota_1,     app,    ota_1,      0x1d0000,   1700K,

以上几种类型均为预设类型，选择其中任意一项，保存并重新构建项目后，可以在 ESP-IDF 终端中输入 idf.py partition-table 查看对应的分区具体详情

  1. Custom partition table CSV

启用自定义分区表后，可以通过 ESP-IDF 提供的分区表编辑器进行编辑，打开方式如下：

VS Code 查看 -> 命令面板（Ctrl+Shift+P）-> 搜索 "ESP-IDF: 打开分区表编辑器 UI" -> 单击 "Add New Row" 增加一行分区 -> 单击 "Save" 保存自定义分区表

其中 Type 和 SubType 的可选类型固定，只能从以下几种中按需选择：

  1. Type
    1. app : 程序分区
      1. factory : 工厂应用
      2. ota_x : OTA 应用
      3. test : 测试数据
    2. data : 数据分区
      1. fat : FAT 文件系统
      2. ota : OTA 数据
      3. phy : 无线 PHY 校准数据
      4. nvs : 非易失性存储
      5. nvs_keys : NVS 密钥
      6. spiffs : SPIFFS 文件系统
      7. coredump : 核心转储

5.4、FreeRTOS 相关

搜索 "FREERTOS_HZ" 配置 FreeRTOS 节拍时钟周期，一般设置其为 1000

6、组件注册表

组件注册表是乐鑫提供给开发者的一个在线平台，这个平台上托管许多组件，开发者可以在其中搜索自己想要的组件，并将其添加到自己的项目中，避免对组件的重复开发。

使用组件注册表主要有如下两种方式：

  1. CMD
  2. VS Code

6.1、CMD

  1. ESP Component Registry
  2. 搜索组件 xxx
  3. ESP-IDF 终端输入 idf.py add-dependency "xxx" 添加组件
  4. 会在 main 文件夹下增加 idf_component.yml 文件
  5. 重新构建项目后会自动下载组件到 managed_components 文件夹中

6.2、VS Code

  1. VS Code 查看 -> 命令面板（Ctrl+Shift+P）
  2. 搜索："ESP-IDF: 乐鑫组件注册表"
  3. 搜索组件
  4. Install
  5. 安装成功后会自动下载组件到 managed_components 文件夹中
相关推荐
OSnotes8 天前
ESP-IDF教程2 GPIO - 输入、输出和中断
esp-idf
大专生学编程3 个月前
基于ESP32-IDF驱动GPIO输出控制LED
嵌入式硬件·esp32·esp-idf
MonkeyKing_sunyuhua6 个月前
ubuntu22.04 桌面系统怎么搭建一个esp-idf的项目，搭建开发环境
esp-idf
柔贝特三哥6 个月前
ESP32 S3 语音识别 语音唤醒程序流程
人工智能·esp32·语音识别·esp-idf·ai对话·语音唤醒·语音命令
事在人wёi6 个月前
VSCode esp-idf环境搭建 报错 ERROR_INVALID_PIP
vscode·esp-idf
咖喱年糕9 个月前
【VSCode】安装 【ESP-IDF】插件及【ESP32-S3】新建工程和工程配置
json·cmake·esp32-s3·esp-idf·project·串口下载
咖喱年糕9 个月前
【Espressif-ESP32S3】【VScode】安装【ESP-IDF】插件及相关工具链
vscode·esp-idf·espressif·esp-idf-tools
宁子希10 个月前
使用 ESP32 和 PlatformIO （arduino框架）实现 Over-the-Air（OTA）固件更新
服务器·网络·c++·php·esp-idf·esp
宁子希1 年前
14.FreeRTOS 消息缓存 Message Buffer
c++·嵌入式硬件·esp-idf
热门推荐
01KGG转MP3工具|非KGM文件|解密音频02从零安装 LLaMA-Factory 微调 Qwen 大模型成功及所有的坑03我决定放弃搞 Java 了04Coze扣子平台完整体验和实践（附国内和国际版对比）05YOLOv8入门 | 重要性能衡量指标、训练结果评价及分析及影响mAP的因素【发论文关注的指标】06DeepSeek各版本说明与优缺点分析07yolov8，yolo11，yolo12 服务器训练到部署全流程 笔记08苍穹外卖面试总结09如何在WPS和Word/Excel中直接使用DeepSeek功能10【2025年最新】OpenWrt 更换国内源的指南（图形界面版)