环境准备

虚拟机装载 ubuntu22.04 系统。

虚拟机搭建系统教程：在虚拟机中安装与卸载Ubuntu-硬件文档博客

这里的太老了，新版本的idf搭建参考：https://blog.csdn.net/sunyuhua_keyboard/article/details/143133398

Linux安装ESP-IDFV5.4.1

全部步骤本人亲测有效，笔记是操作完成后重新记录的。本文章写于2025年8月22日。

修改apt国内镜像源，不然apt安装软件会比较慢。（apt源已改的可以跳过）
以阿里巴巴镜像源为例：（Ubuntu版本22.04）其他版本请参照阿里巴巴镜像站教程。

cd /etc/apt

cp sources.list sources.list.bkp

echo "" > sources.list

sudo vi sources.list

#粘贴以下内容：（按快捷键i进入编辑,粘贴后按ESC键再输入‘:wq’保存退出）
deb https://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse
deb-src https://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse

deb https://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse
deb-src https://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse

deb https://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse
deb-src https://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse

# deb https://mirrors.aliyun.com/ubuntu/ jammy-proposed main restricted universe multiverse
# deb-src https://mirrors.aliyun.com/ubuntu/ jammy-proposed main restricted universe multiverse

deb https://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse
deb-src https://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse

开始安装

为了在 ESP32-S3 中使用 ESP-IDF，需要根据操作系统安装一些软件包：

sudo apt install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0 -y

完成后我打算在系统根目录下新建一个esp的文件夹，后面ESP-IDF相关的文件都放这里。

mkdir esp

进入这个文件夹

cd esp

克隆esp-idf仓库，很大 比较久。建议通过ssh的方式克隆。
用github上注册的用户名和邮箱地址，配置git

git config  --global user.name "username"
git config  --global user.email "username@email.com"

将 username 改为你的名称，username@email.com 改为你的github邮箱

重启ubuntu
查看git是否配置成功

sudo git config --global --list

生成ssh密钥，ed25519也可以用rsa，只是代表两种不同算法生成的密钥

ssh-keygen -t ed25519 -C "username@email.com"

response如下，设置私钥的文件名（产生一个私钥，和一个同名的.pub结尾公钥）和通行短语。不设置可以回车跳过

Enter file in which to save the key (/home/icenter/.ssh/id_ed25519): 
Enter passphrase (empty for no passphrase):
Enter same passphrase again:

使用cat命令查看生成的pub密钥

cat /home/xxx/.ssh/id_ed25519.pub

然后将 id_ed25519.pub 中的内容复制出来，去到 github 的 settings 中添加你的 ssh。

接下来通过ssh下载esp-idf:

git clone -b release/v5.5 --recursive https://github.com/espressif/esp-idf.git

或者

git clone git@github.com:espressif/esp-idf.git

--depth=1 表示只拉取最近的一次代码

切换idf版本：

cd esp-idf
git checkout v5.4.1

安装所有模块：

./install.sh all

如上所示则安装好了。

将idf添加至 PATH 环境变量：

. ~/esp/esp-idf/export.sh

linux安装vscode

为了方便更新以及查看小智AI的代码，建议安装一个vscode，同时在vscode中安装esp-idf插件，UI式操作不用命令行。

1. 从vscode官网下载最新版本，deb包下载地址：Download Visual Studio Code - Mac, Linux, Windows

2. 下载后在放置 deb 包的文件夹直接打开终端，然后输入：
   

   sudo  dpkg  -i code_1.45.1-1589445302_amd64.deb

   
   其中的 -i 后面的就是deb包名；执行之后等待安装完成就行了。

后面在系统中直接通过UI打开VSCODE就好。

3. 安装esp-idf插件

后面的操作就根据这里来了 1.3.2在线安装章节：1. IDF环境安装 | 立创开发板技术文档中心

小智AI源码下载

下载地址：78/xiaozhi-esp32: An MCP-based chatbot | 一个基于MCP的聊天机器人

仓库拉取命令：

git clone https://github.com/78/xiaozhi-esp32.git

或者

git clone git@github.com:78/xiaozhi-esp32.git

拉取完成后使用VSCODE打开这个文件夹。

小智AI源码新增开发板

新增开发板的步骤参考官方文档：xiaozhi-esp32/main/boards/README.md at main · 78/xiaozhi-esp32

接下来介绍我的步骤。

1. 在 main/boards 路径下，新建自己的板子文件夹，我直接复制lichuang-dev文件夹，且粘贴重新命名为 aaa-lichuang-dev。
   

在里面根据官方文档说的配置三个文件：

配置config.json文件：

配置config.h文件为你硬件的IO：

改.cc 文件里面为你板子的名称：

同时也要把 .cc 文件改错为你板子的名字。

完成后为了编译能够编译我们的新板子代码，需要在main文件夹下的 CMakeLists.txt 中添加自己板子的配置：

在同目录下的 Kconfig.projbuild 中添加我们板子的名称：

完成后打开终端：

执行编译命令：

按照官方文档说的执行编译打包命令：

使用 python scripts/release.py [开发板目录名字] 来编译打包固件。

编译完成后，会告诉你固件的路径：

到此完成。

如何修改唤醒词

在工程的命令行下，输入idf.py menuconfig进入配置界面
键盘上下选择“ESP Speech Recognition”

选择“Load Multiple Wake Words”

选择任意唤醒词后按Enter确定后按键盘的'S'保存 ESC退出

更改之后不能用 python scripts/release.py 命令，它会删除我们的配置，需要使用命令：idf.py build进行编译，编译完成后在编译提醒处找到我们项目的所有散固件，按照提示地址烧录即可。

idf.py 命令行操作

# 设置目标芯片
idf.py set-target esp32s3

# 编译项目
idf.py build

# 烧录固件
idf.py -p COMx flash

# 监控串口
idf.py -p COMx monitor

ctrl + ] 退出  monitor