ESP-IDF 开发
使用时请将屏幕亮度控制在 50% 以内，避免长时间满亮度运行。亮度过高会使屏幕温度升高，可能导致屏幕出现黑色阴影，影响显示。
如果显示异常，请将开发板静置一段时间后，再烧录较低亮度的程序使用。
本章节包含以下部分，请按需阅读：
ESP-IDF 入门教程
初次接触 ESP32 ESP-IDF 开发，想要快速上手？我们为您准备了一套通用的 入门教程。
- 第0节 认识 ESP32
- 第1节 搭建环境
- 第2节 运行实例
- 第3节 创建项目
- 第4节 使用组件
- 第5节 调试程序
- 第6节 FreeRTOS
- 第7节 驱动外设
- 第8节 Wi-Fi 编程
- 第9节 BLE 编程
请注意：该教程使用 ESP32-S3-Zero 作为教学示例，所有硬件代码均基于其引脚布局。在动手实践前，建议您对照手中的开发板引脚图，确认引脚配置无误。
配置 ESP-IDF 开发环境
请参考 安装 ESP-IDF 开发环境。
ESP32-C5-LCD-1.47 示例需要 ESP-IDF v5.3.0 或更新版本。
以下内容以 Windows 系统为例，使用 VS Code + ESP-IDF 扩展 的方式进行开发。Mac/Linux 用户请参考 官方说明。
此部分图示以安装 ESP-IDF V5.5.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 环境,无需手动配置。
示例程序
示例程序位于资料包的 examples/esp-idf 目录。各示例的 sdkconfig.defaults 已指定目标芯片为 esp32c5，一般无需再次执行 idf.py set-target esp32c5。
编译和烧录
进入任意 ESP-IDF 示例目录后执行：
cd esp-idf/02_lvgl_hello
idf.py build flash monitor
如果需要指定串口，请将 COMx 替换为实际串口号，例如 COM5：
idf.py -p COMx build flash monitor
示例列表
| 示例目录 | 功能 |
|---|---|
01_lcd_panel_basic | 初始化 LCD，不使用 LVGL，绘制彩条和移动色块。 |
02_lvgl_hello | 启动 BSP LVGL 显示接口，并显示基础 UI。 |
03_backlight_fade | 调节 LCD 背光亮度，并在屏幕上显示亮度变化。 |
04_ws2812_rgb | 控制板载 WS2812B RGB LED 循环显示不同颜色。 |
05_sdcard_rw | 挂载 Micro SD 卡，并执行文件写入和读回检查。 |
06_spiffs_rw | 挂载内部 Flash 的 SPIFFS 分区，并执行文件写入和读回检查。 |
07_wifi_scan | 扫描附近 Wi-Fi 热点，并通过串口输出扫描结果。 |
08_board_showcase | 综合演示 LCD、背光、RGB LED、SPIFFS、SD 卡和 Wi-Fi 状态。 |
01_lcd_panel_basic
程序说明
- 本示例通过 BSP 初始化 ST7789 LCD，不启动 LVGL。
- LCD 先显示多色条纹背景，再显示一个上下移动的色块，用于检查屏幕显示和局部刷新。
硬件连接
- 将开发板接入电脑。
- 该示例仅使用板载 LCD 和背光，无需外接模块。
代码分析
app_main()：创建 LCD 面板、初始化背光、注册传输完成回调，并启动显示流程。bsp_display_new()：创建 LCD panel 和 panel IO 对象。bsp_display_brightness_init()和bsp_display_brightness_set()：初始化并设置 LCD 背光。draw_color_bars()：按块绘制多色条纹背景。esp_lcd_panel_draw_bitmap()：向 LCD 指定区域写入图像数据。draw_moving_bar_region()：刷新移动色块及其覆盖过的背景区域。
运行效果
- LCD 显示多色条纹背景，屏幕上有一个色块持续上下移动。
02_lvgl_hello
程序说明
- 本示例启动 BSP LVGL 显示接口，并在 LCD 上绘制基础界面。
- 页面显示开发板名称、LCD 分辨率、SPI 引脚信息和状态条。
硬件连接
- 将开发板接入电脑。
- 该示例仅使用板载 LCD 和背光，无需外接模块。
代码分析
app_main()：启动 BSP 显示服务，设置屏幕方向和背光，并创建 LVGL 页面。bsp_display_start()：启动 LCD panel 和 LVGL port。bsp_display_rotate()：设置屏幕旋转方向。bsp_display_backlight_on()：打开 LCD 背光。bsp_display_lock()和bsp_display_unlock()：保护 LVGL 界面创建过程。create_ui()：创建标题、说明文本、设备信息和状态条。
运行效果
- LCD 显示 LVGL 示例界面，可看到开发板名称、LCD 参数和 SPI 引脚信息。
03_backlight_fade
程序说明
- 本示例通过
bsp_display_brightness_set()调节 LCD 背光亮度。 - LVGL 页面同步显示当前亮度百分比和进度条。
硬件连接
- 将开发板接入电脑。
- 该示例仅使用板载 LCD 和背光，无需外接模块。
代码分析
app_main()：启动 BSP 显示服务，创建亮度页面，并进入亮度循环。create_ui()：创建亮度标题、百分比标签和进度条。bsp_display_brightness_set()：按当前百分比设置 LCD 背光。update_ui()：更新 LVGL 标签和进度条数值。bsp_display_lock()和bsp_display_unlock()：保护 LVGL 控件更新过程。
运行效果
- LCD 背光亮度循环变化，屏幕上的百分比和进度条同步更新。
04_ws2812_rgb
程序说明
- 本示例初始化板载 WS2812B RGB LED，并循环显示不同颜色。
- 该示例主要用于验证板载 RGB LED 控制功能。
硬件连接
- 将开发板接入电脑。
- 该示例仅使用板载 RGB LED，无需外接模块。
代码分析
app_main()：初始化 RGB LED，并进入颜色循环。bsp_ws2812b_init()：初始化板载 WS2812B LED。bsp_setledcolor()：设置指定 LED 的红、绿、蓝亮度。vTaskDelay()：控制颜色切换间隔。
运行效果
- 板载 WS2812B RGB LED 按顺序切换颜色。
05_sdcard_rw
程序说明
- 本示例通过 SDSPI 挂载 Micro SD 卡，并执行文件写入和读回检查。
- LCD 页面显示 SD 卡挂载、写入、读取和结果状态。
硬件连接
- 将开发板接入电脑。
- 将 FAT 或 FAT32 格式的 Micro SD 卡装入开发板。
代码分析
app_main()：启动 LCD 和 LVGL 页面，挂载 SD 卡，并执行读写检查。bsp_sdcard_mount()：挂载 Micro SD 卡。sd_write_file()：向 SD 卡写入测试文件。sd_read_file()：读回测试文件内容，并检查数据是否一致。set_item()和set_summary()：更新 LCD 上的步骤状态和最终结果。bsp_sdcard_unmount()：测试完成后卸载 SD 卡。
运行效果
- LCD 显示 SD 卡容量、文件写入和读回结果；串口同步输出检测信息。
06_spiffs_rw
程序说明
- 本示例挂载名为
storage的 SPIFFS 分区。 - 程序会写入测试文件，再读回文件内容并通过串口输出结果。
硬件连接
- 将开发板接入电脑。
- 该示例使用工程内的自定义分区表，无需外接模块。
代码分析
app_main()：挂载 SPIFFS，写入测试文件，读回文件内容，并输出检查结果。bsp_spiffs_mount()：挂载storageSPIFFS 分区。fopen()、fwrite()和fread()：执行文件写入和读回。bsp_spiffs_unmount()：测试完成后卸载 SPIFFS。
运行效果
- 串口输出 SPIFFS 挂载、文件读写和示例完成状态。
07_wifi_scan
程序说明
- 本示例使用 ESP32-C5 内置 Wi-Fi 扫描附近热点。
- 串口输出可打印 SSID、RSSI、信道和认证方式等信息。
硬件连接
- 将开发板接入电脑。
- 确认周围存在可扫描到的 2.4 GHz 或 5 GHz Wi-Fi 热点。
代码分析
app_main()：初始化 NVS 和 Wi-Fi STA 模式，并创建扫描任务。init_nvs()：初始化 NVS，供 Wi-Fi 组件使用。init_wifi_sta()：初始化 Wi-Fi，并设置为 STA 模式。wifi_scan_task()：周期执行 Wi-Fi 扫描并输出结果。ssid_to_printable_ascii()：过滤不可打印字符，便于串口显示 SSID。
运行效果
- 串口周期输出 Wi-Fi 扫描结果，包括热点数量、SSID、RSSI 和信道信息。
08_board_showcase
程序说明
- 本示例综合检测 LCD、背光、WS2812B RGB LED、SPIFFS、microSD 卡和 Wi-Fi 扫描。
- LCD 页面显示各功能项的
RUN、PASS、WARN或FAIL状态。 - RGB LED 会根据最终检测结果显示不同颜色。
硬件连接
- 将开发板接入电脑。
- 如需检测 SD 卡，请将 FAT 或 FAT32 格式的 Micro SD 卡装入开发板。
代码分析
app_main()：启动 BSP 显示服务，设置屏幕方向和背光，并创建综合检测任务。create_ui()：创建板载资源状态面板。showcase_task()：依次检查 LCD、RGB LED、SPIFFS、SD 卡和 Wi-Fi。write_read_file()：对 SPIFFS 或 SD 卡执行文件写入和读回检查。wifi_scan_once()：执行一次 Wi-Fi 扫描，并生成状态文本。set_item()：更新各功能项状态和说明文本。bsp_setledcolor()：根据最终状态设置 RGB LED 颜色。
运行效果
- LCD 显示各功能检测结果；检测完成后，页面底部显示最终状态，RGB LED 同步显示最终状态颜色。
综合示例状态说明
08_board_showcase 会在 LCD 上显示各功能检查结果，并通过 RGB LED 显示最终状态。
| LED 状态 | 含义 |
|---|---|
| 绿色 | 所有项目均为 PASS。 |
| 黄色 | 存在 WARN，例如未插入 SD 卡或未扫描到 Wi-Fi。 |
| 红色 | 存在 FAIL，表示某个功能检查失败。 |
说明：
- 未插入 SD 卡时，SD 项会显示
CHECK或No card，最终 LED 为黄色。 - Wi-Fi 环境中没有可扫描到的热点时，Wi-Fi 项为告警状态，最终 LED 为黄色。
- SPIFFS 首次运行时可能提示格式化，这是正常现象。
使用说明
05_sdcard_rw运行前，请插入 FAT 或 FAT32 格式的 Micro SD 卡。06_spiffs_rw和08_board_showcase使用自定义分区表，并包含storageSPIFFS 分区。- LCD 和 Micro SD 共用 SPI 时钟与 MOSI 引脚，由 BSP 初始化 SPI 总线。
- 板载 RGB LED 示例按
red, green, blue顺序传入颜色参数。 - 当前 BSP 未启用触摸、按键、音频或 IMU 功能。