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
请参考 安装和配置 Arduino IDE 教程 下载安装 Arduino IDE 并添加 ESP32 支持。
| 开发板支持包 | 安装方式 | 版本要求 |
|---|---|---|
| esp32 by Espressif Systems | “离线”安装 / “在线”安装 | ≥3.0.7 |
环境设置是在 Windows 10 系统下进行，Linux 和 Mac 用户可访问 Arduino-esp32 环境搭建 参考。
2. 安装库
要运行示例，需要安装对应的库。示例代码使用 LVGL 图形库驱动 AMOLED 显示屏。
可从相关资料下载 ESP32-S3-Touch-AMOLED-2.41 开发板对应版本的示例程序。库文件位置如下：
- V1：
Arduino\libraries - V2：
01_Arduino_Libraries
| 库名称 | 说明 | 版本 | 安装方式 |
|---|---|---|---|
| LVGL | 图形库 | v8.4.0 | "离线"安装 |
LVGL 及其驱动库的版本之间存在较强的依赖关系。为确保示例能够稳定复现，推荐使用上表列出的特定版本。混合使用不同版本的库可能导致编译失败或运行时异常。
安装步骤：
-
从相关资料下载与开发板硬件版本对应的示例程序包并解压。
-
将对应版本库目录下的所有文件夹复制到 Arduino 的库文件夹中：V1 使用
Arduino\libraries，V2 使用01_Arduino_Libraries。信息Arduino 库文件夹的路径通常是：
C:\Users\<用户名>\Documents\Arduino\libraries。也可以在 Arduino IDE 中通过 文件 > 首选项，查看"项目文件夹位置"来定位。库文件夹就是此路径下的
libraries文件夹。 -
其他安装方式请参考：Arduino 库管理教程。
3. 其他提示
-
根据硬件版本选择开发板：
- V1：选择 WaveShare ESP32-S3-Touch-AMOLED-2.41。
- V2：选择 ESP32S3 Dev Module，并按照 V2 仓库中的 Tools Configuration.png 配置 Flash、PSRAM 和 USB 选项。
-
ESP32-S3-Touch-AMOLED-2.41 使用 ESP32-S3 原生 USB 接口，而非 UART 转 USB。对于串口通信：
-
printf()函数可直接使用； -
若要使用
Serial.println()函数，需要额外配置：在 IDE 工具菜单中启用"USB CDC On Boot"选项，或在代码中声明 HWCDC 对象处理 USB 串口通信。备注在 Arduino IDE 的"工具"选项中设置"USB CDC On Boot"
-
示例程序
V1 与 V2 的部分引脚定义及工程配置不同，示例程序不能直接混用。请先确认开发板的实际硬件版本，再从相关资料下载对应版本的程序。
Arduino 示例程序位置如下：
- V1：
Arduino/examples - V2：
02_Example/Arduino
以下示例说明以 V1 资料包为基础。V2 示例的目录名称和实现可能不同，请以 V2 仓库中的程序为准。
| 示例程序 | 基础例程说明 | 依赖库 |
|---|---|---|
| 01_ADC_Test | 读取系统当前的电压值 | - |
| 02_I2C_PCF85063 | 打印 RTC 芯片的实时时间 | - |
| 03_I2C_QMI8658 | 打印 IMU 发出来的原始数据 | - |
| 04_SD_Card | 加载显示 SD 卡的信息 | - |
| 05_WIFI_STA | 设置为 STA 模式，可接入 Wi-Fi 获取 IP 地址 | - |
| 06_WIFI_AP | 设置为 AP 模式，可获取接入设备的 IP 地址 | - |
| 07_EX_GPIO | 使用扩展 IO 和内部 IO | - |
| 08_Li_ION_Test | 使能锂电池 | - |
| 09_LVGL_Test | LVGL 例程 | LVGL |
| Arduino_Playablity | 可玩性程序例程 | - |
01_ADC_Test
本示例通过 GPIO 连接的模拟量电压经过 ADC 转换成数字量，然后通过计算得到实际的系统电压，打印到终端。
ADC 引脚说明
| ADC_CHAN | GPIO_PIN |
|---|---|
| ADC2_CHANNEL_6 | GPIO17 |
代码解释
adc_bsp_init(void)：初始化 ADC2，包括创建 ADC 单次触发单元并配置 ADC2 的通道 6。adc_get_value(float *value, int *data)：读取 ADC2 通道 6 的值，并根据参考电压和分辨率计算出对应的电压值存储在传入的指针指向的位置，如果读取失败则存储 0。adc_example(void* parameter)：初始化 ADC2 后，创建一个 ADC 任务，该任务每隔 1 秒读取一次 ADC 的值，通过读取的 ADC 原始值计算出系统的电压。
运行效果
程序编译下载完成，打开串口监控可以看到打印输出的 ADC 值和电压。ADC 采样值约为 1900，系统电压约为 4.9 V。
02_I2C_PCF85063
本示例通过 I2C 协议，分别对 PCF85063 芯片进行初始化、设置时间、间隔读取时间，然后打印到终端。
RTC 芯片引脚说明
| RTC | GPIO_PIN |
|---|---|
| RTC_SDA | GPIO47 |
| RTC_SCL | GPIO48 |
| RTC_INT | EXIO4 |
代码解释
void PCF85063_example(void* parameter)：创建一个 RTC 任务来实现 RTC 功能，每隔 10 秒读取一次 RTC 芯片的时钟，然后打印到终端。
运行效果
打开串口监控，可以看到打印输出的 RTC 时间。数据每隔 10 秒输出一次。
03_I2C_QMI8658
本示例通过 I2C 协议，对 QMI8658 芯片进行初始化设置，然后每隔 1 秒读取对应的姿态信息打印到终端。
IMU 姿态芯片引脚说明
| IMU | GPIO_PIN |
|---|---|
| IMU_SDA | GPIO47 |
| IMU_SCL | GPIO48 |
| IMU_INT1 | EXIO4 |
| IMU_INT2 | EXIO3 |
代码解释
qmi8658c_example(void* parameter)：该函数初始化 QMI8658 设备，在无限循环中读取并打印加速度计、陀螺仪数据和温度数据，每隔 1 秒执行一次。旋转板子的过程中陀螺仪数据随着旋转越快而越大，加速度计会根据当前的位置计算出对应的加速度。
运行效果
打开串口监控，可以看到打印输出的 IMU 发出来的原始数据（欧拉角需要自己转换）。数据每隔 1 秒输出一次。
04_SD_Card
本示例通过宏定义选择 SPI 或者 SDMMC 方向驱动 SD 卡，成功挂载 SD 卡之后把 SD 卡信息打印到终端。
SD 卡控制引脚说明
| SPI/MMC | GPIO_PIN |
|---|---|
| CS | GPIO2 |
| MISO/D0 | GPIO6 |
| MOSI/CMD | GPIO5 |
| SCLK/MCLK | GPIO4 |
代码解释
- 可以根据用户选择来实现 SD 卡的通信协议，在
sd_card_bsp.cpp源文件下找到宏定义SD_Read_Mode，宏定义默认使用 SDMMC 通信协议，可以修改为 SDSPI。
#define SD_Read_Mode USER_SPI
运行效果
点击串口监控设备，可以看到输出的 SD 卡的信息，practical_size 是 SD 卡的实际容量。
想了解更多关于 Arduino ESP32 库关于 SD 卡相关的使用？可访问：Arduino ESP32 库 SD 使用。
05_WIFI_STA
本示例把开发板作为一个终端角色，可以连接环境可用的 AP，成功连接之后打印获取到的 IP 信息到终端。
代码修改
该工程将芯片配置为 STA 模式并连接 Wi-Fi。在编译和下载固件前，需要将代码中的 Wi-Fi 名称和密码修改为当前网络的参数。
代码解释
wifi_init(void)：该函数用于初始化 ESP32 的 Wi-Fi 连接。它将 ESP32 设置为 Wi-Fi 站点模式，尝试连接到指定的 Wi-Fi 网络（通过ssid和password）。如果连接成功，打印本地 IP 地址；如果在一定时间内（20 × 500 毫秒）未能连接成功，则打印连接失败信息。同时，函数还可以设置自动连接和自动重连功能。
运行效果
芯片在 STA 模式下连接 Wi-Fi 后，可在串口监视器中查看获取到的 IP 地址。
06_WIFI_AP
本示例把开发板作为一个 AP 等待 STA 终端的连接。
代码解释
该代码在 ESP32 上初始化串口通信，然后创建名称为 bsp_esp_demo、密码为 waveshare 的 Wi-Fi 接入点。程序的循环中没有其他持续执行的操作。
const char* ssid = "bsp_esp_demo";
const char* password = "waveshare";
WiFi.softAP(ssid, password);
运行效果
使用手机或其他设备连接 Wi-Fi。默认名称为 bsp_esp_demo，密码为 waveshare。
07_EX_GPIO
本示例测试扩展 IO 和内部 GPIO 的基本功能。
硬件连接
需要使用两根线，把 EXIO5 和 EXIO6 连接在一起、GPIO2 和 GPIO1 连接在一起。
GPIO 短接说明
| GPIOx | GPIOy |
|---|---|
| GPIO1 | GPIO2 |
| EXIO5 | EXIO6 |
代码解释
I2C_master_Init()：初始化 I2C，I2C 是外部扩展 IO 的通信协议。esp32_gpio_init()：初始化 GPIO，把 GPIO1、EXIO5 设置为输出，GPIO2、EXIO6 设置为输入。loop()：包含测试 GPIO 功能的逻辑，可根据需要修改。
运行效果
串口监视器输出 GPIO test passed. 表示测试成功，输出 GPIO test failed. 表示失败。
08_Li_ION_Test
本示例通过对 GPIO 的控制，实现锂电池的供电。
代码解释
BAT_GPIO_Init()：使用 GPIO16 控制锂电池的供电，负责初始化 GPIO16。BAT_ON()：使能锂电池对系统的供电。BAT_OFF()：失能锂电池对系统的供电。
运行效果
在软件上使能锂电池供电之后，接入锂电池，然后可以通过 PWR 按键实现锂电池的供电。
09_LVGL_Test
本示例通过移植 LVGL，在屏幕上实现一些多功能的 GUI 界面。
Rotate_90
Rotate_NONO
代码分析
针对 LVGL，lvgl_conf.h 是其配置文件，下面对一些常用内容进行说明：
/*Color depth: 1 (1 byte per pixel), 8 (RGB332), 16 (RGB565), 32 (ARGB8888)*/
#define LV_COLOR_DEPTH 16 // 移植 LVGL 时必须关注的宏定义
#define LV_MEM_CUSTOM 0
#if LV_MEM_CUSTOM == 0
#define LV_MEM_SIZE (48U * 1024U) /*[bytes]*/
#define LV_MEM_ADR 0 /*0: unused*/
#if LV_MEM_ADR == 0
#undef LV_MEM_POOL_INCLUDE
#undef LV_MEM_POOL_ALLOC
#endif
#else /*LV_MEM_CUSTOM*/
#define LV_MEM_CUSTOM_INCLUDE <stdlib.h>
#define LV_MEM_CUSTOM_ALLOC malloc
#define LV_MEM_CUSTOM_FREE free
#define LV_MEM_CUSTOM_REALLOC realloc
#endif /*LV_MEM_CUSTOM*/
还有一些 LVGL 的 demo、文件系统都可以在 conf 配置文件里面设置。
代码修改
如果需要旋转 90 度显示，可以在 09_LVGL_Test.ino 文件找到 AMOLED_Rotate 宏定义，二者取其一：
#define AMOLED_Rotate Rotate_90 // 横屏
#define AMOLED_Rotate Rotate_NONO // 竖屏
运行效果
LVGL 示例占用的 RAM 和 ROM 较多，需要按照环境配置要求设置开发板。程序烧录完成后的运行效果如上图所示。
LVGL 更多学习及使用可参考 LVGL 官方文档。
Arduino_Playablity
我们还提供一些具有可玩性的程序，供大家参考。需要注意一点，下面的例程均基于 ESP32_Arduino 版本低于 V3.0，环境搭建可以参考下面。
Statement
Ammeter
使用流程
- 安装 ESP32-2.0.x：Arduino 板管理教程
- 下载示例程序：ESP32-S3-AMOLED-2.41-Arduino_Playablity
- 移植库文件：离线移植库文件
- 编译上传示例代码即可
参数设置
示例程序需修改参数。
