# esp-spot-doubao

**Repository Path**: flashdwh4/esp-spot-doubao

## Basic Information

- **Project Name**: esp-spot-doubao
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-09
- **Last Updated**: 2026-02-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ESP32-C5 Conversational AI 移植项目

基于火山引擎 ConversationalAI Embedded Kit 2.0 SDK 的 ESP32-C5 移植版本。

## 项目简介

本项目将火山引擎 ConversationalAI SDK 移植到 ESP32-C5 平台，实现了通过 WebSocket 与火山引擎 AI 对话服务的实时语音交互功能。

## 代码来源

- **火山引擎 SDK**: https://github.com/volcengine/ConversationalAI-Embedded-Kit-2.0
- **License**: Apache-2.0

## 目录结构

```
esp-c5-conversational-ai-complete/
├── CMakeLists.txt              # 项目主 CMake 配置
├── sdkconfig.defaults          # 默认 SDK 配置
├── sdkconfig.defaults.esp32c5  # ESP32-C5 特定配置
├── partitions.csv              # 分区表
├── README.md                   # 本文件
├── main/                       # 主程序
│   ├── CMakeLists.txt
│   ├── Kconfig.projbuild       # 项目配置菜单
│   ├── main.c                  # 主程序入口
│   ├── audio_hal.c/h           # 音频 HAL 驱动 (PDM/ADC)
│   └── button.c/h              # 按钮驱动
└── components/
    ├── volc_conv_ai/           # 火山引擎 SDK 组件
    │   ├── CMakeLists.txt
    │   ├── inc/volc_conv_ai.h  # SDK 主头文件
    │   ├── osal/               # 操作系统抽象层
    │   ├── src/                # SDK 核心源码
    │   └── third_party/        # 第三方库
    └── audio_hal/              # 音频 HAL 组件
        ├── CMakeLists.txt
        ├── audio_hal.c
        └── audio_hal.h
```

## 功能特性

- ✅ WebSocket 低功耗模式 (WebSocket Mode)
- ✅ PDM 麦克风输入
- ✅ ADC 麦克风输入支持
- ✅ 按钮控制（短按/长按/双击/三击）
- ✅ 实时语音识别与对话
- ✅ TTS 音频播放输出接口
- ✅ WiFi 网络连接
- ✅ SNTP 时间同步

## 硬件要求

- **开发板**: ESP32-C5 开发板
- **麦克风**: PDM 数字麦克风 或 模拟麦克风
- **按钮**: 用户交互按钮（默认 GPIO 0）
- **扬声器**: I2S DAC 或 PWM 音频输出（需自行实现）

## 引脚定义

| 功能 | GPIO | 说明 |
|------|------|------|
| Button | GPIO 0 | 用户按钮 |
| PDM CLK | GPIO 4 | PDM 麦克风时钟 |
| PDM DATA | GPIO 5 | PDM 麦克风数据 |

## 快速开始

### 1. 环境准备

确保已安装 ESP-IDF v5.2 或更高版本：

```bash
# 设置 ESP-IDF 环境
. $HOME/esp/esp-idf/export.sh
```

### 2. 配置项目

```bash
cd esp-c5-conversational-ai-complete

# 打开配置菜单
idf.py menuconfig

# 配置以下选项：
# - ESP32-C5 Conversational AI Configuration ->
#   - WiFi SSID / Password
#   - Volcano Engine credentials (Instance ID, Product Key, Product Secret, Device Name, Bot ID)
#   - Audio input mode (PDM / ADC)
#   - GPIO pins
```

### 3. 编译和烧录

```bash
# 编译
idf.py build

# 烧录到 ESP32-C5
idf.py -p /dev/ttyUSB0 flash

# 查看日志
idf.py -p /dev/ttyUSB0 monitor
```

## 配置说明

### 火山引擎凭证配置

在 `idf.py menuconfig` 中配置：

```
ESP32-C5 Conversational AI Configuration ->
  - VOLC_INSTANCE_ID: 你的实例 ID
  - VOLC_PRODUCT_KEY: 产品 Key
  - VOLC_PRODUCT_SECRET: 产品 Secret
  - VOLC_DEVICE_NAME: 设备名称
  - VOLC_BOT_ID: Bot ID
```

或在代码中直接修改 `main/main.c`：

```c
#define DEFAULT_INSTANCE_ID "your_instance_id"
#define DEFAULT_PRODUCT_KEY "your_product_key"
#define DEFAULT_PRODUCT_SECRET "your_product_secret"
#define DEFAULT_DEVICE_NAME "esp32_c5_device"
```

### WiFi 配置

方式1：通过 `idf.py menuconfig` 配置默认 WiFi

方式2：通过 NVS 存储 WiFi 凭证（推荐）

方式3：通过 AP 配网模式（需自行实现）

### 音频输入配置

支持三种音频输入模式：

1. **PDM 麦克风** (默认)
   - 配置：CONFIG_AUDIO_INPUT_PDM=y
   - 引脚：CONFIG_PDM_CLK_GPIO, CONFIG_PDM_DATA_GPIO

2. **ADC 模拟麦克风**
   - 配置：CONFIG_AUDIO_INPUT_ADC=y
   - 默认使用 ADC1_CHANNEL_0 (GPIO0)

3. **I2S 麦克风**
   - 需要手动实现 I2S 配置

## API 使用说明

### 初始化流程

```c
// 1. 初始化 WiFi
wifi_init_sta();

// 2. 同步时间
initialize_sntp();
wait_for_time_sync();

// 3. 初始化音频
audio_hal_config_t audio_config = {
    .sample_rate = 16000,
    .bits_per_sample = 16,
    .channels = 1,
    .buffer_size = 2048,
};
audio_hal_init(&audio_config);

// 4. 创建引擎
volc_event_handler_t handler = {
    .on_volc_event = on_event,
    .on_volc_conversation_status = on_status,
    .on_volc_audio_data = on_audio_data,
};
volc_create(&engine, config_json, &handler, NULL);

// 5. 开始对话
volc_opt_t opt = {
    .mode = VOLC_MODE_WS,
    .bot_id = "your_bot_id",
};
volc_start(engine, &opt);
```

### 发送音频数据

```c
volc_audio_frame_info_t info = {
    .data_type = VOLC_AUDIO_DATA_TYPE_PCM,
    .commit = true,
};
volc_send_audio_data(engine, audio_buffer, buffer_len, &info);
```

### 接收 TTS 音频

```c
void on_audio_data(volc_engine_t handle, const void* data_ptr, size_t data_len,
                   volc_audio_frame_info_t* info_ptr, void* user_data) {
    // 播放音频数据
    audio_hal_write(data_ptr, data_len);
}
```

### 中断对话

```c
volc_interrupt(engine);
```

## 回调函数说明

| 回调 | 触发时机 |
|------|----------|
| on_volc_event | 连接/断开事件 |
| on_volc_conversation_status | 对话状态变化 (LISTENING/THINKING/ANSWERING) |
| on_volc_audio_data | 收到 TTS 音频数据 |
| on_volc_video_data | 视频数据（当前版本未使用） |
| on_volc_message_data | 消息数据 |

## 对话状态

```c
VOLC_CONV_STATUS_LISTENING  = 1  // AI 正在听
VOLC_CONV_STATUS_THINKING   = 2  // AI 正在思考
VOLC_CONV_STATUS_ANSWERING  = 3  // AI 正在回答
VOLC_CONV_STATUS_INTERRUPTED = 4 // 被打断
VOLC_CONV_STATUS_ANSWER_FINISH = 5 // 回答完成
```

## 许可证

本项目代码基于 Apache-2.0 许可证，与火山引擎 SDK 保持一致。

```
Copyright (2025) Beijing Volcano Engine Technology Ltd.
SPDX-License-Identifier: Apache-2.0
```

## 常见问题

### Q: 编译失败，提示找不到某些头文件
A: 确保 ESP-IDF 环境已正确设置，并运行 `idf.py fullclean` 后重新编译。

### Q: WiFi 连接失败
A: 检查 WiFi 凭证是否正确，或尝试靠近路由器。

### Q: 音频采集有噪音
A: 检查 PDM 麦克风连接，或调整 ADC 增益。

### Q: 对话连接失败
A: 检查火山引擎凭证是否正确，以及时间是否已同步（SNTP）。

## 技术支持

- 火山引擎文档: https://www.volcengine.com/docs/
- ESP-IDF 文档: https://docs.espressif.com/projects/esp-idf/

## 版本历史

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0.0 | 2025-02 | 初始版本，支持 WebSocket 模式 |