ESP-IDF教程1 开发环境

OSnotes

已于 2025-04-29 10:10:24 修改

阅读量1.5k

点赞数 10

CC 4.0 BY-SA版权

分类专栏： ESP-IDF+ESP32系列教程文章标签：嵌入式软件 ESP-IDF ESP32

于 2025-04-17 14:44:38 首次发布

本文链接：https://blog.youkuaiyun.com/lc_guo/article/details/147305759

ESP-IDF+ESP32系列教程专栏收录该内容

4 篇文章

订阅专栏

本文介绍了如何搭建 ESP-IDF 的开发环境、新建空模板工程、项目结构、操作和配置等相关内容，章节目录如下：

文章目录

1、开发环境
- 1.1、VS Code + ESP-IDF 插件
- 1.2、Espressif-IDE
2、新建项目
- 2.1、VS Code + ESP-IDF 插件
- 2.2、Espressif-IDE
3、项目结构
4、项目操作
5、项目配置
6、组件注册表
- 6.1、CMD
- 6.2、VS Code

1、开发环境

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

ESP-IDF（Espressif IoT Development Framework）
Arduino
PlatformIO

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

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

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

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

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

1.1、VS Code + ESP-IDF 插件

下载 VS Code，VS Code 安装较为简单，一路下一步直到安装即可。
给 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_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_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 文件内容应该如下所示：

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

4、项目操作

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

…
📂：选择当前项目文件夹
ESP-IDF 版本
⭐：选择烧录方式
端口
设备目标
⚙：SDK 配置编辑器（menuconfig）
🗑️：彻底清理整个项目的构建
🔧：构建整个项目
⚡：烧录程序
🖥️：串口终端监视器
调试
🔥：🔧+⚡+🖥️
ESP-IDF 终端
…
错误和警告数量
…

5、项目配置

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

SDK 配置编辑器
menuconfig

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

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

menuconfig 进入方式如下：

单击 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 内存进行区域划分，不同区域存储不同的数据，有如下几种类型：

Single factory app, no OTA

# Name,    Type,   SubType,    Offset,     Size,    Flags
nvs,       data,   nvs,        0x9000,     24K,
phy_init,  data,   phy,        0xf000,     4K,
factory,   app,    factory,    0x10000,    1M,

Single factory app (large), no OTA

# Name,    Type,   SubType,    Offset,     Size,    Flags
nvs,       data,   nvs,        0x9000,     24K,
phy_init,  data,   phy,        0xf000,     4K,
factory,   app,    factory,    0x10000,    1500K,

Factory app, two OTA definitions

# 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,

Two large size OTA partitions

# 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 查看对应的分区具体详情

Custom partition table CSV

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

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

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

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 : 核心转储