diff --git a/README.md b/README.md index 549efb7..e407be4 100644 --- a/README.md +++ b/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://: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