跳到主要内容

ESP-IDF

本章节包含以下部分，请按需阅读：

ESP-IDF 入门教程​

通用开发流程可参考 ESP-IDF 入门教程：

通用教程以 ESP32-S3-Zero 为例。本产品的 SDK 版本、目标芯片和接线以本页配置及各示例说明为准。

配置 ESP-IDF 开发环境​

以下以 Windows 系统为例，使用 VS Code + ESP-IDF 扩展 打开、编译和烧录示例。

ESP-IDF 版本

当前示例使用 ESP-IDF 6.2.0-dev-08e0d30a74ad 开发版，目标为 esp32s31（Preview）。通用教程中的 V5.5.2 不适用于本产品；首次安装请按下方指定版本说明操作。

以下流程已核对示例及乐鑫扩展源码，尚未完成 VS Code 全流程编译、烧录和实板验证。

开始前准备​

  • ESP32-S31-Zero 开发板。
  • 支持数据传输的 USB Type-C 线缆。
  • Windows 电脑。
  • 使用 Wi-Fi 或 BLE 示例时，确认天线选择电阻与所用通路匹配。可使用板载陶瓷天线；切换至 IPEX 一代接口后，需连接适用的 2.4 GHz 外接天线。
  • 从 ESP32-S31-Zero 示例程序入口 下载并解压完整工程。

UART、I2C 和综合测试所需的接线与外设见对应示例。首次连接时先断开扩展设备，通过 Type-C 接口连接电脑。

安装 Visual Studio Code 与 ESP-IDF 扩展​

  1. 下载并安装 Visual Studio Code 编辑器。

    安装时可勾选“通过 Code 打开”相关资源管理器上下文菜单选项，以便打开工程目录。

  2. 启动 VS Code，点击侧边活动栏中的扩展图标，或按 Ctrl + Shift + X 打开“扩展”视图。

    VS Code 扩展视图图标

  3. 搜索 ESP-IDF，安装乐鑫发布的 ESP-IDF 扩展。

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

安装 ESP-IDF 开发环境​

首次使用时安装指定版本的 ESP-IDF。已经安装该版本的电脑可以直接进入 打开示例工程。

首次安装：获取指定 SDK 并安装配套工具

  1. 安装 Git for Windows 工具。在不含中文和空格的开发工具目录打开 Windows PowerShell，执行以下命令：

    git clone --no-checkout https://github.com/espressif/esp-idf.git esp-idf-s31
    git -C esp-idf-s31 checkout 08e0d30a74ad0bfd5a34933142b80f45619ee410
    git -C esp-idf-s31 submodule update --init --recursive

  2. 下载并运行最新版 ESP-IDF Installation Manager 安装工具，选择自定义安装（Expert Installation）。保留默认目标选择；若要求选择版本，先选 master。到安装路径步骤时，选择上一步生成的 esp-idf-s31 文件夹本身。

    安装器会使用该目录中已经检出的指定提交，而不是重新下载 master。按提示完成前置依赖、工具链和 Python 环境安装。此方式见 EIM 自定义安装说明。

  3. 安装完成后回到 VS Code，按 Ctrl+Shift+P，运行 "ESP-IDF: Select Current ESP-IDF Version"，选择路径指向 esp-idf-s31 的环境。

  4. 在命令面板运行 "ESP-IDF: Open ESP-IDF Terminal"，执行一次以下命令，使组件管理器与示例配套版本一致：

    python -m pip install "idf-component-manager==3.1.2"

打开示例工程​

  1. 在 VS Code 中选择“文件” > “打开文件夹”，打开 examples/esp-idf/02_blink_rgb。

    打开后，资源管理器顶层应能看到 CMakeLists.txt、sdkconfig.defaults 和 main 文件夹。每个示例都是独立工程，打开所需示例的文件夹即可。

  2. 按 Ctrl+Shift+P，运行 "ESP-IDF: Select Current ESP-IDF Version"，选择上文安装的 esp-idf-s31 环境。

  3. 在命令面板运行 "ESP-IDF: Set Espressif Device Target"，选择 esp32s31（Preview）。扩展会自动处理预览目标参数，不要选择 esp32s3。

首次配置需要联网下载组件。建议使用新解压的示例；复用旧工程或切换框架前，先备份原有的 sdkconfig、dependencies.lock 和构建目录。

所有示例保留 16 MiB Flash、DIO 和 80 MHz 配置。该配置不等于实装 Flash 容量，详见 Flash 容量说明。

编译与下载​

以下以 02_blink_rgb 为例，在 VS Code 命令面板中完成编译、下载和查看日志。

  1. 运行 "ESP-IDF: Build Your Project" 编译工程。首次编译会下载依赖，等待任务成功结束，确认 build 目录中生成固件。

  2. 通过 Type-C 接口连接开发板。运行 "ESP-IDF: Select Port to Use (COM, tty, usbserial)"，选择开发板对应的端口。

  3. 运行 "ESP-IDF: Flash Your Project"，如提示选择下载方式，选择 UART，通过 USB 串口下载。

    若无法自动进入下载模式，按住 BOOT，按下并松开 RESET，再松开 BOOT，重新确认端口后下载。下载完成后如仍停留在下载模式，松开 BOOT 并按 RESET 启动程序。

  4. 运行 "ESP-IDF: Monitor Device" 查看串口日志，并观察 RGB LED 是否依次显示红、绿、蓝并熄灭。按 Ctrl+] 退出监视器。

使用其他示例时，在 VS Code 中打开对应的示例文件夹，重复上述操作。需要修改 Wi-Fi 等工程选项时，运行 "ESP-IDF: SDK Configuration Editor (Menuconfig)"，保存配置后重新编译、下载。

示例程序​

每个示例都是独立工程。选择下表中的示例，在 VS Code 中打开 examples/esp-idf/ 下对应文件夹，按 编译与下载 操作。以下“运行效果”描述源码预期行为，不代表实板测试记录。示例 11 需要配套转接板及外接设备，不能作为裸板的通用自检程序。

示例目录功能额外条件
01_gpio_output将 15 路引出 GPIO 设为高电平断开外部输出源和负载
02_blink_rgb控制板载 RGB LED无需外接 LED
03_chip_info打印芯片和 Flash 信息USB 控制台
04_boot_button读取 BOOT 按键USB 控制台
05_uart_loopbackUART1 发送、接收及比较GPIO58 与 GPIO59 跳线
06_i2c_scan扫描外部 I2C 设备外部设备及适当上拉
07_wifi_scan扫描附近 Wi-Fi 热点天线通路正确
08_wifi_sta连接指定 Wi-Fi 热点天线通路正确及 2.4 GHz 热点
09_wifi_ap创建 Wi-Fi SoftAP天线通路正确及无线终端
10_ble_advertiserBLE 广播与连接事件天线通路正确及 BLE 调试工具
11_board_test综合测试匹配的触摸屏转接板、SD 卡转接板及外接设备
12_wifi_performanceWi-Fi 吞吐与链路诊断天线通路正确及 iperf 2.x 对端

01_gpio_output：GPIO 输出​

【程序说明】

此示例将 GPIO0～6、GPIO46～51、GPIO58 和 GPIO59 共 15 路信号配置为推挽输出，并保持高电平。

【操作步骤】

  1. 运行前断开这些引脚上的外部输出源和负载，避免信号冲突。
  2. 编译并下载 01_gpio_output。
  3. 用万用表或逻辑分析仪相对 GND 检查电平。

【运行效果】

所列引脚应保持高电平。程序只设置输出，不执行回环测量，也不周期翻转电平。串口中的配置日志不等于全部引脚已通过电气测试。

【程序说明】

此示例通过 GPIO60 使用 RMT 外设发送 WS2812 数据，控制板载 WS2812B-1010。颜色数据按 GRB 顺序发送，不能通过简单翻转 GPIO60 电平替代颜色数据。

【操作步骤】

  1. 通过 Type-C 接口连接开发板，无需外接 LED。
  2. 编译并下载 02_blink_rgb，观察板载 RGB LED。

【运行效果】

源码循环依次为红色 1 秒、绿色 1 秒、蓝色 1 秒、熄灭 0.5 秒。检查实际颜色及顺序是否与该设置一致。

03_chip_info：芯片信息​

【程序说明】

此示例读取并打印目标名称、CPU 核心数、芯片修订号、基础 MAC 地址、功能位和 Flash 信息。

【操作步骤】

编译并下载 03_chip_info，打开 USB 控制台，记录芯片信息及 Flash 读取结果。

【运行效果】

控制台输出芯片信息，重点区分两项 Flash 输出：

  • Physical Flash：通过 esp_flash_get_physical_size() 读取的物理容量。
  • Configured flash size：工程设置的 Flash 容量。

两项数值可能不同。原理图标注 32 MiB 器件，而工程保留 16 MiB 配置；实际结果以所用开发板的读取值为准。

04_boot_button：BOOT 按键​

【程序说明】

此示例将 GPIO61 配置为上拉输入，读取低有效 BOOT 按键，并通过延时确认电平变化。

【注意事项】

正常启动时松开 BOOT。按住 BOOT 的同时复位会选择下载模式，此时不会进入按键示例的正常运行流程。

【操作步骤】

  1. 编译并下载 04_boot_button，打开 USB 控制台。
  2. 程序运行后，按下并松开 BOOT，观察日志。

【运行效果】

串口按状态变化输出 Button PRESSED 或 Button RELEASED。

05_uart_loopback：UART 回环​

【程序说明】

程序使用 UART1，通过 GPIO58（TX）发送带序号的字符串，经跳线回送至 GPIO59（RX），接收后逐字节比较。UART 配置如下：

参数设置
UARTUART1
波特率115200
数据格式8 位数据、无校验、1 位停止位，无硬件流控

【操作步骤】

  1. 断电并断开 GPIO58、GPIO59 上的其他外接设备。
  2. 将 H2 第 2 脚 GPIO58（UART1 TX）与第 1 脚 GPIO59（UART1 RX）短接。
  3. 上电后编译并下载 05_uart_loopback，打开 USB 控制台。无需将 UART1 接到电脑。

【运行效果】

收到的数据长度与内容均一致时输出 PASS，否则输出 FAIL 并提示检查跳线。

06_i2c_scan：I2C 扫描​

【程序说明】

程序每轮扫描 0x08～0x77，输出地址表和设备数。外部设备接线如下：

信号GPIO接口
SDAGPIO52J2 第 19 脚
SCLGPIO53J2 第 21 脚

原理图中的相关外部上拉电阻标注为未装配选项，应按外设和总线要求提供适当的 3.3 V 上拉。

【操作步骤】

  1. 断电后按上表连接适用于 3.3 V 逻辑电平的外部 I2C 设备，并确认共地及 SDA、SCL 上拉条件。
  2. 上电后编译并下载 06_i2c_scan，打开 USB 控制台。

【运行效果】

地址表示应答设备，-- 表示未收到应答，UU 表示探测超时。未接设备时显示 0 个设备可以是正常结果，不能预设板上有固定地址的 I2C 从设备。

07_wifi_scan：Wi-Fi 扫描​

【程序说明】

程序使用 STA 模式扫描热点，每轮打印热点总数，最多显示 20 条记录，包含信道、RSSI、认证模式和 SSID。

【操作步骤】

  1. 确认板载天线通路；使用外接天线时，完成通路切换并连接适用的 2.4 GHz 天线。
  2. 编译并下载 07_wifi_scan，打开 USB 控制台查看扫描结果。

【运行效果】

每轮完成后延时 10 秒再扫描。扫描结果受周围热点、天线及环境影响，不预设固定热点数量。

08_wifi_sta：连接 Wi-Fi​

【程序说明】

此示例连接指定的 2.4 GHz Wi-Fi 热点，并输出连接状态和获取的 IPv4 地址。

【操作步骤】

确认天线通路，打开 08_wifi_sta 工程的 menuconfig，在 "Example Configuration" 中设置以下内容：

  • "Wi-Fi SSID"：待连接的 2.4 GHz 热点名称。
  • "Wi-Fi password"：热点密码。
  • "Maximum connection retries"：最大重试次数。

保存配置，重新编译并下载 08_wifi_sta，打开 USB 控制台。

【运行效果】

程序在获取 IPv4 地址后输出 IPv4 address:；连接失败时会按配置重试，达到次数上限后输出失败信息。

该示例演示热点连接和地址获取，获得地址不等于已验证互联网访问。分享工程或截图前移除本地 Wi-Fi 凭据。

09_wifi_ap：创建 SoftAP​

【程序说明】

此示例创建本地 SoftAP，未实现互联网共享或 NAT 路由。示例允许空密码开放网络，使用时应按实际需求设置。

【操作步骤】

  1. 确认天线通路，打开 09_wifi_ap 工程的 menuconfig。
  2. 在 "Example Configuration" 中配置 SoftAP 名称、密码、信道和最大连接数。
  3. 保存配置，重新编译并下载 09_wifi_ap。
  4. 通过电脑或手机连接所设热点，观察 USB 控制台。

【运行效果】

控制台记录终端加入、离开事件。终端提示无互联网连接时，应结合本地连接状态判断结果。

10_ble_advertiser：BLE 广播​

【程序说明】

此示例使用 NimBLE，广播设备名 ESP32-S31-Zero。该示例未定义串口透传服务，不能将其作为蓝牙串口示例使用。

【操作步骤】

  1. 确认天线通路，编译并下载 10_ble_advertiser。
  2. 通过支持 BLE 扫描的工具查找 ESP32-S31-Zero。
  3. 连接设备后再断开，观察 USB 控制台中的连接状态。

【运行效果】

程序在连接和断开时输出日志，并在连接失败或断开后恢复广播。

11_board_test：综合测试​

【程序说明】

此工程包含 Flash、PSRAM、CPU/RAM、GPIO60 RGB LED，以及外接显示、触摸、SD 和 GPIO54 指示灯等测试。显示、触摸和 SD 卡测试需要连接匹配的触摸屏转接板、SD 卡转接板及外接设备。GPIO54 指示灯为外接器件，不能据此认定开发板另有一颗板载状态灯。

【硬件条件】

运行前需确认转接板、外接设备、引脚及供电与工程匹配。整套转接板及外接设备的兼容性仍待验证，未连接对应设备时不能要求全部项目通过。

项目工程当前设置与范围
LCD外接 800 × 480 RGB565 显示，像素时钟 16 MHz；这是工程配置，不是裸板显示规格
触摸外接 GT911，使用 GPIO52、GPIO53、GPIO38、GPIO7；启动时探测 0x14、0x5D
连续触摸跟踪默认关闭，只保留启动检测；启动检测成功不等于运行中触摸已验证
SD外接卡座，GPIO20～25，4 位 SDMMC，运行时钟配置为 20 MHz
测试数据与 USB 引脚复用

自动测试会擦写专用 testdata 分区的首个 4 KiB 扇区，SD 测试会创建、读回并删除临时文件。运行前确认分区用途并备份数据。LCD 启动后会将 GPIO33、GPIO34 改作 RGB 数据线，USB Serial/JTAG 控制台随之不可用；仅在显示启动失败、未完成引脚接管时保留交互控制台。

【操作步骤】

  1. 断电后，按工程引脚及供电要求连接已确认匹配的转接板及外接设备，核对分区用途并备份数据。
  2. 检查 11_board_test 的 PSRAM、显示、触摸和 SD 配置。
  3. 触摸通信仍有待验证问题。如需启用连续采样，在 "Board test" > "Enable continuous touch sampling and touch marker" 中启用对应选项；默认保持关闭。
  4. 确认硬件条件后，编译并下载 11_board_test，按测试项目检查日志及外设现象。

【结果判断】

启动触摸检测成功不等于连续跟踪已验证。LCD 启动成功后，USB 控制台不能继续用于观察日志。显示失败、触摸失败或 SD 失败应分别检查，不能由其他项目成功推断其通过。

12_wifi_performance：Wi-Fi 吞吐测试​

【程序说明】

此示例提供 USB Serial/JTAG 控制台，用于 Wi-Fi 连接、链路信息、ping 及 TCP、UDP 吞吐测试。

【准备与操作】

确认天线通路，并准备运行 iperf 2.x 的电脑；iperf3 协议与该示例不兼容。编译并下载 12_wifi_performance，打开 USB 控制台。

下载启动后，在 wifi-perf> 控制台输入 help 查看命令。STA 模式连接命令如下，将尖括号中的内容替换为本地参数：

sta_connect <SSID> <PASSWORD>
rf_info
ping <GATEWAY_IP>

吞吐测试需先启动接收端。下表中的 <PC_IP> 为电脑地址，<DUT_IP> 为开发板地址。

方向电脑端命令开发板控制台命令
TCP，开发板发送iperf -s -i 1iperf -c <PC_IP> -i 1 -t 60
TCP，开发板接收iperf -c <DUT_IP> -i 1 -t 60iperf -s -i 1
UDP，开发板发送iperf -s -u -i 1iperf -c <PC_IP> -u -b 20M -i 1 -t 60
UDP，开发板接收iperf -c <DUT_IP> -u -b 20M -i 1 -t 60iperf -s -u -i 1

电脑通过有线网络连接测试路由器，可减少电脑自身无线链路对测试的影响。记录天线、供电、信道、带宽、方向、RSSI、吞吐率及 UDP 丢包情况；结果不预设为固定速率。

【结果判断】

rf_info 中的发射功率字段是软件配置值，不是实测射频功率。该示例用于功能及吞吐测试，不能替代 TRP、TIS 或射频认证测试。

问题排查​

目标无法识别、Flash 容量不同、USB 中断或外设失败时，参见 ESP32-S31-Zero 常见问题。