ESP32之 ESP-IDF + Clion 开发环境搭建（一）—— Windows版

Augtons正(单片机)

已于 2022-09-28 17:57:58 修改

阅读量1.8w

点赞数 22

分类专栏： ESP32 教学专栏 (基于ESP-IDF) 文章标签：单片机物联网嵌入式 c语言 windows

于 2021-12-27 19:59:22 首次发布

本文链接：https://blog.csdn.net/m0_50064262/article/details/122170583

版权

ESP32 教学专栏 (基于ESP-IDF) 专栏收录该内容

28 篇文章 1049 订阅

订阅专栏

本文章 来自原创专栏《ESP32教学专栏 (基于ESP-IDF)》，讲解如何使用 ESP-IDF 构建 ESP32 程序，发布文章并会持续为已发布文章添加新内容！ 每篇文章都经过了精打细磨！

↓↓↓通过下方对话框进入专栏目录页↓↓↓
CSDN 请求进入目录　　　　　　_ O x 是否进入ESP32教学导航(基于ESP-IDF)? 　　　　　　　确定

ESP-IDF 是由乐鑫Espressif官方提供的一套ESP32系列SoC的物联网开发套件（Espressif IoT Development Framework）提供了从工程创建，编译，烧录，调试，量产等的完整解决方案。本文将介绍如何在Windows下搭建ESP-IDF开发环境。

敬告：

① 如果你想使用Arduino来开发ESP32，目前可参考的资料较多，请读者自行查阅。
② 使用Arduino开发ESP32，很难发挥ESP32的全部实力，强烈推荐相关专业人士或技术爱好者转为 ESP-IDF 开发。
③ ESP-IDF是乐鑫官方推荐的SDK。

注意：

下文的 “开发环境” 和 “编程环境” 的含义并非相同
　
编程环境：指代码编写的人机交互环境，例如使Clion IDE或者VS Code等工具对开发环境的耦合和优化。
开发环境：指ESP-IDF工程的建立，配置，编译，调试，量产等基础操作的环境。开发环境不包含编程环境

在文章开始之前，先感受一下Clion带来的流畅丝滑的变成体验吧！

① 丝滑头文件

在这里插入图片描述
② 丝滑结构体

在这里插入图片描述
③ 丝滑提示

在这里插入图片描述

文章目录

（一）开发环境搭建
（二）idf.py 基本操作使用
（三）【全网独家】对开发环境的优化，使其更好与IDE耦合
（四）【全网独家】Clion IDE For Windows 下 ESP-IDF 编程环境搭建

（一）开发环境搭建

方法一，使用命令行安装

1、获取 ESP-IDF

如果你想要安装 ESP-IDFv4.4 或 v4.3.2 ，我为大家准备了一篇锦囊来帮助大家快速安装。

[锦囊文] Windows下 ESP-IDF-v4.4 飞速安装

安装完成后回到本文的（二）即可

由于国内访问Github较慢，官方给我们提供了一个开箱即用的ESP-IDF。前往ESP-IDF的Github或Gitee发行版本页面即可找到（下文已给出）

ESP-IDF v4.4直接下载：https://dl.espressif.com/github_assets/espressif/esp-idf/releases/download/v4.4/esp-idf-v4.4.zip

ESP-IDF v4.3.2直接下载：https://dl.espressif.com/github_assets/espressif/esp-idf/releases/download/v4.3.2/esp-idf-v4.3.2.zip

如果你想要获取其他版本，请从ESP-IDF官方github或者gitee查看最新发行版，并使用提供的对应版本的命令行
Github 发行版页：https://github.com/espressif/esp-idf/tags
Gitee 发行版页：https://gitee.com/EspressifSystems/esp-idf/releases

2、安装所需工具

默认IDF工具安装路径默认为“你的个人文件夹\.espressif”（例如 Windows10 或 Windows11 为“C:\Users\你的用户名\.espressif”）。包含上文除了ESP-IDF其他的组件，虽然官方提供了这个安装目录的更改方法，但是此路径仍然不建议更改

在开始之前，我们要配置一下 espressif 的 github 下载服务器来加速下载

添加一个系统环境变量IDF_GITHUB_ASSETS内容为dl.espressif.com/github_assets。
在这里插入图片描述
再使用①或②完成下面的工作

有时候这样做并不会立即生效，可以在Powershell里执行以下命令来生效（只针对当前命令行串口有效）

PS D:\> $env:IDF_GITHUB_ASSETS='dl.espressif.com/github_assets'

或者在cmd里（路径不加引号）（只针对当前命令行串口有效）

set IDF_GITHUB_ASSETS=dl.espressif.com/github_assets

① 使用PowerShell

PowerShell 进入到 esp-idf目录。路径和文件名支持使用Tab补全

PS D:\> cd esp-idf
PS D:\esp-idf\> .\install.ps1

如果系统提示类似下文的信息，请更改使用命令提示符安装

PS D:\esp-idf> .\export.ps1

.\export.ps1 : 无法加载文件 D:\esp-idf\export.ps1，因为在此系统上禁止运行脚本。有关详细信息，请参阅 https:/go.microsoft
.com/fwlink/?LinkID=135170 中的 about_Execution_Policies。
所在位置 行:1 字符: 1

Win + R 键打开运行，输入cmd即可打开命令提示符

② 使用 cmd （命令提示符）

cmd与powershell不同的是，cmd切换盘符不能用cd命令，参考第一行

C:\Users\Augtons> d:

D:\> cd esp-idf

D:\esp-idf> install.bat

如果安装过程很慢，或者中途有无法连接服务器等不顺利的情况，请按如下方案进行安装。

如果提示找不到git，请看本文本节“方法三：遗留的方法”第一步“安装git for windows”

3、检查前边的工作是否成功

全部安装成功后，在esp-idf目录下用cmd执行export.bat

D:\esp-idf> export.bat

如果出现如下输出，即前边的工作成功

Done! You can now compile ESP-IDF projects.
Go to the project directory and run:

  idf.py build

方法二：使用官方提供的安装器

1、安装器简介

为简化Windows下对ESP-IDF开发环境的安装，乐鑫官方提供了Windows下ESP-IDF开发环境的快速安装其器。有在线安装版和离线安装版两个版本。

在线安装：在线安装可以安装 ESP-IDF 的所有版本。在安装过程中，安装程序只下载必要的依赖文件，包括 Git For Windows 安装器。在线安装程序会将下载的文件存储在缓存目录%userprofile%/espressif 中，而IDF的存放目录可自定义。
离线安装：离线安装程序不需要任何网络连接。安装程序中包含了所有需要的依赖文件，包括 Git For Windows 安装器。

2、安装器安装过程

此安装程序会遵循以下步骤进行安装：

安装必要的组件：
① 内置的 Python（多数脚本由python编写，需要使用python执行。为防止干扰到其他的python，安装器会提供一个内置的python）
② 交叉编译器（这是在电脑上编译ESP32可执行文件必要的编译器，由于为在一种平台上编译出另一平台上的可执行文件，故称“交叉编译器”）
③ OpenOCD（针对高级用户。这是ESP32进行JTAG调试必要的组件，同样也支持STLink对stm32进行在线调试）
④ CMake 和 Ninja 编译工具（这是连接源文件和交叉编译器的桥梁工具）
⑤ ESP-IDF （这即为开发包，包含了ESP32系列的库文件和例程代码，以及其他重要的工程依赖项）
配置相关环境变量
提供通过命令行快速使用idf工具的快捷方式

然而，官方提供的安装器并非十全十美，安装过程中可能会出现各种问题，而且相对第二种方法（命令行）错误不容易定位。

因此这里给出一个折中的方法，对于使用安装器的安装，优先使用离线安装器。离线安装不成功且错误很难修复的，使用第二种命令行法在线安装ESP-IDF。

若使用Windows下官方提供的安装器，请参考官方文章：https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/get-started/windows-setup.html#get-started-windows-tools-installer
下载一个合适版本的安装器，最好使用离线安装器。安装一个合适版本的IDF。（本文发布时，最新稳定版为v4.3.2）

请务必了解：！！！！！！！！

安装器默认ESP-IDF放置路径默认填的是“你的桌面\esp-idf”，强烈不推荐使用此路径，建议改成"D:\esp-idf"等
安装器默认IDF工具安装路径默认为“你的个人文件夹\.espressif”（例如 Windows10 或 Windows11 为“C:\Users\你的用户名\.espressif”）。包含上文除了ESP-IDF其他的组件，此路径不建议更改！使用默认即可，全部安装大约占用 800M 左右的储存空间。
无论如何，请保证两者安装路径不得包含空格、特殊符号、非Ascii字符如汉字等。如果你的用户名包含上述内容也不行，务必更改安装路径。如果有疑问，请评论区留言或私信博主。

方法三：遗留的安装方法 (此方法已改进为当前的方法一)

1、安装 `git for windows`

方法很多，不再赘述。确保git安装成功且能在命令行中使用

安装成功

PS D:\> git

usage: git [--version] [--help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           [--super-prefix=<path>] [--config-env=<name>=<envvar>]
           <command> [<args>]

These are common Git commands used in various situations:
	...

安装失败，或环境变量未设置

PS D:\> git
sdsd : 无法将“git”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如
果包括路径，请确保路径正确，然后再试一次。

2、获取 ESP-IDF

进入你想放置ESP-IDF文件夹的目录。然后执行以下命令获取esp-idf（git会自动创建esp-idf文件夹）

例如：进入目录D:\。使用cd命令

PS C:\Users\Augtons> cd d:\
PS D:\>

① 例如，获取4.3.2版本发行版。（在此文章发布时，此为最新的稳定版，可能将来会成为旧版）

PS D:\> git clone -b v4.3.2 --recursive https://github.com/espressif/esp-idf.git esp-idf-v4.3.2

git会自动创建esp-idf-v4.3.2文件夹

② 再如，获取master分支（通常不是发行版，也可能不是稳定版，如果你并不确定自己要使用哪个版本，而是仅仅是想要入门ESP32开发，建议使用此命令克隆master分支）

PS D:\> git clone --recursive https://github.com/espressif/esp-idf.git

git会自动创建esp-idf文件夹

这一步完成后，回到方法一的第3步“安装所需工具”即可！

（二）idf.py 基本操作使用

注意：使用idf.py之前请务必在esp-idf目录下用cmd执行export.bat，除非你设置了环境变量，否则每次重新打开cmd或者powershell都要这样！

① 创建一个名为NAME的工程

PS xxx\> idf.py create-project NAME

② 打开menuconfig 工程配置菜单

PS xxx\工程根目录> idf.py menuconfig

③ 编译

PS xxx\工程根目录> idf.py build

④ 烧录

#指定烧录端口，以COM3为例
PS xxx\工程根目录> idf.py -p COM3 flash

#自动检测端口（从最大的开始检测）
PS xxx\工程根目录> idf.py flash

⑤ 监视器（使用Ctrl+]退出监视器）

#指定监视端口，以COM3为例
PS xxx\工程根目录> idf.py -p COM3 monitor

#自动检测端口（从最大的开始检测）
PS xxx\工程根目录> idf.py monitor

⑥ 使用组合命令（同样使用Ctrl+]退出监视器）
idf.py的命令可以组合使用

如：编译+烧录+监视

#指定烧录 & 监视的端口，以COM3为例
PS xxx\工程根目录> idf.py -p COM3 build flash monitor 

#自动检测端口（从最大的开始检测）
PS xxx\工程根目录> idf.py build flash monitor

对于其他的功能，请使用--help打开帮助。如下
Commands:行之后即为idf.py所有命令。本文不再赘述

PS D:\> idf.py --help

Usage: idf.py [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

 ESP-IDF CLI build management tool. For commands that are not known to idf.py an attempt
 to execute it as a build system target will be made.

Options:
 --version                       Show IDF version and exit.
 --list-targets                  Print list of supported targets and exit.
 -C, --project-dir PATH          Project directory.
 -B, --build-dir PATH            Build directory.
 -w, --cmake-warn-uninitialized / -n, --no-warnings
                                 Enable CMake uninitialized variable warnings for CMake
                                 files inside the project directory. (--no-warnings is now
                                 the default, and does not need to be specified.) The
                                 default value can be set with the
                                 IDF_CMAKE_WARN_UNINITIALIZED environment variable.

 -v, --verbose                   Verbose build output.
 --preview                       Enable IDF features that are still in preview.
 --ccache / --no-ccache          Use ccache in build. Disabled by default. The default
                                 value can be set with the IDF_CCACHE_ENABLE environment
                                 variable.

 -G, --generator [Ninja|MinGW Makefiles]
                                 CMake generator.
 -D, --define-cache-entry TEXT   Create a cmake cache entry. This option can be used at
                                 most once either globally, or for one subcommand.

 -b, --baud INTEGER              Baud rate for flashing. The default value can be set with
                                 the ESPBAUD environment variable. This option can be used
                                 at most once either globally, or for one subcommand.

 -p, --port TEXT                 Serial port. The default value can be set with the
                                 ESPPORT environment variable. This option can be used at
                                 most once either globally, or for one subcommand.

 --help                          Show this message and exit.

Commands:
 all                    Aliases: build. Build the project.
 app                    Build only the app.
 app-flash              Flash the app only.
 bootloader             Build only bootloader.
 bootloader-flash       Flash bootloader only.
 build-system-targets   Print list of build system targets.
 clean                  Delete build output files from the build directory.
 confserver             Run JSON configuration server.
 create-component       Create a new component.
 create-project         Create a new project.
 efuse_common_table     Generate C-source for IDF’s eFuse fields.
 efuse_custom_table     Generate C-source for user's eFuse fields.
 encrypted-app-flash    Flash the encrypted app only.
 encrypted-flash        Flash the encrypted project.
 erase_flash            Erase entire flash chip.
 erase_otadata          Erase otadata partition.
 flash                  Flash the project.
 fullclean              Delete the entire build directory contents.
 gdb                    Run the GDB.
 gdbgui                 GDB UI in default browser.
 gdbtui                 GDB TUI mode.
 menuconfig             Run "menuconfig" project configuration tool.
 monitor                Display serial output.
 openocd                Run openocd from current path
 partition_table        Build only partition table.
 partition_table-flash  Flash partition table only.
 post_debug             Utility target to read the output of async debug action and stop
                        them.

 python-clean           Delete generated Python byte code from the IDF directory
 read_otadata           Read otadata partition.
 reconfigure            Re-run CMake.
 set-target             Set the chip target to build.
 show_efuse_table       Print eFuse table.
 size                   Print basic size information about the app.
 size-components        Print per-component size information.
 size-files             Print per-source-file size information.
 uf2                    Generate the UF2 binary with all the binaries included
 uf2-app                Generate an UF2 binary for the application only

（三）【全网独家】对开发环境的优化，使其更好与IDE耦合

我们知道，在之前我们使用idf.py之前都执行了一个export.bat。实际上，这个bat文件有扩充环境变量的行为，扩充之后，才能正常使用idf.py工具。

不幸的是，export.bat对环境变量的扩充并非永久的，这是乐鑫官方防止因为此扩充而影响到原本的环境变量。因此，乐鑫要求每次手动执行export.bat来临时扩充环境变量，这个扩充只能影响当前命令行窗口，窗口一旦关闭，下次使用又要执行export.bat来手动扩充。

这样做虽然有好处，但是由于此方案只对当前命令行窗口生效，因此，这不利于在IDE中使用ESP-IDF，因为IDE并没有命令行窗口这个概念。（即使你在IDE自带的终端中执行了export.bat，但IDE的其他服务如加载CMake项目等操作并不在你手动执行扩充的终端里执行。因此这套方案对IDE的支持并不现实）你可能曾经尝试在IDE中加载ESP-IDF工程，但是以失败告终，原因就在于此

网上的其他方法比如在Windows系统环境变量里加入export.bat扩充的那些路径，但是这样做缺点很明显。这样做是永久设置环境变量，因此会影响到其他地方。例如，你的电脑里有自己的Python环境，再将ESP-IDF内置的Python环境加入环境变量会冲突（系统只会使用相对靠前的路径）因此，这方法虽然可行，但是影响过大。

博主花费了一段时间，阅读esp-idf的cmake脚本源代码之后，分析出了一种更好的方法。

下面介绍这种全网首创的方法，锁定相关路径。

一、锁定Python路径

官方文档：https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-guides/build-system.html#python

① 方法一：编辑项目CMakeLists.txt

这是使用idf.py create-project <工程名>

cmake_minimum_required(VERSION 3.5)

include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(hello-world) # 这里是<工程名>

只需要在include之前加入下述语句(下文的路径是我安装ESP-IDF Tools时生成的python路径，请按照自己实际情况更改)

set(PYTHON "C:/Users/用户名/.espressif/python_env/idf4.3_py3.8_env/Scripts/python.exe")

set(python "C:/Users/用户名/.espressif/python_env/idf4.3_py3.8_env/Scripts/python.exe")

# 上文两个set的区别在python大小写上 (如'python'和'PYTHON')
# 因为版本不同，不能确定哪个一定正确。
# 建议两个全加上，或者加其中一个。
# 如果不行再换另一个

改好如下

cmake_minimum_required(VERSION 3.5)

set(PYTHON "C:/Users/用户名/.espressif/python_env/idf4.3_py3.8_env/Scripts/python.exe")

set(python "C:/Users/用户名/.espressif/python_env/idf4.3_py3.8_env/Scripts/python.exe")

include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(hello-world) #这里是<工程名>

② 方法二：永久法

打开esp-idf下的tools\cmake文件夹。
例如D:\esp-idf-v4.3.2\tools\cmake\

分别打开build.cmake和project.cmake，搜索set_default，找到 set_default(python "python") 或 set_default(PYTHON "python") 。并把后边引号中的python改成esp-idf内置的python的 绝对路径。
内置python的绝对路径在.espressif文件夹内

注意：不同版本的esp-idf中这句话的位置可能不同，甚至可能只在一个文件中出现。但是不用担心，只要保证把所有的地方找到并按下文操作即可

如果你的电脑里有vscode，可以直接用vscode打开esp-idf下的tools\cmake目录，直接搜索set_default再逐个点开检查即可。

参考上文 “(一) - 一 - 2 安装器安装过程”
或 “(一) - 二 - 3 —— 安装所需工具”

例如若路径为C:\Users\用户名\.espressif\python_env\idf4.3_py3.8_env\Scripts\python.exe
则

set_default(python "python")
	↓改为
set_default(python "C:/Users/用户名/.espressif/python_env/idf4.3_py3.8_env/Scripts/python.exe")
/******************/
set_default(PYTHON "python")
	↓改为
set_default(PYTHON "C:/Users/用户名/.espressif/python_env/idf4.3_py3.8_env/Scripts/python.exe")

请按照自己的实际情况来。

注意：这里的路径不要用反斜杠“\”，因为命令行会把这个反斜杠当成转义符。所以要么用"/"，要么用双反斜杠\\

二、锁定交叉编译工具链路径

打开esp-idf下的tools\cmake文件夹。
例如D:\esp-idf-v4.3.2\tools\cmake\

找到所有形如toolchain-esp**.cmake的文件，打开
在这里插入图片描述

以toolchain-esp32.cmake举例，文件很短，有如下几行

set(CMAKE_C_COMPILER 	xtensa-esp32-elf-gcc)
set(CMAKE_CXX_COMPILER 	xtensa-esp32-elf-g++)
set(CMAKE_ASM_COMPILER 	xtensa-esp32-elf-gcc)

我们也要将xtensa-esp32-elf-gcc等替换成其绝对路径，例如这个工具链可能在
C:\Users\用户名\.espressif\tools\xtensa-esp32-elf\esp-2020r3-8.4.0\xtensa-esp32-elf\bin\目录下

因此

set(CMAKE_C_COMPILER 	C:/Users/用户名/.espressif/tools/xtensa-esp32-elf/esp-2020r3-8.4.0/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc.exe)
set(CMAKE_CXX_COMPILER 	C:/Users/用户名/.espressif/tools/xtensa-esp32-elf/esp-2020r3-8.4.0/xtensa-esp32-elf/bin/xtensa-esp32-elf-g++.exe)
set(CMAKE_ASM_COMPILER 	C:/Users/用户名/.espressif/tools/xtensa-esp32-elf/esp-2020r3-8.4.0/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc.exe)

改好保存即可

其余的以此类推，其余的所有工具链都在C:\Users\用户名\.espressif\tools\下，按照文件名找即可，本文不在赘述。改好保存即可

注意：这里的路径不要用反斜杠“\”，因为命令行会把这个反斜杠当成转义符。所以要么用"/"，要么用双反斜杠\\

三、关于项目所针对的芯片型号

官方文档：https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-guides/build-system.html#selecting-idf-target

ESP-IDF构建项目时默认认为你在开发ESP32，因此如果你要开发诸如ESP32-S3等芯片时需要手动显示切换芯片Target

① 使用idf.py时

关于使用 idf.py 时，官方提供了方法

idf.py set-target <target>
# 如
idf.py set-target "esp32s2"

这样相当于执行了下述三条命令

清除 build 文件夹 (idf.py fullclean)
移除 sdkconfig 文件 (mv sdkconfig sdkconfig.old)[原理是移动]
根据选择的“目标”芯片配置项目 (idf.py -DIDF_TARGET=esp32 reconfigure)

但是，这却无法对支持 CMake 的 IDE 生效（如本文接下来要介绍的 CLion）
原因是上边第三条指令idf.py -Dxxxx中的-D可以理解为临时指定，而idf.py和IDE的编译产物不在同一位置（如 idf.py 在 ./build/ 下，CLion在 ./cmake-build-debug/）
但是他们的编译产物是一样的（设置相同的情况下）

② 使用 IDE时（如CLion）

使用CLion时要手动显示更改编译目标了

这里给出一种最方便的方法，其余方法留给读者在研究CMake时研究

cmake_minimum_required(VERSION 3.5)

# 不加这句默认为 'esp32'
set(IDF_TARGET "esp32s3")

include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(hello-world) #这里是<工程名>

那就是在include之前设置IDF_TARGET变量

（四）【全网独家】Clion IDE For Windows 下 ESP-IDF 编程环境搭建

本文默认大家已经成功安装Clion，安装方法自行查阅，很简单。本文不再赘述。

参考本文（二）idf.py基本操作使用，创建一个工程。
用Clion打开这个工程，选择加载CMake项目（无弹窗则自动加载）

加载过程中可能出现找不到cmake文件的错误，如下图。是环境变量中缺少IDF_PATH原因导致。可以按照以下方法完成修复。
在这里插入图片描述

下文之所以后边分了两种情况，是因为esp32的ESP-IDF和esp8266的RTOS SDK 都用到了这个IDF_PATH环境变量，可能会造成冲突。请读者根据自己的情况选择合适的方法。

【一】电脑里没有 ESP8266 RTOS SDK 且之后不打算使用RTOS SDK开发esp8266的，可永久指定IDF_PATH路径，一劳永逸

在这里插入图片描述

【二】电脑里已经安装过 ESP8266 RTOS SDK 或之后打算使用RTOS SDK开发esp8266的，并与ESP-IDF共存的，需要打开该工程根目录下的CMakeLists.txt，指定未找到的cmake文件的绝对路径

在这里插入图片描述
将前边的$ENV{IDF_PATH}替换成真实路径，例如

include(D:\esp-idf\tools\cmake\project.cmake)

或者，参考方法一，分别建立IDF32_PATH和IDF8266_PATH两个环境变量。分别改成esp-idf路径和esp8266-rtos-sdk的路径。之后在此CMakeLists.txt改成如下即可

include($ENV{IDF32_PATH}\tools\cmake\project.cmake)

如果你是按照前文所述方法的安装的esp-idf，则不再会有其他的错误，如果仍然有错误，欢迎评论区留言或私信。祝大家搭建顺利！