# 小智 ESP32 语音助手

这是一个基于 ESP32 的语音交互助手系统，支持中文语音识别和播放功能，适用于智能家居控制。作为 Home Assistant 的加载项，提供便捷的安装和管理体验。

## 使用指南

### 安装前准备

1. Home Assistant OS、Supervised 或 Container 安装方式
2. MariaDB 加载项已安装（或外部 MySQL/MariaDB 数据库）
3. 具有较好网络连接的环境
4. 足够的存储空间（至少 500MB）

### 配置选项说明

| 选项             | 描述                                                   |
| ---------------- | ------------------------------------------------------ |
| `mysql_host`     | 数据库主机地址，默认使用 MariaDB 插件为 `core-mariadb` |
| `mysql_port`     | 数据库端口，默认为 `3306`                              |
| `mysql_database` | 数据库名称，默认为 `xiaozhi`                           |
| `mysql_user`     | 数据库用户名，默认为 `xiaozhi`                         |
| `mysql_password` | 数据库密码，默认为 `123456`                            |
| `java_memory`    | Java 应用内存分配，如 `512m`、`1g`、`1.5g`             |

### 数据库设置

**自动配置方式**：
插件会尝试自动创建数据库和所需表结构，您只需在配置中提供有效的数据库连接信息。

**手动配置方式**：
如果您希望手动设置数据库，可以执行以下步骤：

```sql
CREATE DATABASE xiaozhi CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'xiaozhi'@'%' IDENTIFIED BY '你的安全密码';
GRANT ALL PRIVILEGES ON xiaozhi.* TO 'xiaozhi'@'%';
FLUSH PRIVILEGES;
```

### 内存管理

可以通过配置项 `java_memory` 控制分配给 Java 应用的堆内存大小，格式示例：

- `512m`（512 兆字节，适合大多数使用场景）
- `1g`（1 吉字节，适合大量设备和频繁交互场景）
- `1.5g`或更高（适合高负载场景）

**内存管理建议**：

- 默认内存分配（512MB）足够普通使用
- 对于多设备场景，建议分配 1GB 或更多内存
- 如遇内存不足问题，增加分配至 1GB 或更高

**优化资源使用**：

- **关闭其他不必要的加载项释放资源**：Home Assistant 上可能同时运行多个加载项，每个加载项都会消耗系统资源。建议临时停用不常用的加载项，特别是资源密集型的加载项（如 Node-RED、VS Code 等），以释放更多内存给语音识别服务。

- **监控资源使用**：通过 Home Assistant 的系统监控加载项，定期检查系统资源使用情况，确保有足够的可用内存。

- **优化运行时参数**：对于性能有限的设备（如某些 Raspberry Pi 型号），确保系统有足够的交换空间(swap)。

- **定期重启**：如果发现内存使用率持续升高，建议定期重启加载项，以释放累积的内存占用。可以在 Home Assistant 中设置自动化，定期重启此加载项。

### 端口说明

本加载项使用以下端口：

- **8091**：API 服务端口（ESP32 设备通过 WebSocket 连接此端口）
- **8084**：Web 管理界面端口（可通过 Home Assistant 边栏访问）

## Web 界面功能

通过 Home Assistant 的边栏图标或直接访问`http://你的HA地址:8084`进入 Web 管理界面。
默认账号：admin
默认密码：123456

### 设备管理

可以添加、编辑和删除 ESP32 设备，主要功能：

- 设备列表查看
- 设备状态监控（在线/离线）
- 设备信息编辑

### 音色配置

支持为 ESP32 设备配置不同的语音合成音色：

- 预设多种中文音色
- 音色预览功能
- 为不同设备分配不同音色

### 角色设置

可以选择不同的 AI 助手角色：

- AI 助手
- 智能家居助手
- 其他预设角色

### 对话管理

查看与 ESP32 设备的历史对话：

- 按时间查看历史消息
- 按关键词搜索对话内容
- 消息管理功能

## ESP32 设备配置

1. 获取并烧录 ESP32 固件（从[原始项目](https://github.com/78/xiaozhi-esp32)获取）
2. 将 ESP32 设备连接到与 Home Assistant 相同的网络
3. 在 ESP32 固件配置中设置服务器地址：
   ```
   ws://你的HA地址:8091/ws/xiaozhi/v1/
   ```
4. 在 Web 管理界面中添加对应的设备信息

## 高级功能

### 持久化对话

系统支持持久化对话记录，可以记住与用户的对话上下文：

- 自动保存对话历史
- 根据历史对话进行上下文理解
- 提供更自然的对话体验

### 自定义唤醒词（需 ESP32 固件支持）

如果 ESP32 固件支持，可以通过接口设置自定义唤醒词。

## 故障排查

### 加载项无法启动

- 检查 MariaDB 服务是否正常运行
- 验证数据库连接信息（主机、端口、用户名、密码）
- 查看 Home Assistant 日志是否有错误信息
- 确保分配了足够的内存给加载项

### 语音模型问题

- 检查 `/config/models/vosk-model` 目录是否存在模型文件
- 如果模型不存在，请手动下载并解压到该目录
- 确保存储空间足够（至少需要 100MB 空闲空间）
- 确保下载的是中文语音模型

### ESP32 设备无法连接

- 验证 ESP32 和 Home Assistant 在同一网络环境
- 检查 WebSocket 地址格式是否正确（ws://ip:8091/ws/xiaozhi/v1/）
- 确认 ESP32 固件是否正确配置
- 检查防火墙是否阻止了 WebSocket 连接

### 内存不足错误

- **增加`java_memory`配置**：根据设备性能适当增加，如从 512m 改为 1g
- **关闭其他不必要的加载项释放资源**：
  - 在 Home Assistant 的加载项页面，暂时停用不常用的资源密集型加载项
  - 特别关注数据库、多媒体相关加载项，它们通常消耗较多资源
  - 考虑使用 Home Assistant 的"系统诊断"功能，检查哪些加载项占用较多资源
  - 如果使用的是低配置设备（如 Raspberry Pi 3 或更低），可能需要限制同时运行的加载项数量
- **优化系统配置**：
  - 增加系统交换空间（在树莓派等设备上尤为重要）
  - 考虑使用性能更强的设备运行 Home Assistant
  - 确保设备有足够的散热，避免因过热导致的性能降低

## 技术架构

本加载项基于以下技术构建：

- **容器技术**：Docker + S6 Overlay（进程管理）
- **前端**：Vue.js + Ant Design（Web 管理界面）
- **后端**：Java Spring Boot（RESTful API 和 WebSocket 服务）
- **语音处理**：VOSK（语音识别）+ ONNX Runtime（模型推理）
- **数据存储**：MySQL/MariaDB（对话历史和配置）

## 支持与贡献

如有问题或建议，请访问[项目 GitHub 页面](https://github.com/joey-zhou/xiaozhi-esp32-server-java)。
欢迎提交问题报告、功能请求或代码贡献。