Arduino 开发
本章节介绍 Arduino 开发环境配置方法和产品示例程序。
运行示例前，请确认以下条件已满足：
- 已准备 ESP32-C5-Touch-LCD-3.5 开发板和支持数据传输的 USB 线。
- 已安装 Arduino IDE。
- 已安装 Arduino ESP32 Core v3.3.10。
- 运行 Micro SD 卡示例前，已插入 Micro SD 卡。
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 教程 完成安装。
2. 安装 ESP32 开发板支持包
在 Arduino IDE 的开发板管理器中安装 esp32 by Espressif Systems v3.3.10。
示例程序基于 Arduino ESP32 Core v3.3.10 开发并完成验证。使用其他版本时，可能无法正确识别 ESP32-C5 开发板，导致串口下载失败或无法烧录程序。
安装完成后，在 Arduino IDE 中设置：
| 设置项 | 选择 |
|---|---|
| Board | ESP32C5 Dev Module |
| Port | 开发板对应的 USB 串口 |
| USB CDC On Boot | Enabled |
| PSRAM | Enabled |
| Flash Mode | QIO |
| Flash Size | 16MB (128Mb) |
| Partition Scheme | 16M Flash (3MB APP/9.9MB FATFS) |
USB CDC On Boot 用于通过 ESP32-C5 原生 USB 查看串口输出。如果开发板无法进入下载状态，请参考 产品 FAQ。
Arduino ESP32 Core v3.3.10 的 ESP32-C5 菜单最高提供 16 MB Flash 选项，因此上述配置仅使用板载 32 MB Flash 的一部分；出厂 ESP-IDF 工程按 32 MB Flash 配置。
下图中的 Flash Mode: DIO 为旧设置，当前工程请按上表选择 QIO。
3. 安装示例依赖
新版工程的 examples/arduino/libraries 目录包含以下示例依赖库：
| 库 | 版本 | 用途 |
|---|---|---|
SensorLib | 0.3.1 | 04_I2C_pcf85063 的 PCF85063 RTC 驱动 |
XPowersLib | 示例包内版本 | 06_axp2101_example 的 AXP2101 驱动 |
lvgl | 8.4.0 | 07_lvgl_demo 的图形界面库 |
将需要的库目录完整复制到 Arduino Sketchbook 下的 libraries 目录，然后重启 Arduino IDE。Windows 默认路径通常为：
C:\Users\<用户名>\Documents\Arduino\libraries
示例程序
新版产品 示例程序仓库 中，Arduino 示例位于 examples/arduino/examples 目录。每个子目录都是独立工程，请打开与目录同名的 .ino 文件。
旧版工程中的示例位于 example/Arduino-v3.3.10/example，库位于 example/Arduino-v3.3.10/libraries。本页按当前 GitHub 仓库目录说明，已有旧版工程时请重新下载。
示例列表
| 示例目录 | 功能 | 主要验证内容 |
|---|---|---|
| 01_exio | 循环翻转 EXIO8～EXIO15 输出电平 | IO 扩展芯片、I2C |
| 02_I2C_qmi8658 | 读取加速度和角速度 | QMI8658、I2C |
| 03_SD_Card | 挂载 Micro SD 卡并输出容量信息 | Micro SD 卡、SDSPI |
| 04_I2C_pcf85063 | 设置并周期读取 RTC 时间 | PCF85063、I2C |
| 05_shtc3 | 读取环境温度和湿度 | SHTC3、I2C、CRC 校验 |
| 06_axp2101_example | 读取电源和充电状态 | AXP2101、电源管理 |
| 07_lvgl_demo | 显示 LVGL 界面并测试触摸与背光调节 | ST7796、FT6336、LVGL |
01_exio
程序说明
示例通过 I2C 初始化 IO 扩展芯片，将 EXIO8～EXIO15 配置为输出，并每隔 1 秒在高、低电平之间切换。EXIO0～EXIO7 保持输入模式。
硬件连接
- 将开发板通过 USB 连接到电脑。
运行效果
串口每隔 1 秒交替输出：
EXIO8~EXIO15 output: LOW
EXIO8~EXIO15 output: HIGH
如果输出 IO extension not found at 0x24，请检查开发板供电及 GPIO27/GPIO26 对应的 I2C 配置。
02_I2C_qmi8658
程序说明
示例初始化 QMI8658 六轴传感器，然后在 FreeRTOS 任务中周期读取加速度和角速度数据。
硬件连接
- 将开发板通过 USB 连接到电脑。
运行效果
串口输出 QMI8658 初始化信息和传感器数据。转动开发板时，输出值随姿态变化。
03_SD_Card
程序说明
示例使用 SDSPI 挂载 Micro SD 卡，挂载点为 /sd_card，成功后输出卡类型和容量信息。
硬件连接
- 将开发板通过 USB 连接到电脑。
- 将 FAT32 格式的 Micro SD 卡插入卡槽。
当 Micro SD 卡挂载失败时，当前示例配置会尝试格式化存储卡。运行前请备份卡内数据。
运行效果
挂载成功后，串口输出 Micro SD 卡类型和容量信息。
04_I2C_pcf85063
程序说明
示例初始化 PCF85063 RTC，并在每次启动时将时间写入为 2025-09-09 14:51:30。随后每隔 1 秒读取并输出一次 RTC 时间。
如需验证 RTC 持续走时，请注释 setup() 中的 i2c_rtc_setTime()，否则每次重启都会重新写入固定时间。
硬件连接
- 将开发板通过 USB 连接到电脑。
运行效果
串口每隔 1 秒输出一次 RTC 日期和时间。
05_shtc3
程序说明
示例唤醒 SHTC3，读取传感器 ID 并执行软复位，然后每隔 1 秒读取一次温度和湿度。程序会校验传感器返回数据的 CRC。
硬件连接
- 将开发板通过 USB 连接到电脑。
运行效果
SHTC3 ID: 0xXXXX
Temperature: 25.00 C, Humidity: 50.00 %
实际数值由当前环境决定。如果输出 Failed to read SHTC3，请检查供电和 I2C 配置，然后重新上电测试。
06_axp2101_example
程序说明
示例通过 I2C 初始化 AXP2101 电源管理芯片，输出各路 DCDC 和 LDO 的开关状态与电压。程序会监测 VBUS、电池、系统电压和芯片温度，并每隔 5 秒输出一次状态。
示例不会修改或关闭各路 DCDC/LDO 输出，充电参数设置为：
- 预充电电流：50 mA
- 恒流充电电流：400 mA
- 终止电流：25 mA
- 充电截止电压：4.2 V
硬件连接
- 将开发板通过 USB 连接到电脑。
- 如需查看电池电压、电量百分比或充放电状态，将符合产品要求的 3.7 V 锂电池连接到电池接口。
修改 AXP2101 充电电流或截止电压前，必须确认电池规格和硬件充电设计允许该参数。
运行效果
串口首先输出 AXP2101 芯片 ID 和各路电源轨状态，随后周期输出 VBUS、电池、系统电压和芯片温度。
周期状态输出
| 字段 | 可能结果 | 含义 |
|---|---|---|
VBUS | connected / disconnected | USB 或外部电源是否接入 VBUS |
valid | yes / no | VBUS 输入电压是否有效 |
| VBUS 电压 | 数值，mV | VBUS 输入电压 |
Battery | connected / disconnected | 电池是否连接 |
charging | yes / no | 是否正在充电 |
discharging | yes / no | 是否正在放电 |
| 电池电压 | 数值，mV | 当前电池电压 |
| 电量 | 0% 〜 100% | 估算电池电量，仅在检测到电池时输出 |
System | 数值，mV | PMU 系统供电电压，通常为 VSYS |
PMU temperature | 数值，°C | AXP2101 芯片内部温度 |
中断事件输出
| 输出信息 | 含义 |
|---|---|
Event: VBUS inserted | USB 或外部电源接入 |
Event: VBUS removed | USB 或外部电源拔出 |
Event: battery inserted | 电池插入 |
Event: battery removed | 电池移除 |
Event: charging started | 开始充电 |
Event: charging completed | 充电完成 |
Event: power key short press | 短按 PWR 按键 |
Event: power key long press | 长按 PWR 按键 |
07_lvgl_demo
程序说明
示例基于 LVGL v8.4.0 初始化 ST7796 LCD 和 FT6336 电容触摸芯片，用于验证屏幕显示、触摸输入和背光调节功能。
界面包含触摸测试按钮和背光滑块：
- 点击
Touch test按钮后，按钮文本显示累计点击次数。 - 拖动背光滑块可在 10%～100% 范围内调节屏幕亮度。
LCD 使用 60 MHz SPI 时钟和 RGB565 像素格式。LCD 复位、触摸复位和背光 PWM 由 IO 扩展芯片控制。
硬件连接
- 将开发板通过 USB 连接到电脑。
- 本示例不需要插入 Micro SD 卡。
请使用工程随附的 LVGL v8.4.0，新版工程中的路径为 examples/arduino/libraries/lvgl。LVGL v9 的显示和输入设备接口与本示例不兼容。lv_conf.h 必须保留在 07_lvgl_demo 目录中。
运行效果
屏幕显示开发板型号、LCD 和触摸状态、触摸测试按钮以及背光滑块。串口初始化成功后输出：
Touch controller FT6336 initialized
ESP-IDF LCD IO + LVGL demo started
