当前位置：首页 > news >正文

ESP32使用笔记(基于IDF):小智AI项目ESP32二次开发指南

news 2025/10/26 11:28:17

一、项目概述

小智AI是一个基于ESP32系列芯片开发的开源AI语音聊天机器人项目。它支持多种ESP32开发板，具有语音交互、显示界面、OTA升级等功能，可通过MQTT或WebSocket协议与后端服务器通信。本指南将详细介绍如何对该项目进行二次开发，包括环境配置、开发板选择、服务器地址配置以及功能扩展等内容。

在这里插入图片描述

文档地址：https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb

二、开发环境准备

1. 基础环境配置

要进行小智AI项目的二次开发，首先需要配置ESP-IDF开发环境：

# 安装ESP-IDF（可以使用官方安装器或命令行）
# 官方安装器下载地址：https://dl.espressif.cn/dl/esp-idf/

环境配置可参见另一篇博文介绍：ESP32使用日记(基于IDF):环境搭建及第一个HelloWorld

开发板资源链接：https://pan.baidu.com/s/1GrSZ9711QsAc0bDmn59BQg?pwd=ffku#list/path=%2F

2. 项目克隆与依赖安装

# 克隆小智AI项目
git clone https://github.com/your-repo/xiaozhi-esp32.git
cd xiaozhi-esp32# 安装项目依赖
idf.py reconfigure

项目依赖管理通过idf_component.yml文件实现，主要依赖包括：

espressif/esp-sr: 语音识别相关组件
espressif/esp-adf: 音频开发框架
lvgl/lvgl: 图形界面库，版本9.2.2

三、项目结构与组件分析

小智AI项目采用模块化设计，主要目录结构如下：

├── main/              # 主源码目录
│   ├── application.cc # 应用程序入口
│   ├── boards/        # 开发板配置和初始化
│   ├── audio_codecs/  # 音频编解码器支持
│   ├── audio_processing/ # 音频处理功能
│   ├── display/       # 显示界面实现
│   ├── protocols/     # 通信协议实现
│   └── assets/        # 资源文件（语言、图像等）
├── docs/              # 文档目录
├── scripts/           # 辅助脚本
└── CMakeLists.txt     # CMake构建配置

核心模块介绍

开发板抽象层：位于main/boards/目录，提供统一的硬件接口
音频处理：包括音频采集、编码解码、唤醒词检测等功能
显示系统：支持LCD和OLED等不同显示设备
通信协议：支持MQTT和WebSocket两种通信方式
OTA升级：通过配置的URL检查和下载新固件

四、开发板配置与选择

1. 内置开发板支持

小智AI项目支持50多种ESP32系列开发板，包括常见的ESP32、ESP32-S3、ESP32-C3等芯片平台。开发板配置通过menuconfig进行选择：

# 设置目标芯片（以ESP32-S3为例）
idf.py set-target esp32s3# 打开配置菜单
idf.py menuconfig

在菜单中导航至：Xiaozhi Assistant -> Board Type，然后选择您使用的开发板类型。

2. 自定义开发板配置

如果您需要使用未在列表中的开发板，可以按照以下步骤进行自定义：

2.1 创建开发板目录

# 在boards目录下创建新的开发板文件夹
mkdir main/boards/my-custom-board

2.2 编写配置文件

config.h：定义硬件引脚映射

#ifndef _BOARD_CONFIG_H_
#define _BOARD_CONFIG_H_#include <driver/gpio.h>// 音频配置
#define AUDIO_INPUT_SAMPLE_RATE  24000
#define AUDIO_OUTPUT_SAMPLE_RATE 24000// I2S引脚配置
#define AUDIO_I2S_GPIO_MCLK GPIO_NUM_10
#define AUDIO_I2S_GPIO_WS   GPIO_NUM_12
#define AUDIO_I2S_GPIO_BCLK GPIO_NUM_8
#define AUDIO_I2S_GPIO_DIN  GPIO_NUM_7
#define AUDIO_I2S_GPIO_DOUT GPIO_NUM_11// 显示屏配置
#define DISPLAY_WIDTH   320
#define DISPLAY_HEIGHT  240
#define DISPLAY_SPI_SCK_PIN GPIO_NUM_3
#define DISPLAY_SPI_MOSI_PIN GPIO_NUM_5#endif // _BOARD_CONFIG_H_

config.json：定义编译配置

{"target": "esp32s3","builds": [{"name": "my-custom-board","sdkconfig_append": ["CONFIG_ESPTOOLPY_FLASHSIZE_8MB=y"]}]
}

2.3 实现板级初始化代码

创建my_custom_board.cc文件，实现板级初始化逻辑：

#include "board.h"
#include "config.h"class MyCustomBoard : public Board {
public:MyCustomBoard() : Board() {}~MyCustomBoard() {}void Initialize() override {// 初始化音频系统InitializeAudio();// 初始化显示屏InitializeDisplay();// 初始化LEDInitializeLed();}// 实现必要的方法...
};DECLARE_BOARD("my-custom-board", MyCustomBoard);

3. 开发板选择注意事项

选择与您实际使用的硬件最接近的开发板配置
不同芯片平台（ESP32、ESP32-S3、ESP32-C3）需要设置对应的target
对于自定义开发板，确保创建唯一的开发板标识，避免OTA升级问题

五、服务器配置与通信协议

1. 后端服务器地址配置

小智AI项目的服务器地址主要通过OTA URL进行配置。这个地址用于：

检查新版本固件
获取后端服务器配置（MQTT或WebSocket）
设备激活和授权

1.1 通过menuconfig配置OTA URL

idf.py menuconfig

在菜单中导航至：Xiaozhi Assistant -> Default OTA URL，修改为您的服务器地址。默认地址为：

https://api.tenclass.net/xiaozhi/ota/

1.2 通过NVS存储配置

服务器地址也可以在运行时通过NVS存储进行配置：

Settings settings("wifi", false);
settings.SetString("ota_url", "https://your-custom-server.com/ota/");

当设备启动时，它会首先尝试从NVS读取OTA URL，如果没有设置，则使用menuconfig中配置的值。

2. 通信协议选择

小智AI项目支持两种与后端通信的协议：MQTT和WebSocket。

2.1 MQTT协议

当服务器返回MQTT配置时，设备会创建一个MqttProtocol实例进行通信：

if (ota_.HasMqttConfig()) {protocol_ = std::make_unique<MqttProtocol>();
}

2.2 WebSocket协议

当服务器返回WebSocket配置时，设备会创建一个WebsocketProtocol实例进行通信：

else if (ota_.HasWebsocketConfig()) {protocol_ = std::make_unique<WebsocketProtocol>();
}

六、二次开发流程

1. 基础修改流程

克隆仓库：

git clone https://github.com/your-repo/xiaozhi-esp32.git
cd xiaozhi-esp32

配置项目：

idf.py set-target esp32s3  # 根据您的开发板选择目标芯片
idf.py menuconfig

修改代码：根据需求修改相应的代码文件

编译和烧录：

idf.py build
idf.py -p COMx flash monitor  # 将COMx替换为您的串口

2. 功能扩展方法

2.1 添加新的语音处理功能

在main/audio_processing/目录下创建新的音频处理类，继承自AudioProcessor：

class MyAudioProcessor : public AudioProcessor {
public:bool Process(const AudioBuffer& input, AudioBuffer& output) override {// 实现音频处理逻辑return true;}
};

2.2 自定义显示界面

利用LVGL库创建自定义界面，在main/display/目录下扩展：

void CustomDisplaySetup() {// 创建LVGL对象lv_obj_t *label = lv_label_create(lv_scr_act());lv_label_set_text(label, "欢迎使用自定义界面");lv_obj_align(label, LV_ALIGN_CENTER, 0, 0);
}

2.3 集成新的外设

在开发板初始化代码中添加对外设的支持：

void MyCustomBoard::InitializeCustomPeripherals() {// 初始化传感器// 初始化执行器
}

七、OTA升级系统配置

1. OTA功能概述

OTA（Over-The-Air）功能允许设备通过网络远程更新固件。小智AI项目的OTA系统实现位于main/ota.cc和main/ota.h文件中。

2. OTA流程

设备启动时，从NVS或配置中获取OTA URL
向OTA服务器发送版本检查请求
如果有新版本，下载固件并验证
更新固件并重启设备

3. 自定义OTA服务器响应

OTA服务器需要返回以下格式的JSON响应：

{"firmware": {"version": "1.0.0","url": "https://your-server.com/firmware.bin"},"mqtt": {"host": "mqtt-server.com","port": 8883,"username": "user","password": "pass"}
}

八、编译配置文件

1. sdkconfig.defaults文件

项目提供了多个默认配置文件：

sdkconfig.defaults: 基本默认配置
sdkconfig.defaults.esp32c3: ESP32-C3芯片默认配置
sdkconfig.defaults.esp32s3: ESP32-S3芯片默认配置

2. 分区表配置

项目使用CSV格式的分区表定义：

partitions.csv: 默认分区表
partitions_8M.csv: 8MB闪存分区表
partitions_4M.csv: 4MB闪存分区表

九、调试与问题排查

1. 日志级别设置

通过menuconfig调整日志级别：

idf.py menuconfig

导航至：Component config -> Log output -> Default log verbosity

2. 常见问题解决

开发板配置错误：检查BOARD_TYPE配置是否与实际硬件匹配
服务器连接失败：验证OTA URL是否正确，网络连接是否正常
音频问题：确认I2S引脚和音频编解码器配置正确
显示问题：检查显示屏引脚定义和初始化代码

十、自定义开发板注意事项

警告: 对于自定义开发板，当IO配置与原有开发板不同时，切勿直接覆盖原有开发板的配置编译固件。必须创建新的开发板类型，或者通过config.json文件中的builds配置不同的name和sdkconfig宏定义来区分。使用 python scripts/release.py [开发板目录名字] 来编译打包固件。

如果直接覆盖原有配置，将来OTA升级时，您的自定义固件可能会被原有开发板的标准固件覆盖，导致您的设备无法正常工作。