Arduino 开发
本章节包含以下部分，请按需阅读：
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
信息
对于 ESP32-C6-Touch-AMOLED-2.16 开发板，Arduino IDE 需要安装 arduino-esp32 v3.3.0 以上版本。
请参考 安装和配置 Arduino IDE 教程 下载安装 Arduino IDE 并添加 ESP32 支持。
2. 安装库
- 在安装 Arduino 库时，通常有两种方式可供选择：在线安装 和 离线安装。若库安装要求离线安装，则必须使用提供的库文件。
- 对于大多数库，用户可以通过 Arduino 软件的在线库管理器轻松搜索并安装。然而，一些开源库或自定义库未被同步到 Arduino 库管理器中，因此无法通过在线搜索获取。在这种情况下，用户只能通过离线方式手动安装这些库。
- 可从 该处 下载 ESP32-C6-Touch-AMOLED-2.16 开发板的示例程序包。包内的 Arduino\libraries 目录已包含本教程所需的全部库文件。
| 库或文件名称 | 说明 | 版本 | 安装方式 |
|---|---|---|---|
| LVGL | 图形库 | v8.* / v9.* | "离线"安装 |
| SensorLib | 传感器控制库 | v0.3.1 | "离线/在线"安装 |
版本兼容性说明
LVGL 及其驱动库的版本之间存在较强的依赖关系。例如，为 LVGL v8 编写的驱动可能不兼容 LVGL v9。为确保示例能够稳定复现，推荐使用上表列出的特定版本。混合使用不同版本的库可能导致编译失败或运行时异常。
3. Arduino 工程参数设置
示例程序
Arduino 示例程序位于 示例程序包 的 Arduino/examples 目录中。
| 示例程序 | 基础例程说明 | 依赖库 |
|---|---|---|
| 01_ADC_Test | 获取锂电池的电压值 | - |
| 02_I2C_PCF85063 | 打印RTC芯片的实时时间 | SensorLib |
| 03_I2C_QMI8658 | 打印IMU发出来的原始数据 | SensorLib |
| 04_SD_Card | 加载显示SD卡的信息 | - |
| 05_WIFI_AP | 设置为AP模式，可获取接入设备的IP地址 | - |
| 06_WIFI_STA | 设置为STA模式，可接入WiFi获取IP地址 | - |
| 07_BATT_PWR_Test | 单独使用锂电池供电时，通过PWR按键控制电源 | - |
| 08_Audio_Test | 扬声器播放麦克风录到的声音 | - |
| 09_LVGL_V8_Test | LVGLV8例程 | LVGL V8.* |
| 10_LVGL_V9_Test | LVGLV9例程 | LVGL V9.* |
01_AXP2101_Test
【程序说明】
- 通过驱动 AXP2101 获取电源信息，并打印到终端。
【硬件连接】
- 使用 USB 线把板子接入电脑
【代码分析】
axp2101.setDC1Voltage(3300); //设置DCDC1电压值3.3V
axp2101.setALDO1Voltage(3300); //设置ALDO1电压值3.3V
axp2101.setALDO2Voltage(3300); //设置ALDO2电压值3.3V
axp2101.setALDO3Voltage(3300); //设置ALDO3电压值3.3V
axp2101.setALDO4Voltage(3300); //设置ALDO4电压值3.3V
axp2101.setPrechargeCurr(XPOWERS_AXP2101_PRECHARGE_50MA); //设置预充电流50ma
axp2101.setChargerConstantCurr(XPOWERS_AXP2101_CHG_CUR_500MA);//设置恒流充电电流500ma
axp2101.setChargerTerminationCurr(XPOWERS_AXP2101_CHG_ITERM_50MA);//设置截止充电电流50ma
axp2101.getBattVoltage(); //获取锂电池电压
【运行效果】
-
程序编译下载完成，打开串口监控可以看到打印输出的电源信息，如下图所示：
02_I2C_QMI8658
【程序说明】
- 通过驱动 QMI8658 获取姿态信息，并打印到终端。
【硬件连接】
- 使用 USB 线把板子接入电脑
【代码分析】
qmi8658_set_accel_range(&qmi8658, QMI8658_ACCEL_RANGE_8G);// 设置加速度计量程为 ±8G（G=重力加速度）
qmi8658_set_accel_odr(&qmi8658, QMI8658_ACCEL_ODR_1000HZ);// 设置加速度计输出数据速率为 1000Hz（每秒1000次采样）
qmi8658_set_gyro_range(&qmi8658, QMI8658_GYRO_RANGE_512DPS);// 设置陀螺仪量程为 ±512°/s（每秒最大旋转角速度）
qmi8658_set_gyro_odr(&qmi8658, QMI8658_GYRO_ODR_1000HZ);// 设置陀螺仪输出数据速率为 1000Hz
qmi8658_set_accel_unit_mps2(&qmi8658, true);// 设置加速度计输出单位为 m/s²（米/秒²）
qmi8658_set_gyro_unit_rads(&qmi8658, true);// 设置陀螺仪输出单位为 rad/s（弧度/秒）
qmi8658_set_display_precision(&qmi8658, 4);// 设置数据输出/打印的精度为 4 位小数
【运行效果】
-
程序编译下载完成，打开串口监控可以看到打印输出的姿态信息，如下图所示：
03_I2C_QMI8658
【程序说明】
- 通过驱动 PCF85063 设置时间、获取时间，并打印到终端。
【硬件连接】
- 使用 USB 线把板子接入电脑
【代码分析】
pcf85063a_datetime_t datatime = {
.year = 2026,
.month = 1,
.day = 1,
.hour = 8,
.min = 0,
.sec = 0
};
pcf85063a_set_time_date(&pcf85063, datatime); /*设置起始时间2026/1/1 08:00:00*/
pcf85063a_get_time_date(&pcf85063, &datatime); /*获取当前的时间*/
【运行效果】
-
程序编译下载完成，打开串口监控可以看到打印输出的 RTC 时间，如下图所示：
04_SD_Card
【程序说明】
- 使 SDSPI 的方式驱动 SD Card，并将 SD Card 信息打印到终端。
【硬件连接】
- 使用 USB 线把板子接入电脑
【代码分析】
esp_vfs_fat_sdspi_mount(SdName_, &host, &slot_config, &mount_config, &sdCardHead); //挂载 sdcard 到 fatfs 文件系统
int SDPort_WriteFile(const char *path, const void *data, size_t data_len); //往文件写数据
int SDPort_ReadFile(const char *path, uint8_t *buffer, size_t *outLen); //从文件读取数据
int SDPort_ReadOffset(const char *path, void *buffer, size_t len, size_t offset); //带有偏移量从文件读取数据
int SDPort_WriteOffset(const char *path, const void *data, size_t len, bool append); //带有偏移量从文件写数据
【运行效果】
- 程序编译下载完成，打开串口监控可以看到打印输出的 SD Card 信息，如下图所示：
05_WIFI_STA
【程序说明】
- 把开发板设置成 WIFI STA 模式，可连接 AP 路由器，并将获取 IP 地址打印到终端。
【硬件连接】
- 使用 USB 线把板子接入电脑
【代码分析】
nvs_flash_init(); // 初始化 NVS（非易失性存储），用于保存 Wi-Fi 配置等数据
esp_netif_init(); // 初始化 TCP/IP 栈，网络通信所需
esp_event_loop_create_default(); // 创建默认 事件循环，用于系统事件分发（如 Wi-Fi 事件）
esp_netif_create_default_wifi_sta(); // 创建默 认 Wi-Fi STA（Station）接口，用于连接路由器
esp_netif_create_default_wifi_ap(); // 创建默 认 Wi-Fi AP（Access Point）接口，用于自身提供热点
strcpy((char*)sta_config.sta.ssid, "ESP32_STA"); // 设置路由器的SSID
strcpy((char*)sta_config.sta.password, "12345678"); // 设置路由器的密码
esp_wifi_set_mode(WIFI_MODE_STA); // 设置ESP32 WIFI模式
【运行效果】
- 程序编译下载完成，打开串口监控可以看到打印输出的 IP 地址，如下图所示：
06_WIFI_AP
【程序说明】
- 把开发板设置成 WIFI AP 模式，其余 STA 设备可连接该 AP，连接成功之后将获取设备 MAC 打印到终端。
【硬件连接】
- 使用 USB 线把板子接入电脑
【代码分析】
nvs_flash_init(); // 初始化 NVS（非易失性存储），用于保存 Wi-Fi 配置等数据
esp_netif_init(); // 初始化 TCP/IP 栈，网络通信所需
esp_event_loop_create_default(); // 创建默认 事件循环，用于系统事件分发（如 Wi-Fi 事件）
esp_netif_create_default_wifi_sta(); // 创建默 认 Wi-Fi STA（Station）接口，用于连接路由器
esp_netif_create_default_wifi_ap(); // 创建默 认 Wi-Fi AP（Access Point）接口，用于自身提供热点
strcpy((char*)ap_config.ap.ssid, "ESP32_AP"); // 设置 AP（热点）的 SSID 名称为 "ESP32_AP"
strcpy((char*)ap_config.ap.password, "12345678"); // 设置 AP 密码为 "12345678"（至少8位）
ap_config.ap.max_connection = 4; // 设置最多允许 4 台设备同时连接到 AP
ap_config.ap.authmode = WIFI_AUTH_WPA_WPA2_PSK; // 设置认证模式为 WPA/WPA2 PSK（密码验证）
esp_wifi_set_mode(WIFI_MODE_AP); // 将 Wi-Fi 模式设置为 AP 模式（仅热点）
esp_wifi_set_config(WIFI_IF_AP, &ap_config); // 应用 AP 配置，使 Wi-Fi 热点生效
【运行效果】
- 程序编译下载完成，打开串口监控可以看到打印输出的 MAC 地址，如下图所示：
07_Audio_Test
【程序说明】
- 通过驱动 ES8311 和 ES7210 Codec 芯片，实现录音、播放等功能。
【硬件连接】
- 使用 USB 线把板子接入电脑
【代码分析】
esp_err_t play_pcm_from_spiffs(uint8_t *play_buf, const char *file_path,bool *Music_flag); // 从spiffs文件系统里面读取音频数据，然后进行播放
void fac_play_read_storage(uint8_t *play_buf); // 从文件系统读取二进制录音数据，然后进行播放
void fac_rec_write_storage(uint8_t *rec_buf,size_t max_size); // 把录音数据保存到spiffs里面
【运行效果】
-
程序编译下载完成，可看到开发板显示内容，如下图所示：
提示- 点击 Recording 可录音，录音时间 3 秒
- 点击 Play Recording 可播放录音
- 点击 Play Music 可播放音乐
- 点击 Stop Music 可暂停音乐
08_LVGL_V8_Test
【程序说明】
- 通过移植 LVGL V8 ，可帮助用户快速上手 UI 设计。
【硬件连接】
- 使用 USB 线把板子接入电脑
【代码分析】
#define Brightness_Test_EN 1 // 置 0 关闭背光测试，默认置 1
Custom_PmicPortInit(&user_i2cbus,0x34); // 初始化电源 IC
user_display = new DisplayPort(user_i2cbus,480,480); // 初始化 屏幕
user_display->DisplayPort_TouchInit(); // 初始化 触摸
Lvgl_PortInit(*user_display); // LVGL 接口初始化
【运行效果】
- 程序编译下载完成，可看到开发板显示内容，如下图所示：
09_LVGL_V9_Test
【程序说明】
- 通过移植 LVGL V9 ，可帮助用户快速上手 UI 设计。
【硬件连接】
- 使用 USB 线把板子接入电脑
【代码分析】
#define Brightness_Test_EN 1 // 置 0 关闭背光测试，默认置 1
Custom_PmicPortInit(&user_i2cbus,0x34); // 初始化电源 IC
user_display = new DisplayPort(user_i2cbus,480,480); // 初始化 屏幕
user_display->DisplayPort_TouchInit(); // 初始化 触摸
Lvgl_PortInit(*user_display); // LVGL 接口初始化
【运行效果】
- 程序编译下载完成，可看到开发板显示内容，如下图所示：
