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。
2. 安装 ESP32 开发板
- ESP32 相关开发板需要先安装 "esp32 by Espressif Systems" 开发板支持包。
- 安装方式可参考 Arduino 板管理教程。
- 对于 ESP32-C5-LCD-1.47，请选择包含 ESP32-C5 支持的开发板支持包版本。
3. 安装库
示例程序需要以下 Arduino 库。若使用 Arduino IDE 手动安装库，请参考 Arduino 库管理教程。
| 库名称 | 说明 |
|---|---|
| GFX Library for Arduino | LCD 图形驱动库，对应示例中的 GFX_Library_for_Arduino |
| lvgl 9.5.0 | 图形库，用于 LVGL 相关示例 |
版本兼容性说明
LVGL 与示例代码存在版本依赖。请使用 lvgl 9.5.0，避免因库版本差异导致编译失败或显示异常。
示例程序
-
示例程序位于资料包的
examples/arduino目录。烧录前请确认开发板型号、USB 端口和分区方案配置正确。 -
资料包根目录已包含
libraries文件夹。使用 Arduino IDE 编译示例前，请打开 "File" > "Preferences"，将 "Sketchbook location"（项目文件夹位置）设置为资料包根目录esp32-c5-lcd-1.47，即包含libraries和examples的目录。设置完成后，重新启动 Arduino IDE，再打开示例进行编译和烧录。
板载资源
| 功能 | 资源 | GPIO 或说明 |
|---|---|---|
| LCD | ST7789，SPI，172 × 320，RGB565 | SCLK GPIO7，MOSI GPIO6，CS GPIO23，DC GPIO24，RST GPIO26 |
| LCD 背光 | LEDC PWM | GPIO10 |
| Micro SD | SDSPI | SCLK GPIO7，MOSI GPIO6，MISO GPIO5，CS GPIO4 |
| RGB LED | WS2812B，1 颗 LED | GPIO8，RGB 顺序 |
| SPIFFS | 内部 Flash 文件系统 | 选择包含 SPIFFS 的分区方案 |
| Wi-Fi | ESP32-C5 内置无线功能 | 无需额外 GPIO |
Arduino 工程参数设置
- 打开 Arduino IDE。
- 在 "Tools" > "Board" 中选择 ESP32-C5 对应开发板。
- 选择当前连接的 USB 端口。
- 如需查看串口输出，请根据示例说明开启 USB CDC 或使用对应串口配置。
- 编译
06_spiffs_rw和08_board_showcase前，请选择包含 SPIFFS 的分区方案。
使用 arduino-cli 编译时，可参考以下命令：
arduino-cli lib install "GFX Library for Arduino"
arduino-cli lib install "lvgl@9.5.0"
arduino-cli compile --fqbn esp32:esp32:esp32c5 arduino/02_lvgl_hello
示例列表
| 示例目录 | 功能 |
|---|---|
01_lcd_panel_basic | 使用 GFX_Library_for_Arduino 初始化 LCD，并绘制色块。 |
02_lvgl_hello | 启动 LVGL 9.5.0，在 LCD 上显示基础界面。 |
03_backlight_fade | 使用 LEDC 调节 LCD 背光，并通过 LVGL 显示亮度值。 |
04_ws2812_rgb | 使用 rgbLedWrite() 控制板载 WS2812B RGB LED 循环显示不同颜色。 |
05_sdcard_rw | 显示 Micro SD 状态页面，并执行文件写入和读回检查。 |
06_spiffs_rw | 挂载 SPIFFS，在内部 Flash 中执行文件写入和读回检查。 |
07_wifi_scan | 扫描附近 Wi-Fi 热点，并通过串口输出信号较强的扫描结果。 |
08_board_showcase | 综合演示 LCD、WS2812B、SPIFFS、SD 卡和 Wi-Fi 状态。 |
01_lcd_panel_basic
程序说明
- 本示例使用
GFX_Library_for_Arduino初始化 ST7789 LCD，不启动 LVGL。 - LCD 先显示多色条纹背景，再显示一个上下移动的色块，用于检查屏幕显示和局部刷新。
硬件连接
- 将开发板接入电脑。
- 该示例仅使用板载 LCD 和背光，无需外接模块。
代码分析
setup()：初始化串口、LCD 背光和 LCD 驱动，并调用draw_color_bars()绘制背景。init_backlight()：配置 GPIO10 的 LEDC PWM 背光输出。draw_color_bars()：按屏幕宽度绘制多组颜色条。loop()：周期调用draw_motion_frame()，刷新移动色块所在区域。
运行效果
- LCD 显示多色条纹背景，屏幕上有一个色块持续上下移动。
02_lvgl_hello
程序说明
- 本示例启动 LVGL 9.5.0，并通过
GFX_Library_for_Arduino将 LVGL 画面输出到 LCD。 - LCD 页面显示开发板名称、LCD 分辨率、SPI 引脚信息和状态条。
硬件连接
- 将开发板接入电脑。
- 该示例仅使用板载 LCD 和背光，无需外接模块。
代码分析
setup()：复位 LCD，初始化显示驱动、LVGL 和示例界面。reset_lcd_panel()：按 LCD 复位时序控制 CS、DC 和 RST 引脚。init_display()：初始化 ST7789，并设置屏幕方向和背光。init_lvgl()：创建 LVGL 显示对象，配置刷新回调和显示缓冲区。create_ui()：创建标题、设备信息和状态条等界面元素。loop()：调用lvgl_loop_once()处理 LVGL 定时任务。
运行效果
- LCD 显示 LVGL 示例界面，可看到开发板名称、LCD 参数和 SPI 引脚信息。
03_backlight_fade
程序说明
- 本示例使用 LEDC PWM 调节 LCD 背光亮度。
- LVGL 页面同步显示当前亮度百分比和进度条。
硬件连接
- 将开发板接入电脑。
- 该示例仅使用板载 LCD 和背光，无需外接模块。
代码分析
setup()：初始化 LCD、LVGL 和背光演示界面。init_display()：启动 LCD 并设置初始背光。init_lvgl()：配置 LVGL 显示缓冲区和刷新回调。create_ui()：创建亮度数值标签和进度条。loop()：周期调用set_backlight()和update_ui()，让背光亮度按百分比变化。lvgl_loop_once()：推进 LVGL tick 并处理界面刷新。
运行效果
- LCD 背光亮度循环变化，屏幕上的百分比和进度条同步更新。
04_ws2812_rgb
程序说明
- 本示例使用 ESP32 Arduino core 的
rgbLedWrite()控制板载 WS2812B RGB LED。 - LED 会按红、绿、蓝等颜色循环显示。
硬件连接
- 将开发板接入电脑。
- 该示例仅使用板载 RGB LED，无需外接模块。
代码分析
setup()：初始化串口，并输出示例名称。set_led()：封装 RGB LED 颜色设置。板载 LED 调用时使用red, green, blue的参数顺序。loop()：按固定间隔调用set_led()，让 RGB LED 循环显示不同颜色。
运行效果
- 板载 WS2812B RGB LED 按顺序切换颜色。
05_sdcard_rw
程序说明
- 本示例通过 SDSPI 挂载 Micro SD 卡，并执行文件写入和读回检查。
- LCD 页面显示 SD 卡挂载、写入、读取和结果状态。
硬件连接
- 将开发板接入电脑。
- 将 FAT 或 FAT32 格式的 Micro SD 卡装入开发板。
代码分析
setup()：初始化 LCD、LVGL、SD 卡引脚和状态界面，然后执行 SD 卡读写检查。init_sd_pins()：配置 SD 卡相关引脚状态。mount_sd_card()：按 SDSPI 方式挂载 Micro SD 卡，并读取卡类型和容量。write_file()：向 SD 卡写入测试文件。read_file()：读回测试文件内容，并检查数据是否一致。set_item()和set_summary()：更新 LCD 上的步骤状态和最终结果。loop()：调用lvgl_loop_once()保持界面刷新。
运行效果
- LCD 显示 SD 卡容量、文件写入和读回结果；串口同步输出检测信息。
06_spiffs_rw
程序说明
- 本示例挂载内部 Flash 中的 SPIFFS 文件系统。
- 程序会写入
/hello.txt，再读回文件内容并通过串口输出结果。
硬件连接
- 将开发板接入电脑。
- 编译和烧录前，请选择包含 SPIFFS 的分区方案。
代码分析
setup()：初始化串口，调用SPIFFS.begin(true)挂载 SPIFFS，并输出总容量和已用容量。write_read_check()：删除旧测试文件，写入新内容，读回后检查字符串是否一致。loop()：该示例无循环任务。
运行效果
- 串口输出 SPIFFS 容量信息、读回内容和示例完成状态。
07_wifi_scan
程序说明
- 本示例使用 ESP32-C5 内置 Wi-Fi 扫描附近热点。
- 串口输出扫描到的 SSID、RSSI 和信道信息。
硬件连接
- 将开发板接入电脑。
- 确认周围存在可扫描到的 2.4 GHz 或 5 GHz Wi-Fi 热点。
代码分析
setup()：初始化串口，将 Wi-Fi 设置为 STA 模式，并断开已有连接。loop()：调用WiFi.scanNetworks()扫描热点，并输出热点数量、SSID、RSSI 和信道。WiFi.scanDelete()：释放本次扫描结果占用的资源。
运行效果
- 串口每隔约 5 秒输出一次 Wi-Fi 扫描结果。
08_board_showcase
程序说明
- 本示例综合检测 LCD、背光、WS2812B RGB LED、SPIFFS、microSD 卡和 Wi-Fi 扫描。
- LCD 页面显示各功能项的
RUN、PASS、WARN或FAIL状态。
硬件连接
- 将开发板接入电脑。
- 如需检测 SD 卡，请将 FAT 或 FAT32 格式的 Micro SD 卡装入开发板。
- 编译和烧录前，请选择包含 SPIFFS 的分区方案。
代码分析
setup()：初始化 LCD、LVGL、状态界面和综合检测流程。create_ui()：创建板载资源状态面板。run_showcase()：依次检查 LCD、RGB LED、SPIFFS、SD 卡和 Wi-Fi。file_rw_check()：对 SPIFFS 或 SD 卡执行文件写入和读回检查。mount_sd_card()：挂载 SD 卡，并读取容量信息。set_item()：更新各功能项状态和说明文本。loop()：调用lvgl_loop_once()保持界面刷新。
运行效果
- LCD 显示各功能检测结果；检测完成后，页面底部显示最终状态。若未插入 SD 卡或未扫描到 Wi-Fi，相关项目会显示告警。
使用说明
05_sdcard_rw运行前，请插入 FAT 或 FAT32 格式的 Micro SD 卡。06_spiffs_rw和08_board_showcase需要包含 SPIFFS 的分区方案。- LCD 和 Micro SD 共用 SPI 时钟与 MOSI 引脚，示例中已按板载连接配置。
- 板载 RGB LED 示例按
red, green, blue顺序传入颜色参数。