ESP-IDF

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

ESP-IDF 入门教程
配置 ESP-IDF 开发环境
运行乐鑫官方示例程序

ESP-IDF 入门教程

初次接触 ESP32 ESP-IDF 开发，想要快速上手？我们为您准备了一套通用的 入门教程。

请注意：该教程使用 ESP32-S3-Zero 作为教学示例，所有硬件代码均基于其引脚布局。在动手实践前，建议您对照手中的开发板引脚图，确认引脚配置无误。

配置 ESP-IDF 开发环境

备注

以下内容以 Windows 系统为例，使用 VS Code + ESP-IDF 扩展 的方式进行开发。Mac/Linux 用户请参考 官方说明。

安装 ESP-IDF 开发环境

前往 ESP-IDF Installation Manager 下载 ESP-IDF 安装管理器。这是乐鑫最新推出的跨平台安装工具，下文将演示如何使用其离线安装功能。

在页面中点击 Offline Installer 标签，然后在筛选栏中选择 Windows 操作系统和你要安装的版本。

确认选择无误后，点击下载按钮。浏览器将自动同时下载两个文件：一个是 ESP-IDF 离线整合包(.zst)，另一个是 ESP-IDF 安装器(.exe)。

请耐心等待两个文件下载完成。
下载完成后，双击运行 ESP-IDF 安装器(eim-gui-windows-x64.exe)。

启动后，可在右上角将界面语言切换为中文。

安装工具会自动检测同一目录下是否存在离线整合包。点击 从存档安装。

接下来，选择安装路径。建议使用默认路径；若需自定义，请确保路径中不包含中文或空格。确认无误后，点击 开始安装。
当看到如下界面时，表示 ESP-IDF 已安装成功。
建议同时安装驱动程序。点击 完成安装，然后点击 安装驱动程序。

安装 Visual Studio Code 与 ESP-IDF 扩展

下载并安装 Visual Studio Code。
安装时建议勾选 通过 Code 打开操作添加到 Windows 资源管理器文件上下文菜单,以便快速打开项目文件夹。
在 VS Code 中,点击侧边活动栏中的扩展图标(或使用快捷键 Ctrl + Shift + X)打开扩展视图。
在搜索框中输入 ESP-IDF,找到 ESP-IDF 扩展并点击安装。
当 ESP-IDF 扩展版本 ≥ 2.0 时,扩展会自动检测并识别上述步骤中安装的 ESP-IDF 环境,无需手动配置。

示例程序

IDF 示例程序：ESP32-S3-RGB-Matrix 示例程序-GitHub IDF 示例程序：ESP32-S3-RGB-Matrix 示例程序-Gitee

下面给出每个示例的目的、要点说明与运行效果（以便快速上手）。

示例程序	基础例程说明
01_Matrix_RGBW	测试 GPIO 输出控制 LED
02_Matrix_Font_5x7	测试 UART 串口回环
03_Matrix_QMI	测试 QMI 接口收发
04_Matrix_RTC	测试 RTC 接口
05_Matrix_SDCard	测试 SD 卡挂载与容量读取
06_Matrix_SHTC3	测试 RGB LCD 显示与旋转
07_Matrix_WiFi	测试 WiFi 接口
08_Matrix_Audio	测试电容触摸屏多点触控

注意

03_Matrix_QMI,06_Matrix_SHTC3,08_Matrix_Audio 这个三个示例是针对64x64像素大小的屏幕设计的,如果使用其他像素大小的屏幕,会出现文字显示重叠或错位。

01_Matrix_RGBW

【硬件连接】

【代码分析】

rgbw_start()：循环切换板载 RGBW 灯颜色，用于验证灯光驱动与日志输出是否正常。
sizeof(rgbw_colors) / sizeof(rgbw_colors[0])：计算预设颜色数组长度，供循环切换使用。
bsp_display_lock()：加锁后操作显示界面，避免与其他显示任务冲突。
lv_obj_set_style_bg_color(screen, lv_color_hex(0x000000), 0)：将当前屏幕背景设置为黑色，减少灯光测试时的界面干扰。
rgbw_set_color(rgbw_colors[color_index].hex_color)：把当前颜色值输出到 RGBW 灯珠。
ESP_LOGI(TAG, "Current color: %s", ...)：打印当前颜色名称，便于调试和观察切换顺序。
vTaskDelay(pdMS_TO_TICKS(2000))：每种颜色保持 2 秒，方便观察显示效果。
if (color_index >= num_colors)：颜色索引到达末尾后回到起点，实现循环切换。

void rgbw_start(void) {
  /* =======================
   * 1. Basic Parameters
   * ======================= */
  int color_index = 0;
  const int num_colors = sizeof(rgbw_colors) / sizeof(rgbw_colors[0]);

  /* =======================
   * 2. Init Screen
   * ======================= */
  bool locked = bsp_display_lock(1000);
  if (locked) {
    lv_obj_t *screen = lv_scr_act();
    lv_obj_set_style_bg_color(screen, lv_color_hex(0x000000), 0);
    bsp_display_unlock();
  }
  /* =======================
   * 3. Loop Colors
   * ======================= */
  while (true) {
    locked = bsp_display_lock(1000);
    if (locked) {
      rgbw_set_color(rgbw_colors[color_index].hex_color);
      bsp_display_unlock();
    }
    ESP_LOGI(TAG, "Current color: %s", rgbw_colors[color_index].name);
    vTaskDelay(pdMS_TO_TICKS(2000));
    color_index++;
    if (color_index >= num_colors) {
      color_index = 0;
    }
  }
}

【运行效果】

02_Matrix_Font_5x7

【硬件连接】

【代码分析】

font_5x7_start()：启动 5x7 字体示例界面，并保持任务常驻运行。
ESP_LOGI(TAG, "Matrix Font 5x7 start")：输出启动日志，便于确认示例已经进入运行状态。
bsp_display_lock(0)：进入 LVGL 显示上下文前先加锁，确保界面初始化过程安全。
font_5x7_ui_init()：创建 5x7 字体示例所需的界面对象。
font_5x7_ui_apply()：将字体、布局和默认文本等配置应用到界面上。
while (true)：保持任务持续存在，避免示例初始化后立即退出。
vTaskDelay(pdMS_TO_TICKS(1000))：空闲等待，降低任务空转占用。

void font_5x7_start(void) {
  /* =======================
   * 1. Start Display
   * ======================= */
  ESP_LOGI(TAG, "Matrix Font 5x7 start");
  /* =======================
   * 2. Init UI (LVGL Locked)
   * ======================= */
  bool locked = bsp_display_lock(0);
  if (locked) {
    font_5x7_ui_init();
    font_5x7_ui_apply();
    bsp_display_unlock();
  }

  /* =======================
   * 3. Idle Loop
   * ======================= */
  while (true) {
    vTaskDelay(pdMS_TO_TICKS(1000));
  }
}

【运行效果】

03_Matrix_QMI

【硬件连接】

【代码分析】

qmi_start()：完成 QMI8658 传感器界面初始化、驱动启动和定时刷新配置。
qmi_ui_init()：创建 QMI8658 数据显示界面。
middle_init_qmi8658()：初始化 QMI8658 传感器驱动。
qmi_state.qmi_init_ret：保存传感器初始化结果，供界面层判断状态并显示提示。
example_ui_install_timer(100, qmi_data_update)：安装 100 ms 周期定时器，定时刷新姿态或加速度数据。
qmi_data_update：在定时回调中更新传感器数据与界面显示。
while (true)：保持任务常驻运行。
vTaskDelay(pdMS_TO_TICKS(1000))：空闲等待，减少任务资源占用。

void qmi_start(void) {
  /* =======================
   * 1. Start Display & UI
   * ======================= */
  bool locked = bsp_display_lock(0);
  if (locked) {
    qmi_ui_init();
    bsp_display_unlock();
  }

  /* =======================
   * 2. Start Sensor & Timer
   * ======================= */
  qmi_state.qmi_init_ret = middle_init_qmi8658();
  locked = bsp_display_lock(0);
  if (locked) {
    example_ui_install_timer(100, qmi_data_update);
    bsp_display_unlock();
  }

  /* =======================
   * 3. Idle Loop
   * ======================= */
  while (true) {
    vTaskDelay(pdMS_TO_TICKS(1000));
  }
}

【运行效果】

04_Matrix_RTC

【硬件连接】

【代码分析】

rtc_start()：完成 RTC 界面初始化、设时、闹钟配置和实时刷新。
rtc_ui_init()：创建时间显示相关的界面元素。
middle_rtc_init()：初始化 RTC 驱动与底层硬件接口。
middle_rtc_set_time(rtc_state.rtc_time)：将状态结构体中的初始时间写入 RTC 芯片。
middle_rtc_alarm(3)：配置 RTC 闹钟测试条件，用于验证闹钟功能是否正常。
example_ui_install_timer(1, rtc_data_update)：安装高频刷新定时器，使界面实时同步当前时间。
rtc_data_update：在回调中读取 RTC 数据并更新显示内容。
while (true)：保持 RTC 示例任务持续运行。

void rtc_start(void) {
  bool locked = bsp_display_lock(0);
  if (locked) {
    rtc_ui_init();
    bsp_display_unlock();
  }
  middle_rtc_init();
  middle_rtc_set_time(rtc_state.rtc_time);
  middle_rtc_alarm(3);
  locked = bsp_display_lock(0);
  if (locked) {
    example_ui_install_timer(1, rtc_data_update);
    bsp_display_unlock();
  }
  while (true) {
    vTaskDelay(pdMS_TO_TICKS(1000));
  }
}

【运行效果】

05_Matrix_SDCard

【硬件连接】

【代码分析】

sdcard_start()：完成 SD 卡界面初始化、底层驱动启动和状态定时刷新。
sdcard_ui_init()：创建用于显示挂载状态、容量和存储信息的界面组件。
middle_sdcard_init()：执行 SD 卡底层初始化，通常包括总线配置、卡识别和文件系统挂载。
example_ui_install_timer(1000, sdcard_data_update)：安装 1 秒周期定时器，定时刷新 SD 卡状态与容量信息。
sdcard_data_update：在回调中更新 SD 卡显示内容。
while (true)：保持示例任务持续运行。
vTaskDelay(pdMS_TO_TICKS(1000))：空闲等待，减少任务占用。

void sdcard_start(void) {
  /* =======================
   * 1. Start Display & UI
   * ======================= */
  bool locked = bsp_display_lock(0);
  if (locked) {
    sdcard_ui_init();
    bsp_display_unlock();
  }

  /* =======================
   * 2. Init SD Card
   * ======================= */
  middle_sdcard_init();

  /* =======================
   * 3. Periodic Refresh
   * ======================= */
  locked = bsp_display_lock(0);
  if (locked) {
    example_ui_install_timer(1000, sdcard_data_update);
    bsp_display_unlock();
  }

  /* =======================
   * 4. Idle Loop
   * ======================= */
  while (true) {
    vTaskDelay(pdMS_TO_TICKS(1000));
  }
}

【运行效果】

06_Matrix_SHTC3

【硬件连接】

【代码分析】

shtc3_start()：完成 SHTC3 界面初始化、驱动启动和温湿度数据周期刷新。
shtc3_ui_init()：创建温度、湿度和状态提示等界面元素。
middle_init_shtc3()：初始化 SHTC3 传感器驱动。
shtc3_state.shtc3_init_ret：保存初始化结果，供界面层判断是否正常显示数据。
example_ui_install_timer(500, shtc3_data_update)：安装 500 ms 周期定时器，定时更新传感器数据。
shtc3_data_update：在回调中读取温湿度信息并刷新界面。
while (true)：保持示例任务持续运行。
vTaskDelay(pdMS_TO_TICKS(1000))：空闲等待，降低任务占用。

void shtc3_start(void) {
  /* =======================
   * 1. Start Display & UI
   * ======================= */
  bool locked = bsp_display_lock(0);
  if (locked) {
    shtc3_ui_init();
    bsp_display_unlock();
  }
  /* =======================
   * 2. Init Sensor & Timer
   * ======================= */
  shtc3_state.shtc3_init_ret = middle_init_shtc3();
  locked = bsp_display_lock(0);
  if (locked) {
    example_ui_install_timer(500, shtc3_data_update);
    bsp_display_unlock();
  }

  /* =======================
   * 3. Idle Loop
   * ======================= */
  while (true){
    vTaskDelay(pdMS_TO_TICKS(1000));
  }
}

【运行效果】

07_Matrix_WiFi

【硬件连接】

【代码分析】

wifi_start()：完成 WiFi 界面初始化、STA 参数配置、驱动启动和状态刷新。
wifi_ui_init()：创建网络状态显示界面。
middle_wifi_set_sta_config(WIFI_STA_SSID, WIFI_STA_PASS)：设置目标热点的 SSID 和密码。
middle_wifi_init()：启动 WiFi 驱动并发起连接流程。
wifi_state.wifi_init_ret：保存 WiFi 初始化结果，供界面显示连接状态。
example_ui_install_timer(1000, wifi_data_update)：安装 1 秒周期定时器，定时刷新连接状态和网络信息。
wifi_data_update：在回调中更新 WiFi 连接状态、IP 地址等界面内容。
while (true)：保持示例任务持续运行。

void wifi_start(void) {
  /* =======================
   * 1. Start Display & UI
   * ======================= */
  bool locked = bsp_display_lock(0);
  if (locked) {
    wifi_ui_init();
    bsp_display_unlock();
  }

  /* =======================
   * 2. Configure & Enable WiFi
   * ======================= */
  middle_wifi_set_sta_config(WIFI_STA_SSID, WIFI_STA_PASS);
  wifi_state.wifi_init_ret = middle_wifi_init();

  /* =======================
   * 3. Periodic Refresh
   * ======================= */
  locked = bsp_display_lock(0);
  if (locked) {
    example_ui_install_timer(1000, wifi_data_update);
    bsp_display_unlock();
  }

  /* =======================
   * 4. Idle Loop
   * ======================= */
  while (true) {
    vTaskDelay(pdMS_TO_TICKS(1000));
  }
}

【运行效果】

08_Matrix_Audio

【硬件连接】

【代码分析】

audio_start()：完成音频界面初始化、音频任务创建和状态定时刷新。
audio_ui_init()：创建音量、播放状态或频谱相关的界面元素。
audio_state.audio_out_vol = VOLUME：设置默认音频输出音量。
xTaskCreate(audio_task, "aud", 4096, NULL, tskIDLE_PRIORITY + 4, NULL)：创建独立音频任务，在后台处理音频业务逻辑。
example_ui_install_timer(100, audio_data_update)：安装 100 ms 周期定时器，定时同步音频状态到界面。
audio_data_update：在回调中更新播放状态、音量或其他音频信息。
while (true)：保持示例任务持续运行。
vTaskDelay(pdMS_TO_TICKS(1000))：空闲等待，降低主任务占用。

void audio_start(void) {
    /* =======================
     * 1. Start Display & UI
     * ======================= */
    bool locked = bsp_display_lock(0);
    if (locked) {
        audio_ui_init();
        bsp_display_unlock();
    }
    /* =======================
     * 2. Start Audio Task
     * ======================= */
    audio_state.audio_out_vol = VOLUME;
    xTaskCreate(audio_task, "aud", 4096, NULL, tskIDLE_PRIORITY + 4, NULL);
    /* =======================
     * 3. Periodic UI Refresh
     * ======================= */
    locked = bsp_display_lock(0);
    if (locked) {
        example_ui_install_timer(100, audio_data_update);
        bsp_display_unlock();
    }
    /* =======================
     * 4. Idle Loop
     * ======================= */
    while (true) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

【运行效果】

文档反馈

ESP-IDF 入门教程​

配置 ESP-IDF 开发环境​

安装 ESP-IDF 开发环境​

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

示例程序​

01_Matrix_RGBW​

02_Matrix_Font_5x7​

03_Matrix_QMI​

04_Matrix_RTC​

05_Matrix_SDCard​

06_Matrix_SHTC3​

07_Matrix_WiFi​

08_Matrix_Audio​

ESP-IDF 入门教程

配置 ESP-IDF 开发环境

安装 ESP-IDF 开发环境

安装 Visual Studio Code 与 ESP-IDF 扩展

示例程序

01_Matrix_RGBW

02_Matrix_Font_5x7

03_Matrix_QMI

04_Matrix_RTC

05_Matrix_SDCard

06_Matrix_SHTC3

07_Matrix_WiFi

08_Matrix_Audio