跳到主要内容

Arduino 开发

本节介绍 Arduino 示例的环境配置、上传步骤和运行现象。准备开发板、支持数据传输的 USB 数据线,并下载 ESP32-C6-Touch-LCD-2.8 示例程序。

本章节包含以下部分,请按需阅读:

Arduino 入门教程​

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

请注意:该教程使用 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_configCH32V003 IO 扩展、电池 ADC、ST7789 显示和 CST3530 触摸驱动1.0.0使用随附文件
SensorLibPCF85063 等传感器驱动0.3.1使用随附文件
lvgl图形界面框架8.4.0使用随附文件
lv_conf.hLVGL 配置文件随工程提供与 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 连接开发板,在“工具”菜单中按下表配置:

选项设置
BoardESP32C6 Dev Module
Flash Size16 MB
Flash ModeQIO
PSRAM不支持,无需启用
Partition Scheme16M Flash (3MB APP/9.9MB FATFS)
Port开发板实际对应的串口
串口监视器波特率115200

开发板配备 16 MB Flash,无 PSRAM,请保留示例的绘图缓冲区和内存配置。

4. 编译和上传​

  1. 从 examples/arduino/examples 中打开所需示例目录内的同名 .ino 文件。
  2. 点击“验证”进行编译,编译成功后点击“上传”。
  3. 上传完成后打开串口监视器,将波特率设为 115200,按 RESET 查看启动信息。
  4. 按下文说明操作开发板,检查屏幕或串口现象。

若上传时无法连接,断开 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_exioEXIO6/7 电平输出与背光切换board_config串口、电平及背光变化
02_I2C_qmi8658三轴加速度和角速度随示例提供的驱动串口
03_SD_CardSD 卡识别及容量Arduino-ESP32 自带组件串口
04_I2C_pcf85063RTC 设置与读取SensorLib串口
05_shtc3温湿度读取及 CRC 校验Arduino-ESP32 自带 Wire串口
06_lvgl_demo显示、触摸坐标及背光调节board_config、lvglLCD
07_battery_voltage电池电压与 ADC 原始值board_config、lvglLCD、串口

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 用于屏幕、触摸、功放等板载器件,请勿随意翻转。

01_exio 扩展 IO 电平和背光状态串口日志

02_I2C_qmi8658​

程序说明​

通过 I2C 读取板载 QMI8658 六轴传感器的三轴加速度和角速度,并通过串口输出。

硬件连接​

使用 USB 数据线连接开发板与电脑,无需外接传感器。

代码分析​

  • setup():初始化串口,调用 I2C_master_Init() 配置 I2C 总线。
  • qmi8658c_example:由 xTaskCreate() 创建的任务负责传感器初始化、读取和串口输出,loop() 不执行额外操作。

运行效果​

上传后打开串口监视器,观察三轴加速度(m/s²)和角速度(rad/s),约每秒输出一次。轻轻倾斜或转动开发板,数据随之变化。静止时仍会测到重力,各轴不一定为零;本示例不点亮屏幕。

02_I2C_qmi8658 加速度和角速度串口日志

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 示例。

03_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 持续走时时,可移除该设置时间的调用。

04_I2C_pcf85063 实时时钟串口日志

05_shtc3​

程序说明​

通过 I2C 读取板载 SHTC3 温湿度传感器,校验数据后输出环境温度和相对湿度。

硬件连接​

使用 USB 数据线连接开发板与电脑,无需外接传感器。

代码分析​

  • setup():使用 GPIO6(SDA)、GPIO7(SCL)初始化 I2C,复位传感器并读取设备 ID。
  • readShtc3():唤醒传感器,发送测量命令,读取温湿度数据并执行循环冗余校验(CRC,Cyclic Redundancy Check),再转换为摄氏温度和相对湿度。
  • loop():调用读取函数,输出测量结果或错误提示,间隔约 1 秒。

运行效果​

上传后,串口约每秒显示一次温度和相对湿度,屏幕不点亮。传感器读取包含 CRC 校验;若提示找不到传感器或读取失败,重新上电并查看串口错误。

05_shtc3 温湿度串口日志

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 或其他触摸库。

06_lvgl_demo 显示、触摸和背光调节界面

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 分压,需要核对精度时,可用万用表比较。

07_battery_voltage 电池电压屏幕显示

07_battery_voltage 电池电压和 ADC 串口日志

常见问题​

  • **找不到库文件:**检查项目文件夹是否指向 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。