Arduino 开发
本节介绍 Arduino 示例的环境配置、上传步骤和运行现象。准备开发板、支持数据传输的 USB 数据线,并下载 ESP32-C6-Touch-LCD-2.8 示例程序。
本章节包含以下部分,请按需阅读:
Arduino 入门教程
初次接触 Arduino ESP32 开发,想要快速上手?我们为您准备了一套通用的 入门教程。
- 第0节 认识 ESP32
- 第1节 安装和配置 Arduino IDE
- 第2节 Arduino 基础知识
- 第3节 数字输出/输入
- 第4节 模拟输入
- 第5节 脉冲宽度调制 (PWM)
- 第6节 串行通信 (UART)
- 第7节 I2C 通信
- 第8节 SPI 通信
- 第9节 Wi-Fi 基础用法
- 第10节 网页服务器
- 第11节 蓝牙 (Bluetooth)
- 第12节 LVGL 图形界面开发
- 第13节 综合项目
请注意:该教程使用 ESP32-S3-Zero 作为教学示例,所有硬件代码均基于其引脚布局。在动手实践前,建议您对照手中的开发板引脚图,确认引脚配置无误。
配置开发环境
1. 安装 Arduino IDE 和开发板支持包
参考 Arduino IDE 安装教程 安装 IDE。在“文件” > “首选项”的“附加开发板管理器网址”中添加:
https://espressif.github.io/arduino-esp32/package_esp32_index.json
打开开发板管理器,安装 esp32 by Espressif Systems 3.3.12。
本文对应 Arduino-ESP32 3.3.12,示例位于 examples/arduino/examples。显示示例使用附带的 LVGL 8.4.0,不要替换为 LVGL 9。
2. 配置示例库
示例所需的库和配置文件已随源码提供,位于 examples/arduino/libraries:
| 库或文件名称 | 说明 | 版本 | 安装方式 |
|---|---|---|---|
board_config | CH32V003 IO 扩展、电池 ADC、ST7789 显示和 CST3530 触摸驱动 | 1.0.0 | 使用随附文件 |
SensorLib | PCF85063 等传感器驱动 | 0.3.1 | 使用随附文件 |
lvgl | 图形界面框架 | 8.4.0 | 使用随附文件 |
lv_conf.h | LVGL 配置文件 | 随工程提供 | 与 lvgl 文件夹并列放置 |
将“文件” > “首选项”中的“项目文件夹位置”设置为下载仓库中的 examples/arduino,然后重启 Arduino IDE。IDE 会从该目录下的 libraries 加载附带的库:
examples/arduino/
├── examples/
│ ├── 01_exio/
│ ├── 02_I2C_qmi8658/
│ ├── 03_SD_Card/
│ ├── 04_I2C_pcf85063/
│ ├── 05_shtc3/
│ ├── 06_lvgl_demo/
│ └── 07_battery_voltage/
└── libraries/
├── board_config/
├── lvgl/
├── SensorLib/
└── lv_conf.h
- 保留
libraries/lv_conf.h,与lvgl文件夹并列放置。 - 若使用自己的项目文件夹,可将附带的
libraries内容完整复制到该项目文件夹的libraries目录中。
本教程使用随源码提供的库和配置文件。不要同时安装多个不同版本的 LVGL,以免编译时选错库。LVGL 8 与 LVGL 9 的接口不同,替换库版本或混用其他产品的显示、触摸驱动,可能导致编译失败或运行异常。
3. 选择工程参数
通过 USB 连接开发板,在“工具”菜单中按下表配置:
| 选项 | 设置 |
|---|---|
| Board | ESP32C6 Dev Module |
| Flash Size | 16 MB |
| Flash Mode | QIO |
| PSRAM | 不支持,无需启用 |
| Partition Scheme | 16M Flash (3MB APP/9.9MB FATFS) |
| Port | 开发板实际对应的串口 |
| 串口监视器波特率 | 115200 |
开发板配备 16 MB Flash,无 PSRAM,请保留示例的绘图缓冲区和内存配置。
4. 编译和上传
- 从
examples/arduino/examples中打开所需示例目录内的同名.ino文件。 - 点击“验证”进行编译,编译成功后点击“上传”。
- 上传完成后打开串口监视器,将波特率设为 115200,按 RESET 查看启动信息。
- 按下文说明操作开发板,检查屏幕或串口现象。
若上传时无法连接,断开 USB,按住 BOOT 后重新连接 USB,识别到端口后松开 BOOT,再上传。
使用 Arduino CLI 时,在仓库根目录可执行以下命令。将 COM5 替换为实际串口:
arduino-cli core install esp32:esp32@3.3.12
arduino-cli compile --fqbn esp32:esp32:esp32c6:FlashSize=16M,FlashMode=qio,PartitionScheme=app3M_fat9M_16MB --libraries examples/arduino/libraries examples/arduino/examples/06_lvgl_demo
arduino-cli upload -p COM5 --fqbn esp32:esp32:esp32c6:FlashSize=16M,FlashMode=qio,PartitionScheme=app3M_fat9M_16MB examples/arduino/examples/06_lvgl_demo
烧录基础示例后,开发板会运行该示例。需要运行 APP 桌面时,编译并烧录独立的出厂工程 examples/factory。
示例程序
示例位于源码包的 examples/arduino/examples 目录。每个示例文件夹内的同名 .ino 为入口文件,请保留同目录下的配套源码和头文件。
| 示例程序 | 基础例程说明 | 依赖库 | 查看结果 |
|---|---|---|---|
| 01_exio | EXIO6/7 电平输出与背光切换 | board_config | 串口、电平及背光变化 |
| 02_I2C_qmi8658 | 三轴加速度和角速度 | 随示例提供的驱动 | 串口 |
| 03_SD_Card | SD 卡识别及容量 | Arduino-ESP32 自带组件 | 串口 |
| 04_I2C_pcf85063 | RTC 设置与读取 | SensorLib | 串口 |
| 05_shtc3 | 温湿度读取及 CRC 校验 | Arduino-ESP32 自带 Wire | 串口 |
| 06_lvgl_demo | 显示、触摸坐标及背光调节 | board_config、lvgl | LCD |
| 07_battery_voltage | 电池电压与 ADC 原始值 | board_config、lvgl | LCD、串口 |
01_exio
程序说明
通过板载 CH32V003 控制 EXIO6/7 输出和屏幕背光,演示扩展 IO 与背光控制接口。
硬件连接
使用 USB 数据线连接开发板与电脑;可用万用表测量 EXIO6/7 排针相对 GND 的电平。
代码分析
setup():初始化 115200 波特率串口,调用Board_IO_Init()初始化 CH32V003。loop():通过Board_IO_SetOutput()设置 EXIO6/7 电平,通过Board_SetBacklight()切换背光亮度,每秒执行一次并输出结果。
运行效果
上传后,EXIO6/7 输出每秒在高、低电平之间切换,背光在关闭和全亮之间切换,串口输出对应状态。本示例不显示 LCD 界面。
CH32V003 已预装控制固件,无需单独烧录。本示例只使用 EXIO6/7 作为测试输出,其他扩展 IO 用于屏幕、触摸、功放等板载器件,请勿随意翻转。

02_I2C_qmi8658
程序说明
通过 I2C 读取板载 QMI8658 六轴传感器的三轴加速度和角速度,并通过串口输出。
硬件连接
使用 USB 数据线连接开发板与电脑,无需外接传感器。
代码分析
setup():初始化串口,调用I2C_master_Init()配置 I2C 总线。qmi8658c_example:由xTaskCreate()创建的任务负责传感器初始化、读取和串口输出,loop()不执行额外操作。
运行效果
上传后打开串口监视器,观察三轴加速度(m/s²)和角速度(rad/s),约每秒输出一次。轻轻倾斜或转动开发板,数据随之变化。静止时仍会测到重力,各轴不一定为零;本示例不点亮屏幕。

03_SD_Card
程序说明
挂载 SD 卡,并通过串口输出卡信息和容量。
硬件连接
本 Arduino 示例在 SD 卡挂载失败时可能触发格式化。请先备份卡内文件,并使用 FAT32 格式的测试卡。
上电前插入 SD 卡,再使用 USB 数据线连接开发板与电脑。
代码分析
setup():初始化串口,延时后调用SD_card_Init()。SD_card_Init():配置并挂载 SD 卡,打印卡信息和practical_size容量值。- 挂载配置中的
format_if_mount_failed为true,挂载失败时可能格式化测试卡;loop()不执行循环读写。
运行效果
串口会显示 SD 卡信息和 practical_size 容量,本示例不点亮屏幕。当前入口只执行挂载和容量查询,不会自动创建测试文件或执行文件读写校验。
如需写入文件、读回校验并在屏幕显示结果,可运行 ESP-IDF 的 02_sd_card 示例。
04_I2C_pcf85063
程序说明
设置板载 PCF85063 实时时钟(RTC,Real-Time Clock)的日期和时间,并定时读取。
硬件连接
使用 USB 数据线连接开发板与电脑,无需外接时钟模块。
代码分析
rtc_init():初始化时钟模块。i2c_rtc_setTime(2025, 9, 9, 14, 51, 30):在每次启动时写入演示时间。i2c_rtc_loop_task:读取 RTC 日期和时间,并每秒通过串口输出。
运行效果
上传后,串口时间从 2025 年 9 月 9 日 14:51:30 开始,每秒递增;屏幕不点亮。每次复位都会重新写入该演示时间,不进行联网校时。
如需修改起始日期和时间,调整草图中的 i2c_rtc_setTime() 后重新上传。测试 RTC 持续走时时,可移除该设置时间的调用。

05_shtc3
程序说明
通过 I2C 读取板载 SHTC3 温湿度传感器,校验数据后输出环境温度和相对湿度。
硬件连接
使用 USB 数据线连接开发板与电脑,无需外接传感器。
代码分析
setup():使用 GPIO6(SDA)、GPIO7(SCL)初始化 I2C,复位传感器并读取设备 ID。readShtc3():唤醒传感器,发送测量命令,读取温湿度数据并执行循环冗余校验(CRC,Cyclic Redundancy Check),再转换为摄氏温度和相对湿度。loop():调用读取函数,输出测量结果或错误提示,间隔约 1 秒。
运行效果
上传后,串口约每秒显示一次温度和相对湿度,屏幕不点亮。传感器读取包含 CRC 校验;若提示找不到传感器或读取失败,重新上电并查看串口错误。

06_lvgl_demo
程序说明
使用 LVGL 8 创建显示与触摸测试界面,结合 ST7789 显示驱动、CST3530 触摸驱动和背光调节验证屏幕功能。
硬件连接
使用 USB 数据线连接开发板与电脑,无需 SD 卡或喇叭。
代码分析
setup():初始化 CH32V003、LCD 和触摸控制器,分配绘图缓冲区,注册 LVGL 显示和输入设备。display_flush():将 LVGL 绘图数据发送至 LCD,完成后通知 LVGL。touch_read():读取触摸坐标,更新输入状态及界面坐标标签。brightness_slider_event_cb():响应滑块变化,调用Set_Backlight()设置背光。loop():更新 LVGL 时基并执行lv_timer_handler(),处理界面刷新和交互。
运行效果
上传后,LCD 显示 Display OK 和触摸状态。触摸屏幕,坐标会随触摸位置更新;拖动底部滑块,可在 5%~100% 之间调节背光。
使用附带的 LVGL 8.4.0 和 libraries/lv_conf.h,保留 LV_COLOR_DEPTH 16、LV_COLOR_16_SWAP 0 配置。显示驱动为 ST7789,触摸驱动为 CST3530,示例已适配,无需额外安装 GFX 或其他触摸库。

07_battery_voltage
程序说明
通过 CH32V003 读取电池 ADC 采样值,换算电压,并在 LCD 和串口中显示。
硬件连接
接入与开发板匹配的电池,连接前核对正负极,再使用 USB 数据线连接电脑。
代码分析
setup():等待 CH32V003 初始化成功,再初始化 LCD 和 LVGL,创建电压显示标签并开启背光。Board_ReadBatteryVoltage():读取八次 ADC 数据并取平均,按标称 3.3 V 参考电压及 3:1 分压换算电池电压。loop():每秒读取一次数据,更新标签和串口输出;读取失败时显示ADC read failed。
运行效果
上传后,LCD 和串口约每秒更新电池电压及 0~1023 的 ADC 原始值。显示的是估算电压,不是剩余电量百分比。
未接电池或接触不良时,读数可能为零或异常。计算使用标称 3.3 V ADC 参考电压及 3:1 分压,需要核对精度时,可用万用表比较。

常见问题
- **找不到库文件:**检查项目文件夹是否指向
examples/arduino,确认附带的libraries和lv_conf.h完整,再重启 IDE。lvgl.h对应lvgl,SensorPCF85063.hpp对应SensorLib。 - **出现 LVGL 接口错误:**确认安装的是附带的 LVGL 8.4.0,避免误用 LVGL 9 或其他同名库。
- **屏幕黑屏:**先对照示例列表,串口传感器和 SD 卡识别示例不点亮屏幕。显示示例异常时,查看串口中 LCD、触摸及 CH32V003 的初始化结果。
- **上传失败或无串口输出:**检查数据线和串口选择,关闭其他占用串口的软件,按 RESET 重试;串口监视器使用 115200 波特率。
更多问题参见 ESP32-C6-Touch-LCD-2.8 产品 FAQ。