ESP-IDF

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

ESP-IDF 入门教程
配置 ESP-IDF 开发环境
示例程序

ESP-IDF 入门教程

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

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

配置 ESP-IDF 开发环境

信息

对于 EESP32-S3-Touch-LCD-1.85B 开发板，需要使用 ESP-IDF V5.5.3 以上版本。

备注

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

版本选择

此部分图示以安装 ESP-IDF V5.2.2 为例示范，安装时请选用与您开发板示例匹配的 ESP-IDF 版本。

安装 ESP-IDF 开发环境

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

在页面中点击 Offline Installer 标签，然后在筛选栏中选择 Windows 操作系统和你需要的 ESP-IDF 版本（图示仅为参考，请以实际为准）。

确认选择无误后，点击下载按钮。浏览器将自动同时下载两个文件：一个是 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 环境,无需手动配置。

示例程序

ESP-IDF 示例程序位于示例程序包的 ESP-IDF 目录中。

示例程序	基础例程说明
01_comprehensive_example	综合示例程序，驱动 lcd, 音频以及板载传感器
02_lvgl_demo	展示 LVGL demo
03_mp3_player	此示例扫描 TF 卡，并播放 MP3
04_esp_wakeword_det	使用 esp-sr 组件实现语音唤醒以及命令词识别功能
05_esp-brookesia	通过 brookesia 组件展示 LVGL APP 风格 UI
06_qmi8658_test	测试陀螺仪
07_pcf85063_test	测试 RTC 实时时钟
08_bq27220_test	测试板载电池监测 IC

01_comprehensive_example

程序说明

本示例为综合示例程序，演示 LCD 触摸屏驱动，LVGL 初始化，音频驱动以及各种板载外设等

硬件连接

插入 3.7V 锂电池或将开发板接入电脑
需要插入 TF 卡（根目录中创建 music 文件夹用来存放 MP3 文件）

代码分析

初始化屏幕、触摸、背光、 LVGL 以及 TF 卡：

  lv_display_t *disp = bsp_display_start();
  lv_indev_t *tp = bsp_display_get_input_dev();
  bsp_display_backlight_on();
  bsp_sdcard_mount();

初始化音频播放器、板载传感器以及唤醒词监测任务：
```
  Audio_Play_Init();
  msg_driver_init();
  wake_word_drv_init();
```

扫描 music 文件夹下的 MP3 文件：

  esp_err_t err = get_file_list_by_ext("/sdcard/music",".mp3",&mp3_files);
  if (err == ESP_OK) {
      for (int i = 0; i < mp3_files.count; i++) {
          printf("MP3[%d]: %s\n", i, mp3_files.list[i]);
      }
  }

创建 UI：

  bsp_display_lock(-1);

  main_screen = lv_obj_create(NULL);
  lv_obj_t * tv = lv_tileview_create(main_screen);

  lv_obj_t * tile1 = lv_tileview_add_tile(tv, 0, 0, LV_DIR_RIGHT);
  msg_ui_screen_init(main_screen,tile1);
  

  lv_obj_t * tile2 = lv_tileview_add_tile(tv, 1, 0, LV_DIR_LEFT | LV_DIR_RIGHT);
  init_music_ui_screen(tile2,&mp3_files);

  lv_obj_t * tile3 = lv_tileview_add_tile(tv, 2, 0, LV_DIR_LEFT);
  eaf_ui_screen_init(tile3);

  lv_screen_load(main_screen);

  bsp_display_unlock();

测试语音唤醒及命令词指令

  //唤醒词
  Hi,ESP

  // 指令
  Turn on the backlight
  Turn off the backlight
  Backlight is brightest
  Backlight is darkest

运行效果

采用 LVGL 平铺视图 (Tileview) 展示三个界面，左右滑动可以切换

02_lvgl_demo

程序说明

本示例为展示 LVGL 官方示例

硬件连接

将开发板接入电脑

代码分析

加载 LVGL demo 示例：

  bsp_display_lock(-1);
  lv_demo_widgets();
  bsp_display_unlock();

运行效果

03_mp3_player

程序说明

本示例为测试 TF 卡初始化以及扫描 MP3 文件并播放

硬件连接

将开发板接入电脑
需要插入 TF 卡（根目录中创建 music 文件夹用来存放 MP3 文件）

代码分析

扫描 MP3 文件并保存文件名：

void Search_Music(void) 
{        
    esp_err_t err = get_file_list_by_ext("/sdcard/music",".mp3",&MP3_files);
    if (err == ESP_OK) {
        for (int i = 0; i < MP3_files.count; i++) {
            printf("MP3:[%d]: %s\n", i, MP3_files.list[i]);
        }
    }
    file_count = MP3_files.count;                                           
}

运行效果

04_esp_wakeword_det

程序说明

本示例使用 ESP-SR 组件演示离线语音唤醒和语音识别效果

硬件连接

将开发板接入电脑
请勿遮挡麦克风

代码分析

初始化麦克风并获取句柄：

record_dev =  bsp_audio_codec_microphone_init();

esp_codec_dev_sample_info_t fs = {
    .bits_per_sample = 32,
    .channel = 2,
    .sample_rate = 16000,
};
esp_codec_dev_set_in_gain(record_dev, 30.0);
esp_codec_dev_open(record_dev, &fs);

初始化语音模型：

  models = esp_srmodel_init("model"); // partition label defined in partitions.csv
  afe_config_t *afe_config = afe_config_init(bsp_get_input_format(), models, AFE_TYPE_SR, AFE_MODE_LOW_COST);
  afe_handle = esp_afe_handle_from_config(afe_config);
  esp_afe_sr_data_t *afe_data = afe_handle->create_from_config(afe_config);
  afe_config_free(afe_config);
  xTaskCreatePinnedToCore(&detect_Task, "detect", 8 * 1024, (void*)afe_data, 5, NULL, 0);
  xTaskCreatePinnedToCore(&feed_Task, "feed", 8 * 1024, (void*)afe_data, 5, NULL, 1);

运行效果

05_esp-brookesia

程序说明

本示例展示完整手机风格 UI 系统，包含状态栏、导航栏、应用启动器和手势交互等组件

硬件连接

将开发板接入电脑

代码分析

初始化 phone UI：

  ESP_LOGI(TAG, "Create phone object");
  systems::phone::Phone *phone = new systems::phone::Phone(disp);
  phone->setTouchDevice(tp);
  
  Stylesheet *stylesheet = new systems::phone::Stylesheet(STYLESHEET_360_360_DARK);
  ESP_UTILS_CHECK_NULL_EXIT(stylesheet, "Create stylesheet failed");

  ESP_UTILS_LOGI("Using stylesheet (%s)", stylesheet->core.name);
  ESP_UTILS_CHECK_FALSE_EXIT(phone->addStylesheet(stylesheet), "Add stylesheet failed");
  ESP_UTILS_CHECK_FALSE_EXIT(phone->activateStylesheet(stylesheet), "Activate stylesheet failed");
  delete stylesheet;

安装 SquarelineDemo APP：

auto app3 = esp_brookesia::apps::SquarelineDemo::requestInstance();
ESP_UTILS_CHECK_FALSE_EXIT(phone->installApp(app3),"start Drawpanel failed");

运行效果

06_qmi8658_test

程序说明

本示例为测试陀螺仪 QMI8658 驱动程序

硬件连接

将开发板接入电脑

代码分析

初始化 QMI8658, 并循环读取数据：

void app_main(void)
{

    qmi8658_dev = bsp_qmi8658_drv_init();
    
    while (1)
    {
    qmi8658_data_t data;
    bool ready;
    esp_err_t ret = qmi8658_is_data_ready(qmi8658_dev, &ready);
    if (ret == ESP_OK && ready) 
    {
        ret = qmi8658_read_sensor_data(qmi8658_dev, &data);
        if (ret == ESP_OK) 
        {
            ESP_LOGI("TAG", "Accel: X=%.4f m/s², Y=%.4f m/s², Z=%.4f m/s²",data.accelX, data.accelY, data.accelZ);
            ESP_LOGI("TAG", "Gyro:  X=%.4f rad/s, Y=%.4f rad/s, Z=%.4f rad/s",data.gyroX, data.gyroY, data.gyroZ);
            ESP_LOGI("TAG", "Temp:  %.2f °C, Timestamp: %lu",data.temperature, data.timestamp);

        } 
    } 
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
    
}

运行效果

打开串口监视器

07_pcf85063_test

程序说明

本示例为测试 RTC 实时时钟示例程序

硬件连接

将开发板接入电脑
插入 3.7V 锂电池（没有电池无法读取 RTC 数据）

代码分析

初始化 pcf85063a, 并设置时间：

  esp_err_t ret = pcf85063a_init(&dev, bus_handle, PCF85063A_ADDRESS);
  if (ret != ESP_OK) {
      ESP_LOGE(TAG, "Failed to initialize PCF85063A (error: %d)", ret);
      vTaskDelete(NULL);
  }

  ESP_LOGI(TAG, "Set current time.");
  pcf85063a_set_time_date(&dev, Set_Time);

运行效果

打开串口监视器

08_bq27220_test

程序说明

本示例为测试电池电量监测芯片示例程序

硬件连接

插入 3.7V 锂电池（没有电池无法读取电池数据）

代码分析

初始化 bq27220

bq27220_handle_t bq27220_drv_init(void)
{

    i2c_bus = bsp_i2c_bus_get_handle();

    bq27220_config_t bq27220_cfg = {
        .i2c_bus = i2c_bus,
        .cfg = &default_config,
        .cedv = &default_cedv,
    };
    bq27220 = bq27220_create(&bq27220_cfg); 

    if (!bq27220) {
        ESP_LOGE(TAG, "bq27220 create failed");
    }
    return bq27220;
}

打印电池相关信息

static void test_bq27220_print_info(bq27220_handle_t bq27220Handle)
{
    battery_status_t status = {};
    bq27220_get_battery_status(bq27220Handle, &status);

    ESP_LOGI(TAG, "Battery Status1 - DSG:%d SYSDWN:%d TDA:%d BATTPRES:%d AUTH_GD:%d OCVGD:%d TCA:%d RSVD:%d",
            status.DSG, status.SYSDWN, status.TDA, status.BATTPRES,
            status.AUTH_GD, status.OCVGD, status.TCA, status.RSVD);

    ESP_LOGI(TAG, "Battery Status2 - CHGINH:%d FC:%d OTD:%d OTC:%d SLEEP:%d OCVFAIL:%d OCVCOMP:%d FD:%d",
            status.CHGINH, status.FC, status.OTD, status.OTC,
            status.SLEEP, status.OCVFAIL, status.OCVCOMP, status.FD);

    uint16_t vol = bq27220_get_voltage(bq27220Handle);
    int16_t current = bq27220_get_current(bq27220Handle);
    uint16_t rc = bq27220_get_remaining_capacity(bq27220Handle);
    uint16_t full_cap = bq27220_get_full_charge_capacity(bq27220Handle);
    uint16_t temp = bq27220_get_temperature(bq27220Handle) / 10 - 273;
    uint16_t cycle_cnt = bq27220_get_cycle_count(bq27220Handle);
    uint16_t soc = bq27220_get_state_of_charge(bq27220Handle);
    int16_t avg_power = bq27220_get_average_power(bq27220Handle);
    int16_t max_load = bq27220_get_maxload_current(bq27220Handle);
    uint16_t time_to_empty = bq27220_get_time_to_empty(bq27220Handle);
    uint16_t time_to_full = bq27220_get_time_to_full(bq27220Handle);

    ESP_LOGI(TAG,
            "Battery Info - Vol:%dmV Cur:%dmA Pwr:%dmW RC:%dmAh FCC:%dmAh "
            "Temp:%dC Cycle:%d SOC:%d%% MaxLoad:%dmA TTE:%dmin TTF:%dmin",
            vol, current, avg_power, rc, full_cap, temp,
            cycle_cnt, soc, max_load, time_to_empty, time_to_full);
}

运行效果

打开串口监视器

文档反馈

ESP-IDF 入门教程​

配置 ESP-IDF 开发环境​

安装 ESP-IDF 开发环境​

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

示例程序​

01_comprehensive_example​

程序说明​

硬件连接​

代码分析​

运行效果​

02_lvgl_demo​

程序说明​

硬件连接​

代码分析​

运行效果​

03_mp3_player​

程序说明​

硬件连接​

代码分析​

运行效果​

04_esp_wakeword_det​

程序说明​

硬件连接​

代码分析​

运行效果​

05_esp-brookesia​

程序说明​

硬件连接​

代码分析​

运行效果​

06_qmi8658_test​

程序说明​

硬件连接​

代码分析​

运行效果​

07_pcf85063_test​

程序说明​

硬件连接​

代码分析​

运行效果​

08_bq27220_test​

程序说明​

硬件连接​

代码分析​

运行效果​

ESP-IDF 入门教程

配置 ESP-IDF 开发环境

安装 ESP-IDF 开发环境

安装 Visual Studio Code 与 ESP-IDF 扩展

示例程序

01_comprehensive_example

程序说明

硬件连接

代码分析

运行效果

02_lvgl_demo

程序说明

硬件连接

代码分析

运行效果

03_mp3_player

程序说明

硬件连接

代码分析

运行效果

04_esp_wakeword_det

程序说明

硬件连接

代码分析

运行效果

05_esp-brookesia

程序说明

硬件连接

代码分析

运行效果

06_qmi8658_test

程序说明

硬件连接

代码分析

运行效果

07_pcf85063_test

程序说明

硬件连接

代码分析

运行效果

08_bq27220_test

程序说明

硬件连接

代码分析

运行效果