ESP-IDF/VSCode安装和使用（ESP32开发环境）

ESP-IDF/VSCode安装和使用

1 概述

   在国产MCU中，众鑫的ESP-32系列对开发者是比较友好的，除了有较为丰富的外设接口（例如，对WiFi和蓝牙的支持）外，它的开发环境相对来说也是优秀的。
   众鑫提供的开发环境是ESP-IDF，它可以以字符界面的方式独立运行，也可以作为插件，在集成开发环境（如VSCode）下运行。本文总结了在Windows、MacOS 和 Ubuntu 几个不同操作系统环境下安装和配置 ESP-IDF/VSCode的过程，供读者参考。

2 Windows环境下的安装

1.1 下载安装ESP-IDF

   ESP-32的生产厂家众鑫提供了一个字符界面的开发环境，这就是ESP-IDE。但如果需要用GUI IDE进行ESP-32系列的应用开发就必须将ESP-IDE插件安装到集成开发环境中，当前中鑫推荐的环境是VSCode。
   可以用两种不同的方式安装ESP-IDF/VSCode环境：一是先安装VSCode，然后在VSCode中下载和安装ESP-IDF插件；二是先安装ESP-IDF开发工具，然后安装VSCode，再在VSCode下安装ESP-IDF插件，安装插件的过程中就不用再下载了。
   在安装VSCode前下载安装ESP-IDF环境有两个好处：

• • 可以缩短VSCode插件安装时间；
• • 能够了解手动安装过程。

   通过在Ubuntu上的自动安装可以知道，两者安装以后的使用是没有差别的。
   ESP-IDF的Windows安装软件（installer）和安装包的官方下载地址是：https://dl.espressif.cn/dl/esp-idf/。这个网页包含在线安装软件和多个版本带安装软件的离线安装包，如下图所示。

   Windows下的安装过程比较简单，可以选择“Universal Online Installer” 一项进行在线安装。Installer不仅安装ESP-IDF本身，还安装所有的依赖，按官方文档的描述，它安装以下模块或组件：

• • 内置的 Python
• • 交叉编译器
• • OpenOCD
• • CMake 和 Ninja 编译工具
• • ESP-IDF

   安装完成后形成的是一个容器环境，直接用Windows CMD或PowerShell 并不能运行ESP-IDF，而是需要使用安装生成的ESP-IDF xxx CMD或ESP-IDF xxx PowerShell来运行，其中xxx是ESP-IDF的版本号，例如ESP-IDF 5.0.1 CMD。在这两个ESP-IDF界面中，CMD和PowerShell的原有功能仍然保持。

1.2 下载安装VSCode

   可以直接到微软官网上下载。但在下载安装时，遇到下载速度极慢，多次重新下载也无法成功的问题。网上给出了使用国内镜像（vscode.cdn.azure.cn）解决这个问题的方法，详见网页：https://blog.csdn.net/ZoeCXY/article/details/124391379。
   应当注意的是，在VSCode的官网上，右键点下载文件的链接并不是真正的链接，要如上述网页介绍的那样，先点保存，在从浏览器的下载对话框中点右键，在弹出的菜单中选“复制下载链接”找到正确的下载链接（见下图），然后按照上面网页所述，拷贝到浏览器进行修改后访问。如果连下载对话框都进不了，那就彻底歇菜，只好等待一段时间再试。

   下载后的文件是Windows执行文件。Windows下的VSCode的安装比较简单，官网上介绍得比较详细，整个过程基本上按提示进行即可，也可以参见网页：https://blog.csdn.net/Zhangguohao666/article/details/105665412/，这里不再赘述。

1.3 配置VSCode环境

   配置VSCode环境的第一步是安装ESP-IDF插件，步骤如下：

• • 如下图所示，在VSCode的边栏打开插件图标，这时会显示已经安装和推荐安装的各种插件；
    
• • 在该部分上部的搜索框中，输入ESP-IDF（见第一个红框），如下图所示，就会出现所有符合条件的可选插件；
    
• • 选择的插件是Espressif IDF（见图中的第二个红框），如果该插件还没被安装，则其下面会出现一个“安装”或“install”按钮（见图中第三个红框，图中的ESP-IDF已经安装）；
• • 按“安装”按钮，进入安装过程，安装完成后Espressif IDF插件下面的“安装”就变成了齿轮图标；
• • 然后进行配置，在VSCode菜单中选“查看”-“命令面板”，出现以下图中的界面；

• • 在命令面板的下拉菜单中找到ESP-IDF:Configure ESP-IDF extension，点击、回车，启动配置界面如下图：

• • 各种文档中介绍，如果系统中没有ESP-IDF，就不会有“USE EXISING SETUP”，但这次手动安装并且启动成功以后，仍然没有这一项；
• • 其实无论有没有ESP-IDF，都可以选“EXPRESS”项进行安装，这时出现下列界面；
• • 点击“Select download server”下拉菜单，选“Espressif”，不选“Github”，因为后者速度很慢；
• • 由于已经手动安装过ESP-IDF的字符界面版，所以“Select ESP-IDF”下拉菜单选择“Find ESP-IDF in your system”；
• • 点击“Install”，然后是漫长的等待，出现以下图中界面表示安装完成。
    

3 Ubuntu和MacOS下的安装

3.1 要点

   与Windows 下的安装相比，Ubuntu和MacOS的安装有些方面不同。本节主要描述它们与Windows不同的方面。而Ubuntu和MacOS安装的差别就更小一些，其中包括：

• • 二者安装Cmake和ninja及其他依赖的过程和内容不同，MacOS使用：brew install cmake ninja dfu-util命令；而Unbutu则安装更多的东西，使用sudo apt-get install git wget flex bison gperf python3 python3-venv python3-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0命令。
• • 有些模块可能只有Intel CPU的版本，所以，在Apple M1上安装时，要下载Apple Rosetta 2。

   官方网站给出的手动下载安装指南还是比较靠谱的，（链接：https://docs.espressif.com/projects/esp-idf/zh_CN/v5.0.1/esp32c3/get-started/linux-macos-setup.html）但有两个问题需要注意：

• • 要理解指南中每个步骤的作用，结合自己环境的情况有所取舍，例如：系统中已经安装了Python3就没有必要执行安装Python的步骤；
• • 大部分安装问题都是由于软件下载源速度慢引起的超时失败，所以如果超时失败，可以再次启动安装，多试几次就可以成功。

3.2 在 Ubuntu 上的安装

   在Ubuntu下，没有手动安装字符界面的ESP-IDF，而是下载VSCode后，在VSCode中下载安装和配置ESP-IDF。
   下载安装时，遇到以下问题：

• • 官网下载速度极慢，甚至多次尝试无法下载，解决方法：
• • • 网上给出用国内镜像的方式进行下载，可以解决下载速度慢的问题，参见：https://blog.csdn.net/ZoeCXY/article/details/124391379；
• • • 应当注意的是，在官网上，右键点下载文件的链接并不是真正的链接，要如上述网页介绍的那样，先点保存，在从浏览器的下载对话框中点右键进入属性找到正确的下载链接，如果保存都进不了，那就彻底歇菜，只有等待一段时间再行下载；
• • ESP-IDF插件的安装和配置，一般的安装过程和Windows下相仿，但出现和解决了一些问题：
• • • 如下图，在安装插件选快速下载（第一项express选项）时，不选择github源而使用Espressif源，这样下载速度会快很多，如果没有手动安装和配置过ESP-IDF，不会出现第三项；

• • • 如果上次插件安装失败而重新进入时，仍然选择“EXPRESS”安装，进入后，在“Select ESP-IDF version”下拉框中选择“Find ESP-IDF in your system”一项，这样不用清除原有已安装的内容，可以继续未完成的安装，安装软件会自动检测已经安装成功的项目，不会重复安装；
• • • 如果未安装成功后，重新进入时，要选择不同的版本号，系统会提示要清除ESP-IDF的安装目录后才能再次安装；
• • • 最后一步配置Python虚拟环境时，多次重复未能成功，后发现是卡在pip升级这个步骤上，后修改pip源到阿里服务器直接升级后，再进入VSCode安装解决了此问题。

3.3 在 MacOS M1 上的安装

   在MacOS M1上，首先手动安装了ESP-IDF，然后安装配置VSCode。其步骤的大部分已经在Windows和Ubuntu的描述中提及，需要补充的内容如下：

• • 如前所述，M1在安装ESP-IDF前必须先装Rosetta 2；
• • 手动安装ESP-IDF前，要先下载HomeBrew，因为系统中是没有这个程序的，HomeBrew的网页url：https://brew.sh/index_zh-cn，按照网页上提示的命令，在MacOS终端下执行即可安装，没有遇到困难，也没有卡顿的现象；

   手动安装步骤大致按照官方网页上的指南进行，包括如下操作：

• • 在$HOME目录下生成esp子目录；
• • 用以下命令下载ESP-IDF：
    git clone -b v5.0.1 --recursive https://github.com/espressif/esp-idf.git
• • 用以下三条命令将下载源指向Espressif后下载安装，以加快工具的下载速度：
    cd ~/esp/esp-idf
    export IDF_GITHUB_ASSETS=“dl.espressif.com/github_assets”
    ./install.sh all
• • 用以下命令设置环境变量，注意：开始的点后面要带一个空格：
    . $HOME/esp/esp-idf/export.sh
• • VSCode的安装和设置与前面的Windows和Ubuntu无异，配置插件时，遇到超时，多次重复安装过程后才完成。

4 示例程序的生成、编译和下载

4.1 安装插件以后的VSCode环境

   这里主要涉及的是在VScode下的示例程序生成、编译和下载操作。未涉及自行生成的程序。终端界面的操作按照官方网站给出的说明进行，基本没有遇到太多问题。在各种环境下的程序生成、编译和下载的过程基本上是相同的。
VSCode及其ESP-IDF插件安装配置成功以后，打开VScode它的下方会出现如下图的工具条：

   常用的ESP-IDF操作都可以在这个工具条上启动，这些操作也在命令面板上输入或选择命令启动。
   工具条中，有关ESP-IDF的图标从左到右为：

• • 下载端口选择；
• • 目标器件选择；
• • 当前项目；
• • 项目设置；
• • 清除编译连接结果；
• • 编译连接（make）；
• • 下载方式选择（JTAG、UART等）；
• • 程序下载到目标板；
• • 终端进入ESP-IDF监控界面；
• • 顺序进行编译连接、下载和进入监控界面；
• • 打开终端。

4.2 操作步骤

   示例程序的编译和下载包括如下步骤：

• • 在主菜单中点击“视图”-“命令面板”，启动命令：“ESP-IDF: Show Example Projects”，这时，会弹出示例程序列表界面，如下图所示；
    
• • 双击所需要的样例名称，即可生成基于样例的ESP-IDF项目；
• • 项目生成后，设置下载串口、目标器件、下载方式等常用参数，方法是点击图标，打开命令面板及相应菜单，选择正确项目即可；
• • 点击下方的编译连接图标，完成编译连接；
• • 点击下方的下载编程图标，对目标板编程，编程结束后，目标板自动进入运行；
• • 点击下方的进入ESP-IDF监控图标，可以监控目标板的log及串口输出。

   关于终端界面的开发环境，有以下要注意的方面：

• • 如1.1节所述，Windows下必须用安装形成的ESP-IDF xxx CMD或ESP-IDF xxx PowerShell启动和使用ESP-IDF；
• • 在Ubuntu和MacOS系统下，执行ESP-IDF前，必须先设置环境变量，方法是执行命令：. $HOME/esp/esp-idf/export.sh，由于ESP-IDF是一个虚拟环境，所以不建议将命令放到启动shell文件中。

4.3 遇到的问题

   在测试和使用样例程序时，遇到的问题及其解决办法如下：

• • 在下载编程时，有时会发生无法下载的情况，这时可以重新拔插目标板USB连接线恢复连接；
• • 在Ubuntu环境下，下载烧录时报串口错误，问题的原因是用户没有使用串口的权限，可以用两种方法解决这个问题：a. 将用户加入dailout组（group），命令是：sudo usermod -a -G dialout user_name，然后重启操作系统生效；b. 将相应的串口权限改为666，例如：sudo chmod 666 /dev/ttyUSB0；
• • VSCode中，直接拷贝示例项目到工程目录下，编译时会出现找不到头文件的问题（并不影响编译烧录，但影响程序的跟踪查找），解决方法有两个：
• • 在在视图 – 命令面板中选“IDF: Show Example Projects”，如3.2节所述，导入示例项目；
• • 如果已经直接复制了项目，可以在视图 – 命令面板中选择执行“IDF: Add vscode configuration folder”命令即可解决（见下图，ESP-IDF：添加vscode配置文件夹）；

5 相关网页链接

• ESP32主页，可以浏览器件、开发板等。在顶端的菜单中，选择产品 – 开发板 – 概览，可以转向开发板入门的文档（下面的2.项链接） ：
  https://www.espressif.com.cn/zh-hans/products/socs/esp32
• 开发板概览网页，在此网页上可以浏览众鑫的各种官方开发板，点击相应开发板项目右侧的“入门指南”可以进入开发板入门的网页（下面的3.项链接）：
  https://www.espressif.com.cn/zh-hans/products/devkits
• ESP-IDF开发板入门（此为ESP32-C3的链接，在网页左侧选择不同器件可进入不同的链接，除硬件以外，内容大同小异），该网页可以转向ESP-IDF的手动下载和配置方法的网页（下面的4.项和6项链接）：
  https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32c3/get-started/index.html
• Windows平台的ESP-IDF的手动下载操作指南，可以转向Windows安装软件和安装包的下载网页（下面的5.项链接）：
  https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32c3/get-started/windows-setup.html
• Windows平台的ESP-IDF安装程序和安装包下载网页：
  https://dl.espressif.cn/dl/esp-idf
• Linux/MacOS平台的ESP-IDF手动下载操作指南：
  https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32c3/get-started/linux-macos-setup.html
• VSCode中，ESP-IDF的下载以及插件安装、配置指南：
  https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/tutorial/install.md
• VSCode下载速度慢的解决方法：
  https://blog.csdn.net/ZoeCXY/article/details/124391379
• VSCode主页：
  https://code.visualstudio.com/
• HomeBrew主页：
  https://brew.sh/index_zh-cn
• 《ESP32-C3 物联网工程开发实战》一书的GitHub和Gitee网址，用git clone命令下载。在Windows上未下载成功，MacOS和Ubuntu均无问题，GitHub速度太慢，用Gitee比较快：
  GitHub: https://github.com/espressif/book-esp32c3-iot-projects
  Gitee: https://gitee.com/EspressifSystems/book-esp32c3-iot-projects