numworks移植记录：1.使用 CLion 和 ESP-IDF 搭建 ESP32-S3 开发环境

你家人养牛
4 阅读5分钟

使用 CLion 和 ESP-IDF 搭建 ESP32-S3 开发环境

1. 引言

将 NumWorks 图形计算器移植到 ESP32-S3 的第一步，是搭建一个稳定、高效的开发环境。ESP32-S3 是乐鑫推出的高性能 Wi-Fi + Bluetooth LE 物联网芯片，具有强大的处理能力和丰富的外设，非常适合运行复杂的图形界面应用程序。而 ESP-IDF（Espressif IoT Development Framework）是官方提供的软件开发框架，提供了完善的驱动库、工具链和构建系统，能够确保项目的稳定性和可维护性。

本文将以 CLion 作为集成开发环境，详细讲解如何在 Windows 系统上使用 ESP-IDF 为 ESP32-S3 编译并烧录固件。CLion 强大的代码导航、重构和调试功能，结合 ESP-IDF 的底层支持，将大大提升开发效率。

2. 准备工作

在开始之前，请确保你拥有以下硬件和软件：

硬件：

  • 一块 ESP32-S3 开发板（如 ESP32-S3-DevKitC-1 或任何兼容板）
  • USB 数据线（用于供电和烧录）

软件：

  • 操作系统：Windows 10 或 11（64 位）
  • Git for Windows（用于克隆仓库和管理版本）
  • Python 3.7 或更高版本（ESP-IDF 依赖）
  • CMake（CLion 自带，也可单独安装）
  • Ninja 构建工具（CLion 支持，ESP-IDF 推荐使用）
  • CLion 最新版本（建议 2023.2 以上，以获得对 ESP-IDF 的最佳支持）

3. 安装 ESP-IDF

ESP-IDF 是乐鑫官方提供的物联网开发框架，它包含了 RTOS、驱动、工具链和构建系统。安装方法有两种：使用官方安装器或手动安装。这里推荐使用官方安装器，因为它会自动处理依赖和路径配置。

步骤：

  1. 访问乐鑫官网 ESP-IDF 下载页面 下载离线或在线安装器。
  2. 运行安装器，选择安装路径（建议使用短路径，如 C:\esp-idf）。
  3. 安装器会自动下载工具链、Python 包和必要的依赖。整个过程可能需要 10~20 分钟。
  4. 安装完成后，会在桌面生成“ESP-IDF Command Prompt”快捷方式。打开它，输入 idf.py --version 验证安装是否成功，如果显示版本信息，则安装正确。

环境变量说明：安装器会将 ESP-IDF 的路径添加到系统环境变量中，并设置 IDF_PATH。后续 CLion 需要依赖这些环境变量，因此安装后建议重启电脑。

4. 安装和配置 CLion

CLion 是一款跨平台的 C/C++ IDE，支持 CMake 构建系统，非常适合与 ESP-IDF 配合使用。

安装 CLion：从 JetBrains 官网下载并安装，试用或激活后即可使用。

配置 Toolchains（工具链）：

CLion 需要知道如何调用编译器、CMake 和 Ninja。我们需要为 ESP32-S3 创建一个新的工具链。

  1. 打开 CLion，进入 File -> Settings -> Build, Execution, Deployment -> Toolchains。
  2. 点击 + 添加一个新工具链，命名为 ESP-IDF。
  3. CMake：选择 Bundled CMake（或自定义路径，但推荐使用 CLion 自带的）。
  4. Make：选择 Bundled Make（ESP-IDF 默认使用 Ninja，但 Make 也可用）。
  5. C Compiler 和 C++ Compiler：点击右侧的 ... 浏览到 ESP-IDF 工具链中的编译器。默认路径通常在 C:\Users\<用户名>\.espressif\tools\xtensa-esp32s3-elf\esp-2021r2-patch3-8.4.0\xtensa-esp32s3-elf\bin\xtensa-esp32s3-elf-gcc.exe（具体版本号可能不同）。你需要找到对应的 xtensa-esp32s3-elf-gcc.exe 和 xtensa-esp32s3-elf-g++.exe 并分别设置。
  6. Debugger：选择同目录下的 xtensa-esp32s3-elf-gdb.exe。
  7. 保存设置。

现在，CLion 已经知道如何为 ESP32-S3 编译代码了。

5. 创建第一个 ESP32-S3 项目

为了验证环境是否配置正确，我们创建一个最简单的 LED 闪烁示例。

方法一：使用 ESP-IDF 提供的示例

在终端（ESP-IDF Command Prompt）中，进入你希望存放项目的目录，执行：

bash

cp -r $IDF_PATH/examples/get-started/blink ./my_blink
cd ./my_blink

这会将官方 blink 示例复制到当前目录下的 my_blink 文件夹中。

方法二：在 CLion 中直接创建 CMake 项目

  1. 在 CLion 中，选择 File -> New CMake Project from Sources，然后选择 blink 示例所在的目录（如果你复制了示例）。
  2. 或者创建一个全新的项目，但需要手动编写 CMakeLists.txt，稍显复杂。对于初学者，推荐使用方法一。

6. 配置 CMakeLists.txt

ESP-IDF 项目通常有一个顶层的 CMakeLists.txt，它通过 include($ENV{IDF_PATH}/tools/cmake/project.cmake) 来引入 ESP-IDF 的构建系统。确保你的 CMakeLists.txt 内容如下（以 blink 为例）：

cmake

cmake_minimum_required(VERSION 3.5)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(my_blink)

这里 project 名称必须与项目文件夹名称一致，且 main 组件内的源文件会被自动编译。

CLion 中打开项目：

  1. 在 CLion 中，选择 File -> Open，然后选择你的 my_blink 目录。
  2. CLion 会自动检测 CMakeLists.txt 并提示配置。确保在设置中选择了之前创建的 ESP-IDF 工具链。
  3. 等待 CMake 生成缓存，如果一切正常，底部信息栏会显示“Build finished”。

7. 编译与烧录

编译固件：

  • 在 CLion 底部工具栏找到 Terminal 标签，打开内置终端（默认路径已是项目根目录）。
  • 输入 idf.py build 开始编译。或者，你也可以通过 CLion 的 CMake 构建按钮（锤子图标）来编译，但 idf.py 提供了更完整的构建流程，包括生成分区表等。
  • 编译完成后，会在 build 目录下生成 my_blink.bin 等文件。

烧录到 ESP32-S3：

  1. 用 USB 线连接开发板到电脑，查看设备管理器，确认端口号（如 COM3）。

  2. 在 CLion 终端中执行：

    bash

    idf.py -p COM3 flash

    将 COM3 替换为你实际的端口号。

  3. 如果一切正常，你会看到烧录进度条，完成后开发板自动复位，LED 开始闪烁（如果板载 LED 连接在 GPIO2 等默认引脚）。

8. 调试（可选）

ESP32-S3 支持使用 OpenOCD 进行 JTAG 调试。CLion 可以通过 GDB 与 OpenOCD 对接，实现断点调试。

  1. 安装 OpenOCD（ESP-IDF 已自带，路径在 $IDF_PATH/tools/openocd-esp32 下）。
  2. 连接 JTAG 调试器（如 ESP-PROG），或使用内置的 USB-JTAG 功能（ESP32-S3 支持通过 USB 直接调试）。
  3. 在 CLion 中配置运行/调试配置：
    • 添加一个“Embedded GDB Server”类型。
    • 选择之前配置的工具链。
    • 设置 GDB Server 为 OpenOCD 可执行文件，参数指定目标芯片和配置文件。
    • 设置 GDB 为工具链中的 xtensa-esp32s3-elf-gdb。
  4. 启动调试，即可在代码中设置断点，观察变量。

9. 验证移植环境

成功烧录 blink 示例后，说明你的开发环境已经可以正常工作。后续移植 NumWorks 时，你只需要在 CMake 项目中添加源文件、包含路径，并链接必要的库。ESP-IDF 提供的丰富组件（如 LCD 驱动、Wi-Fi、文件系统）将大大简化底层适配工作。

10. 常见问题与解决

Q1: idf.py build 提示找不到 Python 或模块 A: 确保在 ESP-IDF Command Prompt 中执行，或者在普通终端中先运行 %USERPROFILE%\esp-idf\export.bat 来设置环境变量。

Q2: CLion 中 CMake 配置失败，提示找不到编译器 A: 检查工具链中的编译器路径是否正确，确保路径中没有空格或中文。另外，可以尝试在 CLion 的 CMake 选项中添加 -DCMAKE_TOOLCHAIN_FILE=$ENV{IDF_PATH}/tools/cmake/toolchain-esp32s3.cmake 来指定工具链文件。

Q3: 烧录时提示“无法打开端口” A: 可能是端口号错误，或者驱动程序未安装。ESP32-S3 通常使用 CH340/CP210x 等串口芯片，需安装相应驱动。在设备管理器中查看端口号。

Q4: 烧录成功但 LED 不闪烁 A: 检查开发板 LED 连接的 GPIO 引脚是否与代码一致（blink 示例默认使用 GPIO2）。可以修改 main.c 中的 BLINK_GPIO 宏。

至此，你已经成功搭建了 ESP32-S3 的开发环境，并验证了编译和烧录流程。下一篇文章，我们将深入探讨如何将 NumWorks 的核心模块（如 Ion、Kandinsky、Poincaré）逐步移植到 ESP32-S3 上。敬请期待！

avatar
文章
阅读
粉丝