Files

tanjianbin fea2ba7591 feat: 新增机器人运动控制、任务管理及远程监控功能

- 扩展 NavController 支持旋转、倾斜及遥控操作
- 实现任务控制器统一管理接待、巡逻、通知等任务逻辑
- 新增遥测管理器定期上报状态并支持低电量预警
- 增强 LiveKit 管理器支持自动重连与麦克风状态联动
- 优化人体检测去抖逻辑并更新技术文档
- 调整设置界面文本描述并添加网络异常提示

2026-03-20 15:36:38 +08:00

6.8 KiB

Raw Permalink Blame History

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 构建与安装

.\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 示例

{"action":"goto","location":"前台"}

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

{"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 人体检测去抖与录音时序

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 稳定状态逻辑图（门禁/问候/录音）

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 接待与巡逻任务流程图

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[结束巡逻任务]

6.8 KiB Raw Permalink Blame History Unescape Escape

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

1. 项目概览

2. 系统架构

2.1 分层结构

2.2 核心模块职责

3. 运行与构建

3.1 环境要求

3.2 构建与安装

4. MQTT 通信协议

4.1 连接信息

4.2 基础指令

4.3 播报指令

4.4 任务指令

4.5 示例

5. 任务与导航逻辑

5.1 接待模式

5.2 巡逻模式

5.3 到达逻辑

5.4 人体检测与录音逻辑

6. 表情与语音联动

7. 配置项与持久化

7.1 SharedPreferences 关键字段

7.2 设置页功能

8. 特殊任务模式

9. LiveKit 连接

10. 权限要求

11. 依赖说明

12. 安全注意事项

13. 时序图与逻辑图

13.1 人体检测去抖与录音时序

13.2 稳定状态逻辑图（门禁/问候/录音）

13.3 接待与巡逻任务流程图

6.8 KiB

Raw Permalink Blame History