166 lines
7.7 KiB
Markdown
166 lines
7.7 KiB
Markdown
# CLAUDE.md
|
||
|
||
## 项目概述
|
||
|
||
这是一个 ROS 2 Humble 工作空间，用于 Ackermann 转向小车的 Gazebo 仿真、SLAM 建图和 Nav2 导航。同时支持实车部署（无 Gazebo）。
|
||
|
||
## 工作空间结构
|
||
|
||
```
|
||
test_ws/
|
||
├── src/
|
||
│ ├── gc_navigation2_slamtoolbox/ # 仿真版：导航+SLAM 启动文件和配置
|
||
│ │ ├── launch/ # Python launch 文件
|
||
│ │ ├── config/ # slam_toolbox 参数
|
||
│ │ ├── params/ # Nav2 参数
|
||
│ │ ├── maps/ # 地图文件 (.pgm, .yaml, .posegraph)
|
||
│ │ └── world/ # Gazebo 模型 (zhihui/)
|
||
│ ├── gc_navigation2_real/ # 实车版：导航+SLAM 启动文件和配置（无 Gazebo）
|
||
│ │ ├── launch/ # Python launch 文件
|
||
│ │ ├── config/ # slam_toolbox 参数（实车调优）
|
||
│ │ ├── params/ # Nav2 参数（use_sim_time=false）
|
||
│ │ ├── maps/ # 实车地图存放目录
|
||
│ │ └── behavior_tree/ # 阿克曼自定义行为树
|
||
│ ├── origincar_description/ # 机器人 URDF 和 Gazebo world
|
||
│ │ ├── urdf/ # origincar.urdf
|
||
│ │ ├── world/ # .world 文件
|
||
│ │ ├── meshes/ # 3D 模型
|
||
│ │ ├── launch/ # display.launch.py
|
||
│ │ └── rviz/ # RViz 配置
|
||
│ ├── origincar_base/ # 实车底盘驱动（串口通信+EKF+IMU融合）
|
||
│ │ ├── src/ # C++ 源码（origincar_base.cpp）
|
||
│ │ ├── scripts/ # cmd_vel_to_ackermann_drive.py
|
||
│ │ ├── launch/ # origincar_bringup / base_serial / ekf
|
||
│ │ └── config/ # ekf.yaml / imu.yaml
|
||
│ ├── origincar_msg/ # 自定义 ROS 2 消息
|
||
│ │ └── msg/ # Data.msg / Sign.msg
|
||
│ └── LSLIDAR_X_ROS2-20240228/ # 镭神激光雷达 ROS 2 驱动
|
||
│ └── src/
|
||
│ ├── lslidar_driver/ # 雷达驱动核心
|
||
│ └── lslidar_msgs/ # 雷达消息定义
|
||
├── build/ # colcon build 输出
|
||
├── install/ # colcon install 输出 (含符号链接)
|
||
└── log/ # 构建日志
|
||
```
|
||
|
||
## 构建命令
|
||
|
||
```bash
|
||
cd /home/guoch/test_ws
|
||
source /opt/ros/humble/setup.bash
|
||
colcon build --symlink-install
|
||
source install/setup.bash
|
||
```
|
||
|
||
## 常用 Launch 文件
|
||
|
||
### 仿真版 (gc_navigation2_slamtoolbox)
|
||
|
||
| 文件 | 功能 |
|
||
|------|------|
|
||
| `gc_slam_mapping.launch.py` | Gazebo + SLAM 建图模式 |
|
||
| `gc_nav2_with_slam_online.launch.py` | 已知地图 + SLAM 在线更新 + Nav2 导航 |
|
||
| `gc_nav2_with_slam.launch.py` | 已知地图 + SLAM 定位 + Nav2 导航 |
|
||
| `gc_nav2_with_amcl.launch.py` | AMCL 定位 + Nav2 导航 |
|
||
|
||
### 实车版 (gc_navigation2_real)
|
||
|
||
| 文件 | 功能 |
|
||
|------|------|
|
||
| `real_bringup.launch.py` | 基础 bringup（底盘驱动+雷达+TF，无导航） |
|
||
| `real_slam_mapping.launch.py` | 实车 SLAM 建图模式 |
|
||
| `real_nav2_slam.launch.py` | 已知地图 + SLAM 定位 + Nav2 导航 |
|
||
| `real_nav2_slam_online.launch.py` | 已知地图 + SLAM 在线更新 + Nav2 导航 |
|
||
|
||
## 机器人参数 (origincar)
|
||
|
||
- **类型**: Ackermann 转向小车
|
||
- **尺寸**: 0.276 × 0.214 × 0.211 m (长×宽×高)
|
||
- **轴距**: 0.143 m（URDF 中前轮 x=0.0715，后轮 x=-0.0715），**轮距**: 0.189 m
|
||
- **轮子**: 半径 0.03 m，厚 0.025 m
|
||
- **激光雷达**: 360°, 0.12~3.5 m, 5 Hz（仿真）; 镭神 N10 0.15~12m（实车）
|
||
- **IMU**: 100 Hz, 含高斯噪声
|
||
- **Gazebo 插件**: `gazebo_ros_ackermann_drive`, `gazebo_ros_ray_sensor`, `gazebo_ros_imu_sensor`
|
||
|
||
## 实车 TF 树
|
||
|
||
```
|
||
map ──→ odom_combined ──→ base_footprint ──→ base_link ──→ laser
|
||
↑ ↑ ↑ ↑
|
||
slam_toolbox EKF static TF URDF/static
|
||
(定位) (融合odom+IMU) (origincar_bringup)
|
||
```
|
||
|
||
- slam_toolbox 发布 `map → odom_combined`
|
||
- EKF 发布 `odom_combined → base_footprint`
|
||
- origincar_bringup 发布 `base_footprint → base_link`（z=0）、`base_link → laser`
|
||
- robot_state_publisher 发布 URDF 各连杆 TF
|
||
|
||
### 仿真 vs 实车关键差异
|
||
|
||
| 方面 | 仿真版 | 实车版 |
|
||
|------|--------|--------|
|
||
| use_sim_time | `true` | `false` |
|
||
| odom_frame | `odom` | `odom_combined`（EKF 融合后） |
|
||
| 底盘驱动 | Gazebo plugin | origincar_base 串口驱动 |
|
||
| 激光雷达 | Gazebo ray plugin | lslidar_driver（镭神 N10） |
|
||
| robot_state_publisher | launch 文件内启动 | origincar_bringup 已包含，勿重复启动 |
|
||
| joint_state_publisher | launch 文件内启动 | origincar_bringup 已包含，勿重复启动 |
|
||
|
||
## 阿克曼底盘模式
|
||
|
||
通过 `akmcar` 参数控制，链路如下：
|
||
|
||
```
|
||
origincar_bringup.launch.py
|
||
└─ akmcar=LaunchConfiguration('akmcar', default='true')
|
||
└─ 传入 base_serial.launch.py
|
||
├─ IfCondition(true) → origincar_base_node (akm_cmd_vel='ackermann_cmd')
|
||
│ + cmd_vel_to_ackermann_drive.py (Twist→Ackermann)
|
||
└─ UnlessCondition(false) → 差速模式（跳过）
|
||
```
|
||
|
||
数据流：`MPPI cmd_vel(Twist) → cmd_vel_to_ackermann_drive.py → ackermann_cmd(AckermannDriveStamped) → STM32`
|
||
|
||
关键参数：
|
||
- `cmd_vel_to_ackermann_drive.py`: `wheelbase = 0.143`（与 URDF 一致）
|
||
- `akmcar=true` 时 STM32 接收 `speed + steering_angle`
|
||
- `akmcar=false` 时 STM32 接收 `vx + vy + wz`（固件自行转换）
|
||
|
||
## 关键设计
|
||
|
||
1. **map_server** 提供全量静态底图（`/map`）
|
||
2. **slam_toolbox** 负责定位和增量建图，重映射 `/map` → `/slam_map` 避免冲突
|
||
3. **Nav2** 使用 `global_costmap/static_layer ← /map` + `local_costmap/obstacle_layer ← /scan`
|
||
4. 保存地图: `ros2 service call /slam_toolbox/serialize_map ...`
|
||
5. 实车版 launch 文件**不应**自行启动 `robot_state_publisher` 和 `joint_state_publisher`，`origincar_bringup` 已包含
|
||
|
||
## 地图文件
|
||
|
||
地图放在 `src/gc_navigation2_slamtoolbox/maps/`（仿真）和 `src/gc_navigation2_real/maps/`（实车），包含:
|
||
- `xxx.pgm` — 地图图像
|
||
- `xxx.yaml` — 地图元数据 (resolution, origin, thresholds)
|
||
- `xxx.posegraph` — 序列化的位姿图
|
||
|
||
## Gazebo World
|
||
|
||
World 文件在 `src/origincar_description/world/`:
|
||
- `zhihui.world` — 智慧楼墙体环境（内联模型）
|
||
- `test.world` — 测试环境
|
||
- `fishbot.world` / `gc_world.world` — 其他场景
|
||
|
||
## 实车底盘驱动包 (origincar_base)
|
||
|
||
- `origincar_base_node`（C++）: 串口读写（/dev/ttyACM0, 115200bps）、航迹推算、四元数姿态解算（Mahony AHRS）
|
||
- `cmd_vel_to_ackermann_drive.py`（Python）: Twist → AckermannDriveStamped 转换，wheelbase=0.143
|
||
- 帧协议: 24 字节收（帧头0x7B/帧尾0x7D）/ 11 字节发
|
||
- EKF 融合: `/odom` + IMU → `/odom_combined`，`two_d_mode=true`
|
||
|
||
## 注意事项
|
||
|
||
- 使用 `--symlink-install` 构建，Python launch 文件修改后无需重新编译
|
||
- `.world` 文件不应使用 `model://` 外部引用，应将模型内联定义
|
||
- `robot_base_frame` 在 ackermann plugin 中应设为 `base_footprint`
|
||
- 实车 `gc_navigation2_real` 的 launch 文件调用 `origincar_bringup.launch.py` 时，不再重复启动 `robot_state_publisher` 和 `joint_state_publisher`
|
||
- 轴距参数在三处需保持一致：URDF（0.143m）、`cmd_vel_to_ackermann_drive.py`（0.143m）、Nav2 planner `minimum_turning_radius`（0.40m）
|