# robot-client

**Repository Path**: xiaobairisk/robot-client

## Basic Information

- **Project Name**: robot-client
- **Description**: 用于roboflow远程连接的客户端代码
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-12
- **Last Updated**: 2026-01-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RoboFlow 机器人桥接客户端

这是一个运行在机器人端的 Python 客户端，用于将机器人连接到 RoboFlow 云端服务器，实现远程监控和控制。

## 架构

```
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│   浏览器/手机    │ ──────> │  RoboFlow 服务器 │ <────── │   机器人        │
│                 │         │  (公网)          │         │  + Bridge 客户端│
└─────────────────┘         └─────────────────┘         └─────────────────┘
        │                           │                           │
        │ /ws/client               │                           │ /ws/robot
        │ (浏览器连接)              │                           │ (机器人连接)
        └───────────────────────────┴───────────────────────────┘
                                    │
                                    │ WebSocket
                                    │ 双向通信
                                    ▼
                            ┌─────────────────┐
                            │   ROS2 话题      │
                            │   /cmd_vel      │
                            │   /odom         │
                            │   /scan         │
                            └─────────────────┘
```

## 文件说明

| 文件 | 需要 foxglove_bridge | 需要 ROS2 | 说明 |
|------|---------------------|-----------|------|
| `ros2_bridge_v2.py` | ❌ | ✅ | **推荐** - v2.0 优化版，支持二进制协议+LZ4压缩 |
| `ros2_bridge.py` | ❌ | ✅ | v1.0 版本，JSON 协议 |
| `foxglove_tunnel.py` | ✅ | ✅ | Foxglove 透明隧道，完全兼容 Foxglove 协议 |
| `terminal_server.py` | ❌ | ❌ | 远程终端服务，支持 Web SSH |
| `test_bridge.py` | ❌ | ❌ | 测试用模拟机器人 |
| `roboflow_bridge.py` | ❌ | ✅ | 旧版桥接（需手动配置话题） |
| `ros2_bridge.yaml.example` | - | - | v2.0 配置文件示例 |
| `requirements.txt` | - | - | Python 依赖 |

## 两种连接模式

### 模式 1: ROS2 自动桥接 v2.0（推荐）

v2.0 版本参考 Foxglove WebSocket 协议和 cobridge 设计，大幅优化了带宽和稳定性。

```
浏览器 <---> 云端服务器 <---> ros2_bridge_v2.py <---> ROS2 (所有话题)
```

**v2.0 优化内容**：
- ✅ **二进制协议** - 使用 ROS2 CDR 原生序列化，比 JSON 小 50%+
- ✅ **LZ4 压缩** - 高速压缩，进一步减少 30-70% 带宽
- ✅ **自适应采样** - 根据带宽自动调整发送频率
- ✅ **优先级队列** - 控制命令优先，大数据延后
- ✅ **配置文件支持** - 支持 YAML 配置文件和环境变量
- ✅ **完善的异常处理** - 更稳定，减少闪退

**使用方法**：

```bash
# 方式 1: 使用配置文件（推荐）
cp ros2_bridge.yaml.example ros2_bridge.yaml
# 编辑配置文件
python3 ros2_bridge_v2.py

# 方式 2: 使用环境变量
export BRIDGE_SERVER_URL=wss://39.106.224.176/ws/robot
export BRIDGE_ROBOT_ID=robot-001
python3 ros2_bridge_v2.py

# 方式 3: 命令行参数
python3 ros2_bridge_v2.py \
    -s wss://39.106.224.176/ws/robot \
    -r robot-001

# 指定压缩方式
python3 ros2_bridge_v2.py \
    -s wss://39.106.224.176/ws/robot \
    -r robot-001 \
    --compression lz4

# 只桥接特定话题
python3 ros2_bridge_v2.py \
    -s wss://39.106.224.176/ws/robot \
    -r robot-001 \
    --include /cmd_vel /odom /scan /map
```

**配置文件示例** (`ros2_bridge.yaml`):

```yaml
server_url: wss://your-server.com/ws/robot
robot_id: robot-001
compression: lz4
max_publish_rate: 30
use_binary_protocol: true

topic_configs:
  /cmd_vel:
    max_rate: 50
    priority: 1
  /camera/image_raw:
    max_rate: 5
    priority: 8
```

### 模式 1b: ROS2 自动桥接 v1.0（兼容旧版）

如果服务端不支持二进制协议，可以使用 v1.0 版本。

```bash
python3 ros2_bridge.py \
    -s wss://39.106.224.176/ws/robot \
    -r robot-001
```

### 模式 2: Foxglove 透明隧道（完全兼容 Foxglove）

如果你需要完全兼容 Foxglove 协议（如使用 Foxglove Studio），使用此模式。

```
浏览器 <---> 云端服务器 <---> foxglove_tunnel.py <---> foxglove_bridge <---> ROS2
```

**优点**：
- ✅ 完全兼容 Foxglove 协议（二进制）
- ✅ 可以使用 Foxglove Studio 连接
- ✅ 支持所有 Foxglove 功能

**使用方法**：

```bash
# 1. 启动 foxglove_bridge（ROS2 环境）
ros2 launch foxglove_bridge foxglove_bridge_launch.xml port:=8765

# 2. 启动隧道
python3 foxglove_tunnel.py \
    -s wss://39.106.224.176/ws/tunnel \
    -r robot-001 \
    -l ws://localhost:8765
```

浏览器连接地址：`ws://39.106.224.176/ws/foxglove/robot-001`

## 安装

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 如果需要 ROS2 支持（生产环境）

确保已安装 ROS2 并 source 了环境：

```bash
source /opt/ros/humble/setup.bash
```

## 快速测试

### 测试 ROS2 自动桥接（推荐）

```bash
# 确保 ROS2 环境已 source
source /opt/ros/humble/setup.bash

# 启动桥接
python3 ros2_bridge.py -s ws://localhost:3001/ws/robot -r test-robot-001
```

### 测试模拟机器人（无需 ROS2）

使用测试脚本模拟一个机器人连接到服务器：

```bash
# 连接到本地开发服务器
python3 test_bridge.py -s ws://localhost:3001/ws/robot -r test-robot-001

# 连接到生产服务器
python3 test_bridge.py -s ws://39.106.224.176/ws/robot -r test-robot-001
```

测试脚本会：
- 模拟机器人运动（响应 /cmd_vel 命令）
- 发送模拟的里程计数据 (/odom)
- 发送模拟的激光雷达数据 (/scan)
- 定期发送心跳

### 测试 Foxglove 隧道

```bash
# 如果没有 ROS2 环境，可以用 Docker 运行 foxglove_bridge
docker run -p 8765:8765 foxglove/bridge

# 启动隧道
python3 foxglove_tunnel.py -s ws://localhost:3001/ws/tunnel -r test-robot-001 -l ws://localhost:8765
```

## 使用方法

### 基本用法

```bash
python3 roboflow_bridge.py \
    --server wss://your-server.com/ws/robot \
    --robot-id robot-001 \
    --token your-secret-token
```

### 参数说明

| 参数 | 简写 | 必需 | 说明 |
|------|------|------|------|
| `--server` | `-s` | ✅ | 服务器 WebSocket URL |
| `--robot-id` | `-r` | ✅ | 机器人唯一标识 |
| `--token` | `-t` | ❌ | 认证 Token（默认: default-token） |
| `--reconnect-interval` | | ❌ | 重连间隔秒数（默认: 5） |
| `--heartbeat-interval` | | ❌ | 心跳间隔秒数（默认: 10） |

### 示例

连接到本地开发服务器：

```bash
python3 roboflow_bridge.py -s ws://localhost:3001/ws/robot -r robot-001
```

连接到生产服务器：

```bash
python3 roboflow_bridge.py -s wss://39.106.224.176/ws/robot -r robot-001 -t my-secret-token
```

## 作为系统服务运行

### 创建 systemd 服务

```bash
sudo nano /etc/systemd/system/roboflow-bridge.service
```

内容：

```ini
[Unit]
Description=RoboFlow Bridge Client
After=network.target

[Service]
Type=simple
User=robot
WorkingDirectory=/home/robot/roboflow-bridge
ExecStart=/usr/bin/python3 roboflow_bridge.py -s wss://your-server.com/ws/robot -r robot-001 -t your-token
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

启用并启动服务：

```bash
sudo systemctl daemon-reload
sudo systemctl enable roboflow-bridge
sudo systemctl start roboflow-bridge
```

查看日志：

```bash
sudo journalctl -u roboflow-bridge -f
```

## 支持的话题

### 机器人 → 云端（上报数据）

| 话题 | 消息类型 | 说明 |
|------|----------|------|
| `/odom` | nav_msgs/Odometry | 里程计数据 |
| `/scan` | sensor_msgs/LaserScan | 激光雷达数据 |
| `/tf` | tf2_msgs/TFMessage | 坐标变换 |

### 云端 → 机器人（控制命令）

| 话题 | 消息类型 | 说明 |
|------|----------|------|
| `/cmd_vel` | geometry_msgs/Twist | 速度控制 |
| `/goal_pose` | geometry_msgs/PoseStamped | 导航目标 |
| `/initialpose` | geometry_msgs/PoseWithCovarianceStamped | 初始位姿 |

## 消息协议

### 机器人注册

```json
{
  "type": "register",
  "robotId": "robot-001",
  "token": "secret-token",
  "capabilities": ["ros2", "navigation", "teleop"]
}
```

### 心跳

```json
{
  "type": "heartbeat",
  "robotId": "robot-001",
  "timestamp": 1704067200000,
  "status": {
    "cpu": 45,
    "memory": 60,
    "battery": 85
  }
}
```

### 话题数据

```json
{
  "type": "topic_data",
  "robotId": "robot-001",
  "topic": "/odom",
  "timestamp": 1704067200000,
  "data": { ... }
}
```

## 故障排除

### 连接失败

1. 检查服务器地址是否正确
2. 检查网络连接
3. 确认服务器端口已开放

### ROS2 话题无数据

1. 确认 ROS2 环境已 source
2. 检查话题名称是否正确
3. 使用 `ros2 topic list` 确认话题存在

### 频繁断线

1. 检查网络稳定性
2. 调整心跳间隔
3. 查看服务器日志

## License

MIT


## 远程终端（Web SSH）

在机器人端启动终端服务，即可通过 Web 界面远程访问机器人的 Shell。

### 启动终端服务

```bash
python3 terminal_server.py \
    -s wss://39.106.224.176/ws/terminal-server \
    -r robot-001
```

### 参数说明

| 参数 | 说明 |
|------|------|
| `--server`, `-s` | 服务器 WebSocket URL |
| `--robot-id`, `-r` | 机器人 ID |
| `--shell` | Shell 程序（默认: /bin/bash） |

### 作为系统服务运行

```bash
sudo nano /etc/systemd/system/roboflow-terminal.service
```

```ini
[Unit]
Description=RoboFlow Terminal Server
After=network.target

[Service]
Type=simple
User=robot
ExecStart=/usr/bin/python3 /home/robot/roboflow-bridge/terminal_server.py -s wss://your-server.com/ws/terminal-server -r robot-001
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl daemon-reload
sudo systemctl enable roboflow-terminal
sudo systemctl start roboflow-terminal
```

## 一键启动所有服务

创建一个启动脚本 `start_all.sh`：

```bash
#!/bin/bash
# RoboFlow 机器人端一键启动脚本

SERVER_URL="wss://your-server.com"
ROBOT_ID="robot-001"

# 方式 1: 使用 ROS2 自动桥接（推荐）
echo "启动 ROS2 自动桥接..."
python3 ros2_bridge.py \
    -s ${SERVER_URL}/ws/robot \
    -r ${ROBOT_ID} &

# 启动终端服务
echo "启动终端服务..."
python3 terminal_server.py \
    -s ${SERVER_URL}/ws/terminal-server \
    -r ${ROBOT_ID} &

echo "所有服务已启动"
wait
```

或者使用 Foxglove 隧道模式：

```bash
#!/bin/bash
# RoboFlow 机器人端一键启动脚本（Foxglove 模式）

SERVER_URL="wss://your-server.com"
ROBOT_ID="robot-001"

# 启动 foxglove_bridge
echo "启动 foxglove_bridge..."
ros2 launch foxglove_bridge foxglove_bridge_launch.xml port:=8765 &
sleep 3

# 启动隧道
echo "启动 Foxglove 隧道..."
python3 foxglove_tunnel.py \
    -s ${SERVER_URL}/ws/tunnel \
    -r ${ROBOT_ID} \
    -l ws://localhost:8765 &

# 启动终端服务
echo "启动终端服务..."
python3 terminal_server.py \
    -s ${SERVER_URL}/ws/terminal-server \
    -r ${ROBOT_ID} &

echo "所有服务已启动"
wait
```

## 端点说明

| 端点 | 说明 |
|------|------|
| `/ws/tunnel` | 机器人 Foxglove 隧道连接 |
| `/ws/foxglove/:robotId` | 浏览器 Foxglove 连接 |
| `/ws/robot` | 机器人 JSON 网关连接 |
| `/ws/client` | 浏览器 JSON 网关连接 |
| `/ws/terminal-server/:robotId` | 机器人终端服务连接 |
| `/ws/terminal/:robotId` | 浏览器终端连接 |