docs: 更新 README 以提供更清晰的功能说明和结构
- 将标题从“开发与预览指南”改为更准确的“终端控制应用” - 详细说明功能概览、页面说明和 MQTT 指令协议 - 补充特殊任务模式的行为说明 - 优化项目结构描述，使其更易于理解 - 保持运行环境与构建步骤的指导性
This commit is contained in:
149
README.md
149
README.md
@@ -1,78 +1,113 @@
|
||||
# Temi 机器人应用开发与预览指南
|
||||
# Temi 终端控制应用
|
||||
|
||||
本项目是一个基于 Temi SDK 的 Android 应用程序，包含主界面和网络 IP 设置功能。
|
||||
本项目是基于 Temi SDK 的 Android 应用，提供 MQTT 指令控制、导航/巡逻/接待流程，以及设置页管理网络 IP、当前位置与特殊任务模式。
|
||||
|
||||
## 1. 预览与运行环境
|
||||
## 1. 运行环境
|
||||
|
||||
### 推荐工具：Android Studio
|
||||
由于 Android 应用依赖于复杂的构建系统 (Gradle) 和特定的运行时环境 (Android OS)，**无法像网页那样直接通过浏览器或简单的编辑器插件预览**。
|
||||
应用依赖 Gradle 与 Android 运行环境，无法通过浏览器直接预览。请使用 Android Studio 导入项目并运行到 Temi 机器人或模拟器。
|
||||
|
||||
最标准的开发和预览工具是 **Android Studio** (官方 IDE)。
|
||||
|
||||
### Trae 的角色
|
||||
Trae 非常适合编写代码、管理项目结构和进行逻辑开发。但为了查看应用的实际运行效果（UI 和交互），你需要将代码编译成 APK 并安装到设备上，这通常需要 Android Studio 的配合。
|
||||
### 运行方式
|
||||
- 方式 A：连接 Temi 机器人（推荐）
|
||||
- 确保 Temi 已开启开发者模式
|
||||
- USB 连接或 ADB over Wi-Fi
|
||||
- Android Studio 选择设备后 Run
|
||||
- 方式 B：Android 模拟器（仅 UI 预览）
|
||||
- Temi 系统服务缺失，Robot SDK 可能报错或不可用
|
||||
|
||||
---
|
||||
|
||||
## 2. 如何在另一台电脑上运行
|
||||
## 2. 功能概览
|
||||
|
||||
### 步骤 1: 安装 Android Studio
|
||||
请访问 [Android Studio 官网](https://developer.android.com/studio) 下载并安装最新版本。
|
||||
|
||||
### 步骤 2: 导入项目
|
||||
1. 打开 Android Studio。
|
||||
2. 选择 **Open** (打开项目)。
|
||||
3. 导航到本项目所在的文件夹 `lzwcai-terminal-temi` 并点击 OK。
|
||||
4. 等待 Android Studio 自动同步 Gradle 依赖（这可能需要几分钟，取决于网络）。
|
||||
|
||||
### 步骤 3: 运行应用 (两种方式)
|
||||
|
||||
#### 方式 A: 连接 Temi 机器人 (强烈推荐)
|
||||
Temi SDK 的很多功能（如语音、导航、跟随）依赖于机器人的硬件传感器。
|
||||
1. 确保 Temi 机器人已开启 **开发者模式** (设置 -> 通用 -> 开发者选项)。
|
||||
2. 使用 USB 线（通常是 USB-A 转 USB-A 或通过背部接口）将电脑连接到 Temi。
|
||||
3. 或者使用 **ADB over Wi-Fi** (确保电脑和 Temi 在同一 Wi-Fi 下)。
|
||||
4. 在 Android Studio 顶部工具栏选择连接的设备，点击 **Run** (绿色三角形按钮)。
|
||||
|
||||
#### 方式 B: 使用 Android 模拟器 (仅限 UI 预览)
|
||||
如果你身边没有机器人，可以使用模拟器预览界面布局，但会报错或功能受限。
|
||||
1. 在 Android Studio 中点击 **Device Manager** 创建一个虚拟设备 (推荐 Pixel 系列，API 30+)。
|
||||
2. 运行模拟器。
|
||||
3. **注意**：由于模拟器没有 Temi 的系统服务，`Robot.getInstance()` 可能会导致崩溃或返回错误。
|
||||
- *提示*：为了在模拟器上查看 UI，你可能需要暂时注释掉 `MainActivity.kt` 中调用 `Robot` 的代码。
|
||||
- 主界面表情与状态反馈（AnimatedEmojiView）
|
||||
- MQTT 控制机器人行为与 TTS 播报
|
||||
- 接待模式：到达指定地点后检测到人出现确认按钮
|
||||
- 巡逻模式：按指定或随机地点巡逻
|
||||
- 特殊任务模式开关
|
||||
- 设置页：网络 IP、当前位置、重启应用
|
||||
|
||||
---
|
||||
|
||||
## 3. 项目结构说明
|
||||
## 3. 页面说明
|
||||
|
||||
- **主界面**: `app/src/main/java/.../MainActivity.kt`
|
||||
- 包含日志显示和跳转设置的按钮。
|
||||
- 初始化 Robot SDK。
|
||||
- **设置界面**: `app/src/main/java/.../SettingsActivity.kt`
|
||||
- 用于设置和保存网络 IP 地址。
|
||||
- **布局文件**:
|
||||
- `app/src/main/res/layout/activity_main.xml` (主页布局)
|
||||
- `app/src/main/res/layout/activity_settings.xml` (设置页布局)
|
||||
### 主界面（MainActivity）
|
||||
- 顶部设置按钮进入设置页
|
||||
- 表情组件根据 TTS 和任务状态切换表情
|
||||
- 接待模式触发时显示 “是的” 按钮，点击后前往目标地点
|
||||
|
||||
## 4. MQTT 指令与行为
|
||||
### 设置页（SettingsActivity）
|
||||
- 网络 IP 配置：保存后作为 MQTT Broker 地址
|
||||
- 当前位置下拉选择：来源于 Temi 已保存地点
|
||||
- 特殊任务模式开关与指示灯
|
||||
- 长按 3 秒重启应用
|
||||
- 版本号显示（当前为硬编码字符串）
|
||||
|
||||
应用订阅 `robot/cmd`，接收 JSON 指令。
|
||||
---
|
||||
|
||||
### 动作列表
|
||||
- `recharge` 前往充电桩
|
||||
- `goto` 前往指定地点（字段 `location` 或 `target`）
|
||||
- `speak` 立即播报（字段 `text` 或 `speech`）
|
||||
- `stream` 流式播报（字段 `text` 或 `content`），按句号/感叹号/问号/换行分句
|
||||
- `stop` 暂停 TTS 与播报队列，不清空 stream buffer
|
||||
- `continue` 继续播报，优先重播被中断的那句话
|
||||
- `terminate` 终止导航与 TTS，清空队列和 buffer
|
||||
## 4. MQTT 指令协议
|
||||
|
||||
### special 模式说明
|
||||
- special 是否启用只看设置页开关 `special_task_mode`
|
||||
- setCurrentTask 不会开启或关闭 special
|
||||
- special 开启时，会跳过门控与问候等场景逻辑
|
||||
应用连接 `tcp://<IP>:1883`，订阅主题 `robot/cmd`，仅处理 JSON payload。
|
||||
|
||||
## 5. 本地验证
|
||||
### 基础指令
|
||||
- `recharge`：回充电桩
|
||||
- `goto`：前往地点（字段 `location` 或 `target`）
|
||||
- `repose`：重新定位
|
||||
- `stop`：停止移动并暂停 TTS（保留队列与 stream buffer）
|
||||
- `continue`：继续播报（优先重播被中断语句）
|
||||
- `terminate`：停止移动并清空所有 TTS 队列与 buffer
|
||||
|
||||
### 播报指令
|
||||
- `speak`：立即播报（字段 `text` 或 `speech`，可选 `lang`）
|
||||
- `stream`：流式播报（字段 `text` 或 `content`，可选 `lang`）
|
||||
- 按 `。！？!?\n` 分句进入队列
|
||||
|
||||
### 任务指令
|
||||
- `patrol`：巡逻
|
||||
- `flag=true` 随机抽取 3~6 个地点（排除 home base）
|
||||
- `flag=false` + `locations` 指定地点列表
|
||||
- `reception`：接待
|
||||
- `location` 接待地点（默认 “前台”）
|
||||
- `text` 询问语（默认 “你是我要接待的贵宾吗？”）
|
||||
- `destination` 目的地（默认 “会议室”）
|
||||
|
||||
### 示例
|
||||
```json
|
||||
{"action":"goto","location":"前台"}
|
||||
```
|
||||
|
||||
```json
|
||||
{"action":"speak","text":"欢迎光临","lang":"zh"}
|
||||
```
|
||||
|
||||
```json
|
||||
{"action":"patrol","flag":false,"locations":["前台","会议室","大厅"]}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 特殊任务模式
|
||||
|
||||
设置页开关 `special_task_mode` 控制以下行为：
|
||||
- 跳过 Home Base 的开门/关门语音逻辑
|
||||
- 跳过检测到人时的问候语
|
||||
- 机器人到达地点时，不播报“已到达”提示（仅在当前无任务时生效）
|
||||
|
||||
---
|
||||
|
||||
## 6. 项目结构
|
||||
|
||||
- `MainActivity.kt`：主逻辑与事件监听
|
||||
- `SettingsActivity.kt`：设置页逻辑
|
||||
- `MqttManager.kt`：MQTT 连接与指令解析
|
||||
- `NavController.kt`：导航与巡逻封装
|
||||
- `AnimatedEmojiView.kt`：表情动画绘制
|
||||
- `LogManager.kt`：Logcat 监听分发
|
||||
- `HttpManager.kt`：HTTP Workflow 请求封装（目前未在流程中启用）
|
||||
- `activity_main.xml` / `activity_settings.xml`：主界面与设置页布局
|
||||
|
||||
---
|
||||
|
||||
## 7. 本地构建与安装
|
||||
|
||||
```bash
|
||||
.\gradlew.bat :app:installDebug
|
||||
|
||||
Reference in New Issue
Block a user