跳到主要内容

Arduino 开发

本章节介绍 ESP32-S3-Touch-AMOLED-2.06 的 Arduino 开发环境配置、依赖库安装方法，以及产品仓库中 Arduino 示例程序的功能和运行现象。

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

阅读前准备

运行示例前，请确认以下条件已经满足：

  • 已准备 ESP32-S3-Touch-AMOLED-2.06 开发板。
  • 已使用 USB 数据线连接开发板和电脑。
  • 已安装 Arduino IDE。
  • 已安装 esp32 by Espressif Systems 开发板包，版本不低于 v3.2.0。
  • 已下载 ESP32-S3-Touch-AMOLED-2.06 Arduino 示例程序。
  • 已按本页说明安装 examples/arduino/libraries 目录中的库和配置文件。

Arduino 入门教程​

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

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

配置开发环境​

1. 安装和配置 Arduino IDE​

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

在 Arduino IDE 的开发板管理器中安装：

开发板包安装方式版本要求
esp32 by Espressif Systems在线或离线安装v3.2.0 或更高版本

2. 设置 Arduino 工程参数​

打开任意示例后，建议按以下方式配置：

Arduino IDE 选项建议设置
BoardESP32S3 Dev Module
Port开发板对应的 COM 端口
USB CDC On BootEnabled
Flash Size与板载 32MB Flash 相匹配
PSRAM启用 OPI PSRAM
Partition SchemeLVGL 示例建议选择具有较大应用程序空间的分区
USB 串口说明

本产品的 Type-C 下载和调试接口由 ESP32-S3 原生 USB 引出。示例 01～07 使用 HWCDC USBSerial 输出调试信息；如自行编写代码并使用 Serial，请启用 USB CDC On Boot。串口监视器波特率建议设置为 115200。

3. 安装依赖库​

产品仓库已提供与示例匹配的离线库，推荐直接使用仓库中的版本：

examples/arduino/libraries
├── Arduino_DriveBus
├── Arduino_GFX
├── SensorLib
├── XPowersLib
├── lvgl
├── Mylibrary
│   └── pin_config.h
└── lv_conf.h
库或文件作用推荐版本或说明安装方式
Arduino_DriveBusFT3168 触摸控制器的 I2C 驱动示例包提供手动安装
Arduino_GFXCO5300 AMOLED 显示驱动和基础图形绘制v1.6.0；库管理器中通常显示为 GFX Library for Arduino推荐使用示例包版本
lvglLVGL 图形界面框架v9.3.0推荐使用示例包版本
SensorLibPCF85063 RTC、QMI8658 IMU 等器件驱动v0.3.1推荐使用示例包版本
XPowersLibAXP2101 电源管理芯片驱动v0.2.6推荐使用示例包版本
Mylibrary/pin_config.h开发板引脚和硬件参数定义示例包提供手动安装
lv_conf.hLVGL 功能、字体和 Demo 配置示例包提供手动安装

推荐安装步骤：

  1. 下载或克隆产品仓库。

  2. 找到 examples/arduino/libraries 目录。

  3. 将该目录中的库文件夹和配置文件复制到 Arduino 库目录。

    Windows 默认库目录通常为：

    C:\Users\<用户名>\Documents\Arduino\libraries

    也可以在 Arduino IDE 中通过 File > Preferences 查看 Sketchbook location，其下的 libraries 文件夹即为库目录。

  4. 重启 Arduino IDE，再打开并编译示例。

LVGL 版本兼容性

本产品当前 Arduino 示例使用 LVGL v9.3.0，代码中包含以下 LVGL v9 接口：

lv_display_t
lv_display_create()
lv_display_set_buffers()
lv_indev_create()
lv_tick_set_cb()

不要沿用 ESP32-S3-Touch-AMOLED-2.16 示例所使用的 LVGL v8.4.0。LVGL v8 与 v9 的显示驱动、输入设备和缓冲区 API 差异较大，混用会导致大量编译错误。

如果通过 Arduino 库管理器在线安装 LVGL，还需要确认 demos 目录可被以下头文件路径找到：

#include <demos/lv_demos.h>

为避免版本和目录结构不匹配，建议优先使用产品仓库内提供的 lvgl 与 lv_conf.h。

4. 编译和下载​

  1. 在 Arduino IDE 中打开示例目录内与目录同名的 .ino 文件。
  2. 选择 ESP32S3 Dev Module 和正确的 COM 端口。
  3. 检查 USB CDC、Flash、PSRAM 和分区设置。
  4. 单击“验证/编译”，确认没有缺失库或版本冲突。
  5. 单击“上传”，等待程序下载完成。
  6. 如需查看调试信息，打开串口监视器并设置为 115200。

如果设备未能自动进入下载模式，可按住 BOOT，重新连接 USB，然后再次上传。

示例程序​

Arduino 示例位于产品仓库的 examples/arduino 目录中。

示例程序基础功能主要依赖
01_HelloWorld使用 Arduino GFX 显示随机文字Arduino_GFX
02_GFX_AsciiTable在屏幕上绘制 ASCII 字符表Arduino_GFX
03_LVGL_PCF85063_simpleTime读取 PCF85063 RTC，并用 LVGL 显示日期和时间LVGL、SensorLib、Arduino_DriveBus
04_LVGL_QMI8658_ui读取 QMI8658，并用 LVGL 绘制三轴加速度曲线LVGL、SensorLib、Arduino_DriveBus
05_LVGL_AXP2101_ADC_Data读取 AXP2101 电源数据并显示LVGL、XPowersLib、Arduino_DriveBus
06_LVGL_Arduino_v9运行 LVGL v9 Widgets Demo，并验证触摸LVGL、Arduino_DriveBus
07_LVGL_SD_Test挂载 TF 卡并显示卡信息和根目录文件LVGL、Arduino_DriveBus、SD_MMC
08_ES8311播放内置音频并执行麦克风到扬声器的音频回环ESP_I2S、示例自带 ES8311 驱动

1. 目录结构​

examples/arduino
├── 01_HelloWorld
├── 02_GFX_AsciiTable
├── 03_LVGL_PCF85063_simpleTime
├── 04_LVGL_QMI8658_ui
├── 05_LVGL_AXP2101_ADC_Data
├── 06_LVGL_Arduino_v9
├── 07_LVGL_SD_Test
├── 08_ES8311
└── libraries

每个编号目录都是一个独立 Arduino 工程。打开示例时，应打开对应目录内的同名 .ino 文件，例如：

examples/arduino/01_HelloWorld/01_HelloWorld.ino

音频示例还包含驱动和音频数据文件：

08_ES8311
├── 08_ES8311.ino
├── canon.h
├── es8311.c
├── es8311.h
└── es8311_reg.h

第一次运行推荐顺序

01_HelloWorld
  ↓
02_GFX_AsciiTable
  ↓
03_LVGL_PCF85063_simpleTime
  ↓
04_LVGL_QMI8658_ui
  ↓
05_LVGL_AXP2101_ADC_Data
  ↓
06_LVGL_Arduino_v9
  ↓
07_LVGL_SD_Test
  ↓
08_ES8311
  • 先用 01_HelloWorld 和 02_GFX_AsciiTable 验证显示屏、分辨率和绘图方向。
  • 再用 03～05 分别验证 RTC、IMU 和电源管理芯片。
  • 使用 06_LVGL_Arduino_v9 综合验证 LVGL v9、显示缓冲区和触摸输入。
  • 插入 TF 卡后运行 07_LVGL_SD_Test。
  • 最后运行 08_ES8311 验证音频播放和回环。

2. 示例说明​

01_HelloWorld​

【功能说明】

该示例使用 Arduino GFX 初始化 CO5300 AMOLED 屏幕，先在屏幕上显示一行红色 Hello World!，随后在随机位置以随机颜色和大小不断绘制文字。

主要功能：

  • 创建 Arduino_ESP32QSPI 显示总线。
  • 创建 Arduino_CO5300 显示对象。
  • 使用 410×502 的屏幕参数和 22 像素列偏移。
  • 清屏并显示固定文字。
  • 在 loop() 中持续绘制随机文字。

【代码入口】

01_HelloWorld/01_HelloWorld.ino
代码作用
Arduino_ESP32QSPI(...)创建 QSPI 显示总线
Arduino_CO5300(...)创建 CO5300 显示对象
gfx->begin()初始化显示屏
gfx->fillScreen(WHITE)使用白色清屏
gfx->setTextColor(...)设置文字颜色
gfx->setTextSize(...)设置随机文字缩放
gfx->println("Hello World!")绘制文字

【正常运行现象】

屏幕先显示红色 Hello World!，两秒后开始在随机位置连续显示不同颜色和大小的同一文字。

【常见排查】

现象可能原因建议处理
找不到 Arduino_GFX_Library.hArduino_GFX 未安装或目录层级错误使用示例包内 Arduino_GFX，并检查 library.properties 所在层级
屏幕不亮开发板、PSRAM、显示引脚或库版本不匹配恢复示例包的 pin_config.h 和库版本
画面整体偏移缺少 CO5300 的列偏移参数恢复 Arduino_CO5300 构造函数中的 22 像素列偏移
串口无输出选错 USB 端口选择原生 USB CDC 对应端口，波特率设为 115200

02_GFX_AsciiTable​

【功能说明】

该示例使用 Arduino GFX 在 AMOLED 屏幕上绘制 ASCII 字符表，用于检查字符绘制、屏幕坐标、行列排布和显示方向。

主要功能：

  • 初始化 CO5300 显示屏。
  • 根据屏幕尺寸计算可显示的行列。
  • 绘制行列编号。
  • 逐个绘制 ASCII 字符。

【代码入口】

02_GFX_AsciiTable/02_GFX_AsciiTable.ino
代码作用
gfx->width() / gfx->height()获取当前屏幕尺寸
gfx->setCursor(...)设置字符绘制位置
gfx->print(...)绘制行列编号
gfx->drawChar(...)绘制单个 ASCII 字符

【正常运行现象】

屏幕显示 ASCII 字符表及行列编号。绘制完成后画面保持不变。

【常见排查】

现象可能原因建议处理
字符表超出屏幕屏幕宽高或字符间距被修改检查 pin_config.h 中的 LCD_WIDTH、LCD_HEIGHT
字符或画面错位CO5300 偏移参数错误使用官方示例中的显示对象构造参数
字符方向不正确显示旋转参数被修改恢复示例默认 rotation 设置

03_LVGL_PCF85063_simpleTime​

【功能说明】

该示例使用 SensorLib 驱动 PCF85063 RTC，通过 LVGL v9 在屏幕中央显示时间和日期，同时初始化 FT3168 触摸控制器。

主要功能：

  • 初始化 CO5300 显示屏和 FT3168 触摸控制器。
  • 初始化 PCF85063 RTC。
  • 设置 RTC 的初始日期和时间。
  • 创建 LVGL v9 显示设备、输入设备和全屏缓冲区。
  • 每秒读取 RTC，并刷新屏幕标签与串口信息。

【代码入口】

03_LVGL_PCF85063_simpleTime/03_LVGL_PCF85063_simpleTime.ino
函数或代码作用
rtc.begin(...)初始化 PCF85063
rtc.setDateTime(...)设置 RTC 日期和时间
rtc.getDateTime()读取当前日期和时间
lv_display_create(...)创建 LVGL v9 显示设备
lv_indev_create()创建 LVGL 触摸输入设备
lv_label_set_text(...)更新时间显示

【正常运行现象】

屏幕中央显示两行内容：

HH:MM:SS
DD-MM-YYYY

串口每秒输出年、月、日、时、分、秒。

RTC 时间设置

官方示例会在每次启动时执行 rtc.setDateTime(...)，默认写入代码中固定的日期和时间。实际项目中应将其修改为用户设置、网络校时或仅在首次启动时写入，否则每次重启都会重置 RTC。

【常见排查】

现象可能原因建议处理
RTC 初始化后停止运行I2C 引脚、地址或 SensorLib 版本错误检查 IIC_SDA、IIC_SCL 和 SensorLib v0.3.1
串口出现 Failed to find PCF8563官方示例错误信息沿用了 PCF8563 名称本板实际器件为 PCF85063，仍应按 RTC I2C 通信失败排查
找不到 LVGL v9 API误装 LVGL v8安装示例包中的 LVGL v9.3.0
字体 lv_font_montserrat_40 未定义lv_conf.h 未启用对应字体使用示例包中的 lv_conf.h

04_LVGL_QMI8658_ui​

【功能说明】

该示例使用 SensorLib 读取 QMI8658 六轴 IMU，并通过 LVGL Chart 实时绘制 X、Y、Z 三轴加速度曲线。

主要功能：

  • 初始化显示屏、FT3168 触摸和 LVGL v9。
  • 初始化 QMI8658。
  • 将加速度计配置为 ±4g、1000Hz。
  • 创建三条不同颜色的 LVGL 曲线。
  • 在串口输出加速度和陀螺仪数据。

【代码入口】

04_LVGL_QMI8658_ui/04_LVGL_QMI8658_ui.ino
函数或代码作用
qmi.begin(...)初始化 QMI8658
qmi.configAccelerometer(...)配置加速度计量程和输出速率
qmi.enableAccelerometer()启用加速度计
lv_chart_create(...)创建折线图
lv_chart_add_series(...)添加 X、Y、Z 三条曲线
lv_chart_set_next_value(...)添加新的加速度数据

【正常运行现象】

屏幕显示三轴加速度折线图。移动或倾斜开发板时，红、绿、蓝三条曲线随姿态变化；串口输出格式类似：

{ACCEL: x,y,z}
{GYRO: x,y,z}

【常见排查】

现象可能原因建议处理
显示 Failed to find QMI8658IMU I2C 通信失败检查 QMI8658_L_SLAVE_ADDRESS、I2C 引脚和 SensorLib
图表不刷新LVGL 任务处理或 IMU 数据就绪逻辑异常确认 loop() 中持续执行 lv_task_handler()
串口有数据但屏幕无图LVGL 缓冲区分配或显示驱动异常先运行 01、02 验证显示，再检查 PSRAM 和 LVGL 版本
曲线变化不明显开发板静止移动或倾斜开发板进行测试

05_LVGL_AXP2101_ADC_Data​

【功能说明】

该示例使用 XPowersLib 驱动 AXP2101 电源管理芯片，并通过 LVGL v9 显示电源和电池状态。

主要显示内容包括：

  • PMU 温度。
  • 充电、放电和待机状态。
  • VBUS 是否接入及是否有效。
  • 充电状态。
  • 电池电压、VBUS 电压和系统电压。
  • 电池电量百分比。

【代码入口】

05_LVGL_AXP2101_ADC_Data/05_LVGL_AXP2101_ADC_Data.ino
函数或代码作用
Wire.begin(IIC_SDA, IIC_SCL)初始化 AXP2101 所在的 I2C 总线
power.disableIRQ(...) / power.enableIRQ(...)配置 AXP2101 中断
adcOn()启用温度、电池、VBUS 和系统电压检测
adcOff()关闭相关 ADC 检测
power.getBattVoltage()读取电池电压
power.getVbusVoltage()读取 VBUS 电压
power.getSystemVoltage()读取系统电压
power.getBatteryPercent()读取电池电量百分比
lv_label_set_text(...)更新屏幕上的电源信息

【正常运行现象】

屏幕显示 AXP2101 的电源状态、电压和电量信息。连接或断开 USB、电池状态改变时，显示内容会随之变化。

【常见排查】

现象可能原因建议处理
显示 PMU 不在线AXP2101 I2C 通信失败检查 I2C 引脚、地址和 pin_config.h
找不到 XPowersLib.hXPowersLib 未安装使用示例包内 XPowersLib v0.2.6
电池百分比不显示未检测到电池检查电池连接、极性和保护状态
电压数据异常ADC 未启用或供电状态不稳定确认调用 adcOn()，并检查 USB/电池连接

06_LVGL_Arduino_v9​

【功能说明】

该示例用于验证 LVGL v9 的显示、触摸和 Widgets Demo。代码默认运行：

lv_demo_widgets();

代码中还预留了其他 Demo：

// lv_demo_benchmark();
// lv_demo_keypad_encoder();
// lv_demo_music();
// lv_demo_stress();

【代码入口】

06_LVGL_Arduino_v9/06_LVGL_Arduino_v9.ino
函数或代码作用
FT3168->begin()初始化 FT3168 触摸控制器
lv_tick_set_cb(millis_cb)为 LVGL 设置系统节拍来源
lv_display_create(...)创建 LVGL v9 显示设备
lv_display_set_buffers(...)配置全屏直接渲染缓冲区
lv_indev_create()创建触摸输入设备
lv_demo_widgets()启动 Widgets Demo

【正常运行现象】

屏幕显示 LVGL Widgets Demo，可通过触摸操作控件。触摸屏幕时，串口输出坐标，例如：

Data x 123
Data y 245

【使用注意】

  • 该示例使用 410×502 的全屏 RGB565 缓冲区，内存占用较高，必须正确启用 PSRAM。
  • LVGL 在线安装版本如未包含可编译的 demos 目录，会在 lv_demo_widgets() 处编译失败。
  • Arduino GFX 在此场景下的刷新性能可能低于 ESP-IDF 双缓冲和防撕裂示例。

【常见排查】

现象可能原因建议处理
找不到 lv_display_t安装了 LVGL v8改用 LVGL v9.3.0
找不到 lv_demo_widgetsDemo 源码未启用或目录位置错误使用仓库内 LVGL 和 lv_conf.h
屏幕黑屏或反复重启PSRAM 未启用或缓冲区分配失败启用 OPI PSRAM并选择合适分区
触摸无响应FT3168 初始化失败或中断引脚错误查看串口是否持续输出 FT3168 initialization fail
触摸坐标方向不正确显示旋转与触摸坐标未同步恢复官方示例的 rotation 和触摸映射

07_LVGL_SD_Test​

【功能说明】

该示例使用 ESP32 Arduino Core 内置的 SD_MMC 驱动挂载 TF 卡，并通过 LVGL 显示卡类型、容量和根目录文件列表。

主要功能：

  • 初始化显示、触摸和 LVGL v9。
  • 通过 SD_MMC.setPins(...) 设置 TF 卡引脚。
  • 以 1-bit 模式挂载 /sdcard。
  • 检测 MMC、SDSC、SDHC 等卡类型。
  • 获取卡容量。
  • 枚举根目录文件，并同时显示在屏幕和串口中。

【代码入口】

07_LVGL_SD_Test/07_LVGL_SD_Test.ino
函数或代码作用
SD_MMC.setPins(...)设置 SDMMC 时钟、命令和数据引脚
SD_MMC.begin("/sdcard", true)以 1-bit 模式挂载 TF 卡
SD_MMC.cardType()获取卡类型
SD_MMC.cardSize()获取卡容量
listDir(SD_MMC, "/", 0)枚举根目录文件
lv_label_set_long_mode(...)设置长文本自动换行

【正常运行现象】

插入已格式化的 TF 卡后，屏幕显示类似：

SD_MMC Card Type: SDHC
SD_MMC Card Size: 29764MB
Listing directory: /
FILE: example.txt  SIZE: 123

【使用注意】

  • 当前示例调用 listDir(..., 0)，只列出根目录，不递归显示子目录内容。
  • 建议使用常见的 FAT32 格式 TF 卡进行首次测试。
  • 文件较多时，标签内容可能超出屏幕可视区域；可减少根目录文件数量后再测试。

【常见排查】

现象可能原因建议处理
显示 Card Mount FailedTF 卡未插好、格式不兼容或引脚错误重新插卡，使用 FAT32，并恢复 pin_config.h
显示 No SD_MMC card attached未检测到有效卡断电后重新插卡，再启动测试
容量正常但文件未显示文件位于子目录或根目录为空将测试文件放到 TF 卡根目录
屏幕文本不完整根目录文件过多减少文件数量或为界面增加滚动容器

08_ES8311​

【功能说明】

该示例使用 ESP32 Arduino Core 的 ESP_I2S 和示例自带的 ES8311 驱动，先播放 canon.h 中的内置 PCM 音频，再进入音频回环：从麦克风读取音频并写回扬声器。

主要功能：

  • 以 16kHz、16-bit、双声道模式初始化 I2S。
  • 通过 I2C 初始化 ES8311。
  • 设置播放音量和麦克风增益。
  • 打开功放控制引脚。
  • 播放 canon.h 中的内置音频。
  • 在 loop() 中持续进行音频读取和写回。

【代码入口】

08_ES8311/08_ES8311.ino

相关文件：

08_ES8311/es8311.c
08_ES8311/es8311.h
08_ES8311/es8311_reg.h
08_ES8311/canon.h
函数或代码作用
i2s.setPins(41, 45, 40, 42, 16)设置 MCLK、BCLK、WS、DOUT 和 DIN 引脚
i2s.begin(...)以 16kHz、16-bit、双声道方式启动 I2S
Wire.begin(IIC_SDA, IIC_SCL)初始化 I2C
digitalWrite(46, HIGH)打开功放控制
es8311_codec_init()初始化 ES8311，并设置音量和麦克风增益
i2s.write((uint8_t *)canon_pcm, canon_pcm_len)播放内置 PCM 音频
i2s.readBytes(...)读取麦克风音频
i2s.write(...)将读取到的音频写回输出

【正常运行现象】

该示例不使用显示屏。启动后设备先播放内置音频，串口输出：

[echo] Echo start

随后进入音频回环。对麦克风说话时，声音会通过音频输出链路播放。

如果 I2S 读写失败，串口可能输出：

[echo] i2s read failed
[echo] i2s write failed

【常见排查】

现象可能原因建议处理
屏幕没有显示该示例不初始化显示屏通过声音和串口输出判断运行状态
没有声音功放未开启、扬声器链路或音量异常检查 GPIO46、音频连接和 EXAMPLE_VOICE_VOLUME
麦克风回环声音很小麦克风增益偏低在允许范围内调整 EXAMPLE_MIC_GAIN
ESP_I2S.h 或 I2S API 编译失败Arduino-ESP32 版本过旧使用 v3.2.0 或更高版本
程序较大或编译较慢canon.h 包含内置 PCM 数据属于正常现象；必要时选择更大的应用程序分区

常见问题汇总​

问题建议
大量 LVGL 类型或函数不存在确认使用 LVGL v9.3.0，而不是 v8.x
编译器选中了多个同名库删除或移走 Arduino 库目录中重复的 LVGL、Arduino_GFX、SensorLib、XPowersLib
LVGL 示例编译成功但运行重启启用 OPI PSRAM，并检查串口中的缓冲区分配失败信息
串口监视器没有输出选择正确的原生 USB 端口；启用 USB CDC，或使用示例中的 HWCDC USBSerial
上传失败或找不到端口更换可传输数据的 USB 线；重新进入下载模式；检查设备管理器中的 COM 端口
显示位置、触摸坐标或外设引脚异常不要混用其他尺寸产品的 pin_config.h，必须使用 ESP32-S3-Touch-AMOLED-2.06 示例包版本