Arduino 开发

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

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

阅读前准备

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

已准备 ESP32-C5-LCD-2.73 开发板。
已使用 USB 数据线连接开发板和电脑。
已安装 Arduino IDE。
已安装支持 ESP32-C5 的 ESP32 Arduino Core。
已下载产品示例程序包。
如需运行 01_lvgl_demo 或 07_example，请安装示例包内置的 libraries/lvgl。
如需运行 04_I2C_pcf85063 或 07_example，请安装 SensorLib，用于提供 SensorPCF85063.hpp。

Arduino 入门教程

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

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

配置开发环境

1. 安装和配置 Arduino IDE

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

2. 安装 ESP32 开发板支持包

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

版本说明

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

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

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

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

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

Arduino 工程参数

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

3. 安装库和示例依赖

本产品 Arduino 示例主要使用 Arduino ESP32 Core 自带能力、示例目录内提供的源码，以及资料包中的库文件。

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

LVGL 版本

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

离线/手动安装方式：

下载并解压产品示例程序包。
找到示例包中的 LVGL 库目录：
```
code/arduino/libraries/lvgl
```
将 lvgl 文件夹完整复制到 Arduino 的库目录。

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

安装检查方法：

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

4. Arduino 工程参数设置

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

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

arduino-cli core install esp32:esp32@3.3.10
arduino-cli compile --fqbn esp32:esp32:esp32c5 code/arduino/examples/01_lvgl_demo

示例程序

Arduino 示例程序位于示例程序包的 code/arduino/examples 目录。各示例已经按照 ESP32-C5-LCD-2.73 的板载硬件连接进行适配。

1. 板载资源

功能	器件或接口	引脚或说明
LCD	ILI9488，SPI，320 x 320	SCLK GPIO6，MOSI GPIO7，MISO GPIO5，DC GPIO4，CS GPIO8
LCD 复位	CH32V003 IO 扩展	IO0
LCD 背光	CH32V003 PWM	PWM 寄存器 `0x05`
IO 扩展	CH32V003，I2C 地址 `0x24`	SDA GPIO27，SCL GPIO26
六轴传感器	QMI8658，I2C 地址 `0x6B`	SDA GPIO27，SCL GPIO26
RTC	PCF85063，I2C 地址 `0x51`	SDA GPIO27，SCL GPIO26
温湿度传感器	SHTC3，I2C 地址 `0x70`	SDA GPIO27，SCL GPIO26
Micro SD	SDSPI	SCLK GPIO6，MOSI GPIO7，MISO GPIO5，CS GPIO9
BOOT 按键	用户按键	GPIO28

二次开发建议

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

2. 示例列表

示例目录	基础例程说明	主要验证内容
01_lvgl_demo	基于 ILI9488 和 LVGL v8.4.0 运行 LVGL 压力测试界面	LCD、背光、LVGL
02_SD_Card	通过 SDSPI 挂载 Micro SD 卡，并执行文件写入和读回检查	Micro SD、SDSPI、文件读写
03_I2C_qmi8658	读取 QMI8658 六轴传感器数据，并通过串口输出加速度和陀螺仪数据	IMU、I2C 总线
04_I2C_pcf85063	初始化 PCF85063 RTC，设置测试时间，并通过串口周期打印 RTC 时间	RTC、I2C 总线
05_shtc3	读取 SHTC3 温湿度传感器 ID、温度和湿度，并通过串口输出	温湿度传感器、CRC 校验
06_exio	测试板载 CH32V003 IO 扩展芯片，循环翻转 IO4~IO14 输出电平	IO 扩展、I2C 总线
07_example	综合显示 RTC、SHTC3、QMI8658 和 SD 卡状态，并通过 BOOT 按键切换页面	LCD、背光、传感器、RTC、SD 卡

3. 目录结构

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

code/arduino
|-- examples
|   |-- 01_lvgl_demo
|   |-- 02_SD_Card
|   |-- 03_I2C_qmi8658
|   |-- 04_I2C_pcf85063
|   |-- 05_shtc3
|   |-- 06_exio
|   `-- 07_example
`-- libraries
    `-- lvgl

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

code/arduino/examples/01_lvgl_demo/01_lvgl_demo.ino

libraries/lvgl 是 01_lvgl_demo 和 07_example 使用的 LVGL v8.4.0 库文件。编译这两个示例前，需要将 lvgl 复制到 Arduino 库目录。

4. 第一次运行推荐顺序

建议按以下顺序运行：

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

先用 06_exio 验证 CH32V003 IO 扩展和 I2C 总线。LCD 复位和背光控制都与 CH32V003 有关，建议先确认该示例正常。
再用 05_shtc3、03_I2C_qmi8658 和 04_I2C_pcf85063 验证 I2C 外设。
然后用 02_SD_Card 验证 Micro SD 卡和 SDSPI。
最后运行 01_lvgl_demo 和 07_example，验证 LCD、背光、LVGL 和综合页面。

5. 使用说明

Arduino 示例目录为 code/arduino/examples，请不要与 ESP-IDF 示例目录混用。
本产品共用一组 I2C：SDA GPIO27、SCL GPIO26，CH32V003、QMI8658、PCF85063 和 SHTC3 都在该 I2C 总线上。
02_SD_Card 和 07_example 运行前需要插入 FAT 或 FAT32 格式的 Micro SD 卡。
04_I2C_pcf85063 默认每次上电都会写入固定测试时间，若需要 RTC 持续计时，请注释 i2c_rtc_setTime()。
01_lvgl_demo 和 07_example 已经适配 ILI9488 显示，不需要额外引入 GFX 显示库。
如果从其他工程复制代码，请重点确认 LCD SPI 引脚、SD 卡片选引脚和 CH32V003 IO 扩展配置。
编译、屏幕点亮、I2C 地址等排查内容请参考产品 FAQ。

6. 示例说明

01_lvgl_demo

【功能说明】

该示例用于验证 LCD 显示、背光和 LVGL 基础运行。程序通过 SPI 初始化 ILI9488 LCD，使用 CH32V003 控制 LCD 复位和背光，然后启动 LVGL 压力测试界面。

【代码入口】

01_lvgl_demo/01_lvgl_demo.ino
01_lvgl_demo/esp_lcd_ili9488.c
01_lvgl_demo/esp_lcd_ili9488.h
01_lvgl_demo/lv_conf.h

建议优先查看：

代码	作用
`LCD_H_RES` / `LCD_V_RES`	LCD 分辨率，320 x 320
`LCD_SPI_SCLK` / `LCD_SPI_MOSI` / `LCD_SPI_MISO`	LCD SPI 引脚，GPIO6/GPIO7/GPIO5
`LCD_SPI_DC` / `LCD_SPI_CS`	LCD DC/CS 引脚，GPIO4/GPIO8
`IO_EXT_LCD_RST`	LCD 复位，CH32V003 IO0
`io_ext_pwm()`	通过 CH32V003 PWM 设置背光
`esp_lcd_new_panel_ili9488()`	创建 ILI9488 面板驱动
`lv_demo_stress()`	启动 LVGL 压力测试界面

【正常运行现象】

LCD 显示 LVGL 压力测试界面。
串口输出 ESP32-C5-LCD-2.73 Arduino LVGL demo 和 LVGL stress demo started。

【常见排查】

现象	可能原因	处理方法
编译找不到 `lvgl.h`	未安装示例包内 LVGL	将 `code/arduino/libraries/lvgl` 复制到 Arduino `libraries` 目录
编译出现大量 `lv_disp_drv_t` 相关错误	使用了 LVGL v9	删除错误版本 LVGL，使用示例包内 LVGL v8.4.0
屏幕不亮	CH32V003、LCD 复位、背光或 ILI9488 初始化异常	先运行 `06_exio`，确认 CH32V003 正常；再恢复 `01_lvgl_demo` 原始引脚配置
显示颜色异常	像素格式或颜色顺序配置被修改	保持示例中的 `bits_per_pixel = 18`、`LCD_RGB_ELEMENT_ORDER_BGR` 和颜色反转配置

02_SD_Card

【功能说明】

该示例用于验证 Micro SD 卡接口。程序通过 SDSPI 挂载 SD 卡，挂载路径为 /sd_card，随后写入 sd_rw_test.txt 并读回校验。

【代码入口】

02_SD_Card/02_SD_Card.ino
02_SD_Card/sd_card_bsp.cpp
02_SD_Card/sd_card_bsp.h

建议优先查看：

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

【正常运行现象】

插入 FAT 或 FAT32 格式的 Micro SD 卡后，串口会打印 SD 卡类型、容量、写入长度、读回长度和 PASS 结果。

【常见排查】

现象	可能原因	处理方法
SD 卡挂载失败	未插卡、卡格式异常或接触不良	使用 FAT/FAT32 格式 Micro SD 卡，重新插拔后再测试
文件读写失败	挂载失败或路径错误	先确认 `SD_card_Init()` 已成功打印卡信息
与 LCD 示例切换后 SD 卡异常	SPI 总线状态或 CS 电平未恢复	重新上电后单独运行 `02_SD_Card`

03_I2C_qmi8658

【功能说明】

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

【代码入口】

03_I2C_qmi8658/03_I2C_qmi8658.ino
03_I2C_qmi8658/i2c_bsp.cpp
03_I2C_qmi8658/qmi8658c.cpp
03_I2C_qmi8658/qmi8658c.h

建议优先查看：

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

【正常运行现象】

串口会先输出 QMI8658 初始化信息，随后周期输出传感器数据。
轻微倾斜或转动开发板时，加速度和陀螺仪数据会随姿态变化。

【常见排查】

现象	可能原因	处理方法
串口提示 QMI8658 初始化失败	QMI8658 I2C 通信失败	确认 I2C 引脚为 GPIO27/GPIO26，先运行 `05_shtc3` 或 `06_exio` 验证 I2C
数据一直不变化	开发板静止或任务未运行	轻微转动开发板，并确认串口波特率为 115200
编译报 I2C 相关接口错误	Arduino ESP32 Core 版本不匹配	使用包含 ESP32-C5 支持的开发板支持包

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 GPIO27、SCL GPIO26
`i2c_rtc_setTime()`	设置 RTC 时间
`i2c_rtc_get()`	读取 RTC 时间结构体
`i2c_rtc_loop_task()`	周期读取并串口打印 RTC 时间

【正常运行现象】

串口每秒输出一次 RTC 时间。

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

【常见排查】

现象	可能原因	处理方法
编译提示找不到 `SensorPCF85063.hpp`	缺少 SensorLib 依赖	安装 `SensorLib` 后重新编译
串口提示 `Failed to find PCF85063`	RTC I2C 通信失败	确认 I2C 引脚为 GPIO27/GPIO26，并先测试其它 I2C 示例
每次上电时间都回到固定时间	示例主动写入测试时间	注释或删除 `i2c_rtc_setTime()` 后再测试 RTC 走时

05_shtc3

【功能说明】

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

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

【代码入口】

05_shtc3/05_shtc3.ino

建议优先查看：

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

【正常运行现象】

串口先输出 SHTC3 ID，随后周期输出温湿度。

【常见排查】

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

06_exio

【功能说明】

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

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

【代码入口】

06_exio/06_exio.ino
06_exio/io_extension.cpp
06_exio/io_extension.h

建议优先查看：

代码	作用
`Wire.begin(I2C_SDA, I2C_SCL)`	初始化 I2C，总线引脚为 SDA GPIO27、SCL GPIO26
`IO_EXTENSION_ADDR`	CH32V003 I2C 地址，默认 `0x24`
`IO_EXTENSION_Init(Wire)`	初始化 IO 扩展芯片
`IO_EXTENSION_IO_Mode(0xFFF7)`	配置 IO 扩展引脚模式
`IO_EXTENSION_Output()`	设置指定 IO 扩展引脚输出电平

【正常运行现象】

串口输出 IO4~IO14 will toggle every second.。
随后每秒输出一次 IO4~IO14 的当前电平。

【常见排查】

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

07_example

【功能说明】

该示例用于综合验证 LCD、背光、RTC、SHTC3、QMI8658 和 Micro SD 卡。程序启动后初始化 I2C、CH32V003、ILI9488、LVGL 和板载外设，LCD 页面显示系统状态、RTC、温湿度、IMU 和 SD 卡信息。

按下 BOOT 按键可切换页面。

【代码入口】

07_example/07_example.ino
07_example/esp_lcd_ili9488.c
07_example/esp_lcd_ili9488.h
07_example/i2c_bsp.cpp
07_example/qmi8658c.cpp
07_example/rtc_bsp.cpp
07_example/sd_card_bsp.cpp
07_example/lv_conf.h

建议优先查看：

代码	作用
`init_lcd_panel()`	初始化 SPI 总线和 ILI9488 面板
`init_lvgl()`	初始化 LVGL 显示缓冲区和刷新回调
`init_peripherals()`	依次检查 RTC、SHTC3、QMI8658 和 SD 卡
`refresh_sensors()`	周期读取传感器和 RTC 数据
`refresh_screen()`	按当前页面刷新 LCD 显示内容
`handle_button()`	读取 GPIO28 BOOT 按键并切换页面

【正常运行现象】

LCD 显示 System Status 页面。
按下 BOOT 按键后，页面在系统状态、RTC、SHTC3、QMI8658 IMU 和 SD Card 之间切换。
串口周期输出 RTC、温湿度、加速度、陀螺仪和 SD 卡容量信息。

【常见排查】

现象	可能原因	处理方法
编译找不到 `lvgl.h`	未安装示例包内 LVGL	将 `code/arduino/libraries/lvgl` 复制到 Arduino `libraries` 目录
编译找不到 `SensorPCF85063.hpp`	缺少 SensorLib 依赖	安装 `SensorLib` 后重新编译
页面显示某外设为 `NO`	对应外设初始化或通信失败	先单独运行该外设对应的基础示例
BOOT 按键无法切换页面	按键 GPIO 配置异常	确认示例保留 `BOOT_BUTTON = GPIO_NUM_28` 和 `INPUT_PULLUP` 配置
SD 页面显示未挂载	未插入 SD 卡或格式异常	插入 FAT/FAT32 格式 Micro SD 卡后重新上电测试

文档反馈

Arduino 入门教程​

配置开发环境​

1. 安装和配置 Arduino IDE​

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

3. 安装库和示例依赖​

4. Arduino 工程参数设置​

示例程序​

1. 板载资源​

2. 示例列表​

3. 目录结构​

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

5. 使用说明​

6. 示例说明​

01_lvgl_demo​

02_SD_Card​

03_I2C_qmi8658​

04_I2C_pcf85063​

05_shtc3​

06_exio​

07_example​

Arduino 入门教程

配置开发环境

1. 安装和配置 Arduino IDE

2. 安装 ESP32 开发板支持包

3. 安装库和示例依赖

4. Arduino 工程参数设置

示例程序

1. 板载资源

2. 示例列表

3. 目录结构

4. 第一次运行推荐顺序

5. 使用说明

6. 示例说明

01_lvgl_demo

02_SD_Card

03_I2C_qmi8658

04_I2C_pcf85063

05_shtc3

06_exio

07_example