# Daystar Robot SDK Demo GUI

这是一个基于 Web 的机器人控制界面，可以通过浏览器实际调用 Daystar 机器人 SDK 接口。支持跨网络部署，可在机器人本体上运行服务，通过 PC 浏览器远程访问控制。

## 功能特点

### 🤖 机器人控制功能

- **连接管理**: 连接/断开机器人 GRPC 和 WebSocket 服务
- **系统信息**: 获取 MC 版本、机器人名称等基础信息
- **电池监控**: 实时获取电池电量、电流、功率和充电状态
- **姿态控制**: 控制机器人站立/趴下
- **驱动控制**: 启用/禁用机器人驱动器
- **灯光控制**: 设置机器人灯光样式（关闭/常亮/呼吸灯/闪烁）
- **运动控制**: 速度控制、高度调节、步态设置、避障控制等

### 🧭 导航控制功能

- **位置管理**: 添加、删除、获取导航位置点
- **导航控制**: 导航到指定位置、取消导航、暂停/继续导航
- **状态监控**: 实时显示导航状态和位置信息
- **事件监听**: 实时显示导航事件日志，包含完整的 JSON 数据
- **快速操作**: 一键设置当前位置为目标、紧急停止等
- **3D 地图显示**: 支持 PCD 点云地图加载和显示（默认 map.pcd）

### 📹 视频流功能

- **实时视频**: 支持 RTSP 视频流实时显示
- **多路视频**: RGB 相机和云台相机双路视频
- **跨网络流媒体**: 独立视频服务器，支持跨网络访问
- **动态配置**: 支持动态 RTSP 地址配置，自动适配网段

### 🎥 云台控制功能

- **方向控制**: 上下左右移动云台
- **精确控制**: 通过滑块精确控制 Pan/Tilt/Zoom 速度
- **预设位置**: 快速移动到预设位置（居中、左右巡视、上下监控）
- **停止控制**: 紧急停止所有云台运动
- **实时视频**: 云台相机实时视频流显示

### 🌐 跨网络部署

- **自动 IP 检测**: 自动检测服务器 IP 地址
- **动态 URL 配置**: 根据连接网段动态配置 API 地址
- **跨网络访问**: 支持在机器人本体运行，PC 浏览器访问
- **自动断线**: 浏览器关闭时自动断开连接

### 🎮 双模式设计

- **真实 API 模式**: 实际调用机器人 SDK 接口
- **模拟器模式**: 用于演示和测试，无需真实机器人

## 系统架构

```
┌─────────────────┐    HTTP API     ┌─────────────────┐    GRPC/WebSocket    ┌─────────────────┐
│   Web Browser   │ ─────────────► │  Python Flask   │ ──────────────────► │  Robot Hardware │
│   (demo_gui.    │                 │   API Server    │                     │                 │
│    html)        │ ◄───────────── │ (demo_api_      │ ◄────────────────── │  (IP:50051/     │
│                 │    JSON/HTML    │  server.py)     │    SDK Response     │   3232)         │
└─────────────────┘                 └─────────────────┘                     └─────────────────┘
                                              │                                        │
                                              │ HTTP Proxy                            │
                                              ▼                                        │
                                     ┌─────────────────┐    OpenCV/RTSP              │
                                     │  Video Stream   │ ──────────────────────────► │
                                     │    Server       │    Video Processing         │
                                     │(video_stream_   │ ◄────────────────────────── │
                                     │ server.py:5011) │                             │
                                     └─────────────────┘                             │
                                                                                     │
┌─────────────────────────────────────────────────────────────────────────────────────┘
│  跨网络部署架构
├─ 机器人本体 (192.168.100.105)
│  ├─ demo_api_server.py (端口5010) - 主API服务器
│  ├─ video_stream_server.py (端口5011) - 视频流服务器
│  └─ Robot SDK Services (端口50051/3232)
│
└─ PC浏览器 (192.168.100.x)
   └─ 访问 http://192.168.100.105:5010 获取GUI和API服务
```

## 部署方式

### 方式一：跨网络部署（推荐）

适用于机器人实际部署场景，在机器人本体上运行服务，PC 浏览器远程访问。

#### 机器人本体部署

```bash
# 在机器人本体上运行
cd sdk_control_panel/src
python start_servers.py
```

#### PC 浏览器访问

1. 确保 PC 和机器人在同一局域网
2. 浏览器访问：`http://192.168.100.105:5010`
3. 系统会自动检测网段并配置 API 地址
4. 输入连接参数进行连接

### 方式二：本地开发模式

适用于开发和测试，所有服务在本地运行。

#### 本地启动步骤

```bash
cd sdk_control_panel/src
python start_servers.py
```

然后浏览器访问：`http://localhost:5010`

## 环境依赖

### Python 依赖包

```bash
pip install flask flask-cors opencv-python requests
```

### 系统要求

- Python 3.7+
- 支持 WebSocket 的浏览器
- 网络连接（用于 RTSP 视频流）

## 使用说明

### 首次连接配置

1. **跨网络访问**：

   - 浏览器访问机器人 IP：`http://192.168.100.105:5010`
   - 页面自动检测并配置 API 基础 URL
   - 输入连接参数：机器人 IP 和端口

2. **连接参数**：
   - **机器人 IP**: 192.168.100.105（机器人实际 IP）
   - **GRPC 端口**: 50051（默认）
   - **WebSocket 端口**: 3232（默认）
   - **模拟器模式**: 勾选后可无机器人测试

### 功能使用指南

1. **基础机器人控制**：

   - 系统信息：获取版本、名称等信息
   - 电池监控：查看电量和充电状态
   - 姿态控制：让机器人站立或趴下
   - 灯光控制：设置不同的灯光模式
   - 运动控制：速度、高度、步态等参数调节

2. **视频流功能**：

   - **RGB 相机**: 主视角实时视频流
   - **云台相机**: 可控制的 PTZ 相机视频流
   - **动态配置**: 根据网段自动配置 RTSP 地址
   - **流媒体切换**: 支持在不同视频流间切换

3. **导航控制**：

   - **位置管理**: 添加当前位置、删除位置点
   - **导航执行**: 选择目标位置进行导航
   - **状态监控**: 查看实时导航状态和事件
   - **3D 地图**: 加载 PCD 点云地图进行可视化
   - **快速操作**: 一键设置目标、紧急停止等

4. **云台控制**：
   - **方向控制**: 使用方向按钮移动云台
   - **精确控制**: 通过滑块设置精确的移动速度
   - **预设位置**: 快速移动到预设位置
   - **实时视频**: 云台视角实时视频流
   - **停止控制**: 立即停止所有运动

### 高级功能

1. **自动断线功能**：

   - 浏览器页面关闭时自动断开机器人连接
   - 防止连接泄漏和资源占用
   - 支持页面刷新重连

2. **动态网络配置**：

   - 自动检测服务器 IP 地址
   - 根据连接网段动态配置 API URL
   - 支持不同网段的 RTSP 视频流配置

3. **跨网络视频流**：
   - 独立的视频流服务器（端口 5011）
   - 支持跨网络视频流传输
   - 实时 RTSP 流解码和 Web 显示

### 查看日志和事件

界面提供多种信息显示：

- **操作日志**: 右侧日志区域显示 API 调用结果和状态信息
- **导航事件**: 专门的导航事件日志，显示完整的 JSON 数据
- **实时状态**: 导航状态、位置信息的实时更新
- **错误信息**: 详细的错误提示和异常信息

## API 接口说明

### 连接管理

- `POST /api/connect` - 连接机器人 GRPC 和 WebSocket 服务
- `POST /api/disconnect` - 断开所有连接
- `GET /api/status` - 获取连接状态

### 机器人基础信息

- `GET /api/robot/version` - 获取 MC 版本信息
- `GET /api/robot/name` - 获取机器人名称
- `GET /api/robot/battery` - 获取电池信息
- `GET /api/robot/common_status` - 获取通用状态信息

### 机器人控制

- `POST /api/robot/posture` - 控制站立/趴下
- `POST /api/robot/driver` - 启用/禁用驱动器
- `POST /api/robot/light` - 设置灯光样式
- `POST /api/robot/velocity` - 控制机器人速度
- `POST /api/robot/height` - 调节机器人高度
- `POST /api/robot/speed_limit` - 设置速度限制
- `POST /api/robot/gait` - 设置步态模式
- `POST /api/robot/obstacle_avoidance` - 控制避障功能
- `POST /api/robot/action` - 执行预定义动作

### 导航控制

- `GET /api/nav/locations` - 获取所有导航位置点
- `POST /api/nav/location/add` - 添加新的位置点
- `DELETE /api/nav/location/delete` - 删除指定位置点
- `POST /api/nav/goto` - 导航到指定位置
- `POST /api/nav/cancel` - 取消当前导航
- `POST /api/nav/pause` - 暂停导航
- `POST /api/nav/resume` - 继续导航
- `GET /api/nav/status` - 获取导航状态
- `GET /api/nav/events` - 获取导航事件日志
- `POST /api/nav/events/clear` - 清空导航事件

### 云台控制

- `POST /api/ptz/position` - 设置云台绝对位置
- `POST /api/ptz/move` - 控制云台相对移动
- `POST /api/ptz/light` - 控制云台灯光

### 视频流服务

- `GET /video_feed/rgb` - RGB 相机视频流（通过视频服务器代理）
- `GET /video_feed/ptz` - 云台相机视频流（通过视频服务器代理）
- 实际视频服务器地址: `http://server_ip:5011/video_feed/*`

## 故障排除

### 常见问题

1. **无法访问 Web 界面**

   - 检查服务器是否正常启动（端口 5010）
   - 确认防火墙没有阻止端口访问
   - 检查 IP 地址和端口配置是否正确
   - 尝试本地访问：`http://localhost:5010`

2. **无法连接机器人**

   - 检查机器人 IP 地址和端口是否正确
   - 确认机器人服务是否正常运行（GRPC:50051, WebSocket:3232）
   - 检查网络连接是否正常
   - 尝试使用模拟器模式测试界面

3. **视频流无法显示**

   - 确认视频流服务器是否正常运行（端口 5011）
   - 检查 RTSP 地址配置是否正确
   - 确认相机设备是否正常工作
   - 检查网络带宽是否足够

4. **跨网络部署问题**

   - 确认机器人和 PC 在同一局域网
   - 检查网段配置是否正确（192.168.100.x）
   - 验证 API_BASE_URL 是否自动更新
   - 检查视频流服务器的跨网络访问

5. **导航功能无响应**

   - 确认 WebSocket 连接是否成功（端口 3232）
   - 检查导航服务是否已启动
   - 尝试清空导航事件后重新操作
   - 验证 PCD 地图文件是否存在

6. **云台控制无响应**

   - 确认 WebSocket 连接状态
   - 检查是否已调用 advertise_ptzf_cmd_vel()
   - 确认云台设备是否已正确初始化
   - 尝试停止所有运动后重新控制

7. **浏览器自动断线失效**
   - 检查浏览器是否支持 beforeunload 事件
   - 确认 sendBeacon API 可用性
   - 查看浏览器控制台错误信息

### 调试技巧

1. **查看浏览器控制台**：

   - 按 F12 打开开发者工具
   - 查看 Console 标签的错误信息和日志
   - 查看 Network 标签的 API 请求状态和响应
   - 检查 WebSocket 连接状态

2. **查看服务器日志**：

   - **主 API 服务器**: demo_api_server.py 的终端输出
   - **视频流服务器**: video_stream_server.py 的终端输出
   - 查看具体的错误信息和堆栈跟踪
   - 观察 WebSocket 连接和断开事件

3. **网络诊断**：

   - 使用 ping 命令测试机器人 IP 连通性
   - 检查端口是否开放：`telnet 192.168.100.105 5010`
   - 使用浏览器直接访问 API 测试：`http://ip:5010/api/status`
   - 检查视频流服务器：`http://ip:5011/video_feed/rgb`

4. **使用模拟器模式**：

   - 先在模拟器模式下测试界面功能
   - 确认界面逻辑正常后再连接真实机器人
   - 模拟器模式可用于功能开发和界面调试

5. **视频流调试**：

   - 检查 RTSP 地址格式是否正确
   - 使用 VLC 等播放器直接测试 RTSP 流
   - 查看 OpenCV 视频捕获状态和帧率
   - 监控视频服务器的 CPU 和内存使用

6. **导航事件调试**：
   - 查看导航事件日志的完整 JSON 数据
   - 使用导航监控功能实时查看状态
   - 检查 WebSocket 连接状态和消息流
   - 验证 PCD 文件路径和格式

### 性能优化建议

1. **视频流优化**：

   - 调整视频分辨率和帧率
   - 优化网络带宽使用
   - 使用硬件加速解码（如可用）

2. **跨网络性能**：

   - 确保稳定的 WiFi 连接
   - 减少不必要的 API 轮询
   - 优化 WebSocket 消息频率

3. **浏览器优化**：
   - 使用现代浏览器（Chrome/Firefox/Edge）
   - 启用硬件加速
   - 关闭不必要的浏览器扩展

## 界面功能详解

### 🔄 导航事件监控

- **实时事件**: 自动刷新显示最新的导航事件
- **完整数据**: 显示格式化的 JSON 数据，包含所有字段
- **事件分类**: 区分导航结果、反馈和错误信息
- **状态监控**: 实时显示当前导航状态和位置

### 📊 数据显示优化

- **自动换行**: 长文本和 JSON 数据自动换行显示
- **格式化显示**: JSON 数据使用等宽字体和缩进格式
- **颜色区分**: 不同类型的事件使用不同的颜色标识
- **滚动查看**: 日志区域支持滚动查看历史记录

### 📹 视频流集成

- **双路显示**: RGB 和云台相机同时显示
- **流媒体切换**: 支持在 RGB 和云台视角间切换
- **实时性能**: 低延迟视频流显示
- **自适应分辨率**: 根据网络条件自动调整

### 🌐 跨网络功能

- **自动配置**: 页面加载时自动检测和配置网络环境
- **动态 URL**: 根据访问 IP 自动生成 API 基础 URL
- **网段适配**: 支持不同网段的 RTSP 地址配置
- **连接管理**: 智能的连接状态管理和自动重连

## 扩展开发

### 添加新的机器人控制功能

1. **在 API 服务器中添加新接口**：

   ```python
   @app.route('/api/robot/new_function', methods=['POST'])
   def robot_new_function():
       try:
           data = request.get_json()
           # 调用SDK接口实现功能
           result = robot_client.new_function(data.get('param'))
           return jsonify({'success': True, 'data': result})
       except Exception as e:
           return jsonify({'success': False, 'message': str(e)})
   ```

2. **在 HTML 中添加对应的 UI**：

   ```html
   <div class="control-group">
     <h3>🔧 新功能控制</h3>
     <button class="btn" onclick="callNewFunction()">执行新功能</button>
     <input type="text" id="new-param" placeholder="参数值" />
   </div>
   ```

3. **在 JavaScript 中添加调用函数**：
   ```javascript
   async function callNewFunction() {
     const param = document.getElementById("new-param").value;
     try {
       const response = await fetch(`${API_BASE_URL}/robot/new_function`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ param: param }),
       });
       const result = await response.json();
       addLog(
         result.success
           ? `新功能执行成功: ${result.data}`
           : `执行失败: ${result.message}`
       );
     } catch (error) {
       addLog(`新功能调用失败: ${error.message}`);
     }
   }
   ```

### 添加新的视频流源

1. **在视频服务器中添加新的流处理**：

   ```python
   @app.route('/video_feed/new_camera')
   def new_camera_feed():
       return Response(generate_frames('new_camera'),
                      mimetype='multipart/x-mixed-replace; boundary=frame')
   ```

2. **在主 API 服务器中添加代理**：

   ```python
   @app.route('/video_feed/new_camera')
   def proxy_new_camera():
       return proxy_video_request('new_camera')
   ```

3. **在 HTML 中添加显示元素**：
   ```html
   <div class="video-container">
     <h3>🎥 新相机视频流</h3>
     <img
       id="new-camera-stream"
       src=""
       alt="新相机视频流"
       style="max-width: 100%;"
     />
     <button onclick="toggleNewCameraStream()">切换新相机</button>
   </div>
   ```

### 扩展 WebSocket 事件处理

1. **添加新的 WebSocket 事件监听**：

   ```python
   def on_new_robot_event(data):
       """处理新的机器人事件"""
       new_events.append({
           'type': 'new_event',
           'message': f"新事件: {data}",
           'timestamp': time.time(),
           'data': data
       })
   ```

2. **在前端添加事件显示**：
   ```javascript
   function displayNewEvents() {
     fetch(`${API_BASE_URL}/new_events`)
       .then((response) => response.json())
       .then((events) => {
         const container = document.getElementById("new-events");
         container.innerHTML = events
           .map((event) => `<div class="event-item">${event.message}</div>`)
           .join("");
       });
   }
   ```

### 自定义主题和样式

修改 HTML 中的 CSS 样式来个性化界面：

```css
:root {
  --primary-color: #your-color;
  --secondary-color: #your-secondary-color;
  --background-color: #your-background;
}

.custom-theme {
  background: var(--background-color);
  color: var(--primary-color);
}

.custom-button {
  background: linear-gradient(
    45deg,
    var(--primary-color),
    var(--secondary-color)
  );
  border: none;
  border-radius: 8px;
  padding: 10px 20px;
}
```

## 技术栈

### 后端技术

- **Python Flask**: Web 框架和 API 服务器
- **Flask-CORS**: 跨域资源共享支持
- **OpenCV**: 视频流处理和图像操作
- **Requests**: HTTP 请求代理和转发
- **Threading**: 多线程视频处理和 WebSocket 管理
- **daystar-robot-sdk-python**: 机器人控制 SDK

### 前端技术

- **HTML5**: 现代 Web 标准和语义化标记
- **CSS3**: 响应式布局和动画效果
- **JavaScript (ES6+)**: 原生 JavaScript，支持现代浏览器特性
- **WebSocket API**: 实时双向通信
- **Fetch API**: 现代 HTTP 请求接口
- **Three.js**: 3D 图形库，用于 PCD 点云显示

### 通信协议

- **HTTP REST API**: 主要的 API 通信方式
- **WebSocket**: 实时事件和状态更新
- **RTSP**: 实时流协议，用于视频传输
- **GRPC**: 高性能 RPC 框架，用于机器人控制

### 部署架构

- **跨网络部署**: 支持机器人本体运行，远程浏览器访问
- **进程隔离**: 主 API 服务器和视频流服务器分离
- **动态配置**: 自动网络检测和 URL 配置
- **负载均衡**: 支持多实例部署（可扩展）

## 更新日志

### v3.0 (最新)

- ✅ 添加跨网络部署支持
- ✅ 实现独立视频流服务器
- ✅ 动态 IP 检测和 URL 配置
- ✅ 自动断线功能
- ✅ 云台相机视频流集成
- ✅ 导航地图配置更新（map.pcd）
- ✅ 改进的错误处理和日志记录

### v2.0

- ✅ 云台控制功能
- ✅ 导航事件监控
- ✅ WebSocket 实时通信
- ✅ 3D 点云地图显示
- ✅ 完善的 API 接口

### v1.0

- ✅ 基础机器人控制
- ✅ Web 界面框架
- ✅ 模拟器模式
- ✅ HTTP API 服务器

## 许可证

本项目遵循与 Daystar Robot SDK 相同的许可证。
