yiliao2026/CLAUDE.md

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/                              # 构建日志

构建命令

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.123.5 m, 5 Hz（仿真）; 镭神 N10 0.1512m（实车）
• 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）