# Temi 终端控制应用 — 技术文档

## 1. 项目概览
本项目为基于 Temi SDK 的 Android 应用，核心能力是通过 MQTT 指令驱动机器人导航、接待/巡逻与语音播报，并配合表情状态展示与 LiveKit 音视频连接能力。

主要入口与核心逻辑集中在：
- MainActivity（主界面与机器人事件监听）
- MqttManager（MQTT 连接与指令解析）
- NavController（导航控制封装）

## 2. 系统架构

### 2.1 分层结构
- **UI 层**
  - MainActivity：主界面、机器人事件监听、任务状态流转
  - SettingsActivity：配置页面（IP、当前位置、特殊任务模式、LiveKit 参数）
  - AnimatedEmojiView：表情动画组件
- **业务层**
  - MqttManager：MQTT 连接与指令协议处理、TTS 队列与流式播报
  - NavController：导航/巡逻/重定位封装
- **连接能力**
  - LiveKitManager：LiveKit 房间连接与状态管理

### 2.2 核心模块职责
- **MainActivity**
  - 监听 TTS、导航状态、人检测事件
  - 驱动表情变化与任务状态
  - 管理 MQTT / LiveKit 连接生命周期
- **MqttManager**
  - MQTT 连接、订阅主题
  - JSON 指令解析与动作下发
  - 流式播报与 TTS 队列管理
- **NavController**
  - 封装 goTo、patrol、repose、recharge 等指令

## 3. 运行与构建

### 3.1 环境要求
- Android Studio
- Gradle
- Temi SDK 依赖
- 真实 Temi 设备或 Android 模拟器（模拟器仅可预览 UI）

### 3.2 构建与安装
```bash
.\gradlew.bat :app:installDebug
```

## 4. MQTT 通信协议

### 4.1 连接信息
- Broker：`tcp://<IP>:1883`
- 订阅主题：
  - `robot/cmd`：指令通道
  - `soul2user`：流式播报通道

### 4.2 基础指令
| action | 说明 |
|---|---|
| recharge | 前往充电桩 |
| goto | 前往地点（location / target） |
| repose | 重新定位 |
| stop | 停止移动并暂停播报 |
| continue | 继续播报 |
| terminate | 停止移动并清空 TTS |

### 4.3 播报指令
| action | 说明 |
|---|---|
| speak | 立即播报（text / speech，可选 lang） |
| stream | 流式播报（text / content，可选 lang） |

### 4.4 任务指令
| action | 说明 |
|---|---|
| patrol | 巡逻：flag=true 随机地点，flag=false 使用 locations |
| reception | 接待：location / text / destination |

### 4.5 示例
```json
{"action":"goto","location":"前台"}
```

```json
{"action":"speak","text":"欢迎光临","lang":"zh"}
```

```json
{"action":"patrol","flag":false,"locations":["前台","会议室","大厅"]}
```

## 5. 任务与导航逻辑

### 5.1 接待模式
- 接收到 reception 指令后进入接待任务
- 到达接待点后检测到人显示确认按钮并播报提示
- 点击确认后前往目的地并结束接待模式

### 5.2 巡逻模式
- 随机巡逻：从已有地点中随机抽取 3~6 个（排除 home base）
- 指定巡逻：按 locations 列表执行
- 完成全部地点后自动结束巡逻任务

### 5.3 到达逻辑
- 到达地点后更新 current_location
- 若为巡逻任务则推进巡逻索引
- 特殊任务模式下可跳过“已到达”播报

## 6. 表情与语音联动

- **TTS STARTED**：表情变为 TALKING
- **TTS COMPLETED/CANCELED**：
  - 巡逻中显示 ANGRY
  - 非巡逻显示 SMILE
- **TTS ERROR**：表情显示 SAD
- 闲置时自动眨眼动画

## 7. 配置项与持久化

### 7.1 SharedPreferences 关键字段
- `network_ip`：MQTT Broker 地址
- `current_location`：当前位置
- `special_task_mode`：特殊任务模式开关
- `livekit_url / livekit_room / livekit_token / livekit_enabled`
- `agent_demp_id`：stream 匹配字段

### 7.2 设置页功能
- MQTT IP 设置
- LiveKit 连接参数设置
- 特殊任务模式开关
- 当前位置选择与保存
- 长按 3 秒重启应用

## 8. 特殊任务模式

开启后会：
- 跳过 Home Base 的开门/关门语音逻辑
- 跳过检测到人时的问候语
- 到达地点时不播报“已到达”（无任务状态下）

## 9. LiveKit 连接

- 默认 URL 会根据 IP 自动拼接 `ws://<IP>:7880`
- 若未配置 token，则在本地使用默认 key/secret 生成临时 token
- 连接状态与 MQTT 状态共同驱动主界面状态指示灯

## 10. 权限要求
- Temi 权限：MAP / SEQUENCE / FACE_RECOGNITION / SETTINGS
- Android 权限：RECORD_AUDIO / CAMERA（LiveKit）

## 11. 依赖说明
- Temi SDK：`com.robotemi:sdk:1.137.1`
- MQTT：`org.eclipse.paho:org.eclipse.paho.android.service:1.1.1`
- LiveKit：`io.livekit:android`
- AndroidX / Material 等基础依赖

## 12. 安全注意事项
- MQTT 用户名/密码在代码内配置
- LiveKit 默认 key/secret 也在代码内生成 token
- 建议正式环境将敏感信息迁移至安全配置源