第2节 运行示例

重要提示：关于开发板的兼容性

本教程的核心逻辑适用于所有 ESP32 开发板，但所有操作步骤均以 微雪 ESP32-S3-Zero 迷你开发板 为例进行讲解。如果您使用其他型号的开发板，请根据实际情况修改相应设置。

信息

在按照本指南操作之前，需要在 VS Code 上安装 ESP-IDF 扩展并配置好开发环境。如果你还未完成，请按照以下指南进行安装：

• ESP-IDF 入门教程 - 第1节 环境搭建

本节将基于 ESP-IDF 官方的 "Hello World" 与 "Blink" 示例，帮助熟悉 ESP-IDF 项目结构，并演示在 Visual Studio Code(VS Code) 中配置、构建、烧录和监视的完整开发流程。

1. Hello World 示例

我们将从 "Hello World" 示例开始，此程序的功能是在设备的串行监视器上输出 "Hello, world!" 信息。

1.1 打开示例

1. 打开 VS Code，点击图标启动 ESP-IDF 扩展。在 "Advanced" 选项中点击 "显示示例项目"。

   

2. 选择 ESP-IDF 版本。

   

3. 在示例列表中的 "get-started" 分类下选择 "hello_world"。然后，点击 "Select location for creating hello_world project" 选择项目存放文件夹。

   ESP-IDF 扩展将自动复制示例代码到指定位置并打开新项目。

   注意

   项目存放路径中不要包含空格、中文和特殊字符。

   

1.2 项目结构

项目创建完成后，你能看到如下的核心文件和文件夹结构：

hello_world/
├── CMakeLists.txt
├── pytest_hello_world.py
├── main
│   ├── CMakeLists.txt
│   └── hello_world_main.c
└── README.md

• main/：项目的主代码目录，也是 ESP-IDF 默认的主组件。
  • hello_world_main.c：项目的 C 语言源文件，包含了程序的主体逻辑和入口函数 app_main。
  • CMakeLists.txt：组件级构建脚本。定义该组件的源文件、包含路径等，供构建系统编译链接。
• CMakeLists.txt （项目根目录）：项目级构建脚本。声明这是一个 ESP-IDF 项目并包含子目录等信息。在此定义了项目名称（例如 project(hello_world)）。

项目构建后会自动生成：

• build/：由构建系统自动生成的目录。其中包含了编译过程中产生的所有中间文件、目标文件以及最终生成的固件二进制文件（.bin）。
• sdkconfig：项目配置文件。通过 menuconfig 修改配置（如 Wi-Fi、日志等级等）后，相关设置会保存到此文件中。首次构建或配置时自动生成。避免手动修改 sdkconfig，以免破坏配置间的依赖关系。

1.3 配置

在构建和烧录之前，我们需要设置目标硬件和连接方式。VS Code ESP-IDF 扩展在底部状态栏提供了 集成工具栏，可以直接在工具栏中进行设置。

1. 点击 选择烧录方式：选择 UART 接口。

   

2. 点击 选择串口：将 ESP32 开发板连接到电脑。点击端口号，从列表中选择开发板对应的串口。

   • 提示：如果不确定是哪一个，可以拔下开发板再插上，看看哪个端口号是新出现的。

   • 故障排查：如果未能找到新端口，请尝试手动进入下载模式：按住 “BOOT” 按钮，同时插入 USB 数据线，然后再松开按钮。 之后再次检查，即可找到正确的端口。

   

3. 点击 选择目标设备：点击芯片名称（如 esp32s3），选择与开发板完全匹配的芯片型号。

   

   设置目标设备时，ESP-IDF 需要配置相应的工具链和库，此过程可能需要一些时间，请耐心等待其完成。更多详情可查阅 官方文档。

1.4 构建

构建：用 CMake/Ninja 将项目及各组件编译、链接成可执行固件。

点击 按钮即可编译固件。

在此步骤会生成：

• 应用程序 ELF 文件（用于调试）
• 可烧录的二进制文件（.bin）
• 引导加载程序（bootloader.bin）
• 分区表（partition-table.bin）

详细说明请参考：ESP-IDF 构建系统

1.5 烧录

烧录：将构建好的固件通过串口等方式写入目标 ESP32 开发板的闪存（Flash）中。

点击 按钮烧录固件。

烧录时，ESP-IDF 扩展会自动调用 esptool.py 工具来完成实际的通信和写入操作。终端会显示烧录进度。

1.6 监视

监视：打开 IDF 监视器 查看设备运行日志与打印输出，是调试程序、观察运行状态的重要手段。

点击 即可监视 ESP32 串口。

启动后，终端将连接到开发板。你将看到 "Hello World" 示例的输出。

使用快捷键 Ctrl + ] 可以退出 ESP-IDF 监视器。

1.7 构建、烧录和监视组合操作

也可以点击 一键自动依次执行构建、烧录和监视这三个步骤。

2. Blink 示例

接下来，我们通过经典的 "Blink" (LED 闪烁) 示例来学习如何修改项目配置。

此程序的功能是让开发板上的板载 LED 以固定的频率闪烁。示例支持普通 LED（GPIO）与可寻址 LED（如 WS2812，使用 RMT 或 SPI 驱动）。

2.1 打开项目

打开 "Blink" 示例的步骤与 "Hello World" 完全相同，只需在示例列表中选择 get-started/blink 即可。

2.2 项目结构与 sdkconfig

Blink 项目整体结构与 Hello World 相似，但额外提供了一组 sdkconfig 默认值文件，用于不同目标芯片。

blink/
├── CMakeLists.txt
├── main
│   ├── blink_example_main.c
│   ├── CMakeLists.txt
│   ├── idf_component.yml
│   └── Kconfig.projbuild
├── pytest_blink.py
├── README.md
├── sdkconfig.defaults
├── sdkconfig.defaults.esp32
├── sdkconfig.defaults.esp32c3
├── sdkconfig.defaults.esp32c5
├── sdkconfig.defaults.esp32c6
├── sdkconfig.defaults.esp32c61
├── sdkconfig.defaults.esp32h2
├── sdkconfig.defaults.esp32p4
├── sdkconfig.defaults.esp32s2
└── sdkconfig.defaults.esp32s3

构建时，ESP-IDF 会先应用通用的 sdkconfig.defaults，再按目标芯片追加 sdkconfig.defaults.<TARGET>（如 sdkconfig.defaults.esp32s3）。若同一键在多个文件中出现，后应用的值会覆盖先前的值。

为便于配置 LED 引脚等项目专属参数，Blink 示例在 main/ 下提供 Kconfig.projbuild 文件，用于定义该项目的配置项(例如 Blink LED type和 BLINK_GPIO )。这些选项会出现在 menuconfig 中，最终写入 sdkconfig。

2.3 常规项目配置

首先，在构建和烧录之前，请务必检查并设置正确的目标设备、串口和烧录方式。参考 1.3 。

2.4 配置 LED 引脚

VS Code

1. 点击 打开 SDK 配置编辑器。

   不同于 idf.py menuconfig 提供的命令行配置工具 (TUI)，ESP-IDF VS Code 插件提供了更直观的图形化配置界面。

2. 根据开发板板载 LED 修改配置：

   

   • Blink LED type：选择 LED 类型。
     • GPIO：普通 LED。
     • LED strip: 可寻址 LED (如 WS2812)。
   • Blink GPIO number：设置 LED 所连接的 GPIO 引脚编号。
   • Blink period in ms： 设置 LED 闪烁的周期（单位：毫秒）。
   信息

   本教程使用的 微雪 ESP32-S3-Zero 迷你开发板 板载了一颗 WS2812 可寻址 LED，它连接在 GPIO 21 引脚上。

3. 修改完成后，点击 "保存" 按钮。

menuconfig

1. 点击 打开 ESP-IDF 终端，输入以下命令：

   idf.py menuconfig

   

2. 这将打开一个基于文本的菜单界面，可通过方向键导航，按回车键或空格键进入，按 Esc 返回，用于设置项目的具体参数。

   

   进入 Example Configuration 修改项目配置：

   • Blink LED type：选择 LED 类型。
     • GPIO：普通 LED。
     • LED strip: 可寻址 LED (如 WS2812)。
   • Blink GPIO number：设置 LED 所连接的 GPIO 引脚编号。
   • Blink period in ms： 设置 LED 闪烁的周期（单位：毫秒）。

   

   信息

   本教程使用的 微雪 ESP32-S3-Zero 迷你开发板 板载了一颗 WS2812 可寻址 LED，它连接在 GPIO 21 引脚上。

3. 更改后按 S 保存，按 Q 退出。

2.5 构建、烧录与监视

1. 点击 一键自动依次执行构建、烧录和监视这三个步骤。

2. 烧录完成后，您会看到开发板上的 LED 开始闪烁。同时，串口监视器会启动并输出如下日志信息：