Arduino 开发

本章节包含以下内容，请按需阅读：

Arduino 入门教程
配置开发环境
示例程序
产品 FAQ

阅读前准备

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

已准备 ESP32-C5-Touch-LCD-2.8 或 ESP32-C5-Touch-LCD-2.8-EN 开发板。
已使用 USB 数据线连接开发板和电脑。
已安装 Arduino IDE。
已安装 ESP32 Arduino Core，页面对应示例目录为 Arduino-v3.3.10，请使用与示例包匹配的 Arduino-ESP32 版本。
已下载产品示例程序包。
如需运行 04_I2C_pcf85063，请安装示例包内置的 lib/SensorLib；如需运行 06_lvgl_demo，请安装示例包内置的 lib/lvgl。

Arduino 入门教程

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

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

配置开发环境

1. 安装和配置 Arduino IDE

请参考 安装和配置 Arduino IDE 教程 下载并安装 Arduino IDE。

2. 安装 ESP32 开发板支持包

请在 Arduino IDE 的开发板管理器中安装 esp32 by Espressif Systems 开发板支持包。

版本说明

ESP32-C5-Touch-LCD-2.8 板载 MCU 模组为 ESP32-C5-WROOM-1-N32R8，芯片版本属于 v1.2，请使用 esp32 by Espressif Systems 的 v3.3.10 版本。

如果使用较旧版本的 ESP32 Arduino core，可能无法正确识别该开发板，导致串口下载失败或无法烧录程序。

ESP32-C5-Touch-LCD-2.8 所需开发板安装说明：

板名称	板安装要求	版本号要求
ESP32 by Espressif Systems	"离线"安装 / "在线"安装	`v3.3.10`

安装完成后，在 Arduino IDE 中选择 ESP32-C5 对应开发板，并选择当前连接的 USB 串口。

Arduino 工程参数

ESP32-C5-Touch-LCD-2.8 Arduino 工程参数设置中，开发板需要选择 ESP32C5 Dev Module。

3. 安装库和示例依赖

本产品 Arduino 示例尽量减少外部库依赖，主要使用 Arduino ESP32 core 自带能力和示例目录内提供的源码。示例包已经在 example/Arduino-v3.3.10/lib 目录中预置了所需库，可手动复制安装，适合无法联网或不方便使用 Arduino Library Manager 的环境。

库或文件	作用	推荐版本或来源	使用示例	安装方式
Arduino ESP32 core	ESP32-C5 开发板支持、下载和基础外设接口	`v3.3.10`	全部示例	Arduino IDE 开发板管理器
`lvgl`	LVGL 图形界面框架	示例包 `lib/lvgl`，LVGL v8.4.0	`06_lvgl_demo`	离线手动复制到 Arduino 库目录
`SensorLib` / `SensorPCF85063.hpp`	PCF85063 RTC 驱动	示例包 `lib/SensorLib`，SensorLib v0.3.1	`04_I2C_pcf85063`	离线手动复制到 Arduino 库目录

LVGL 版本

06_lvgl_demo 基于 LVGL v8.4.0。请勿替换为 LVGL v9，否则 lv_disp_drv_t、lv_disp_draw_buf_t、lv_disp_drv_register()、lv_indev_drv_t 等接口会不兼容。

离线/手动安装方式：

下载并解压产品示例程序包。后续库安装可以离线完成，不需要从 Arduino Library Manager 联网下载第三方库。

找到示例包中的库目录：

example/Arduino-v3.3.10/lib/lvgl
example/Arduino-v3.3.10/lib/SensorLib

将 lvgl 和 SensorLib 两个文件夹完整复制到 Arduino 的库目录。

Windows 默认库目录通常是：
```
C:\Users\<用户名>\Documents\Arduino\libraries
```
也可以在 Arduino IDE 中通过 File > Preferences 查看 Sketchbook location，其下的 libraries 文件夹就是库目录。
安装完成后重启 Arduino IDE，再打开示例进行编译。

安装检查方法：

Documents\Arduino\libraries 下可以看到 lvgl 和 SensorLib 目录。
Documents\Arduino\libraries\SensorLib\library.properties 中可以看到 version=0.3.1。
Documents\Arduino\libraries\lvgl\library.properties 中可以看到 version=8.4.0。
06_lvgl_demo 目录中的 lv_conf.h 需要保留在当前示例目录内，不要移动到 Arduino 全局库目录，也不要删除。
不要同时保留多个不同版本的 lvgl 或 SensorLib，避免头文件冲突。
如果编译 04_I2C_pcf85063 提示找不到 SensorPCF85063.hpp，请确认示例包中的 lib/SensorLib 已经复制到 Arduino 库目录。

4. Arduino 工程参数设置

打开 Arduino IDE。
安装 esp32 by Espressif Systems v3.3.10。
在 Tools > Board 中选择 ESP32C5 Dev Module。
选择当前连接的 USB 串口。
打开 example/Arduino-v3.3.10 下的对应示例 .ino 文件进行编译和烧录。

使用 arduino-cli 时，可参考以下命令：

arduino-cli core install esp32:esp32@3.3.10
arduino-cli compile --fqbn esp32:esp32:esp32c5 example/Arduino-v3.3.10/06_lvgl_demo

示例程序

Arduino 示例程序位于示例程序包的 example/Arduino-v3.3.10 目录。各示例已经按照 ESP32-C5-Touch-LCD-2.8 的实际硬件连接进行适配。

1. 板载资源

功能	器件或接口	引脚或说明
LCD	ST7789，SPI，240 x 320，RGB565	SCLK GPIO6，MOSI GPIO7，DC GPIO9，CS GPIO10
LCD 复位	CH32V003 IO 扩展	EXIO1
LCD 背光	CH32V003 PWM	CH32 PWM
触摸	CST3530，I2C	SDA GPIO0，SCL GPIO1，INT GPIO5
触摸复位	CH32V003 IO 扩展	EXIO0
IO 扩展	CH32V003，I2C 地址 `0x24`	SDA GPIO0，SCL GPIO1
六轴传感器	QMI8658，I2C 地址 `0x6B`	SDA GPIO0，SCL GPIO1
RTC	PCF85063，I2C 地址 `0x51`	SDA GPIO0，SCL GPIO1
温湿度传感器	SHTC3，I2C 地址 `0x70`	SDA GPIO0，SCL GPIO1
Micro SD	SDSPI	SCLK GPIO6，MOSI GPIO7，MISO GPIO8，CS GPIO23

二次开发建议

显示、触摸、背光、复位和传感器引脚已经在示例中按产品硬件连接适配。常规二次开发建议优先修改应用层和 UI 逻辑，不建议随意修改底层引脚定义；只有在更换硬件连接或移植到其他板卡时才需要改动底层驱动。

2. 示例列表

示例目录	基础例程说明	主要验证内容
01_exio	测试板载 CH32V003 IO 扩展芯片，循环翻转 EXIO0~EXIO7 输出电平	IO 扩展、I2C 总线
02_I2C_qmi8658	读取 QMI8658 六轴传感器数据，并通过串口输出加速度和陀螺仪数据	IMU、I2C 总线
03_SD_Card	通过 SDSPI 挂载 Micro SD 卡，打印 SD 卡信息和容量，并提供文件读写接口	Micro SD、SDSPI
04_I2C_pcf85063	初始化 PCF85063 RTC，设置测试时间，并通过串口周期打印 RTC 时间	RTC、I2C 总线
05_shtc3	读取 SHTC3 温湿度传感器 ID、温度和湿度，并通过串口输出	温湿度传感器、CRC 校验
06_lvgl_demo	基于 ST7789、CST3530 和 LVGL v8.4.0 显示触摸演示界面	LCD、背光、触摸、LVGL

3. 目录结构

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

example/Arduino-v3.3.10
|-- 01_exio
|-- 02_I2C_qmi8658
|-- 03_SD_Card
|-- 04_I2C_pcf85063
|-- 05_shtc3
|-- 06_lvgl_demo
`-- lib
    |-- SensorLib
    `-- lvgl

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

example/Arduino-v3.3.10/01_exio/01_exio.ino

lib/SensorLib 是 04_I2C_pcf85063 使用的 RTC 驱动库，当前随包版本为 SensorLib v0.3.1；lib/lvgl 是 06_lvgl_demo 使用的 LVGL v8.4.0 库文件。编译 04_I2C_pcf85063 前至少需要复制 SensorLib，编译 06_lvgl_demo 前至少需要复制 lvgl。

4. 第一次运行推荐顺序

建议按以下顺序运行：

01_exio
  -> 02_I2C_qmi8658
  -> 03_SD_Card
  -> 04_I2C_pcf85063
  -> 05_shtc3
  -> 06_lvgl_demo

先用 01_exio 验证 CH32V003 IO 扩展和 I2C 总线。LCD 复位、触摸复位和背光都与 CH32V003 有关，建议先确认该示例正常。
再用 02_I2C_qmi8658 验证六轴传感器数据读取。
然后用 03_SD_Card 验证 Micro SD 卡和 SDSPI。
接着用 04_I2C_pcf85063 验证 RTC 时间设置和读取。
再用 05_shtc3 验证 SHTC3 温湿度读取和 CRC 校验。
最后运行 06_lvgl_demo，一次性验证 LCD、背光、触摸和 LVGL。

5. 使用说明

Arduino 示例目录为 example/Arduino-v3.3.10，请不要与 ESP-IDF 示例目录混用。
本产品共用一组 I2C：SDA GPIO0、SCL GPIO1，CH32V003、QMI8658、PCF85063、SHTC3 和 CST3530 都在该 I2C 总线上。
03_SD_Card 运行前需要插入 FAT 或 FAT32 格式的 Micro SD 卡。
04_I2C_pcf85063 默认每次上电都会写入固定测试时间，若需要 RTC 持续计时，请注释 i2c_rtc_setTime()。
06_lvgl_demo 已经适配 ST7789 显示和 CST3530 触摸，不需要额外引入 GFX 显示库或第三方触摸库。
如果从其他工程复制代码，请重点确认 LCD 和触摸复位脚：LCD_RST = CH32 EXIO1，TP_RST = CH32 EXIO0。
编译、屏幕点亮、触摸响应、I2C 地址等排查内容请参考产品 FAQ。

6. 示例说明

01_exio

【功能说明】

该示例用于验证板载 CH32V003 IO 扩展芯片通信是否正常。CH32V003 通过 I2C 与 ESP32-C5 通信，地址为 0x24，示例会将 EXIO0~EXIO7 配置为输出，并每秒翻转一次电平。

CH32V003 出厂时已经烧录好固件，无需单独烧录 CH32 固件。

【代码入口】

01_exio/01_exio.ino
01_exio/io_extension.cpp
01_exio/io_extension.h

建议优先查看：

代码	作用
`Wire.begin(I2C_SDA, I2C_SCL)`	初始化 I2C，总线引脚为 SDA GPIO0、SCL GPIO1
`IO_EXTENSION_ADDR`	CH32V003 I2C 地址，默认 `0x24`
`IO_EXTENSION_Init(Wire)`	初始化 IO 扩展芯片
`IO_EXTENSION_IO_Mode(0xFF)`	将 EXIO0~EXIO7 配置为输出
`IO_EXTENSION_Output()`	设置指定 EXIO 输出电平

【正常运行现象】

串口日志参考如下：

Arduino EXIO test serial log

【常见排查】

现象	可能原因	处理方法
串口提示 `IO extension not found at 0x24`	I2C 通信失败	确认使用 SDA GPIO0、SCL GPIO1，确认开发板供电正常
后续 LCD 或触摸不正常	CH32V003 未正常通信	先确保 `01_exio` 正常，再排查显示和触摸
想重新烧录 CH32V003固件	不需要	CH32V003 出厂已烧录固件，正常使用无需操作

02_I2C_qmi8658

【功能说明】

该示例用于读取板载 QMI8658 六轴传感器。程序初始化 I2C 后创建 qmi8658c_example 任务，每秒读取一次加速度和陀螺仪数据，并通过串口输出。

【代码入口】

02_I2C_qmi8658/02_I2C_qmi8658.ino
02_I2C_qmi8658/i2c_bsp.cpp
02_I2C_qmi8658/qmi8658c.cpp

建议优先查看：

代码	作用
`I2C_master_Init()`	初始化 I2C，总线引脚为 SDA GPIO0、SCL GPIO1，频率 400 kHz
`QMI8658_SLAVE_ADDR_H`	QMI8658 I2C 地址，默认 `0x6B`
`qmi8658_init()`	初始化 QMI8658
`qmi8658_read_xyz()`	读取加速度和陀螺仪数据

【正常运行现象】

串口会先输出 QMI8658 初始化信息，随后每秒输出一次传感器数据。
轻微倾斜或转动开发板时，加速度和陀螺仪数据会随姿态变化，日志参考如下：

Arduino QMI8658 test serial log

【常见排查】

现象	可能原因	处理方法
串口提示 `qmi8658_init fail`	QMI8658 I2C 通信失败	确认 I2C 引脚为 GPIO0/GPIO1，先运行 `01_exio` 或 `05_shtc3` 验证 I2C
数据一直不变化	开发板静止或任务未运行	轻微转动开发板，并确认串口波特率为 115200
编译报 I2C 相关接口错误	Arduino ESP32 core 版本不匹配	使用 `esp32 by Espressif Systems v3.3.10`

03_SD_Card

【功能说明】

该示例用于验证 Micro SD 卡接口。示例默认使用 SDSPI 模式挂载 SD 卡，挂载路径为 /sd_card，成功后会打印 SD 卡信息和容量。

【代码入口】

03_SD_Card/03_SD_Card.ino
03_SD_Card/sd_card_bsp.cpp
03_SD_Card/sd_card_bsp.h

建议优先查看：

代码	作用
`PIN_NUM_CLK`	SD SCLK，GPIO6
`PIN_NUM_MOSI`	SD MOSI，GPIO7
`PIN_NUM_MISO`	SD MISO，GPIO8
`PIN_NUM_CS`	SD CS，GPIO23
`SD_card_Init()`	初始化 SPI 总线并挂载 Micro SD 卡
`s_example_write_file()` / `s_example_read_file()`	示例中预留的文件写入和读取接口

【正常运行现象】

插入 FAT32 格式的 Micro SD 卡后，串口会打印 SD 卡类型、容量等信息，日志参考如下：

Arduino SD card test serial log

【常见排查】

现象	可能原因	处理方法
SD 卡挂载失败	未插卡、卡格式异常或接触不良	使用 FAT/FAT32 格式 Micro SD 卡，重新插拔后再测试
编译失败，提示 SDMMC/SDSPI 相关接口错误	Arduino ESP32 core 版本不匹配	使用 `v3.3.10`
文件读写失败	挂载失败或路径错误	先确认 `SD_card_Init()` 已成功打印卡信息

04_I2C_pcf85063

【功能说明】

该示例用于验证板载 PCF85063 RTC。程序会初始化 RTC，并在 setup() 中调用：

i2c_rtc_setTime(2025, 9, 9, 14, 51, 30);

随后创建 i2c_rtc_loop_task 任务，每秒读取并打印一次 RTC 时间。

【代码入口】

04_I2C_pcf85063/04_I2C_pcf85063.ino
04_I2C_pcf85063/rtc_bsp.cpp
04_I2C_pcf85063/rtc_bsp.h

建议优先查看：

代码	作用
`rtc.begin(Wire, SENSOR_SDA, SENSOR_SCL)`	初始化 PCF85063，默认 SDA GPIO0、SCL GPIO1
`i2c_rtc_setTime()`	设置 RTC 时间
`i2c_rtc_get()`	读取 RTC 时间结构体
`i2c_rtc_loop_task()`	周期读取并串口打印 RTC 时间

【正常运行现象】

串口每秒输出一次 RTC 时间，日志参考如下：

Arduino PCF85063 test serial log

由于示例在 setup() 中每次上电都会重新写入固定测试时间，如需验证 RTC 持续计时，请注释或删除 i2c_rtc_setTime()。

【常见排查】

现象	可能原因	处理方法
编译提示找不到 `SensorPCF85063.hpp`	缺少 SensorLib 依赖	将 `example/Arduino-v3.3.10/lib/SensorLib` 复制到 Arduino `libraries` 目录
串口提示 `Failed to find PCF85063`	RTC I2C 通信失败	确认 I2C 引脚为 GPIO0/GPIO1，并先测试其它 I2C 示例
每次上电时间都回到固定时间	示例主动写入测试时间	注释或删除 `i2c_rtc_setTime()` 后再测试 RTC 走时

05_shtc3

【功能说明】

该示例用于读取板载 SHTC3 温湿度传感器。程序使用 Wire 发送 SHTC3 命令，启动后唤醒传感器、读取 ID、执行软复位，并在 loop() 中每秒读取一次温度和湿度。

示例读取数据时会校验 SHTC3 CRC，避免无效数据被当成正常温湿度输出。

【代码入口】

05_shtc3/05_shtc3.ino

建议优先查看：

代码	作用
`SHTC3_ADDR`	SHTC3 I2C 地址，默认 `0x70`
`SHTC3_CMD_READ_ID`	读取传感器 ID
`SHTC3_CMD_MEASURE_T_RH`	触发温湿度测量
`shtc3Crc()`	校验 SHTC3 返回数据
`readShtc3()`	读取并换算温度、湿度

【正常运行现象】

串口先输出 SHTC3 ID，随后周期输出温湿度，日志参考如下：

Arduino SHTC3 temperature and humidity test serial log

【常见排查】

现象	可能原因	处理方法
串口提示 `SHTC3 not found`	I2C 通信失败	确认 I2C 引脚为 GPIO0/GPIO1，确认开发板供电正常
串口提示 `Failed to read SHTC3`	CRC 校验失败或传感器未正确响应	保持开发板稳定供电，重新上电后再测试
温湿度数值偶发异常	I2C 数据无效	示例已做 CRC 校验，建议以通过校验的数据为准

06_lvgl_demo

【功能说明】

该示例用于验证 LCD 显示、背光、触摸和 LVGL 基础界面。示例不依赖 GFX 显示库；LCD 驱动参考 ST7789 示例拆分到 Display_ST7789，触摸驱动参考 CST3530 示例拆分到 Touch_CST3530，CH32V003 IO 扩展、LCD 复位、触摸复位和背光控制统一放在 Board_IO 中。

界面会显示开发板名称、显示状态、触摸状态、触摸坐标和背光亮度。

【代码入口】

06_lvgl_demo/06_lvgl_demo.ino
06_lvgl_demo/Board_IO.cpp
06_lvgl_demo/Board_IO.h
06_lvgl_demo/Display_ST7789.cpp
06_lvgl_demo/Display_ST7789.h
06_lvgl_demo/Touch_CST3530.cpp
06_lvgl_demo/Touch_CST3530.h
06_lvgl_demo/lv_conf.h

建议优先查看：

代码	作用
`LCD_WIDTH` / `LCD_HEIGHT`	LCD 分辨率，240 x 320
`EXAMPLE_PIN_NUM_SCLK` / `EXAMPLE_PIN_NUM_MOSI`	LCD SPI 引脚，GPIO6/GPIO7
`EXAMPLE_PIN_NUM_LCD_DC` / `EXAMPLE_PIN_NUM_LCD_CS`	LCD DC/CS 引脚，GPIO9/GPIO10
`BOARD_LCD_RST_EXIO`	LCD 复位，CH32V003 EXIO1
`BOARD_TP_RST_EXIO`	触摸复位，CH32V003 EXIO0
`CST3530_ADDR`	CST3530 I2C 地址，默认 `0x58`
`LCD_Init()`	初始化 SPI 总线和 ST7789 面板
`TOUCH2_Init()`	初始化 CST3530 触摸
`create_demo_ui()`	创建 LVGL 示例界面

【正常运行现象】

LCD 显示 ESP32-C5 Touch LCD 2.8 示例界面。触摸屏幕时，界面会更新触摸坐标；拖动底部进度条可以调节屏幕背光亮度；串口会输出：

ESP32-C5-Touch-LCD-2.8 Arduino LVGL demo
Touch controller CST3530 initialized
LVGL demo started

如果触摸未识别，界面会显示 Touch: not found。

【常见排查】

现象	可能原因	处理方法
编译找不到 `lvgl.h`	未安装示例包内 LVGL	将 `example/Arduino-v3.3.10/lib/lvgl` 复制到 Arduino `libraries` 目录
编译出现大量 `lv_disp_drv_t`、`lv_indev_drv_t` 相关错误	使用了 LVGL v9	删除错误版本 LVGL，使用示例包内 LVGL v8.4.0
屏幕不亮	CH32V003、LCD 复位、背光或 ST7789 初始化异常	先运行 `01_exio`，确认 CH32V003 正常；再恢复 `06_lvgl_demo` 原始引脚配置
触摸无响应	CST3530 未识别或触摸复位异常	确认 I2C 为 GPIO0/GPIO1，触摸中断为 GPIO5，触摸复位为 CH32 EXIO0
显示颜色异常	RGB565 字节序或色深配置被修改	确认 `lv_conf.h` 使用 `LV_COLOR_DEPTH 16`，并保持示例中的 `LV_COLOR_16_SWAP` 配置

文档反馈

Arduino 入门教程​

配置开发环境​

1. 安装和配置 Arduino IDE​

2. 安装 ESP32 开发板支持包​

3. 安装库和示例依赖​

4. Arduino 工程参数设置​

示例程序​

1. 板载资源​

2. 示例列表​

3. 目录结构​

4. 第一次运行推荐顺序​

5. 使用说明​

6. 示例说明​

01_exio​

02_I2C_qmi8658​

03_SD_Card​

04_I2C_pcf85063​

05_shtc3​

06_lvgl_demo​

Arduino 入门教程

配置开发环境

1. 安装和配置 Arduino IDE

2. 安装 ESP32 开发板支持包

3. 安装库和示例依赖

4. Arduino 工程参数设置

示例程序

1. 板载资源

2. 示例列表

3. 目录结构

4. 第一次运行推荐顺序

5. 使用说明

6. 示例说明

01_exio

02_I2C_qmi8658

03_SD_Card

04_I2C_pcf85063

05_shtc3

06_lvgl_demo