# Bobac_S 实机连接与验证指南

> 生成日期：2026-06-01
> 适用场景：虚拟机（Ubuntu 18.04 + ROS Melodic）远程连接 Bobac_S 实机

---

## 一、网络拓扑

| 设备 | IP 地址 | 说明 |
|------|---------|------|
| 手机热点 | 10.215.51.x 网段 | 提供局域网 |
| 机器人（Ubuntu） | **10.215.51.22** | ROS Master 运行于此 |
| 虚拟机（VMware） | **10.215.51.59** | 开发环境，桥接模式 |

### 虚拟机网络设置
- **网络适配器**：桥接模式（Bridged）
- **不要勾选**"复制物理网络连接状态"
- 确保虚拟机获得与机器人在同一网段的 IP（10.215.51.x）

---

## 二、ROS 分布式通信配置

### 2.1 机器人端配置（10.215.51.22）

编辑 `~/.bashrc`，确保包含：

```bash
source /opt/ros/noetic/setup.bash
source ~/bobac3_ws/devel/setup.bash

# ROS 分布式通信（机器人端）
export ROS_IP=10.215.51.22
```

生效：
```bash
source ~/.bashrc
```

> ⚠️ 机器人系统为 **ROS Noetic**（不是 Melodic）。如果 `source ~/.bashrc` 后 ROS 命令仍找不到，直接执行 `source /opt/ros/noetic/setup.bash`。

### 2.2 虚拟机端配置（10.215.51.59）

编辑 `~/.bashrc`，在 setup.bash 之后添加：

```bash
# ROS 分布式通信（虚拟机端）
export ROS_MASTER_URI=http://10.215.51.22:11311
export ROS_IP=10.215.51.59
```

生效：
```bash
source ~/.bashrc
```

---

## 三、启动硬件节点（在机器人上执行）

### 3.1 启动 ROS Master

```bash
source /opt/ros/noetic/setup.bash
source ~/bobac3_ws/devel/setup.bash
roscore
```
> 保持终端运行，不要关闭。

### 3.2 启动底盘驱动

新开终端：
```bash
source /opt/ros/noetic/setup.bash
source ~/bobac3_ws/devel/setup.bash
roslaunch rei_robot_base base.launch
```

### 3.3 启动激光雷达

新开终端：
```bash
source /opt/ros/noetic/setup.bash
source ~/bobac3_ws/devel/setup.bash
roslaunch cspc_lidar bobac3_lidar.launch
```

**启动后验证**（必须做）：
```bash
source /opt/ros/noetic/setup.bash
source ~/bobac3_ws/devel/setup.bash
# 前雷达必须有数据
rostopic hz /front_lidar/scan
# 后雷达也必须有数据
rostopic hz /rear_lidar/scan
# 融合雷达必须有数据
rostopic hz /fuse_scan
```

> ⚠️ 如果 `/rear_lidar/scan` 或 `/fuse_scan` 没有数据，雷达融合失败，后续 gmapping 无法建图。重启雷达 launch 或检查硬件连接。

**说明**：实机配置为**前后双雷达**，通过 `laserscan_multi_merger` 融合为 `/fuse_scan`。

### 3.4 启动相机（可选）

```bash
source /opt/ros/noetic/setup.bash
source ~/bobac3_ws/devel/setup.bash
roslaunch berxel_camera berxel_base_color.launch
```

### 3.5 启动导航（可选，需加载地图）

```bash
source /opt/ros/noetic/setup.bash
source ~/bobac3_ws/devel/setup.bash
roslaunch bobac3_navigation bobac3_nav_2d.launch
```

---

## 四、验证通信（在虚拟机上执行）

### 4.1 基础验证

```bash
source ~/.bashrc

# 查看话题列表
rostopic list

# 查看运行节点
rosnode list

# 查看 tf 树
rosrun tf view_frames
```

### 4.2 传感器数据验证

```bash
source ~/.bashrc

# 融合雷达数据频率（正常约 10-20Hz）
rostopic hz /fuse_scan

# 里程计数据频率
rostopic hz /odom

# 查看雷达原始数据
rostopic echo /fuse_scan

# 查看里程计
rostopic echo /odom

# 查看相机图像（实际话题名）
rostopic hz /bobac3_base/rgb/rgb_raw
```

### 4.3 预期话题列表（底盘+雷达启动后）

| 话题名 | 类型 | 来源 |
|--------|------|------|
| `/fuse_scan` | LaserScan | 前后雷达融合 |
| `/front_lidar/scan` | LaserScan | 前雷达原始数据 |
| `/rear_lidar/scan` | LaserScan | 后雷达原始数据 |
| `/odom` | Odometry | 底盘里程计 |
| `/cmd_vel` | Twist | 速度指令（订阅） |
| `/tf` | TFMessage | 坐标变换 |
| `/tf_static` | TFMessage | 静态坐标变换 |

### 4.4 预期节点列表

| 节点名 | 功能 |
|--------|------|
| `/front_lidar/front_lidar` | 前雷达驱动 |
| `/rear_lidar/rear_lidar` | 后雷达驱动 |
| `/laserscan_multi_merger` | 雷达数据融合 |
| `/rei_base` | 底盘驱动 |
| `/rosout` | ROS 日志 |

---

## 五、常见问题排查

### 5.1 `rostopic list` 为空或报错

1. 确认机器人 `roscore` 已启动
2. 确认两边 `source ~/.bashrc` 已执行
3. 互相 ping 测试：`ping 10.215.51.22`（虚拟机） / `ping 10.215.51.59`（机器人）
4. 关闭防火墙：`sudo ufw disable`

### 5.2 没有 `/scan` 话题

实机使用 **双雷达融合方案**，导航时应使用 `/fuse_scan` 而非 `/scan`。`bobac3_nav_2d.launch` 中应已配置正确。

### 5.3 虚拟机 IP 不在 10.215.51.x 网段

检查 VMware 网络适配器是否为**桥接模式**，并确认桥接到正确的物理网卡（无线网卡）。

### 5.4 `roslaunch bobac3_bringup bringup.launch` 报错

机器人上**没有 `bobac3_bringup` 包**。实机启动请使用：
- `rei_robot_base/base.launch`（底盘）
- `cspc_lidar/bobac3_lidar.launch`（雷达）

### 5.5 rviz 中地图全黑 / gmapping 无地图

排查步骤（按顺序）：

1. **检查雷达数据**（最关键）：
   ```bash
   rostopic hz /front_lidar/scan   # 应有 ~10Hz
   rostopic hz /rear_lidar/scan    # 应有 ~10Hz
   rostopic hz /fuse_scan          # 应有 ~10Hz
   ```
   如果 `/fuse_scan` 无数据，前后雷达正常，**检查 4 个 TF 是否全部启动**（见 8.3 节）。

2. **检查 TF 树**：
   ```bash
   rosrun tf tf_echo odom base_link
   rosrun tf tf_echo base_link fuse_lidar_link
   ```
   如果报错 `does not exist`，启动 TF 修复（见 8.3 节）。

3. **确认机器人在移动**：gmapping 需要机器人移动才能生成地图，原地不动时 `/map` 是空的。

### 5.6 机器人自动偏移（不按转向键也会转弯）

底盘左右轮电机速度不一致导致。前进时轻微按转向键补偿，或在底盘驱动参数中校准。

---

## 六、SSH 连接机器人（用于远程查询）

```bash
ssh bobac3@10.215.51.22
# 密码：root
```

**红线**：SSH 登录机器人后**只执行只读操作**（查看、查询），禁止修改机器人系统上的任何文件、环境和配置。所有代码修改在虚拟机上完成，通过 ROS 分布式部署运行。

---

## 七、关键 Launch 文件索引（机器人系统）

| 功能 | 包名 | Launch 文件 |
|------|------|------------|
| 底盘驱动 | `rei_robot_base` | `launch/base.launch` |
| 激光雷达 | `cspc_lidar` | `launch/bobac3_lidar.launch` |
| 彩色相机 | `berxel_camera` | `launch/berxel_base_color.launch` |
| 深度相机 | `berxel_camera` | `launch/berxel_base_depth.launch` |
| 实机导航 | `bobac3_navigation` | `launch/bobac3_nav_2d.launch` |
| AMCL 定位 | `bobac3_navigation` | `launch/amcl.launch` |
| 地图服务 | `bobac3_navigation` | `launch/map_server.launch` |
| 语音唤醒 | `robot_audio` | `launch/voice_awake.launch` |
| 语音交互 | `robot_audio` | `launch/voice_interaction.launch` |
| 人脸识别 | `face_rec` | `launch/face_rec_topic.launch` |
| 自动充电 | `auto_charging` | `launch/`（需确认） |

## 八、建图操作（gmapping）

### 8.1 启动建图前准备（一键脚本）

**推荐**：使用一键启动脚本（已放置在机器人 `~/start_slam.sh`）：

```bash
source /opt/ros/noetic/setup.bash
~/start_slam.sh
```

脚本会自动：启动底盘（如未启动）→ 启动雷达（如未启动）→ 发布 4 个 TF 修复 → 启动 gmapping。

**或手动逐个启动**：
```bash
# 终端1：底盘
source /opt/ros/noetic/setup.bash
source ~/bobac3_ws/devel/setup.bash
roslaunch rei_robot_base base.launch

# 终端2：雷达
source /opt/ros/noetic/setup.bash
source ~/bobac3_ws/devel/setup.bash
roslaunch cspc_lidar bobac3_lidar.launch
```

**验证雷达数据**（必须做）：
```bash
source /opt/ros/noetic/setup.bash
source ~/bobac3_ws/devel/setup.bash
rostopic hz /front_lidar/scan   # 应有 ~10Hz
rostopic hz /rear_lidar/scan    # 应有 ~10Hz
rostopic hz /fuse_scan          # 应有 ~10Hz
```

### 8.2 启动 gmapping

**机器人上**新开终端：
```bash
source /opt/ros/noetic/setup.bash
source ~/bobac3_ws/devel/setup.bash
roslaunch bobac3_slam bobac3_gmapping.launch
```

### 8.3 修复 TF 树（必须做）

机器人底盘驱动没有发布完整的 TF 树，gmapping 和雷达融合节点需要以下 TF 才能工作：

**机器人上**新开终端，一次性执行全部 4 个 TF 发布：

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

# 1. base_footprint -> base_link（底盘到 base）
rosrun tf static_transform_publisher 0 0 0 0 0 0 base_footprint base_link 100 &

# 2. base_link -> front_lidar_link（前雷达）
rosrun tf static_transform_publisher 0.2 0 0.3 0 0 0 base_link front_lidar_link 100 &

# 3. base_link -> rear_lidar_link（后雷达，朝后 180 度）
rosrun tf static_transform_publisher -0.2 0 0.3 3.14159 0 0 base_link rear_lidar_link 100 &

# 4. base_link -> fuse_lidar_link（融合雷达）
rosrun tf static_transform_publisher 0 0 0.3 0 0 0 base_link fuse_lidar_link 100 &

echo "TF 修复已启动"
```

> 保持此终端运行，不要关闭。

> ⚠️ **遗漏任何一个 TF 都会导致 `/fuse_scan` 无数据或地图不更新。**

### 8.4 启动 rviz 查看地图

**机器人上**新开终端：
```bash
source /opt/ros/noetic/setup.bash
source ~/bobac3_ws/devel/setup.bash
rviz
```

在 rviz 中配置：
1. **Global Options** → **Fixed Frame** 改为 **`map`**
2. 左下角 **Add** → 选择 **Map** → **OK**
3. 右侧 **Topic** 栏选择 `/map`
4. 勾选 **Map** 显示
5. （可选）**Add** → **LaserScan** → Topic 选 `/fuse_scan`，看雷达扫描线

> ⚠️ **如果 rviz 中地图全黑**：
> 1. 检查 TF 修复节点（8.3）是否已启动
> 2. 检查雷达数据是否正常（`rostopic hz /fuse_scan`）
> 3. 让机器人动起来，gmapping 需要移动才能生成地图

### 8.5 键盘遥控建图（在机器人上操作）

**注意**：机器人系统为 **ROS Noetic**，所有操作在**机器人终端**执行。

#### 安装键盘遥控包（首次使用）

**机器人上**：
```bash
sudo apt-get install ros-noetic-teleop-twist-keyboard
```

#### 启动键盘遥控

**机器人上**新开终端：
```bash
source /opt/ros/noetic/setup.bash
source ~/bobac3_ws/devel/setup.bash
rosrun teleop_twist_keyboard teleop_twist_keyboard.py
```

#### 按键映射（源码级确认）

| 操作 | 按键 | 说明 |
|------|------|------|
| **前进** | **`i`** | 按住不放 |
| **后退** | **`,`** | 按住不放 |
| **左转** | **`j`** | 按住不放 |
| **右转** | **`l`** | 按住不放 |
| **停止** | **松开按键** 或 **`k`** | 松开任何键即停止 |
| **加速** | **`q`** | 速度 × 1.1 |
| **减速** | **`z`** | 速度 × 0.9 |

> ⚠️ **`z` 是减速，不是前进**。如果按 `z` 时机器人向前走，是因为之前按了 `i` 没停，`z` 只是降低了速度。

#### 建图前检查

1. **急停按钮**：确认机器人上的红色急停按钮**已弹起**（顺时针旋转）。如果按下，底盘不会响应任何速度指令。
2. **速度调整**：按 `z` 几次将速度降到 `0.1` 左右，慢速建图更精确。

#### 建图路线

```
出发区 → 卧室 → 客厅 → 餐厅 → 厨房 → 回到出发区
```

**要点**：
- 速度控制在 **0.1 m/s 以下**
- 贴着墙走，每个房间走遍（包括角落）
- 每到一个新区域，**原地旋转一圈**（`j` 或 `l` 按住不放），让雷达扫全
- 最后必须回到出发点（回环闭合，gmapping 自动修正地图）

### 8.6 保存地图

**机器人上**执行：
```bash
source /opt/ros/noetic/setup.bash
source ~/bobac3_ws/devel/setup.bash
rosrun map_server map_saver -f ~/.reinovo/maps/home_scene
```

生成文件：
- `~/.reinovo/maps/home_scene.pgm` — 地图图像
- `~/.reinovo/maps/home_scene.yaml` — 地图参数

### 8.7 手柄遥控（备用方案）

如果手柄可用，启动方式：
```bash
source /opt/ros/noetic/setup.bash
source ~/bobac3_ws/devel/setup.bash
roslaunch robot_joy robot_joy.launch
```

**手柄按键（X360布局）**：
| 操作 | 按键 |
|------|------|
| 前进/后退 | 左摇杆 上下 |
| 左转/右转 | 左摇杆 左右 |
| 加速 | RT 扳机键 |
| 减速 | LT 扳机键 |
| 速度上限+ | A 键 |
| 速度上限- | B 键 |

> ⚠️ 手柄需要用户 `bobac3` 在 `input` 组，否则无数据。若不在，执行 `sudo usermod -a -G input bobac3` 后重新登录。

---

*本文档基于 2026-06-01 实机连接验证结果编写，2026-06-06 修正 ROS 版本、添加完整 TF 修复（4 个）、雷达验证、一键启动脚本、故障排查等关键步骤。*