产品特性​

• 采用 ESP32-C5-WROOM-1 系列模组，搭载 RISC-V 32 位处理器，主频高达 240MHz
• 集成 384KB SRAM、320KB ROM、8MB PSRAM 和 32MB Flash，兼顾程序运行、图形界面和数据存储需求
• 集成 2.4GHz 与 5GHz 双频 Wi-Fi、Bluetooth 5 (LE) 以及 IEEE 802.15.4 （支持 Zigbee 3.0 和 Thread) 无线通信
• 板载电池充电管理模块，预留 3.7V MX1.25 锂电池接口，可外接电池进行供电
• 采用 Type-C 接口，支持正反插，便于供电、下载和调试
• 板载 2.8 英寸 LCD 屏，240 × 320 分辨率，262K 彩色
• 支持 I2C 接口控制电容触摸，支持中断
• 引出 UART、I2C 以及部分 IO 接口，集成全速 USB 串口
• 板载 QMI8658 六轴传感器、RTC 时钟传感器、SHTC3 温湿度传感器和 Micro SD 卡座等
• 支持灵活时钟，多种电源模式等准确控制，实现多场景低功耗模式
• 板载 ES8311 音频编解码芯片、NS4150B 功放芯片、麦克风和喇叭，可用于语音交互和音频播放应用
• 支持 ESP-IDF / Arduino 等开发环境，便于示例验证和二次开发

板载资源​

接口介绍​

产品尺寸​

本节提供出厂固件各功能示例的使用说明，用于了解 ESP32-C5-Touch-LCD-2.8 的板载资源和接口使用方式。运行示例前，请准备以下器件：

器件准备​

• ESP32-C5-Touch-LCD-2.8 ×1
• Micro SD 卡 ×1
• 喇叭 ×1
• 电池 ×1

Wi-Fi 设置​

• 使用前请先开启 Wi-Fi 热点。ESP32-C5 支持双频 Wi-Fi，可根据实际情况选择 2.4GHz 或 5GHz 频段。
• Wi-Fi 名称：weather-wifi
• Wi-Fi 密码：12345678
• 频段：2.4GHz / 5GHz 均可。请注意，部分手机可能不支持 5GHz 热点，若无法连接，建议切换为 2.4GHz 热点。
• 出厂固件中的 Wi-Fi 名称和密码为固定配置，开启的热点信息需与上述配置保持一致，否则设备将无法连接 Wi-Fi。

注意事项​

⚠️ USB 下载注意事项（重要）​

BAT_PWR 按键测试​

• 接入电池后，设备可由电池直接供电并点亮屏幕（由硬件电路控制，非软件控制）
• 长按 BAT_PWR 按键约 2 秒可关机；关机后再次按下 BAT_PWR 按键可重新开机。

固件下载​

• 出厂固件位于 示例程序包 的 Firmware 目录中。

示例介绍​

• 固件基于 brookesia 组件实现 APP 风格界面，包含设置、电子相册、音乐播放器、2048 小游戏、天气、画板、小智 AI、重力小球、Factory 等 APP。

APP 示例介绍​

设置 APP​

• 支持 Wi-Fi 扫描和配网功能，点击 Wi-Fi 界面的 wifi config 可扫描二维码进行配网操作。

• 可调节显示亮度，显示 SD 卡大小，并在产品关于界面查看 MAC 地址。

  
  

小智 AI APP​

• 点击 APP 即可进入小智 AI 应用，跟小智官网适配的版本一致，操作方式相同
• 长按 boot 按键可以回到 brookesia 界面

Sensor APP​

• 用于实时显示各传感器的数据。
• 旋转开发板时，陀螺仪数据会随姿态变化而改变；RTC 时钟会按秒递增。
• 用手覆盖温湿度传感器时，湿度数值会逐渐升高，温度数值通常变化较小或基本不变。
• 
  

画板 APP​

• 可以实现自由绘画

2048 APP​

• 支持实时显示当前分数，历史最佳分数，并可以一键重新开始

音乐播放器 APP​

• 支持播放 MP3 格式音频文件。
• 使用前，请先将喇叭连接到板载喇叭接口，然后点击播放按钮，即可播放存储在 Flash 中的 MP3 文件。
• 目前示例仅写了播放和暂停，不支持切换歌曲。

天气 APP​

• 设备联网后，等待数秒即可自动获取并解析深圳当日天气信息。
• 如需二次开发，请基于 ESP-IDF 示例 06_wifi_weather 进行修改。

Gravity Ball​

• 该示例展示了基于六轴姿态传感器的重力小球 App。小球会根据开发板的倾斜角度和姿态变化实时移动。
• 使用前，请先将开发板水平放置在桌面上，等待小球加载完成后再拿起使用。
• 单击 BOOT 按键可重置小球位置。

电子相册 APP​

• 支持 240x320 及其以下分辨率的 jpg 图片显示

• 模拟电子相册的界面，此 APP 需要插入 SD 卡，并将 示例程序 sdcard/ 目录下的 photo 文件夹拷贝到 SD 卡根目录。

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

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

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 开发板支持包​

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

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

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

3. 安装库和示例依赖​

本产品 Arduino 示例尽量减少外部库依赖，主要使用 Arduino ESP32 core 自带能力和示例目录内提供的源码。示例包已经在 example/Arduino-v3.3.10/lib 目录中预置了所需库，可手动复制安装，适合无法联网或不方便使用 Arduino Library Manager 的环境。

离线/手动安装方式：

1. 下载并解压产品示例程序包。后续库安装可以离线完成，不需要从 Arduino Library Manager 联网下载第三方库。

2. 找到示例包中的库目录：

   example/Arduino-v3.3.10/lib/lvgl
   example/Arduino-v3.3.10/lib/SensorLib
   

3. 将 lvgl 和 SensorLib 两个文件夹完整复制到 Arduino 的库目录。

   Windows 默认库目录通常是：

   C:\Users\<用户名>\Documents\Arduino\libraries
   

   也可以在 Arduino IDE 中通过 File > Preferences 查看 Sketchbook location，其下的 libraries 文件夹就是库目录。

4. 安装完成后重启 Arduino IDE，再打开示例进行编译。

安装检查方法：

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

4. Arduino 工程参数设置​

1. 打开 Arduino IDE。
2. 安装 esp32 by Espressif Systems v3.3.10。
3. 在 Tools > Board 中选择 ESP32C5 Dev Module。
4. 选择当前连接的 USB 串口。
5. 打开 example/Arduino-v3.3.10 下的对应示例 .ino 文件进行编译和烧录。

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

arduino-cli core install esp32:esp32@3.3.10
arduino-cli compile --fqbn esp32:esp32:esp32c5 example/Arduino-v3.3.10/06_lvgl_demo

示例程序​

Arduino 示例程序位于示例程序包的 example/Arduino-v3.3.10 目录。各示例已经按照 ESP32-C5-Touch-LCD-2.8 的实际硬件连接进行适配。

1. 板载资源​

2. 示例列表​

3. 目录结构​

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

example/Arduino-v3.3.10
|-- 01_exio
|-- 02_I2C_qmi8658
|-- 03_SD_Card
|-- 04_I2C_pcf85063
|-- 05_shtc3
|-- 06_lvgl_demo
`-- lib
    |-- SensorLib
    `-- lvgl

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

example/Arduino-v3.3.10/01_exio/01_exio.ino

lib/SensorLib 是 04_I2C_pcf85063 使用的 RTC 驱动库，当前随包版本为 SensorLib v0.3.1；lib/lvgl 是 06_lvgl_demo 使用的 LVGL v8.4.0 库文件。编译 04_I2C_pcf85063 前至少需要复制 SensorLib，编译 06_lvgl_demo 前至少需要复制 lvgl。

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

建议按以下顺序运行：

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

• 先用 01_exio 验证 CH32V003 IO 扩展和 I2C 总线。LCD 复位、触摸复位和背光都与 CH32V003 有关，建议先确认该示例正常。
• 再用 02_I2C_qmi8658 验证六轴传感器数据读取。
• 然后用 03_SD_Card 验证 Micro SD 卡和 SDSPI。
• 接着用 04_I2C_pcf85063 验证 RTC 时间设置和读取。
• 再用 05_shtc3 验证 SHTC3 温湿度读取和 CRC 校验。
• 最后运行 06_lvgl_demo，一次性验证 LCD、背光、触摸和 LVGL。

5. 使用说明​

• Arduino 示例目录为 example/Arduino-v3.3.10，请不要与 ESP-IDF 示例目录混用。
• 本产品共用一组 I2C：SDA GPIO0、SCL GPIO1，CH32V003、QMI8658、PCF85063、SHTC3 和 CST3530 都在该 I2C 总线上。
• 03_SD_Card 运行前需要插入 FAT 或 FAT32 格式的 Micro SD 卡。
• 04_I2C_pcf85063 默认每次上电都会写入固定测试时间，若需要 RTC 持续计时，请注释 i2c_rtc_setTime()。
• 06_lvgl_demo 已经适配 ST7789 显示和 CST3530 触摸，不需要额外引入 GFX 显示库或第三方触摸库。
• 如果从其他工程复制代码，请重点确认 LCD 和触摸复位脚：LCD_RST = CH32 EXIO1，TP_RST = CH32 EXIO0。
• 编译、屏幕点亮、触摸响应、I2C 地址等排查内容请参考 产品 FAQ。

6. 示例说明​

01_exio​

【功能说明】

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

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

【代码入口】

01_exio/01_exio.ino
01_exio/io_extension.cpp
01_exio/io_extension.h

建议优先查看：

【正常运行现象】

• 串口日志参考如下：

【常见排查】

02_I2C_qmi8658​

【功能说明】

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

【代码入口】

02_I2C_qmi8658/02_I2C_qmi8658.ino
02_I2C_qmi8658/i2c_bsp.cpp
02_I2C_qmi8658/qmi8658c.cpp

建议优先查看：

【正常运行现象】

• 串口会先输出 QMI8658 初始化信息，随后每秒输出一次传感器数据。
• 轻微倾斜或转动开发板时，加速度和陀螺仪数据会随姿态变化，日志参考如下：

【常见排查】

03_SD_Card​

【功能说明】

该示例用于验证 Micro SD 卡接口。示例默认使用 SDSPI 模式挂载 SD 卡，挂载路径为 /sd_card，成功后会打印 SD 卡信息和容量。

【代码入口】

03_SD_Card/03_SD_Card.ino
03_SD_Card/sd_card_bsp.cpp
03_SD_Card/sd_card_bsp.h

建议优先查看：

【正常运行现象】

• 插入 FAT32 格式的 Micro SD 卡后，串口会打印 SD 卡类型、容量等信息，日志参考如下：

【常见排查】

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 时间，日志参考如下：

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

【常见排查】

05_shtc3​

【功能说明】

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

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

【代码入口】

05_shtc3/05_shtc3.ino

建议优先查看：

【正常运行现象】

• 串口先输出 SHTC3 ID，随后周期输出温湿度，日志参考如下：

【常见排查】

06_lvgl_demo​

【功能说明】

该示例用于验证 LCD 显示、背光、触摸和 LVGL 基础界面。示例不依赖 GFX 显示库；LCD 驱动参考 ST7789 示例拆分到 Display_ST7789，触摸驱动参考 CST3530 示例拆分到 Touch_CST3530，CH32V003 IO 扩展、LCD 复位、触摸复位和背光控制统一放在 Board_IO 中。

界面会显示开发板名称、显示状态、触摸状态、触摸坐标和背光亮度。

【代码入口】

06_lvgl_demo/06_lvgl_demo.ino
06_lvgl_demo/Board_IO.cpp
06_lvgl_demo/Board_IO.h
06_lvgl_demo/Display_ST7789.cpp
06_lvgl_demo/Display_ST7789.h
06_lvgl_demo/Touch_CST3530.cpp
06_lvgl_demo/Touch_CST3530.h
06_lvgl_demo/lv_conf.h

建议优先查看：

【正常运行现象】

LCD 显示 ESP32-C5 Touch LCD 2.8 示例界面。触摸屏幕时，界面会更新触摸坐标；拖动底部进度条可以调节屏幕背光亮度；串口会输出：

ESP32-C5-Touch-LCD-2.8 Arduino LVGL demo
Touch controller CST3530 initialized
LVGL demo started

如果触摸未识别，界面会显示 Touch: not found。

【常见排查】

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

• ESP-IDF 入门教程
• 配置 ESP-IDF 开发环境
• 示例程序

ESP-IDF 入门教程​

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

• 第0节 认识 ESP32
• 第1节 搭建环境
• 第2节 运行实例
• 第3节 创建项目
• 第4节 使用组件
• 第5节 调试程序
• 第6节 FreeRTOS
• 第7节 驱动外设
• 第8节 Wi-Fi 编程
• 第9节 BLE 编程

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

配置 ESP-IDF 开发环境​

请参考 安装 ESP-IDF 开发环境。

安装 ESP-IDF 开发环境​

1. 前往 ESP-IDF Installation Manager 下载 ESP-IDF 安装管理器。这是乐鑫最新推出的跨平台安装工具，下文将演示如何使用其离线安装功能。

   在页面中点击 Offline Installer 标签，然后在筛选栏中选择 Windows 操作系统和你需要的 ESP-IDF 版本（图示仅为参考，请以实际为准）。

   
   

   确认选择无误后，点击下载按钮。浏览器将自动同时下载两个文件：一个是 ESP-IDF 离线整合包(.zst)，另一个是 ESP-IDF 安装器(.exe)。

   
   

   请耐心等待两个文件下载完成。

2. 下载完成后，双击运行 ESP-IDF 安装器(eim-gui-windows-x64.exe)。

   启动后，可在右上角将界面语言切换为中文。

   
   

   安装工具会自动检测同一目录下是否存在离线整合包。点击 从存档安装。

   
   

   接下来，选择安装路径。建议使用默认路径；若需自定义，请确保路径中不包含中文或空格。确认无误后，点击 开始安装。

   
   

3. 当看到如下界面时，表示 ESP-IDF 已安装成功。

   
   

4. 建议同时安装驱动程序。点击 完成安装，然后点击 安装驱动程序。

   
   

安装 Visual Studio Code 与 ESP-IDF 扩展​

1. 下载并安装 Visual Studio Code。

2. 安装时建议勾选 通过 Code 打开操作添加到 Windows 资源管理器文件上下文菜单,以便快速打开项目文件夹。

3. 在 VS Code 中,点击侧边活动栏中的  扩展图标(或使用快捷键 Ctrl + Shift + X)打开 扩展 视图。

4. 在搜索框中输入 ESP-IDF,找到 ESP-IDF 扩展并点击安装。

   
   

5. 当 ESP-IDF 扩展版本 ≥ 2.0 时,扩展会自动检测并识别上述步骤中安装的 ESP-IDF 环境,无需手动配置。

示例程序​

ESP-IDF 示例程序位于示例程序包的 example/ESP-IDF-V554 目录。各示例工程已经按照 ESP32-C5-Touch-LCD-2.8 的板载硬件资源进行适配，可用于验证显示、触摸、音频、SD 卡、Wi-Fi、传感器和图形界面等功能。

编译和烧录​

进入任意 ESP-IDF 示例目录后执行：

cd example/ESP-IDF-V554/02_2048
idf.py build flash monitor

如果需要指定串口，请将 COMx 替换为实际串口号，例如 COM5：

idf.py -p COMx build flash monitor

示例列表​

使用说明​

• 二次开发时，建议优先修改应用层或 UI 逻辑。BSP 已完成开发板基础硬件资源和底层接口的定义与初始化，常规界面、交互和业务功能修改通常不需要改动 BSP；仅在更换硬件连接、调整底层驱动或适配新外设时，再修改 BSP 相关代码。
• 01_ch32_test 用于测试板载 CH32V003 IO 扩展芯片。CH32V003 出厂时已经烧录好固件，无需单独烧录 CH32 固件，运行 ESP32-C5 示例即可验证 IO 扩展通信和控制功能。
• 02_2048 的 UI 基于 GUI Guider 生成，界面布局主要位于 components/generated/setup_scr_Game2048.c，事件函数主要位于 components/generated/events_init.c，自定义初始化和扩展逻辑位于 components/custom/custom.c。
• 03_sd_lvgl 运行前，请在 SD 卡根目录放置 Test.txt 文件。
• 04_sd_music 运行前，请在 SD 卡根目录创建 music 文件夹，并放入 .mp3 文件。
• 05_spiff_music 使用 SPIFFS 中的 MP3 文件，适合配合 LVGL 界面实现音乐播放器效果。
• 06_wifi_weather 默认连接 weather-wifi 热点，密码为 12345678，热点支持 2.4GHz 或 5GHz 频段；如需修改热点或城市，请在示例源码中调整对应配置。
• 07_Ball_qmi 校准时需要保持开发板水平静止，否则小球可能出现明显偏移。
• 08_bookesia 使用 ESP-Brookesia 框架，适合作为触摸 GUI、多应用界面和画板功能的二次开发参考。

01_ch32_test​

程序说明​

• 本示例用于验证板载 CH32V003 IO 扩展芯片。
• 程序会初始化 I2C 总线和 CH32V003 IO 扩展设备，然后依次测试 IO 输出和输入读取功能。
• 示例先将 IO_EXP_PIN_0 到 IO_EXP_PIN_7 配置为输出模式，并循环输出高低电平；随后切换为输入模式并读取输入状态。

硬件连接​

• 将开发板通过 USB 连接到电脑即可。
• 示例仅使用板载 CH32V003 IO 扩展芯片，无需外接模块。

运行效果​

• 串口会打印 I2C 初始化、IO 扩展初始化、输出电平切换和输入电平读取结果。
• 若 IO 扩展通信正常，可看到 IO_EXP_PIN_0~7 配置、输出和读取成功的日志。

02_2048​

程序说明​

• 本示例基于 LVGL v9 实现 2048 小游戏。
• UI 界面基于 GUI Guider 生成，工程中的 main.c 会依次调用 setup_ui()、custom_init() 和 events_init() 完成界面创建、自定义初始化和事件绑定。
• 屏幕显示 4 x 4 数字方块、当前分数、历史最高分以及重新开始按钮。
• 支持通过触摸滑动控制方块移动，程序会自动合并相同数字并更新分数。
• 当合成 2048 时显示胜利提示；无可移动方块时显示游戏结束提示。
• 二次开发时，可参考 components/generated/setup_scr_Game2048.c 查看 2048 页面控件布局，参考 components/generated/events_init.c 查看触摸和按钮事件逻辑，参考 components/custom/custom.c 查看自定义初始化和业务扩展逻辑。

硬件连接​

• 将开发板通过 USB 连接到电脑即可。
• 示例使用板载 LCD 和电容触摸屏，无需外接模块。

运行效果​

• LCD 显示 2048 游戏界面。
• 可在触摸屏上滑动操作，实时查看分数变化和游戏结果。

03_sd_lvgl​

程序说明​

• 本示例用于演示 SD 卡文件读取和 LVGL 屏幕显示。
• 程序启动后会初始化 LCD 和 LVGL 页面，然后挂载 Micro SD 卡。
• 示例会读取 SD 卡根目录下的 Test.txt 文件，并将文件内容显示在 LCD 中央。
• 若未检测到 SD 卡或文件读取失败，屏幕会显示对应错误提示。

硬件连接​

• 将开发板通过 USB 连接到电脑。
• 将 FAT32 格式的 Micro SD 卡插入卡槽。
• 在 SD 卡根目录放置 Test.txt 文件。

运行效果​

• LCD 先显示 Waiting for SD card...。
• 成功读取后，屏幕显示 Test.txt 中的文本内容。
• 如果没有检测到 SD 卡，则显示 SD card not detected!。

04_sd_music​

程序说明​

• 本示例用于验证 SD 卡 MP3 音频播放功能。
• 程序会初始化板载 IO 扩展、挂载 SD 卡，并扫描 /sdcard/music 目录下的 .mp3 文件。
• 扫描到音乐文件后，示例会初始化音频驱动和功放，并自动播放第一首 MP3。
• 该示例主要用于验证 SD 卡读取、音频 Codec、功放和喇叭播放链路。

硬件连接​

• 将开发板通过 USB 连接到电脑。
• 将 FAT32 格式的 Micro SD 卡插入卡槽。
• 在 SD 卡根目录创建 music 文件夹，并放入 .mp3 音频文件。
• 将喇叭连接到板载 Speaker 接口。

运行效果​

• 串口打印扫描到的 MP3 文件列表。
• 程序自动播放扫描到的第一首 MP3 音乐。
• 若 SD 卡挂载失败或未找到 MP3 文件，串口会输出错误提示。

05_spiff_music​

程序说明​

• 本示例基于 SPIFFS 和 LVGL v9 实现音乐播放器界面。
• 程序会挂载 SPIFFS 文件系统，并扫描 /spiffs/music 目录下的 .mp3 文件。
• 屏幕显示音乐封面和播放控制按钮。
• 点击播放按钮后，程序播放第一首 MP3，同时音乐封面持续旋转。
• 再次点击按钮可暂停播放，封面旋转会停止；继续播放时会从暂停角度恢复旋转。
• 播放完成后，程序会自动停止动画并恢复播放按钮状态。

硬件连接​

• 将开发板通过 USB 连接到电脑。
• 将喇叭连接到板载 Speaker 接口。
• 需要提前将 MP3 文件打包到 SPIFFS 的 music 目录中。

运行效果​

• LCD 显示音乐播放器界面。
• 点击播放按钮后开始播放音乐，并显示旋转的音乐封面动画。
• 支持播放、暂停和播放结束状态恢复。

06_wifi_weather​

程序说明​

• 本示例用于演示 Wi-Fi 联网和天气数据显示。
• 程序会连接固定 Wi-Fi 热点，并通过 HTTP 请求获取深圳实时天气数据。
• 屏幕显示城市、日期、天气状态、温度、湿度、风速和风向等信息。
• 程序支持 Wi-Fi 断线自动重连。
• 天气数据会定时刷新，成功获取后约每 5 分钟更新一次。

默认 Wi-Fi 配置​

硬件连接​

• 上电前请先开启与示例一致的 Wi-Fi 热点。
• 将开发板通过 USB 连接到电脑并上电。
• 热点可使用 2.4GHz 或 5GHz 频段，但热点名称和密码需要与示例配置保持一致，并确保热点可以正常访问互联网。
• 示例使用板载 LCD 和 Wi-Fi 功能，无需外接模块。

运行效果​

• 连接 Wi-Fi 后，屏幕会显示深圳天气信息。
• 若热点未开启或网络异常，程序会持续重试连接和请求。

07_Ball_qmi​

程序说明​

• 本示例用于演示 QMI8658 加速度传感器和 LVGL 图形交互。
• 程序会初始化 QMI8658，并配置加速度量程为 8G、输出数据率为 500Hz。
• 启动后会进行水平校准，用于消除静止状态下的偏移。
• 校准完成后，屏幕中央生成一个小球，小球会根据开发板倾斜方向实时移动。
• 程序会限制小球移动范围，避免超出屏幕边界和圆角区域。

硬件连接​

• 将开发板通过 USB 连接到电脑。
• 示例使用板载 LCD 和 QMI8658 六轴传感器，无需外接模块。
• 校准时请将开发板水平放置在稳定桌面上。

运行效果​

• 屏幕显示一个绿色小球。
• 倾斜开发板时，小球会随重力方向移动。
• 串口会打印校准状态和传感器相关日志。

08_bookesia​

程序说明​

• 本示例基于 ESP-Brookesia 框架实现类似手机系统的图形界面。
• 程序使用 240 x 320 深色主题，支持状态栏、应用管理和触摸交互。
• 示例会安装系统默认应用，并额外安装 Drawing Board 画板应用。
• 画板应用支持通过电容触摸屏进行自由绘图和涂鸦。
• 状态栏时钟会每秒刷新。
• 最近任务界面会周期性显示 SRAM 和 PSRAM 使用情况。

硬件连接​

• 将开发板通过 USB 连接到电脑。
• 示例使用板载 LCD 和电容触摸屏，无需外接模块。

运行效果​

• LCD 显示 ESP-Brookesia 风格的界面。
• 可通过触摸进入画板应用并进行绘图。
• 系统界面支持状态栏、最近任务和内存信息显示。

XiaozhiAI（小智 AI）是一个基于 ESP32 开发板的开源 AI 语音聊天机器人项目，旨在将大语言模型（LLM）的通用智能赋予边缘设备。它提供了一套软硬件结合的解决方案，支持全双工语音对话及 IoT 设备控制，致力于协助开发者低成本、快速地构建高定制度的实体 AI 智能体。

本文演示如何为微雪电子支持小智 AI 的 ESP32 开发板烧录固件，包括无开发环境烧录（直接烧录预编译固件）和有开发环境烧录（从源码编译并烧录）两种方式。

0. 烧录固件流程参考​

1. 无开发环境烧录​

1.1 通过小智官方 GitHub 下载固件​

1. 访问 小智 GitHub 下载对应设备的固件文件，点击 Assets 展开全部文件列表：

   
   

2. 参考 Flash 固件的烧录与擦除教程 完成固件烧录。

1.2 通过微雪电子 GitHub 下载固件​

1. 访问 微雪 GitHub 仓库，根据需求选择合适版本的固件进行下载：

   
   

2. 参考 Flash 固件的烧录与擦除教程 完成固件烧录。

2. ESP-IDF 环境烧录​

2.1 通过小智 GitHub 下载工程​

访问 XiaoZhi AI Chatbot 仓库下载完整工程代码：

2.2 环境搭建​

参考 ESP-IDF 环境搭建教程 完成开发环境的配置。

2.3 配置编译​

1. 点击  选择目标设备，根据您的开发板选择对应的芯片型号（如 esp32s3）：

   
   

   提示

   设置目标设备时，ESP-IDF 会自动配置相应的工具链和库，此过程可能需要一些时间，请耐心等待。更多详情请参阅 官方文档。

2. 点击  打开 ESP-IDF 终端，执行 idf.py menuconfig 命令进入配置界面，选择 Xiaozhi Assistant:

   
   

3. 选择 Board Type 进入开发板类型选择：

   
   

4. 选择与您的开发板对应的产品型号：

   
   

5. 按 S 键保存配置并退出，然后点击  一键构建、烧录和监视图标，自动完成编译、烧录和串口监视。

2.4 开始配网​

1. 使用手机或电脑连接设备的 WiFi 热点：Xiaozhi-xxxxxx。连接成功后通常会自动跳转到配置页面，若未自动跳转，请手动在浏览器中访问 http://192.168.4.1。

2. 在网络配置页面选择要连接的 WiFi 名称（仅支持 2.4G 频段；若要连接 iPhone 热点，需在手机系统设置中开启最大兼容性），SSID 将自动填入，输入密码后点击 Connect 开始连接：

   
   

2.5 添加新设备到管理后台​

1. 确保设备已成功连接到互联网，此时设备会播报 6 位设备验证码（可重复唤醒设备再次播报）。

2. 访问 小智 AI 控制面板，如未注册请先完成账号注册并登录：

   
   

   
   

   
   

3. 输入 6 位验证码后，设备将自动激活并显示在设备管理页面，即可正常使用。

4. 说出唤醒词 "你好，小智" 即可唤醒设备，开始语音对话。

5. ESP32-S3-Touch-AMOLED-1.8 按键说明：

   • BOOT 按键：按下可唤醒小智
   • PWR 按键：短按开机，长按 6 秒以上关机

   
   

3. 小智资料​

• 小智 AI 聊天机器人百科全书
• 小智 AI 聊天机器人常见问题及解答

1. 硬件资料​

开发板设计文件

• 原理图
• 结构图

2. 技术手册​

• ESP32-C5 芯片官方手册

  • 技术规格书：中文版 | 英文版
  • 技术参考手册：中文版 | 英文版

• 板载器件数据手册

  • ES8311 数据手册
  • ES8311 用户手册
  • ST7789V2 数据手册
  • QMI8658 数据手册

3. 示例程序​

• ESP32-C5-Touch-LCD-2.8 示例程序（Github 仓库）

4. 软件工具​

• Arduino:
  • Arduino IDE 官方下载链接
• VScode:
  • VScode 官方下载链接
• 调试工具：
  • 串口调试助手
• 固件烧录工具：
  • Flash_download_tool
• 其他资料链接：
  • ESP32-Arduino 官方文档
  • ESP32-Arduino 官方资料
  • ESP-IDF 官方资料
  • MicroPython 官方文档

技术支持

周一-周五（9:30-6:30）周六（9:30-5:30）

手机：13434470212

邮箱：services04@spotpear.cn

QQ：202004841