feat(设置页): 添加 Agent 过滤配置字段
- 在设置页添加 Agent ID 输入框,用于过滤流式播报消息 - 新增字符串资源 label_agent_filter 和 hint_agent_id - 在 MQTT 管理器中处理 soul2user 主题消息,根据配置的 demp_id 进行过滤 - 更新 README 文档结构,将详细技术说明移至 technique.md 文件
This commit is contained in:
160
technique.md
Normal file
160
technique.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# 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
|
||||
- 建议正式环境将敏感信息迁移至安全配置源
|
||||
Reference in New Issue
Block a user