目录

基于VSCode搭建ESP-IDF与ESP-ADF开发环境

乐鑫官方提供的VSCode插件Espressif IDF实在是称不上好用。实际上,基于VSCode手动搭建的ESP-IDF的开发环境可以获得与插件几乎相同的使用体验。

获取ESP-IDF及ESP-ADF

ESP-IDF可以在乐鑫官方的GitHub仓库中获取,ESP-ADF也可以从GitHub仓库中获取。ESP-ADF是基于ESP-IDF的一系列与音频相关的功能扩充包,因此若不需要对音频功能进行开发,可以只下载ESP-IDF,后文中出现的有关ESP-ADF的操作也可以忽略。

git clone --recursive -b v4.3 https://github.com/espressif/esp-idf.git
git clone --recursive -b v2.3 https://github.com/espressif/esp-adf.git

在本文中,ESP-IDF的安装路径为D:\Programs\esp-idf,版本为v4.3,ESP-ADF的安装路径为D:\Programs\esp-adf,版本为v2.3

配置ESP-IDF

提示
在开始之前,强烈建议您安装Windows Terminal来提升PowerShell的体验。

除了ESP-IDF源码本身之外,为了配置及编译工程,还需要安装工具链等工具,安装这些工具的脚本已经包含在了ESP-IDF源码中。这些工具默认将安装在用户文件夹下的.espressif目录中,需要占用超过1GB的空间。若不希望在系统盘存放它们,可以在运行安装脚本之前,设置环境变量IDF_TOOLS_PATH为存放工具的目录。

设置环境变量

在系统设置中使用GUI设置环境变量的操作,在此不再赘述。除此之外,也可以通过修改PowerShell的profile.ps1文件来达到仅在PowerShell内对环境变量进行修改的效果。该文件的作用类似于Linux下的.bashrc文件,可以配置在PowerShell启动时要执行的命令。

profile.ps1文件在用户文件夹的文档\WindowsPowerShell目录中,完整路径为C:\Users\<User>\Documents\WindowsPowerShell\profile.ps1。若WindowsPowerShell目录以及profile.ps1不存在,请手动创建它们。

设置环境变量的命令为$env:NAME=VALUE。例如,若要将存放ESP-IDF工具的目录设置为D:\Programs\esp-tools,可以向profile.ps1中加入此命令:

$env:IDF_TOOLS_PATH="D:\Programs\esp-tools"

在配置好环境变量后,进入存放ESP-IDF的路径,打开PowerShell并执行install.ps1即可进行工具的下载与安装。

安装完毕后,还需要设置编译工程的环境,ESP-IDF同样使用脚本来完成这一操作。在PowerShell中执行ESP-IDF目录下的export.ps1即可自动配置编译环境。配置完成后,在这个终端窗口内就可以编译ESP-IDF的工程了。

cd examples\get-started\hello_world
idf.py build

在编译时,每次重新打开PowerShell都需要执行export.ps1来配置编译环境。为了简化操作,可以将执行脚本的操作添加到前述的profile.ps1中,让每次打开PowerShell时自动执行该脚本。将profile.ps1的绝对路径加入之前设置环境变量的下一行,即可自动配置环境变量并使用此变量来配置编译环境。

$env:IDF_TOOLS_PATH="D:\Programs\esp-tools"
D:\Programs\esp-idf\export.ps1

https://img.yuanze.wang/posts/esp-idf-vscode-tutorial/auto-export.jpg
自动配置环境

在VSCode中开发

注意
请首先在VSCode中安装C/C++插件。

在VSCode中打开项目文件夹,此处以esp-idf\examples\get-started\hello_world工程为例。按Ctrl+`打开VSCode中的终端,此时终端中应该会自动配置编译环境,并切换到当前项目的目录中。

在配置之前,首先需要对工程进行一次编译。

idf.py build

编译完毕后,编译器会自动在build路径下生成编译指令文件,该文件中包含了工程所有的头文件信息,C/C++插件可以使用这个文件中的信息来配置代码高亮及跳转功能。

技巧
此文件在CMake配置阶段生成,只要工程的CMakeLists.txt无误便可以完成配置。即使工程编译失败,该文件也可以被正确的创建。

编译指令文件生成之后,打开任意一个C语言文件,稍等一会右下角便会弹出

是否要使用compile_commands.json文件为此文件夹自动配置IntelliSense?

的提示,选是即可。之后,VSCode会弹出选项,询问要使用哪一个compile_commands.json文件来配置包含路径,此处选择build/compile_commands.json即可,该文件为用户app的编译指令文件,另一个则为bootloader的编译指令文件。

https://img.yuanze.wang/posts/esp-idf-vscode-tutorial/configure-compile-commands.jpg
使用编译指令文件自动配置包含路径

配置完成编译指令文件后,可以发现还有一些代码出现了红色波浪线。这是因为除了IDF的包含路径之外,一些C语言的标准库,例如printf函数等,是随着编译器同时分发的,还需要配置编译器的路径才能让C/C++插件找到这些标准库的头文件。

点击VSCode右下角的C/C++配置按钮(默认状态显示的是Win32),选择编辑配置(UI),进入IntelliSense配置菜单。在编译器菜单中,输入编译器可执行文件的路径即可。需要注意的是,编译器的路径需要根据所使用的芯片型号对应的编译器路径进行更改。对于ESP32来说,其编译器可执行文件为ESP-IDF工具路径下的tools\xtensa-esp32-elf\esp-2020r3-8.4.0\xtensa-esp32-elf\bin\xtensa-esp32-elf-gcc.exe。将该路径中的反斜杠\全部更改为正斜杠/或双反斜杠\\后,复制到VSCode设置项的输入框即可。

配置完成后,只要不更改编译器的安装路径,只需要复制工程路径下.vscode\c_cpp_properties.json文件到新的工程根目录中,便可以自动完成上述配置。

此处提供一个已经配置完毕的c_cpp_properties.json文件,只需要更改编译器路径compilerPath并放置到.vscode\下即可直接被VSCode读取,可以免去前述的配置步骤。

{
    "configurations": [
        {
            "name": "ESP32",
            "includePath": [
                "${workspaceFolder}/**"
            ],
            "cStandard": "c11",
            "compilerPath": "D:/Programs/esp-tools/tools/xtensa-esp32-elf/esp-2020r3-8.4.0/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc.exe",
            "compileCommands": "${workspaceFolder}/build/compile_commands.json"
        }
    ],
    "version": 4
}

添加ESP-ADF支持

ESP-ADF是作为ESP-IDF的扩充包发行的。按照前文配置好ESP-IDF并获取ESP-ADF后,只需要将ADF_PATH加入环境变量中即可使用ESP-ADF提供的扩充功能。

此处使用PowerShell的profile文件来添加环境变量,完整配置后的profile.ps1文件内容如下。

$env:IDF_TOOLS_PATH="D:\Programs\esp-tools"
$env:ADF_PATH="D:\Programs\esp-adf"
D:\Programs\esp-idf\export.ps1

实用操作

完全配置完毕后,便得到了一个可以开发ESP32项目的VSCode环境。只要使用VSCode打开项目文件夹,便可以使用代码高亮以及代码补全功能,并且在嵌入式终端中可以使用完整的idf.py工具。

idf.py工具的指令支持同时输入多个,若输入多个指令,idf.py将会按照正确的顺序执行它们。对于一个新打开的工程,可以使用

idf.py -b 921600 build flash monitor

来启动idf.py工具,此时该工具将会编译并使用921600波特率烧录,在烧录完毕后会自动启动串口监视器。按下Ctrl+]可以退出监视器。在终端中监视器保持打开的时候,若对代码做出了编辑,可以保存代码后,在终端窗口中按下Ctrl+T激活菜单后,再按Ctrl+A一键重新编译、重新烧录app并继续进行串口监视,也可以按下Ctrl+R来复位芯片。

https://img.yuanze.wang/posts/esp-idf-vscode-tutorial/develop-esp32-in-vsode.jpg
在VSCode中进行ESP32开发

在VSCode内置终端中运行menuconfig
若需要在VSCode内置终端中运行menuconfig,则需要注意由于VSCode默认的按键映射的问题,方向键在menuconfig中是失效的,只能使用vim风格的H/J/K/L键来进行←/↓/↑/→的导航操作。