跳到主要内容

Arduino 开发

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

Arduino 入门教程​

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

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

配置开发环境​

1. 安装和配置 Arduino IDE​

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

2. 安装库​

  • 在安装 Arduino 库时，通常有两种方式可供选择：在线安装 和 离线安装。若库安装要求离线安装，则必须使用提供的库文件。
  • 对于大多数库，用户可以通过 Arduino 软件的在线库管理器轻松搜索并安装。然而，一些开源库或自定义库未被同步到 Arduino 库管理器中，因此无法通过在线搜索获取。在这种情况下，用户只能通过离线方式手动安装这些库。 =
库或文件名称说明版本安装方式
LVGL图形库v8.4.0“在线”安装
JPEGDECJPEG 解码器库v1.8.4“在线”安装
GFX_Library_for_ArduinoLCD 驱动库v1.5.9"在线 安装"
版本兼容性说明

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

3. Arduino 工程参数设置​

示例程序​

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

示例程序基础例程说明依赖库版本
01_gfx_helloworld屏幕上显示 HelloWorldGFX_Library_for_Arduino
02_sd_card_test测试 SD 卡JPEGDEC-
03_Brightness使用按键控制背光LVGL8.4.0
04_LVGL使用 lvgl 跑分示例LVGL8.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) 保持现场便于排查。

【运行效果】