跳到主要内容

第1节 搭建环境

本节介绍 ESP-IDF 的基础概念，并演示如何在 VS Code 中搭建 ESP32 官方开发框架(ESP-IDF)的开发环境，为后续项目开发奠定基础。

1. 什么是 ESP-IDF？​

ESP-IDF (Espressif IoT Development Framework) 是乐鑫官方推出的物联网开发框架，是 ESP32、ESP32-S、ESP32-C、ESP32-H 和 ESP32-P 系列芯片的官方开发框架。

它基于 C/C++ 语言，提供了完整的软件开发工具链，包括编译器、调试器、烧录工具等，让开发者能够充分发挥 ESP32 系列芯片的强大功能。

ESP-IDF

官方仓库：https://github.com/espressif/esp-idf

2. 为什么选择 ESP-IDF？​

许多开发者通过 Arduino 或 MicroPython 平台入门 ESP32，这些平台非常适合快速原型验证和简单的项目。然而，当需要开发更复杂、更稳定、性能更强的商业级产品时，ESP-IDF 是专业开发的首选。它提供了更深层次的硬件控制、更优的性能表现，以及安全启动和 OTA 固件升级等生产级功能。

ESP-IDF 的核心优势：

  • 官方优先支持：作为乐鑫官方核心开发框架，ESP-IDF 拥有最高的维护和适配优先级。新芯片、新功能和新标准（如 Matter）通常会首先在 ESP-IDF 中实现，开发者能够第一时间体验和应用最新技术。
  • 内置 FreeRTOS 实时操作系统：ESP-IDF 集成了 FreeRTOS 内核，支持多任务并发和实时调度。开发者可以轻松创建多个独立任务（如 Wi-Fi 连接、传感器采集、界面刷新等），实现复杂的物联网应用。
  • 底层可控性强，功能全面：ESP-IDF 提供对硬件资源和底层 API 的全面访问，适合需要高级功能、底层优化和复杂项目的开发者。相比 Arduino 等方式，开发者可以灵活配置系统参数、优化性能，并实现更复杂的功能。
  • 高性能与组件化架构：ESP-IDF 支持以“组件”方式组织代码，开发者可通过 ESP Registry 组件管理平台，便捷地查找、集成和维护第三方或官方组件，提升开发效率和项目可维护性。
  • 适合量产和商业化产品开发：ESP-IDF 支持 OTA 升级、安全启动、Flash 加密、分区管理等功能，便于产品的量产部署和后期维护，满足商业化产品对安全性和可维护性的高要求。

3. 安装 ESP-IDF 开发环境​

ESP-IDF 主要开发方式

用 ESP-IDF 开发 ESP32 主要有以下几种方式：

  • ESP-IDF 命令行工具：通过官方提供的安装器或脚本设置命令行环境，使用 idf.py 工具进行项目的配置、编译、烧录和监控。搭配任意文本编辑器编写代码。
  • Eclipse 插件 (Espressif-IDE)：基于 Eclipse CDT 的集成开发环境，内置 ESP-IDF 工具链和插件，支持项目创建、编译、烧录、调试、监视等一站式开发体验。适合有一定嵌入式开发经验、习惯使用 Eclipse 的用户。
  • VS Code 插件：在 Visual Studio Code 编辑器中安装乐鑫官方 ESP-IDF 扩展，集成了环境安装、项目管理、编译、烧录、监视、调试等全部功能。支持一键配置 ESP-IDF 及相关工具链。
信息

我们推荐使用 VS Code + ESP-IDF 插件 的方式，这是目前最主流且对新手最友好的方法。需要离线安装请参考 此教程。

备注

以下环境设置适用于 Windows 10/11 系统，Mac/Linux 用户请参考 官方说明。

3.1 安装 Visual Studio Code​

  1. 下载并安装 Visual Studio Code。

  2. 安装时建议勾选 “通过 Code 打开操作添加到 Windows 资源管理器文件上下文菜单”。

3.2 安装 ESP-IDF 扩展​

  1. 在 VS Code 中，通过点击 VS Code 侧边活动栏中的 扩展图标 (或使用快捷键 Ctrl + Shift + X) 来打开 扩展 视图。

  2. 然后，搜索 ESP-IDF 扩展并安装。

    在 VS Code 中搜索并安装 ESP-IDF 扩展

3.3 运行快速配置向导​

  1. 安装扩展后，VS Code 左侧活动栏中会出现 Espressif 图标 图标，点击该图标可查看 ESP-IDF 扩展的基本命令列表，在 Advanced 中选择 配置 ESP-IDF 扩展。

    选择“配置 ESP-IDF 扩展”

  2. 选择 "Express" 进入快速配置模式：

    选择快速配置模式

  3. 根据需求修改以下选项。

    ESP-IDF 扩展快速配置模式选项

    • 选择下载服务器：
      • Espressif：使用乐鑫中国服务器，下载速度更快。
      • Github：使用 GitHub 官方发布链接。
    • ESP-IDF 版本：通常根据开发板要求选择对应版本，如无特殊要求建议使用最新的正式版本。对于本教程，建议 Espressif IDF 版本 ≥ v5.5。
    • ESP-IDF 仓库安装地址：建议使用默认地址，或使用纯英文路径且路径中不包含空格。
    • ESP-IDF 工具安装地址：建议使用默认地址，或使用纯英文路径且路径中不包含空格。
      注意

      要注意 ESP-IDF 仓库安装地址 与 ESP-IDF 工具安装地址 不能是相同目录。

  4. 点击 Install 开始安装。你将看到一个显示安装进度的页面，包括 ESP-IDF 下载、ESP-IDF 工具下载安装以及 Python 虚拟环境创建的进度状态。

    安装进度

  5. 如果安装正确，你会看到所有设置已配置完成的提示，即可开始使用该扩展程序。

    安装成功

    注意

    如果 ESP-IDF 安装失败或需要重新安装，可以尝试删除 C:\Users\%Username%\esp 和 C:\Users\%Username%\.espressif 文件夹后重试。

4. VS Code ESP-IDF 插件界面概览​

打开 ESP-IDF 项目后，ESP-IDF 插件加载完成时，底部会显示工具栏，如图所示：

VS Code 用户界面底部工具栏说明

  • ① ESP-IDF 版本：显示并切换当前项目使用的 ESP-IDF 版本。当项目使用特定版本时，可通过此功能进行切换。
  • ② 选择烧录方式：选择用于烧录项目命令的烧录方法，可选择 DFU、JTAG 或 UART 接口。
  • ③ 选择要使用的端口：选择用于 ESP-IDF 任务（如烧录或监视设备）的串口。
  • ④ 设置乐鑫设备目标：该命令为当前项目设置目标 (IDF_TARGET)，效果等同于 idf.py set-target。在此选择对应的芯片型号。
  • ⑤ SDK 配置编辑器：启动 UI 界面进行 ESP-IDF 项目设置。该命令效果等同于 idf.py menuconfig。
  • ⑥ 彻底清理：删除当前 ESP-IDF 项目的构建目录。
  • ⑦ 构建项目：使用 CMake 和 Ninja-build 来构建项目。
  • ⑧ 烧录项目：将当前项目生成的二进制文件烧录至目标设备。
  • ⑨ 监视设备：启动计算机与乐鑫设备之间的串行通信。效果等同于 idf.py monitor。
  • ⑩ 调试：启动调试功能。
  • ⑪ 构建、烧录和监视：用于构建项目、将二进制程序写入设备，并启动监视终端，效果类似于 idf.py build flash monitor。
  • ⑫ 打开 ESP-IDF 终端：打开终端并激活 IDF_PATH 和 Python 虚拟环境。

5. 安装 C/C++ 语言扩展​

对于代码导航和 C/C++ 语法高亮，推荐使用 Microsoft C/C++ 扩展。

  1. 在 VS Code 中，通过点击 VS Code 侧边活动栏中的 扩展图标 (或使用快捷键 Ctrl + Shift + X) 来打开 扩展 视图。

  2. 然后，搜索 C/C++ Extension Pack 扩展并安装。

    在 VS Code 中搜索并安装 C/C++ 扩展

6. 附录：核心工具链概览​

ESP-IDF 的开发流程背后，是由一系列工具支撑的。这里做个简单介绍，让你有个初步印象：

  • idf.py

    ESP-IDF 的顶层命令行工具。它为开发者提供了一个统一、便捷的接口，封装了底层的构建系统（CMake）、编译工具（Ninja）、烧录工具（esptool.py）和调试工具。

    常用命令预览：

    • 创建新项目： idf.py create-project <project name>
    • 选择目标芯片： idf.py set-target <target>
    • 启动图形配置工具： idf.py menuconfig
    • 构建项目： idf.py build
    • 烧录项目： idf.py flash

  • Kconfig / menuconfig

    源自 Linux 内核的组件配置系统。ESP-IDF 使用 Kconfig 机制来管理项目中大量的可配置选项。开发者通过运行 idf.py menuconfig 命令，可以启动一个基于文本的用户界面（TUI），在其中启用或禁用特定组件、配置网络参数、调整日志等级等。所有配置项最终会保存在项目根目录下的 sdkconfig 文件中，并以宏定义的形式在编译时提供给源代码使用。

  • CMake

    一个开源的、跨平台的自动化构建系统。在 ESP-IDF 中，它负责解析项目中的 CMakeLists.txt 文件，管理源代码、组件依赖关系、编译器选项和链接器脚本，最终生成特定构建工具（如 Ninja）所需的构建指令。

  • Ninja

    一个专注于速度的小型构建系统。在 ESP-IDF 中，CMake 在配置阶段生成构建规则后，默认由 Ninja 来高效地执行这些规则。Ninja 的主要优势在于其极快的增量构建速度，它能精确判断哪些文件自上次编译后发生了更改，并只重新编译这些文件，从而显著缩短开发周期中的编译时间。

  • esptool.py

    与乐鑫芯片 ROM Bootloader 通信的 Python 工具。它的核心功能包括：将编译生成的固件二进制文件（.bin）烧录到芯片的 Flash 中、读取芯片信息（如 MAC 地址）、擦除 Flash 以及进行其他低级别的 Flash 读写操作。idf.py flash 命令在底层就是调用了 esptool.py 来完成实际的烧录任务。

7. 参考链接​

最后由 wulu 于 更新