ESP32-C3-LCD-1.47 使用教程

产品特性

采用 ESP32-C3FH4 主控芯片，搭载 RISC-V 32 位单核低功耗 SoC，主频最高可达 160MHz
支持 2.4GHz Wi-Fi（802.11 b/g/n）与蓝牙 BLE 5 无线通信
内置 400KB SRAM 和 384KB ROM，叠封 4MB Flash
板载陶瓷天线，便于集成到用户自定义底板或嵌入式设备中
集成 USB 全速串口控制器，方便程序下载与调试
引出 15 路 GPIO，可灵活扩展多种外设功能
提供丰富外设资源，包括 3 × SPI、1 × I2C、2 × UART、1 × I2S、2 × ADC 等接口

产品参数

参数名称	参数
接口	USB Type-C
主控芯片	ESP32-C3FH4
屏幕类型	ISP
屏幕分辨率	172 × 320
显示芯片	ST7798

接口介绍

产品尺寸

Arduino 开发

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

Arduino 入门教程

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

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

配置开发环境

1. 安装和配置 Arduino IDE

请参考安装和配置 Arduino IDE 教程下载安装 Arduino IDE 并添加 ESP32 支持。

2. 安装库

在安装 Arduino 库时，通常有两种方式可供选择：在线安装和离线安装。若库安装要求离线安装，则必须使用提供的库文件。
对于大多数库，用户可以通过 Arduino 软件的在线库管理器轻松搜索并安装。然而，一些开源库或自定义库未被同步到 Arduino 库管理器中，因此无法通过在线搜索获取。在这种情况下，用户只能通过离线方式手动安装这些库。 =

库或文件名称	说明	版本	安装方式
LVGL	图形库	v8.4.0	“在线”安装
JPEGDEC	JPEG 解码器库	v1.8.4	“在线”安装
GFX_Library_for_Arduino	LCD 驱动库	v1.5.9	"在线安装"

版本兼容性说明

LVGL 及其驱动库的版本之间存在较强的依赖关系。例如，为 LVGL v8 编写的驱动可能不兼容 LVGL v9。为确保示例能够稳定复现，推荐使用上表列出的特定版本。混合使用不同版本的库可能导致编译失败或运行时异常。

3. Arduino 工程参数设置

示例程序

Arduino 示例程序位于示例程序包的 Arduino/examples 目录中。

示例程序	基础例程说明	依赖库	版本
01_gfx_helloworld	屏幕上显示 HelloWorld	GFX_Library_for_Arduino
02_sd_card_test	测试 SD 卡	JPEGDEC	-
03_Brightness	使用按键控制背光	LVGL	8.4.0
04_LVGL	使用 lvgl 跑分示例	LVGL	8.4.0

01_gfx_helloworld

【程序说明】

本示例演示了 ESP32-C3-LCD-1.47 使用 GFX_Library_for_Arduino 库驱动屏幕并在屏幕上显示 HelloWorld

【硬件连接】

使用 USB 线把板子接入电脑

【代码分析】

loop()：循环刷新显示内容，每次随机位置/颜色/字号输出一行文字。
gfx->setCursor()：设置本次文字输出的起始坐标。
gfx->setTextColor()：设置前景色/背景色（这里用随机值，便于观察刷新效果）。
gfx->setTextSize()：设置字号缩放倍率（随机变化）。
gfx->println("Hello World!") / delay(1000)：输出文本并延时 1 秒，形成跳动的动态演示。

  void loop(void)
  {
    gfx->setCursor(random(gfx->width()), random(gfx->height()));
    gfx->setTextColor(random(0xffff), random(0xffff));
    gfx->setTextSize(random(6), random(6), random(2));
    gfx->println("Hello World!");
    delay(1000);
  }

【运行效果】

屏幕上显示 helloworld。

02_SD

【程序说明】

本示例演示了 ESP32-C3-LCD-1.47 测试读取SD卡中的jpg图片并且显示在屏幕上。

【硬件连接】

将板子接入电脑
将 Micro SD 卡插入卡槽（SD 卡需要格式化为 FAT32 ）
将图片 image_01.jpg 放到 SD 卡的根目录下

【代码分析】

jpgPath：待显示的 jpg 文件路径（从 SD 卡根目录查找得到）。
Serial.printf("draw: %s\r\n", jpgPath)：串口输出当前要绘制的文件名，便于确认读取到的图片是否正确。
gfx->fillScreen(RGB565_BLACK)：绘制前清屏，避免残影/叠帧影响观感。
```
Serial.printf("draw: %s\r\n", jpgPath);
gfx->fillScreen(RGB565_BLACK);
```

【运行效果】

烧录完程序，屏幕上将显示图片。

03_Brightness

【程序说明】

本示例演示了通过BOOT按键控制屏幕亮度,通过双击BOOT按键可以切换控制逻辑。

【硬件连接】

将板子接入电脑

【代码分析】

gfx->fillScreen(RGB565_WHITE)：清屏并设置 UI 的底色。
gfx->printf("Brightness %u%%", backlight)：把当前背光百分比输出到屏幕上。
drawBarFrame() / drawBarValue()：绘制亮度条边框与当前亮度填充，直观展示亮度变化。
increase ? ... : ...：根据当前控制逻辑显示“增亮/减亮”模式，并用红/绿做区分。

  gfx->fillScreen(RGB565_WHITE);
  gfx->setTextColor(RGB565_BLACK, RGB565_WHITE);
  gfx->setTextSize(2);
  gfx->setCursor(18, 30);
  gfx->println("BOOT Control");

  gfx->setCursor(18, 90);
  gfx->printf("Brightness %u%%", backlight);

  drawBarFrame(18, 125, 144, 20);
  drawBarValue(18, 125, 144, 20, backlight);

  gfx->setCursor(18, 175);
  gfx->setTextColor(increase ? RGB565_RED : RGB565_GREEN, RGB565_WHITE);
  gfx->println(increase ? "Mode: Increase" : "Mode: Decrease");

  gfx->setCursor(18, 260);
  gfx->setTextColor(RGB565_BLACK, RGB565_WHITE);
  gfx->println("Double Click Switch");

【运行效果】

04_LVGL

【程序说明】

本示例演示了 ESP32-C3-LCD-1.47 运行 lvgl 跑分示例。

  Serial.begin(115200);
  delay(50);
  Serial.println("ESP32_C3_LCD_1in47 LVGL example");

  if (!lcd.begin()) {
    Serial.printf("lcd.begin failed: %s\r\n", esp_err_to_name(lcd.lastError()));
    while (true) {
      delay(1000);
    }
  }

  gfx = lcd.gfx();
  gfx->fillScreen(RGB565_BLACK);

  if (!initLvgl()) {
    Serial.println("LVGL init failed");
    gfx->setCursor(8, 8);
    gfx->setTextColor(RGB565_RED);
    gfx->println("LVGL init failed");
    while (true) {
      delay(1000);
    }
  }

【代码分析】

Serial.begin(115200)：初始化串口，便于输出运行日志与错误信息。
lcd.begin()：初始化 LCD 驱动与底层总线；失败则打印错误并在 while (true) 中停住，避免继续运行导致异常。
gfx = lcd.gfx() / gfx->fillScreen(RGB565_BLACK)：获取绘图库句柄并清屏，为后续界面绘制准备初始画面。
initLvgl()：初始化 LVGL（显示缓冲/驱动注册等）；失败则在屏幕上提示并进入 while (true) 保持现场便于排查。

【运行效果】

ESP-IDF

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

ESP-IDF 入门教程

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

配置 ESP-IDF 开发环境

信息

对于 ESP32-C3-LCD-1.47 开发板，需要使用 ESP-IDF V5.5.0 以上版本。

备注

以下内容以 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_Factory	综合测试程序	-
02_SD	测试 SD 卡读写	-
03_Brightness	lvgl 示例程序	-
04_LVGL	使用 lvgl 跑分示例	-

01_Factory

【程序说明】

本示例测试 ESP32-C3-LCD-1.47 板载模块的功能，屏幕上将显示各个模块的信息，用户可以通过按下BOOT按键进行页面切换

【硬件连接】

将板子接入电脑
将 Micro SD 卡插入卡槽

【代码分析】

IO_EXTENSION_Init()：初始化 IO 扩展（如背光/按键等外设控制口）。
LCD_Init()：初始化 LCD 屏与显示接口。
SD_Init() / QMI8658_Init() / Wireless_Init()：初始化 SD 卡、IMU、无线等板载模块，用于综合功能演示。
lvgl_display_init() / Lvgl_Example1()：初始化 LVGL 显示并启动示例 UI 页面。

while (true) { lv_timer_handler(); ... }：在任务循环里周期性驱动 LVGL 和传感器轮询，保持界面与数据刷新。

void Factory_Example(void)
{
    ESP_LOGI(TAG, "board init");
    IO_EXTENSION_Init();
    ESP_ERROR_CHECK(LCD_Init());
    SD_Init();
    QMI8658_Init();
    Wireless_Init();

    ESP_LOGI(TAG, "lvgl init");
    lvgl_display_init();
    Lvgl_Example1();

    while (true) {
        lv_timer_handler();
        vTaskDelay(pdMS_TO_TICKS(10));
        QMI8658_Loop();
    }
}

【运行效果】

烧录完程序，屏幕上将显示图片。

02_SD

【程序说明】

本示例演示了 ESP32-C3-LCD-1.47 测试读取SD卡中的jpg图片并且显示在屏幕上。

【硬件连接】

将板子接入电脑
将 Micro SD 卡插入卡槽（SD 卡需要格式化为 FAT32 ）
将图片 image_01.jpg 放到 SD 卡的根目录下

【代码分析】

ESP_GOTO_ON_ERROR(..., EXIT, ...)：串行初始化/检查流程，任一步失败直接跳转到统一退出路径，减少层层判断。
jpg_decode_buffer_init()：初始化 JPEG 解码所需的全局缓冲区。
sd_init_with_retry() / sd_find_jpg() / sd_read_file_retry()：SD 卡初始化、查找 jpg、读取文件（带重试），提升可靠性。
lcd_draw_jpg(jpg_data, jpg_size)：对读到的 jpg 数据解码并绘制到屏幕。

EXIT: free(jpg_data)：释放动态申请的图片缓存，随后进入 while (true) 保持任务存活便于观察现象。

void SD_Example(void)
{
    esp_err_t ret = ESP_OK;
    char jpg_path[SD_EXAMPLE_PATH_MAX] = {0};
    uint8_t *jpg_data = NULL;
    size_t jpg_size = 0;

    ESP_GOTO_ON_ERROR(IO_EXTENSION_Init(), EXIT, TAG, "IO init failed");
    ESP_GOTO_ON_ERROR(LCD_Init(), EXIT, TAG, "LCD init failed");
    ESP_GOTO_ON_ERROR(jpg_decode_buffer_init(), EXIT, TAG, "alloc global jpg buffer failed");
    ESP_GOTO_ON_ERROR(sd_init_with_retry(), EXIT, TAG, "SD init failed");
    ESP_GOTO_ON_ERROR(sd_find_jpg(jpg_path, sizeof(jpg_path)), EXIT, TAG, "jpg not found");
    ESP_GOTO_ON_ERROR(sd_read_file_retry(jpg_path, &jpg_data, &jpg_size), EXIT, TAG, "read jpg failed");
    ESP_GOTO_ON_ERROR(lcd_draw_jpg(jpg_data, jpg_size), EXIT, TAG, "draw jpg failed");

EXIT:
    free(jpg_data);
    while (true) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

【运行效果】

烧录完程序，屏幕上将显示图片。

03_Brightness

【程序说明】

本示例演示了通过BOOT按键控制屏幕亮度,通过双击BOOT按键可以切换控制逻辑。

【硬件连接】

将板子接入电脑

【代码分析】

IO_EXTENSION_Init() / LCD_Init()：初始化 IO 扩展与 LCD 显示，为 LVGL 显示提供底层驱动。
lvgl_display_init()：注册显示驱动与缓冲区，让 LVGL 可以正常刷新屏幕。
boot_key_init() / boot_key_poll()：初始化并轮询 BOOT 按键，用于切换亮度调节逻辑/触发事件。
ui_init()：初始化亮度控制示例的界面元素（文本、进度条等）。

while (true) { ... lv_timer_handler(); ... }：循环驱动按键与 LVGL 任务调度，实现实时 UI 更新。

void Brightness_Example(void)
{
    ESP_ERROR_CHECK(IO_EXTENSION_Init());
    ESP_ERROR_CHECK(LCD_Init());
    lvgl_display_init();
    boot_key_init();
    ui_init();

    while (true) {
        boot_key_poll();
        lv_timer_handler();
        vTaskDelay(pdMS_TO_TICKS(10));
    }
}

【运行效果】

04_LVGL

【程序说明】

本示例演示了 ESP32-C3-LCD-1.47 运行 lvgl 跑分示例。

void LVGL_Benchmark_Example(void)
{
    ESP_ERROR_CHECK(IO_EXTENSION_Init());
    ESP_ERROR_CHECK(LCD_Init());
    lvgl_display_init();
    xTaskCreate(lvgl_benchmark_task, "lvgl_bench", 6144, NULL, 5, NULL);
}

【代码分析】

IO_EXTENSION_Init() / LCD_Init()：初始化板级 IO 与 LCD 显示接口。
lvgl_display_init()：初始化 LVGL 显示层，使 benchmark 可以输出到屏幕。
xTaskCreate(lvgl_benchmark_task, ...)：创建跑分任务，避免在初始化函数内阻塞；benchmark 逻辑在独立任务里执行并刷新界面。

【运行效果】

技术支持

周一-周五（9:30-6:30）周六（9:30-5:30）

手机：13434470212

邮箱：services04@spotpear.cn

QQ：202004841

斑梨电子

ESP32-C3-LCD-1.47 使用教程

产品特性

产品参数

接口介绍

产品尺寸

Arduino 开发

Arduino 入门教程

配置开发环境

1. 安装和配置 Arduino IDE

2. 安装库

3. Arduino 工程参数设置

示例程序

01_gfx_helloworld

02_SD

03_Brightness

04_LVGL

ESP-IDF

ESP-IDF 入门教程

配置 ESP-IDF 开发环境

安装 ESP-IDF 开发环境

安装 Visual Studio Code 与 ESP-IDF 扩展

示例程序

01_Factory

02_SD

03_Brightness

04_LVGL

相关资料

1. 硬件资料

2. 示例程序

3. 技术手册

技术支持

ESP32-C3 1.47寸开发板LCD显示屏 SD卡槽172×320

[教程导航]

斑梨电子

ESP32-C3-LCD-1.47 使用教程

产品特性​

产品参数​

接口介绍​

产品尺寸​

Arduino 入门教程​

配置开发环境​

1. 安装和配置 Arduino IDE​

2. 安装库​

3. Arduino 工程参数设置​

示例程序​

01_gfx_helloworld​

02_SD​

03_Brightness​

04_LVGL​

ESP-IDF 入门教程​

配置 ESP-IDF 开发环境​

安装 ESP-IDF 开发环境​

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

示例程序​

01_Factory​

02_SD​

03_Brightness​

04_LVGL​

1. 硬件资料​

2. 示例程序​

3. 技术手册​

技术支持

ESP32-C3 1.47寸开发板LCD显示屏 SD卡槽172×320

[教程导航]

产品特性

产品参数

接口介绍

产品尺寸

Arduino 入门教程

配置开发环境

1. 安装和配置 Arduino IDE

2. 安装库

3. Arduino 工程参数设置

示例程序

01_gfx_helloworld

02_SD

03_Brightness

04_LVGL

ESP-IDF 入门教程

配置 ESP-IDF 开发环境

安装 ESP-IDF 开发环境

安装 Visual Studio Code 与 ESP-IDF 扩展

示例程序

01_Factory

02_SD

03_Brightness

04_LVGL

1. 硬件资料

2. 示例程序

3. 技术手册