tanjianbin
fea2ba7591
- 扩展 NavController 支持旋转、倾斜及遥控操作 - 实现任务控制器统一管理接待、巡逻、通知等任务逻辑 - 新增遥测管理器定期上报状态并支持低电量预警 - 增强 LiveKit 管理器支持自动重连与麦克风状态联动 - 优化人体检测去抖逻辑并更新技术文档 - 调整设置界面文本描述并添加网络异常提示
234 lines
6.8 KiB
Markdown
234 lines
6.8 KiB
Markdown
# 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
|
||
- 若为巡逻任务则推进巡逻索引
|
||
- 特殊任务模式下可跳过“已到达”播报
|
||
|
||
### 5.4 人体检测与录音逻辑
|
||
- 人体检测事件先做稳定判定（去抖）
|
||
- DETECTED：延迟确认（默认 0.8s），仍为 DETECTED 才进入“稳定检测”状态
|
||
- IDLE：延迟确认（默认 5s），仍为 IDLE 才退出“稳定检测”状态
|
||
- 录音（LiveKit）仅在稳定状态切换时开启/关闭
|
||
- 稳定 DETECTED：开启录音
|
||
- 稳定 IDLE：关闭录音
|
||
- 特殊任务模式仅跳过门禁与问候，不影响录音逻辑
|
||
|
||
## 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
|
||
- 建议正式环境将敏感信息迁移至安全配置源
|
||
|
||
## 13. 时序图与逻辑图
|
||
|
||
### 13.1 人体检测去抖与录音时序
|
||
```mermaid
|
||
sequenceDiagram
|
||
autonumber
|
||
participant Temi as Temi SDK
|
||
participant Main as MainActivity
|
||
participant LK as LiveKitManager
|
||
Temi->>Main: onDetectionStateChanged(DETECTED)
|
||
Main->>Main: 启动 DETECTED 确认延迟
|
||
Main->>Main: 状态稳定为 DETECTED
|
||
Main->>LK: setDetectionActive(true)
|
||
Temi->>Main: onDetectionStateChanged(IDLE)
|
||
Main->>Main: 启动 IDLE 确认延迟
|
||
Main->>Main: 状态稳定为 IDLE
|
||
Main->>LK: setDetectionActive(false)
|
||
```
|
||
|
||
### 13.2 稳定状态逻辑图（门禁/问候/录音）
|
||
```mermaid
|
||
flowchart TD
|
||
A[稳定状态变化] --> B{state == DETECTED?}
|
||
B -- 是 --> C[录音开启]
|
||
B -- 否 --> D[录音关闭]
|
||
C --> E{空任务?}
|
||
D --> E
|
||
E -- 否 --> H[结束]
|
||
E -- 是 --> F{在 Home Base?}
|
||
F -- 是 --> G{特殊任务模式?}
|
||
G -- 否 --> I[执行开门/关门逻辑]
|
||
G -- 是 --> H
|
||
F -- 否 --> J{特殊任务模式?}
|
||
J -- 否 --> K[执行问候语]
|
||
J -- 是 --> H
|
||
```
|
||
|
||
### 13.3 接待与巡逻任务流程图
|
||
```mermaid
|
||
flowchart TD
|
||
A[MQTT 指令进入] --> B{action}
|
||
B -- reception --> C[进入接待任务]
|
||
C --> D[导航到接待点]
|
||
D --> E{到达?}
|
||
E -- 否 --> D
|
||
E -- 是 --> F[检测到人提示确认]
|
||
F --> G{用户确认?}
|
||
G -- 否 --> F
|
||
G -- 是 --> H[播报确认语]
|
||
H --> I[导航到目的地]
|
||
I --> J[结束接待任务]
|
||
|
||
B -- patrol --> K[进入巡逻任务]
|
||
K --> L{随机/指定路线}
|
||
L --> M[导航到下一个点]
|
||
M --> N{到达?}
|
||
N -- 否 --> M
|
||
N -- 是 --> O[更新索引/剩余圈数]
|
||
O --> P{是否完成}
|
||
P -- 否 --> M
|
||
P -- 是 --> Q[结束巡逻任务]
|
||
```
|