ElatoAI 详细部署教程

ElatoAI 是一个完整的开源项目，旨在让你使用 ESP32-S3 微控制器 打造一个能与 100 多种 AI 模型进行实时语音对话的设备。它由前端、边缘服务器和 ESP32 固件三部分组成，全程使用安全 WebSocket 通信，可实现长达20分钟的连续对话。

本教程将指导你完成从零开始的完整部署。

1. 准备工作

1.1 软件环境要求

要求 版本/说明
操作系统 macOS、Linux 或 Windows (推荐使用 WSL2)
Node.js 最新 LTS 版本
npm 随 Node.js 安装
Git 用于克隆代码仓库
Docker Desktop 必须安装并运行（用于本地 Supabase）
Deno 用于运行边缘服务器
Supabase CLI 用于本地数据库管理
Visual Studio Code 推荐，用于开发
PlatformIO IDE 扩展 VS Code 插件，用于 ESP32 开发
OpenAI API Key 或其他支持的 AI 模型 API Key

1.2 硬件组件清单

要实现完整的语音对话功能，你需要准备以下硬件：

组件 型号/说明 参考用途
微控制器 ESP32-S3 开发板 (如 ESP32-S3-DevKitC-1) 主控核心
麦克风 INMP441 (I2S 接口) 拾取用户语音
音频放大器 MAX98357A (I2S 接口) 驱动扬声器
扬声器 小型 3W-5W 扬声器 播放 AI 回复
LED RGB LED (共阴极或共阳极) 状态指示
按钮或触摸传感器 轻触开关或触摸板 唤醒/控制设备
连接线 杜邦线若干 连接组件
电源 USB 数据线 (Type-C) 供电与编程

可选：你也可以直接从 ElatoAI 官网 购买预组装的开发套件或成品设备。

2. 软件环境搭建

2.1 克隆代码仓库

在终端中执行以下命令，将项目克隆到本地：

1
2
git clone https://github.com/akdeb/ElatoAI.git
cd ElatoAI

2.2 启动本地 Supabase 后端

ElatoAI 使用 Supabase (PostgreSQL + 认证) 来存储用户、设备、对话记录等数据。

  1. 安装 Supabase CLI (如果尚未安装)：

    1
    brew install supabase/tap/supabase

    Windows (WSL2) 用户：可通过 curl -fsSL https://supabase.com/install.sh | sh 安装。

  2. 启动本地 Supabase 服务：
    确保 Docker Desktop 正在运行，然后在项目根目录下执行：

    1
    supabase start

    此命令会拉取所需的 Docker 镜像并初始化数据库。记录下终端输出的 API URL 和 anon key，后续步骤会用到。

2.3 配置并启动 Next.js 前端

  1. 进入前端目录并安装依赖：

    1
    2
    cd frontend-nextjs
    npm install

  2. 配置环境变量：

    1
    cp .env.example .env.local

    编辑 .env.local 文件，填入上一步获取的 anon key 和你的 OpenAI API Key：

    1
    2
    NEXT_PUBLIC_SUPABASE_ANON_KEY=<你的-supabase-anon-key>
    OPENAI_API_KEY=<你的-openai-api-key>

  3. 启动前端开发服务器：

    1
    npm run dev

    前端服务默认运行在 http://localhost:3000。你可以使用默认账号登录进行测试：

    • 邮箱: admin@elatoai.com
    • 密码: admin

2.4 配置并启动 Deno 边缘服务器

边缘服务器是 ESP32 设备与 AI 模型 API 之间的桥梁。

  1. 进入服务器目录并配置环境变量：

    1
    2
    cd ../server-deno
    cp .env.example .env

    编辑 .env 文件，至少需要设置 SUPABASE_KEY（即上一步的 anon key）和你打算使用的 AI 模型 API Key（如 OPENAI_API_KEY）。

  2. 启动 Deno 服务器：

    1
    deno run -A --env-file=.env main.ts

    该命令会启动 WebSocket 服务器，默认监听端口 8000。请保持此终端窗口运行。

3. 配置与烧录 ESP32 固件

3.1 配置固件服务器地址

这一步是让 ESP32 知道你的电脑（服务器）在哪里。

  1. 打开固件配置文件：
    在项目目录中，找到 firmware-arduino/src/Config.cpp 文件，用 VS Code 或其他文本编辑器打开。

  2. 找到你的本地 IP 地址：

    • macOS / Linux：在终端运行 ifconfig，查找 en0 或 wlan0 接口下的 inet 地址 (例如 192.168.1.100)。
    • Windows：在命令提示符运行 ipconfig，查找“无线局域网适配器 Wi-Fi”下的 IPv4 地址。

  3. 修改配置文件：
    在 Config.cpp 中，找到 ws_server 和 backend_server 的设置项，将它们的值改为你电脑的本地 IP 地址，并保留端口号。

    1
    2
    3
    // 示例：假设你的电脑IP是 192.168.1.100
    const char* ws_server = "192.168.1.100";
    const char* backend_server = "192.168.1.100";

    重要：确保你的电脑和 ESP32 连接在同一个 WiFi 网络下。

  4. 选择运行模式（可选）：
    在 firmware-arduino/src/Config.h 文件中，你可以选择开发模式 (DEV_MODE)。对于本地测试，通常保持 DEV_MODE 启用即可。

3.2 烧录固件到 ESP32

  1. 打开 PlatformIO：
    在 VS Code 中，打开整个 ElatoAI 项目文件夹，PlatformIO 扩展会自动识别 firmware-arduino 项目。
  2. 连接硬件：
    使用 USB 线将你的 ESP32-S3 开发板连接到电脑。
  3. 编译并上传：
    在 VS Code 底部状态栏，点击 PlatformIO 工具栏中的 “Upload” 按钮（右箭头图标）。PlatformIO 会自动编译固件并将其烧录到 ESP32 中。

4. 首次启动与配网

  1. 设备上电：
    烧录完成后，ESP32 会自动重启。如果没有，可以拔掉 USB 再重新插上。
  2. 连接设备热点：
    在你的手机或电脑的 WiFi 列表中，会出现一个名为 ELATO-DEVICE 的网络。连接它。
  3. 配置 WiFi：
    连接成功后，打开浏览器访问 http://192.168.4.1，这会打开一个配置页面。在此页面输入你家的 WiFi 名称和密码，然后保存。
  4. 设备重启并连接：
    配置完成后，ESP32 会重启并自动连接到你的家庭 WiFi。此时，设备应已准备好与服务器通信。

5. 设备注册与使用

  1. 获取设备 MAC 地址：
    为了将 ESP32 硬件与你网页端的账户绑定，你需要知道设备的 MAC 地址。在烧录了测试固件后，可以通过 PlatformIO 的串口监视器（Serial Monitor）查看。
  2. 在网页端注册设备：
    • 打开你运行中的 Next.js 前端页面 (http://localhost:3000) 并登录。
    • 进入 Settings（设置）页面。
    • 在“设备管理”区域，输入你获取到的 ESP32 MAC 地址，将其注册到你的账户下。
  3. 创建并选择 AI 角色：
    • 在前端页面，你可以创建具有不同人设和声音的 AI Agent（AI角色）。
    • 创建一个角色后，在设备控制面板选择它，你的 ESP32 设备就会使用这个角色的设定来与你对话。
  4. 开始对话：
    一切就绪后，按下 ESP32 设备上的按钮（或触摸感应区）即可开始与 AI 对话。你会看到设备上的 LED 灯在不同状态下变换颜色：
    • 🟡 黄色：设备正在聆听
    • 🔵 蓝色：AI 正在说话
    • 🔴 红色：正在处理请求

6. 故障排除

问题 可能原因与解决方案
ESP32 无法连接 WiFi 检查配网时输入的 WiFi 密码是否正确；确保路由器信号强度足够。
设备连接服务器失败 1. 检查电脑 IP 地址是否正确，且 ESP32 与电脑在同一网络。 2. 确保电脑防火墙允许 8000 端口通信。 3. 确认 Deno 服务器 (main.ts) 正在运行。
语音对话无响应 1. 检查硬件连接是否正确（麦克风、扬声器）。 2. 确认 API Key 有效且账户余额充足。 3. 检查网页端是否已将 AI 角色分配到该设备。
编译固件失败 1. 确保已正确安装 PlatformIO 及其依赖。 2. 检查 Config.cpp 和 Config.h 的语法是否有误。
网页端无法登录 确认本地 Supabase 服务 (supabase start) 正在运行，且前端 .env.local 中的 anon key 正确无误。
串口监视器输出乱码 在 PlatformIO 中，设置串口监视器的波特率为 115200。

7. 进阶探索与支持

  • 切换 AI 模型：ElatoAI 支持 OpenAI Realtime API、Gemini Live API、xAI Grok、ElevenLabs 等多种模型。在 .env 文件中配置对应的 API Key 即可在网页端选择。
  • 部署到生产环境：研究项目中的 server-deno 和 frontend-nextjs 目录，可以将边缘服务器部署到 Deno Deploy，将前端部署到 Vercel，实现全球可访问的服务。
  • 贡献代码：项目欢迎贡献，可以参考 README.md 中的“Contributing”部分，例如添加新的 API 支持或优化 ESP32 的语音中断检测功能。
  • 加入社区：通过项目 GitHub 页面或官网 Discord 链接获取最新支持和交流。

这套方案为构建一个可定制、可扩展的物理 AI 语音交互设备提供了完整的蓝图。祝你部署顺利，做出有趣的 AI 伙伴！