跳到主要内容

Arduino 开发

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

阅读前准备

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

  • 已准备 ESP32-S3-Touch-AMOLED-2.16 开发板。
  • 已使用 USB 数据线连接开发板和电脑。
  • 已安装 Arduino IDE。
  • 已安装 ESP32 Arduino Core，页面对应示例目录为 Arduino-v3.3.5，建议使用与示例包匹配的 Arduino-ESP32 版本。
  • 已下载产品示例程序包。
  • 已按示例包要求安装 libraries 目录中的库文件。

Arduino 入门教程​

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

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

配置开发环境​

1. 安装和配置 Arduino IDE​

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

2. 安装库​

库或文件作用推荐版本或说明安装方式
GFX Library for Arduino显示驱动和基础图形绘制v1.6.4库管理器或手动安装
SensorLibPCF85063、QMI8658 等传感器驱动v0.3.3库管理器或手动安装
XPowersLibAXP2101 电源管理芯片驱动v0.2.6库管理器或手动安装
lvglLVGL 图形界面框架v8.4.0库管理器或手动安装
Mylibrary开发板引脚宏定义示例包提供手动安装
lv_conf.hLVGL 配置文件示例包提供手动安装
版本兼容性提醒

LVGL v8 和 LVGL v9 的 API 差异较大。当前 Arduino 示例使用的是 LVGL v8 风格接口，例如：

lv_disp_drv_t
lv_disp_draw_buf_t
lv_disp_drv_register()

如果误装 LVGL v9，可能出现大量编译错误。建议严格使用示例包内提供的库版本。

推荐安装方式：

  1. 下载产品示例程序包。

  2. 找到：

    examples/Arduino-v3.3.5/libraries

  3. 将该目录下的库文件夹复制到 Arduino 的库目录。

    Windows 默认库目录通常是：

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

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

  4. 库安装检查方法

    安装完成后建议检查：

    • Documents\Arduino\libraries 下能看到 GFX_Library_for_Arduino、SensorLib、XPowersLib、lvgl 等目录。
    • lv_conf.h 已放到 Arduino 编译能找到的位置。
    • Arduino IDE 重启后再编译示例。
    • 不要同时保留多个不同版本的 lvgl、XPowersLib 或 GFX_Library_for_Arduino，避免头文件冲突。

示例程序​

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

示例程序基础例程说明依赖库
01_HelloWorld展示了基本的图形库功能，也可以用于测试显示屏的基础性能以及随机文本显示效果GFX_Library_for_Arduino
02_GFX_AsciiTable根据屏幕尺寸，在显示屏上按行列打印 ASCII 字符GFX_Library_for_Arduino
03_LVGL_AXP2101_ADC_Data通过移植后的 XPowersLib 驱动 AXP2101 获取电源相关数据GFX_Library_for_Arduino
04_LVGL_QMI8658_uiLVGL 绘制加速度折线图LVGL，SensorLib
05_LVGL_WidgetsLVGL 演示LVGL，Arduino_DriveBus ,Adafruit_XCA9554
06_ES7210ES7210 驱动示例，拾取人声检测——
07_ES8311ES8311 驱动示例，播放简单的音频——

1. 目录结构​

当前 Arduino 示例目录包含以下工程：

examples/Arduino-v3.3.5/examples
├── 01_HelloWorld
├── 02_GFX_AsciiTable
├── 03_LVGL_AXP2101_ADC_Data
├── 04_LVGL_QMI8658_ui
├── 05_LVGL_Widgets
├── 06_ES7210
└── 07_ES8311

每个子目录都是一个独立 Arduino 示例。打开示例时，应打开对应目录下的 .ino 文件，例如：

examples/Arduino-v3.3.5/examples/01_HelloWorld/01_HelloWorld.ino

部分音频示例还包含额外驱动或音频数据文件：

06_ES7210
├── 06_ES7210.ino
├── audio_hal.h
├── es7210.cpp
└── es7210.h

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

【第一次运行推荐顺序】

建议客户按以下顺序运行：

01_HelloWorld
  ↓
02_GFX_AsciiTable
  ↓
03_LVGL_AXP2101_ADC_Data
  ↓
04_LVGL_QMI8658_ui
  ↓
05_LVGL_Widgets
  ↓
06_ES7210
  ↓
07_ES8311
  • 先用 01_HelloWorld 验证屏幕最基础的显示能力。
  • 再用 02_GFX_AsciiTable 验证字符绘制、坐标和显示方向。
  • 然后用 03_LVGL_AXP2101_ADC_Data 验证 PMU、电源数据和 LVGL 基础显示。
  • 再用 04_LVGL_QMI8658_ui 验证 IMU 数据读取和 LVGL 图表刷新。
  • 接着用 05_LVGL_Widgets 验证触摸、LVGL Demo、屏幕旋转和较大内存场景。
  • 最后运行 06_ES7210 和 07_ES8311 验证音频输入与音频播放。

2. 示例说明​

01_HelloWorld​

【功能说明】

该示例使用 Arduino GFX 库初始化 AMOLED 显示屏，并在屏幕上随机显示 Hello World! 文本。

主要作用：

  • 初始化 QSPI 显示总线。
  • 初始化 Arduino_CO5300 显示对象。
  • 设置屏幕方向寄存器。
  • 清屏。
  • 设置亮度。
  • 随机绘制文字。

【代码入口】

01_HelloWorld/01_HelloWorld.ino

建议优先查看：

代码作用
Arduino_ESP32QSPI创建 QSPI 显示总线
Arduino_CO5300创建显示屏驱动对象
gfx->begin()初始化显示屏
bus->writeC8D8(0x36, 0xA0)设置显示方向或扫描参数
gfx->setBrightness(128)设置屏幕亮度
gfx->println("Hello World!")绘制文字

【正常运行现象】

屏幕先显示一行红色 Hello World!。随后屏幕会不断在随机位置显示不同颜色、不同大小的 Hello World!，串口会周期性输出：

loop

【常见排查】

现象可能原因建议处理
编译找不到 Arduino_GFX_Library.hGFX 库未安装或路径错误检查 GFX_Library_for_Arduino 是否在 Arduino libraries 目录
屏幕不亮板卡配置、屏幕驱动或供电异常检查 Board、PSRAM、库版本，必要时先重新安装示例包库
串口无输出串口选错或波特率不对选择正确 Port，串口监视器设为 115200
显示方向异常显示方向寄存器或屏幕参数被修改恢复原始示例代码测试

02_GFX_AsciiTable​

【功能说明】

该示例使用 Arduino GFX 库在屏幕上绘制 ASCII 字符表。它比 01_HelloWorld 更适合检查屏幕坐标、字符绘制、行列排布和显示方向。

主要作用：

  • 根据屏幕宽高计算行列数量。
  • 绘制行列编号。
  • 逐个绘制 ASCII 字符。

【代码入口】

02_GFX_AsciiTable/02_GFX_AsciiTable.ino

建议优先查看：

代码作用
numCols = LCD_WIDTH / 8按字符宽度计算列数
numRows = LCD_HEIGHT / 10按字符高度计算行数
gfx->drawChar(...)绘制单个字符
gfx->setTextColor(...)设置字符颜色

【正常运行现象】

屏幕显示一张 ASCII 字符表，顶部和左侧有行列编号。该示例不会在 loop() 中继续刷新，显示完成后画面保持不变。

【常见排查】

现象可能原因建议处理
字符表超出屏幕屏幕宽高宏定义错误检查 pin_config.h 中 LCD_WIDTH、LCD_HEIGHT
字符方向不对显示方向配置不匹配检查 bus->writeC8D8(0x36, 0xA0) 是否被修改
编译失败GFX 库版本不匹配使用示例包内库或官方页面推荐版本

03_LVGL_AXP2101_ADC_Data​

【功能说明】

该示例使用 XPowersLib 驱动 AXP2101 PMU，并用 LVGL 在屏幕上显示电源相关数据。

主要显示内容包括：

  • PMU 温度。
  • 是否正在充电。
  • 是否正在放电。
  • 是否处于待机。
  • VBUS 是否接入。
  • VBUS 是否正常。
  • 充电状态。
  • 电池电压。
  • VBUS 电压。
  • 系统电压。
  • 电池电量百分比。

【代码入口】

03_LVGL_AXP2101_ADC_Data/03_LVGL_AXP2101_ADC_Data.ino

建议优先查看：

函数或代码作用
power.begin(...)初始化 AXP2101
adcOn()打开温度、电池、VBUS、系统电压检测
adcOff()关闭 ADC 检测
my_disp_flush()LVGL 刷屏回调
lv_disp_drv_register()注册 LVGL 显示驱动
lv_label_set_text(info_label, info.c_str())刷新屏幕上的电源信息

【正常运行现象】

屏幕显示电源状态信息，包含温度、电池电压、VBUS 电压、系统电压和充电状态。串口会输出 LVGL 版本信息和初始化完成信息。

如果 PMU 初始化失败，串口会输出：

PMU is not online...

【常见排查】

现象可能原因建议处理
显示 PMU is not online...AXP2101 I2C 通信失败检查 I2C 引脚、pin_config.h、库版本
编译找不到 XPowersLib.hXPowersLib 未安装安装示例包内 XPowersLib
编译 LVGL 报错LVGL 版本不匹配使用 LVGL v8.4.0，不要使用 LVGL v9
屏幕显示乱码或异常LVGL 配置或颜色格式不匹配检查 lv_conf.h 和 LV_COLOR_16_SWAP

04_LVGL_QMI8658_ui​

【功能说明】

该示例使用 SensorLib 读取 QMI8658 IMU 的加速度和陀螺仪数据，并用 LVGL 图表实时显示加速度 X/Y/Z 三轴曲线。

主要作用：

  • 初始化显示和 LVGL。
  • 初始化 QMI8658。
  • 配置加速度计量程和输出速率。
  • 在串口输出加速度和陀螺仪数据。
  • 在屏幕上用 LVGL Chart 显示加速度曲线。

【代码入口】

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}

如果 QMI8658 初始化失败，串口会输出：

Failed to find QMI8658 - check your wiring!

【常见排查】

现象可能原因建议处理
QMI8658 初始化失败I2C 地址或引脚配置异常检查 QMI8658_L_SLAVE_ADDRESS 和 IIC_SDA/IIC_SCL
图表不刷新LVGL 定时器或 lv_timer_handler() 未运行确认 loop() 中保留 lv_timer_handler()
串口有数据但屏幕无图LVGL 显示驱动异常先运行 03_LVGL_AXP2101_ADC_Data 验证 LVGL
曲线没有变化开发板静止或传感器未启用移动开发板，检查 qmi.enableAccelerometer()

05_LVGL_Widgets​

【功能说明】

该示例是较完整的 LVGL 演示示例，同时包含触摸控制器、IMU 姿态检测、屏幕旋转和 LVGL Demo。当前代码默认运行：

lv_demo_music();

代码中还预留了其他 Demo：

// lv_demo_widgets();
// lv_demo_benchmark();
// lv_demo_keypad_encoder();
// lv_demo_stress();

【代码入口】

05_LVGL_Widgets/05_LVGL_Widgets.ino

建议优先查看：

代码作用
HWCDC USBSerial使用 USB CDC 串口输出
touch.begin(...)初始化触摸控制器
attachInterrupt(TP_INT, ...)注册触摸中断
my_touchpad_read(...)LVGL 触摸读取回调
heap_caps_malloc(..., MALLOC_CAP_DMA)为 LVGL 分配 DMA 刷屏缓冲
lv_disp_set_rotation(...)根据 IMU 姿态旋转屏幕
lv_demo_music()启动 LVGL 音乐 Demo

【正常运行现象】 正常运行现象

屏幕显示 LVGL Music Demo。触摸屏幕时，串口会输出触摸坐标，例如：

Data x ...
Data y ...

倾斜开发板时，屏幕方向会根据 IMU 数据自动切换。串口初始化成功后会输出 LVGL 和 Arduino 相关信息。

【使用注意】

  • 该示例比前几个示例更依赖内存，建议开启 PSRAM。
  • 该示例使用 USBSerial，建议开启 USB CDC On Boot。
  • 如果串口监视器看不到输出，请确认选择的是 USB CDC 对应串口。
  • 如果编译提示内存不足或程序过大，请更换更大的 Partition Scheme。

【常见排查】

现象可能原因建议处理
编译失败，提示 LVGL API 不存在安装了 LVGL v9使用 LVGL v8.4.0
屏幕黑屏或重启PSRAM 未启用或内存不足开启 PSRAM，选择大 APP 分区
触摸无反应触摸初始化失败或中断未触发查看是否输出 touch is not online...，检查 TP_RST/TP_INT
串口无输出USB CDC 未开启或选错串口开启 USB CDC On Boot，重新选择 Port
屏幕旋转异常IMU 数据或旋转阈值不合适先运行 04_LVGL_QMI8658_ui 验证 IMU

06_ES7210​

【功能说明】

该示例使用 I2S 驱动 ES7210 音频 ADC，采集麦克风音频，并使用 VAD 进行人声检测。该示例不会在屏幕上显示内容，主要通过串口判断运行结果。

主要作用：

  • 初始化 ES7210。
  • 配置 I2S 输入。
  • 设置麦克风增益。
  • 创建 VAD 实例。
  • 读取音频数据并检测人声。

【代码入口】

06_ES7210/06_ES7210.ino

相关驱动文件：

06_ES7210/es7210.cpp
06_ES7210/es7210.h
06_ES7210/audio_hal.h

建议优先查看：

代码作用
es7210_adc_init(...)初始化 ES7210
es7210_adc_config_i2s(...)配置 ES7210 I2S
es7210_adc_set_gain(...)设置麦克风增益
i2s_driver_install(...)安装 I2S 驱动
i2s_read(...)读取音频采样
vad_process(...)人声检测

【正常运行现象】

屏幕无显示变化。串口会输出 PSRAM 和 Flash 大小。对麦克风讲话或发出人声时，串口应输出：

Speech detected

【常见排查】

现象可能原因建议处理
屏幕无现象该示例本来不使用屏幕通过串口判断是否正常
没有 Speech detected输入音量太低或麦克风增益不合适靠近麦克风讲话，检查增益配置
编译找不到 esp_vad.hArduino-ESP32 版本或组件不匹配使用示例包匹配的 Arduino-v3.3.5 环境
I2S 读取异常I2S 引脚配置或 ES7210 初始化异常检查 pin_config.h 中 ES7210 引脚

07_ES8311​

【功能说明】

该示例使用 ES8311 音频 Codec 播放内置音频数据，并在后续循环中读取输入音频再写回输出，实现简单音频回环。

主要作用：

  • 初始化 I2S。
  • 初始化 ES8311。
  • 打开功放控制引脚。
  • 播放 canon.h 中的内置 PCM 音频。
  • 在 loop() 中进行音频读取和写回。

【代码入口】

07_ES8311/07_ES8311.ino

相关文件：

07_ES8311/es8311.c
07_ES8311/es8311.h
07_ES8311/es8311_reg.h
07_ES8311/canon.h

建议优先查看：

代码作用
i2s.setPins(...)配置 I2S 引脚
i2s.begin(...)启动 I2S
Wire.begin(IIC_SDA, IIC_SCL)初始化 I2C
digitalWrite(PA, HIGH)打开功放控制
es8311_codec_init()初始化 ES8311
i2s.write((uint8_t *)canon_pcm, canon_pcm_len)播放内置音频
i2s.readBytes(...)读取音频输入

【正常运行现象】

屏幕无显示变化。开发板应播放内置音频。串口输出：

[echo] Echo start

随后进入音频回环逻辑。如果读取或写入失败，串口会输出：

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

【常见排查】

现象可能原因建议处理
没有声音功放未打开、音量过低、扬声器连接异常检查 PA 引脚、音量、外接音频设备
编译很慢或文件很大canon.h 内置 PCM 数据较大属于正常现象
程序过大无法上传分区太小选择更大的 Partition Scheme
I2S 初始化失败引脚或 Arduino Core 不匹配检查 I2S_BCK_IO、I2S_WS_IO、I2S_DO_IO 等定义