《DNESP32S3使用指南-IDF版_V1.6》第五章搭建开发环境

开发板

第五章搭建开发环境

在前面章节中，我们已经大致了解了ESP32-S3基础知识及ESP-IDF物联网开发框架的编译与链接原理，现在，我们将进入实际操作阶段，逐步搭建ESP-IDF的开发环境。

本章分为如下几个小节：

5.1 安装ESP-IDF物联网开发框架

5.2 IDF前端工具

5.3 搭建集成开发环境

5.1 安装ESP-IDF物联网开发框架

为了安装ESP32的开发环境，我们需要前往乐鑫官方的Windows安装下载中心下载ESP32-IDF安装包。在这里，我们推荐下载离线的安装包，虽然安装速度可能会稍慢一些，但它能够确保安装的成功率。相比之下，在线的安装包需要稳定的网络支持，如果网络状况不佳，可能会导致安装失败。当然，也可以在A盘à6，软件资料à1，软件à1，IDF开发工具à04-ESP32-IDF Offline Installer路径下找到5.1.2离线安装包。ESP_IDF物联网开发框架安装包如下图所示：

图5.1.1 下载V5.1.2离线安装包（教程编写时最新版本）

下载成功后，在安装程序上单击右键选择<以管理员身份运行>运行esp-idf-tools-setup-offline-5.1.2.exe文件，如下图所示：

图5.1.2 以管理员身份运行安装包

打开安装程序后选择简体中文安装，如下图所示：

图5.1.3 选择安装语言

往下走就是许可协议，勾选“我同意此协议”，单击下一步，如下图所示：

图5.1.4 勾选“我同意此协议”选择

点击下一步之后，会跳出安装前系统检查界面，如下图所示：

图5.1.5 安装界面

安装程序会检查你当前系统有没有打开"长路径支持"，因为GNU编译器产生的编译文件会有非常深的目录结构，如果不支持长路径，编译可能出现文件不存在，目录不存在等奇怪的错误。这里单击应用修复按钮，可以修复这个问题。在弹出的确认对话框中，选择是，开始修复。

图5.1.6 在注册表中启用长路径

如果修复不成功，一般情况是安装软件打开时没有使用管理员权限打开，可以手动修改注册表来支持长路径：打开注册表HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled 设置为 1。如下图所示：

图5.1.7 手动启用长路径

图3.1.6提示修复完成后，点击下一步进入配置安装路径，如下图所示：

图5.1.8 配置安装路径

安装程序默认的安装位置为C:\Espressif，但这里我是安装在D盘，如果全部源码编译后可能产生几十G的大小占用，我们在D盘下创建ESP32\Espressif文件夹来保存ESP32-IDF库安装过程中生成的文件。注意：这个安装路径非常重要，因为VS Code软件的IDF插件需要此路径来获取相关文件，所以开发者务必牢记该路径。

设置安装路径后点击 “下一步”选项，进入确认安装组件界面，这里全部打勾，默认完全安装时ESP32C2是不打勾的（如下图所示），看需要自己选择。然后单击下一步。

图5.1.9 选择安装组件

我们选择全部安装。点击下一步再次确认安装目录信息，然后单击安装。安装完成，三个全部勾选，1、2用于测试环境安装是否成功，3是将ESP-IDF工具链加入杀毒工具排除项，以加快编译速度，如下图所示：

图5.1.10 ESP32-IDF库安装完成

安装成功后，桌面自动生成ESP-IDF 5.1 PowerShell和ESP-IDF 5.1 CMD命令提示符终端，PowerShell提供了更强大的脚本和自动化功能，适合需要执行复杂任务或管理复杂环境的用户；而CMD则更适合进行基础的命令行操作和简单的脚本执行。用户可以根据自己的需求和偏好选择使用其中一个工具。

打开其中一个终端，如果终端提示“idf.py build”指令时，说明我们的环境已经安装成功了。如下图所示：

图5.1.11 PowerShell窗口

从上图中可以看到，当出现红色方框内的内容时，可以初步证明安装是没有问题的。在这终端下，我们可以采用命令形式进行配置、编译、链接和构建项目，这与在Linux中的开发方式颇为相似。下一个小节，将详细讲解ESP-IDF常用的命令。

为了让系统能够找到和识别ESP-IDF的相关工具和库，从而能够顺利地进行编译、构建和调试ESP32或其他Espressif芯片的项目，我们必须设置ESP-IDF的环境变量，设置方法如下：

按照此过程（此电脑à属性à高级系统à环境变量）打开，如下图所示：

图5.1.12 添加环境变量

如果ESP-IDF库安装成功，则系统自动为我们添加上图中的IDF_TOOLS_PATH和IDF_PATH环境变量，否则手动添加这两个环境变量。

安装完成后，系统会自动安装Espressif-IDE集成开发环境，这是专为乐鑫SoC芯片开发的集成开发环境。鉴于该软件在国内发布时间尚短，且国内开发者多倾向于使用VS Code IDE进行开发，因此本教程的例程主要基于VS Code IDE展开。然而，我们正点原子也致力于推广Espressif-IDE集成开发环境，故决定额外编写一个关于Espressif-IDE集成开发环境的使用教程，以更好地帮助国内开发者熟悉并利用这一强大的集成开发环境（请读者查看《Espressif-IDE集成开发环境使用指南》）。

安装USB虚拟串口驱动

ESP32-S3的USB串口可用于下载程序和ESP监控器之间的交互。通过USB连接ESP32-S3开发板，在项目文件夹中执行特定指令，然后可以使用如idf.py等工具编译程序并下载到开发板中。正点原子的ESP32-S3开发板的串口信号是通过CH340C芯片进行转换，才能与PC端进行通信。CH340C芯片能够将ESP32-S3的串口信号转换为USB信号，并通过USB接口与PC进行连接。在PC端安装相关的串口调试助手软件，再安装CH340C芯片的驱动程序，就可以在PC端实现通过虚拟串口与ESP32-S3进行通信了。

接下来需要在电脑上安装CH340C芯片的驱动程序。CH340C的官方厂商沁恒提供了该驱动程序的下载选项，您可以前往沁恒的官方网站下载并安装CH340C的驱动程序，也可在6，软件资料à1，软件àCH340驱动文件夹下找到CH340C的驱动安装程序，如下图所示。

图5.1.13 CH340C驱动安装程序

打开CH340C驱动安装程序后，点击安装程序中的“安装”按钮，若提示“驱动安装成功”，则说明CH340C驱动已经安装成功了，如下图所示。

图5.1.14 CH340C驱动安装成功

安装完CH340C驱动后，使用跳线帽将正点原子ESP32-S3开发板P4排针的U0TX-RXD和U0RX-TXD接上，如下图所示。

图5.1.15 连接USB-UART0

接下来，使用USB线将开发板UART接口与PC的USB端口相连接即可。此时，PC端的设备管理器中查看到CH340C虚拟出的串口，如下图所示。

图5.1.16 PC端显示的虚拟串口

从上图可以看出，CH340C虚拟出的串口被PC分配了COM3的端口号。这个端口号用于串口调试助手等上位机确定与之通信的串口端。需要注意的是，当CH340C与不同的PC连接，甚至是与同一台PC的不同USB端口连接后，虚拟出的串口被PC分配到的端口号可能是不同的，例如COM4或COM5。读者可以根据设备管理器中端口设备的名称来判断具体是哪个端口号。如果同时连接了多个CH340系列的芯片，则需要逐个测试端口号。

安装完USB虚拟串口驱动后，就可以使用串口调试助手，如正点原子开发的ATK-XCOM软件，与板卡通过串口进行通信了。

接下来，作者将详细阐述ESP-IDF的两种开发方式。这两种方式分别是命令式开发和基于IDE集成开发环境下的开发。为了让读者能够更深入地理解和掌握这两种开发方式，作者将分别用两个小节来讲解这两部分的内容。

5.2 IDF 前端工具

在上一章节中，作者已经介绍过，ESP-IDF能够通过命令的形式来构建或编译系统，这一命令被称为ESP-IDF的前端工具。此工具旨在简化ESP32以及其他Espressif芯片系列的开发流程。它提供了诸多实用功能，从而协助开发者更加高效地构建、烧录以及调试项目。

以下是 idf.py 的一些主要功能：

(1) 构建系统：idf.py 是一个构建系统，它使用 CMake 来生成适用于不同目标平台的构建文件。你可以使用 idf.py 来构建你的项目，它会处理所有必要的编译和链接步骤。

(2) 菜单配置：idf.py menuconfig 命令提供了一个文本用户界面，用于配置项目的各种选项。你可以通过这个界面选择目标硬件、设置编译选项、启用或禁用组件等。

(3) 烧录和调试：idf.py 支持将构建好的二进制文件烧录到目标设备上。你可以使用 idf.py -p PORT flash 命令来烧录固件，其中 PORT 是你的设备的串口或USB端口。此外，idf.py 还可以与调试器配合使用，例如 GDB，以便在目标设备上调试代码。

(4) 清理和重新构建：idf.py提供了清理构建文件的功能，以确保每次构建都是从头开始的。这对于在修改配置或更新源代码后重新构建项目非常有用。

(5) 项目模板和示例：idf.py 通常与 ESP-IDF 提供的项目模板和示例代码一起使用。这些模板和示例为你提供了一个良好的起点，帮助你快速设置和开始你的项目。

(6) 扩展性：idf.py 是可扩展的，允许开发者添加自定义的构建步骤和脚本。这使得开发者可以根据需要定制构建过程，以满足特定项目的需求。

下面作者来讲解一下IDF 前端工具的常用命令。

1，创建新工程（create-project）

“idf.py create-project --path ”是 ESP-IDF 提供的一个命令，用于创建一个新的项目目录结构，并将必要的文件和模板复制到该目录中。这个命令的目的是帮助开发者快速设置一个新的 IoT 项目，而无需手动创建所有必要的文件和目录

下面是这个命令的参数解析和使用方法。

①：参数解析

--path：指定创建工程的位置（必须在文件夹路径下）。

：项目工程名称。

②：使用方法

在桌面新建test_1文件夹，用来保存ESP-IDF新建的工程，然后打开ESP-IDF CMD终端输入“idf.py create-project --path C:\Users\ATK\Desktop\test_1 led”命令创建项目工程，如下图所示：

图5.2.1 指定路径创建工程

此时桌面会创建test_1项目，而工程名称为led。如下图所示：

图5.2.2 新建项目工程

2，创建新组件（create-component）

“idf.py create-component ” 创建一个新的组件，包含构建所需的最基本文件集。一般存放第三方组件，如编写的驱动程序等。

下面是这个命令的参数解析和使用方法。

①：参数解析

：组件名称

②：使用方法

首先使用“cd”命令进入新建工程路径，然后在此路径下新建组件文件夹，如下图所示：

图5.2.3 新建组件

component文件夹一般用来存储第三方组件或者用户的程序驱动代码。

3，设置目标芯片

“idf.py set-target ”命令用于设置工程的目标芯片。由于ESP-IDF支持多款乐鑫SoC芯片，新建工程时默认会选择ESP32类型的芯片。因此，如果我们希望创建一个针对ESP32-S3类型的工程，就必须使用此命令来指定该工程的目标芯片为ESP32-S3。

下面是这个命令的参数解析和使用方法。

①：参数解析

< target >：目标芯片，可使用“idf.py --list-targets”命令查看支持的芯片类型。

②：使用方法

首先输入“idf.py --list-targets” 命令查看支持的芯片类型，然后输入“idf.py set-target esp32s3”命令设置工程的目标芯片，如下图所示：

图5.2.4 设置工程目标芯片

注意： “idf.py set-target”命令将清除构建目录，并从头开始重新生成sdkconfig文件。旧的sdkconfig文件将保存为sdkconfig.old。

4，编译工程

“idf.py build”命令用来编译当前项目工程。如下图所示：

图5.2.5 编译当前项目工程

5，监控项目

“idf.py monitor”命令用来监控当前项目。监控之前必须安装USB虚拟串口驱动以及开发板上的USB串口接入到电脑当中，才能监控当前项目工程。

图5.2.6 监控项目工程（类似串口打印系统数据）

注意：请按“Ctrl + ”快捷键退出监控器。

6，配置项目

“idf.py menuconfig” 这个命令会启动一个文本用户界面，允许开发者为他们的 ESP32 或其他 Espressif SoC 芯片系列的项目配置各种选项。如下图所示：

图5.2.7 配置项目

menuconfig菜单项的内容解析，作者会在以后的章节中讲解这部分的内容，读者先知道有这么一回事即可。

7，下载代码

“idf.py -p COM9 flash”这个命令用来把编译出来的可执行文件烧录到ESP32-S3芯片当中。注意：烧录之前必须调用“idf.py build”命令编译项目工程，编译完成后方能烧录代码。如下图所示：

图5.2.8 烧录代码

上述COM9端口需要根据自己的开发板识别出来的虚拟串口端口。

8，清除编译文件

“idf.py clean”和“idf.py fullclean” 是ESP-IDF（Espressif IoT Development Framework）中用于清理构建目录和输出文件的两个命令，它们的主要区别在于清理的彻底程度和范围。

①“idf.py clean”命令：

这个命令主要用于清理构建目录中的构建输出文件。它会删除build文件夹中的某些文件，但不会删除CMake的配置输出和其他相关文件。这意味着下次构建时，CMake将基于现有的配置信息重新生成所需的构建输出，但不需要从头开始配置整个项目。这通常用于在不需要更改项目配置的情况下，重新构建项目以解决可能存在的构建问题或更新代码。

②“idf.py fullclean”命令：

这个命令则更为彻底，它会删除整个build目录下的所有内容，包括所有的CMake配置输出文件。这意味着下次构建项目时，CMake将需要从头开始配置项目，重新生成所有的构建输出和配置文件。这个命令通常用于在需要完全重置项目构建环境的情况下使用，例如在更改了项目的硬件配置或需要确保从头开始全新构建。

上述提到的命令是IDF前端工具中极为常用的指令，掌握了这些命令，您就可以开始着手开发ESP32项目了。至于其他命令的详细信息，建议读者查阅ESP-IDF编程指南中的IDF前端工具章节内容。

看到此处，许多读者对命令式开发感到束手束脚，毕竟命令式开发难以轻松调试和编写代码，更何况在大型项目中，开发效率会大大降低。因此，为了让开发者能够更顺畅地使用ESP-IDF，作者建议开发者选择基于集成开发环境（IDE）的开发方式。这种方式能更好地支持代码的调试和编写。至于IDE的选择，作者特别推荐VS Code IDE，因为它是一款免费且开源的IDE软件，非常适合用于ESP-IDF的开发工作。

5.3 搭建集成开发环境

在上一小节中，作者详细阐述了命令式开发的常用命令。然而，对于初学者来说，他们更倾向于使用图形界面式的开发方式，因为图形界面能更直观地展示整个开发过程。因此，作者在这里推荐使用VS Code IDE作为开发工具，该软件支持下载ESP-IDF插件，从而方便开发者进行项目开发和调试。ESP-IDF Eclipse 插件可便利开发人员在VS Code开发环境中开发基于 ESP32 的 IoT 应用程序。本插件集成了编辑、编译、烧录和调试等基础功能，还有安装工具、SDK 配置和 CMake 编辑器等附加功能，可简化并增强开发人员在使用标准VS Code 开发和调试 ESP32 IoT 应用程序时的开发体验。

5.3.1 VS Code安装

鉴于我们使用的是VSCode IDE搭配乐鑫ESP-IDF的方式进行开发，我们接下来便介绍一下VSCode的安装过程。

首先，进入VSCode官方下载页面，根据系统需求选择下载安装包，也可以在A盘à6，软件资料à1，软件à1，IDF开发工具à01-Windows路径下找到VSCode安装包。下图是VSCode官方下载页面。

图5.3.1.1 VSCode官网下载界面

这里，我们选择Windows版本进行下载。因为，我们是在Windows环境下进行的开发，故在此介绍Windows版本的下载步骤。不出意外，其它版本的下载方式应该也是一样的。这里我们不多废话，直接点击下载。

下载完后，我们按照如下所示步骤进行即可：

图5.3.1.2 VSCode下载步骤一

图5.3.1.3 VSCode下载步骤二

在该步骤中，路径如需更改的，请您点击“浏览”进行更改，但请注意：修改的路径最好不要出现中文，以避免在往后的开发过程中遇到问题而导致重装软件，这对您来说就得不偿失了。

图5.3.1.4 VSCode下载步骤三

如需修改，同样点击“浏览”进行设置，无需修改的话直接点击“下一步”即可。

图5.3.1.5 VSCode下载步骤四

这一步骤同样是有需求的都勾上，我们建议是都勾上。

图5.3.1.6 VSCode下载步骤五

点击“安装”后，您只需静候佳音即可。

图5.3.1.7 VSCode下载步骤六

到这一步便可以开始运行VSCode了。打开VS Code，在扩展商店的搜索区域输入“Chinese”安装中文插件，如下图所示：

图5.3.1.8 VSCode中文界面设置

至此，VSCode的安装与配置便算是大功告成了。感谢您能耐心看到此处。

5.3.2 安装与配置ESP-IDF插件

打开VS Code软件，然后按下快捷键“Ctrl+Shift+X”进入应用商城，在搜索栏下搜索Espressif IDF插件，点击安装即可：

图5.3.2.1 Espressif IDF插件安装

至此Espressif IDF插件就算安装好了，接下来我们来看看插件的配置。

快捷键ctrl+shift+p呼出命令栏，在弹如下提示框后，搜索“配置 ESP-IDF 插件”，或者在使用快捷键ctrl+shift+p呼出命令栏后，在搜索框输入配置命令：Configure ESP-IDF。

图5.3.2.2 配置ESP-IDF插件

回车后，进入配置 ESP-IDF 插件界面，如下图所示：

图5.3.2.3 配置 ESP-IDF 插件界面

在上图中，点击“ADVANCED”进入高级配置界面，如下图所示：

图5.3.2.4 配置ESP-IDF插件

配置ESP-IDF插件完成后，点击上图“Configure Tools”选项执行配置操作，此时需要等待系统配置成功，如下图所示：

图5.3.2.5 配置操作

注意：如果出现“python.exe -m pip is not valid”错误，大概是python环境搭建原因。请参考这位博主的解决方案。

从上图可以看到，配置ESP-IDF插件需要进行三个流程，等待第一个流程配置完成，此时进入ESP-IDF Tools配置流程，如下图所示：

图5.3.2.6 下载ESP-IDF Tools

接着点击 “Download Tools”选项下载工具（需要网络加持），如下图所示：

图5.3.2.7 下载ESP-IDF工具

下载成功后，系统进入第三个流程Python环境搭建，如下图所示：

图5.3.2.8 安装Python环境

三个流程完成后，系统提示如下信息，如下图所示：

图5.3.2.9 ESP-IDF配置完成

接下来，作者将讲解插件默认的配置参数，如串口下载的波特率和下载方式，配置流程如下所示：

图5.3.2.10 进入ESP-IDF插件配置

点击“扩展设置”选项，进入配置插件界面，然后找到“Flash Baud Rate”和“Flash Type”选项，如下图所示：

图5.3.2.11 配置下载默认参数

到了这里，我们已经配置ESP-IDF插件完成。

5.3.3 个性化配置和工作环境配置

以 Visual Studio Code（VS Code）为例，settings.json 文件存储了用户的个性化配置和工作环境设置，包括编辑器的外观、语言、代码格式化风格、自动补全行为、调试配置、扩展设置等。在 VS Code 中，可以通过用户设置（全局设置）和工作区设置（针对特定项目或文件夹的设置）来区分不同类型的配置。settings.json文件配置流程如下。

① 打开设置界面

我们按住 “Ctrl +”快捷键，进入settings.json文件编写内容。

② 添加个性化配置和工作环境设置参数

添加内容如下：

{

/* 上面的部分是我自己创建的一些设置 */

"editor.insertSpaces": false, /* 自动插入空格禁用*/

"editor.detectIndentation": false, /* 启用时根据文件内容进行重写*/

"editor.renderControlCharacters": true, /* 是否显示控制字符：启用*/

"editor.renderWhitespace": "all", /* 显示4个空格是.... */

"editor.tabSize": 4, /* tab设置为4个空格*/

"editor.fontSize": 18, /* 代码字体大小*/