xiaozhi/py-xiaozhi-main/documents/docs/guide/02_配置说明.md

# 配置说明

## 项目基础配置

### 配置文件说明
项目使用两种配置方式：初始配置模板和运行时配置文件。

1. **初始配置模板**
   - 位置：`/src/utils/config_manager.py`
   - 作用：提供默认配置模板，首次运行时会自动生成配置文件
   - 使用场景：首次运行或需要重置配置时修改此文件

2. **运行时配置文件**
   - 位置：`/config/config.json`
   - 作用：存储实际运行时的配置信息
   - 使用场景：日常使用时修改此文件

3. **设备身份文件**
   - 位置：`/config/efuse.json`
   - 作用：存储设备唯一标识信息，包括序列号和激活状态
   - 使用场景：设备激活流程中自动生成和更新

### 配置项访问方式
配置系统设计为层级结构，使用点分隔的路径访问特定配置项：

```python
# 示例：获取配置值
from src.utils.config_manager import ConfigManager
config = ConfigManager.get_instance()
mqtt_endpoint = config.get_config("SYSTEM_OPTIONS.NETWORK.MQTT_INFO.endpoint")

# 示例：更新配置值
config.update_config("WAKE_WORD_OPTIONS.USE_WAKE_WORD", True)
```

## 网络配置

网络配置位于`SYSTEM_OPTIONS.NETWORK`下，主要包含以下内容：

```json
"NETWORK": {
  "OTA_VERSION_URL": "https://api.tenclass.net/xiaozhi/ota/",  // OTA更新地址
  "WEBSOCKET_URL": "ws://192.168.31.232:8000/xiaozhi/v1/",     // WebSocket服务器地址
  "WEBSOCKET_ACCESS_TOKEN": "test-token",                      // 访问令牌
  "MQTT_INFO": {
    "endpoint": "",                             // MQTT服务器地址
    "client_id": "",                            // MQTT客户端ID
    "username": "",                             // MQTT用户名
    "password": "",                             // MQTT密码
    "publish_topic": "",                        // 发布主题
    "subscribe_topic": ""                       // 订阅主题
  },
  "ACTIVATION_VERSION": "v2",                   // 激活版本，可选值: v1, v2
  "AUTHORIZATION_URL": "https://xiaozhi.me/"    // 授权URL地址
}
```

## 设备激活

设备首次使用时需要进行激活，激活信息存储在`config/efuse.json`文件中：

```json
{
  "serial_number": "SN-E3E1F618-902e16dbe116",  // 设备序列号
  "hmac_key": "b5bf012dd518080532f928b70ed958799f34f9224e80dd4128795a70a5baca24",  // 密钥
  "activation_status": false  // 激活状态，激活成功后变为true
}
```

激活流程由`ACTIVATION_VERSION`配置项控制：
- `v1`：简化激活模式
- `v2`：完整激活流程，包括验证码确认

## 唤醒词配置

语音唤醒相关配置位于`WAKE_WORD_OPTIONS`下：

```json
"WAKE_WORD_OPTIONS": {
  "USE_WAKE_WORD": false,                                // 是否启用语音唤醒
  "MODEL_PATH": "models/vosk-model-small-cn-0.22",       // 唤醒模型路径
  "WAKE_WORDS": [                                        // 唤醒词列表
    "小智",
    "小美"
  ]
}
```

## 摄像头与视觉识别

摄像头和视觉识别相关配置位于`CAMERA`下：

```json
"CAMERA": {
  "camera_index": 0,                                     // 摄像头索引
  "frame_width": 640,                                    // 画面宽度
  "frame_height": 480,                                   // 画面高度
  "fps": 30,                                             // 帧率
  "Loacl_VL_url": "https://open.bigmodel.cn/api/paas/v4/", // 智普API地址
  "VLapi_key": "你自己的key",                              // 智普视觉大模型API密钥
  "models": "glm-4v-plus"                                // 使用的视觉模型
}
```

## IoT设备配置

### 温度传感器

温度传感器通过MQTT协议连接，配置位于`TEMPERATURE_SENSOR_MQTT_INFO`下：

```json
"TEMPERATURE_SENSOR_MQTT_INFO": {
  "endpoint": "你的Mqtt连接地址",                          // MQTT服务器地址
  "port": 1883,                                          // MQTT服务器端口
  "username": "admin",                                   // MQTT用户名
  "password": "123456",                                  // MQTT密码
  "publish_topic": "sensors/temperature/command",        // 发布主题
  "subscribe_topic": "sensors/temperature/device_001/state" // 订阅主题
}
```

需要注意：
- `endpoint`必须是有效的MQTT服务器地址
- `port`默认为1883，如使用TLS加密则通常为8883
- `publish_topic`用于发送命令到设备
- `subscribe_topic`用于接收设备状态

### Home Assistant集成

Home Assistant智能家居平台集成配置位于`HOME_ASSISTANT`下：

```json
"HOME_ASSISTANT": {
  "URL": "http://你的Home Assistant地址:8123",  // Home Assistant服务器地址
  "TOKEN": "长期访问令牌",                      // 访问令牌
  "DEVICES": []                               // 要集成的设备列表
}
```

通过此配置，可以控制添加到Home Assistant中的各类设备，包括：
- 灯光设备（HomeAssistantLight）
- 开关设备（HomeAssistantSwitch）
- 数值设备（HomeAssistantNumber）
- 按钮设备（HomeAssistantButton）

## 配置修改指南

1. **首次使用配置**
   - 直接运行程序，系统会自动生成默认配置文件
   - 如需修改默认值，可编辑 `config_manager.py` 中的 `DEFAULT_CONFIG`

2. **更换服务器配置**
   - 打开 `/config/config.json`
   - 修改 `SYSTEM_OPTIONS.NETWORK.WEBSOCKET_URL` 为新的服务器地址
   - 示例：
     ```json
     "SYSTEM_OPTIONS": {
       "NETWORK": {
         "WEBSOCKET_URL": "ws://你的服务器地址:端口号/"
       }
     }
     ```
   
3. **启用语音唤醒**
   - 修改 `WAKE_WORD_OPTIONS.USE_WAKE_WORD` 为 `true`
   - 可在 `WAKE_WORD_OPTIONS.WAKE_WORDS` 数组中添加或修改唤醒词

4. **配置摄像头与视觉识别**
   - 修改 `CAMERA` 部分的相关配置
   - 将 `VLapi_key` 设置为你从智普AI平台获取的API密钥
   - 可以根据需要调整分辨率和帧率

5. **配置Home Assistant集成**
   - 在Home Assistant中创建长期访问令牌
   - 填写 `HOME_ASSISTANT.URL` 和 `HOME_ASSISTANT.TOKEN`
   - 设备会自动发现并集成

## 注意事项
- 修改配置文件后需要重启程序才能生效
- WebSocket URL 必须以 `ws://` 或 `wss://` 开头
- 首次运行时会自动生成 CLIENT_ID，建议不要手动修改
- DEVICE_ID 默认使用设备MAC地址，可按需修改
- 配置文件使用 UTF-8 编码，请使用支持 UTF-8 的编辑器修改
- 请妥善保管API密钥和访问令牌等敏感信息
- Home Assistant集成需要保证网络可以正常访问到Home Assistant服务器