ESP-IDF教程1 开发环境

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 文件内容应该如下所示：

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

# 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

# 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

# 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

# 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 文件夹中