---
本仓库是一套**底盘无关**的移动机器人自主导航系统：NeuPAN 规划内核支持差速（`diff`）与阿克曼（`acker`）两类运动学，最终只输出一条与底盘无关的速度指令 `/cmd_vel`（`linear.x` 前进 + `angular.z` 转向）。换底盘 = 换一个“`/cmd_vel` 桥接层”而已，规划器一行不改。目前仓库内置两种桥接：
- **YHS 轮式底盘**（差速 DT / 阿克曼 FW / 四轮 FR / 麦克纳姆 MK）——通过 SocketCAN（PCAN-USB）直连，`yhs_can_control` 驱动。**当前默认底盘。**
- **四足机器人**（FireDog / Unitree Go2）——通过 TCP（tiji SDK）或串口桥接，同样吃 `/cmd_vel`。
系统以 **Odin1** 空间感知模块（3D SLAM 建图 + 重定位，输出点云 / 里程计 / IMU / 图像，可选接入）为传感器，以 **NeuPAN** 端到端神经局部规划器为核心：
- 🚀 **自主导航与动态避障** —— 全局 A\* + NeuPAN 局部规划，支持绕障、卡死脱困、动态障碍记忆
- 🗺️ **建图与重定位导航** —— 一条命令建图，重启后基于 `.bin` 地图自动重定位
- 🔧 **多底盘适配** —— 差速 / 阿克曼 / 四足通吃：重训 DUNE 足迹模型 + 标定安装偏移 + 换桥接层即可
- 🖥️ **纯软件仿真** —— 无硬件也能在 ROS2 仿真里测试规划器、调参、验证新模型
- 🧠 **语义扩展（可选）** —— YOLO 物体检测 + VLM 场景理解 + VLN 视觉语言导航
> **新手指引**：没有机器人 → 从 [路径 A：仿真](#路径-a仿真ros2无硬件先跑通) 开始；有机器人 → 从 [路径 B：Docker 部署](#路径-bdocker-实机部署推荐) 开始；要改源码 → [路径 C：源码编译](#路径-c源码编译开发调试)。
---
## 目录
- [系统架构](#系统架构)
- [支持的底盘与传感器](#支持的底盘与传感器)
- [硬件与软件要求](#硬件与软件要求)
- [仓库目录结构](#仓库目录结构)
- [新手上路：三条路径](#新手上路三条路径)
- [路径 A：仿真（ROS2）](#路径-a仿真ros2无硬件先跑通)
- [路径 B：Docker 部署（推荐）](#路径-bdocker-实机部署推荐)
- [路径 C：源码编译](#路径-c源码编译开发调试)
- [实机工作流：建图 → 导航](#实机工作流建图--导航)
- [接口参考（扩展用）](#接口参考扩展用)
- [速度下发与底盘接入](#速度下发与底盘接入)
- [调参指引](#调参指引)
- [适配新底盘 / 新机器人](#适配新底盘--新机器人)
- [语义扩展：YOLO / VLM / VLN](#语义扩展yolo--vlm--vln)
- [FAQ](#faq)
- [故障排查](#故障排查)
- [开源组件与许可](#开源组件与许可)
---
## 系统架构
```
┌─────────────────────────────────────────────┐
│ Odin1 传感器(可选) │
│ SLAM / 重定位 · 稠密点云 · 里程计 · IMU │
└──────────────┬──────────────────────────────┘
│ USB 3.0
┌──────────────────▼──────────────────┐
│ odin_ros_driver (ROS1) │
│ 发布 /odin1/cloud_slam /odin1/odometry │
│ 发布 TF: odom → odin1_base_link │
│ (重定位模式额外发布 odom → map) │
└───────┬──────────────────┬───────────┘
│ 点云 │ 里程计/TF
┌─────────────▼────────┐ │
│ 点云 → 扫描 │ │
│ pc_to_scan 高度滤波 │ │
│ → /scan(±45° 扇形) │ │
└──────────┬───────────┘ │
▼ │
┌──────────────────────┐ │
│ fake360 障碍记忆 │ │
│ → /scan_360(360°) │ │
│ (或 YHS /scan3) │ │
└──────────┬───────────┘ │
▼ │
┌──────────────────────┐ │
│ 全局规划 map_planner │ │
│ 栅格地图→膨胀→A* │ │
│ → /initial_path │ (重定位/建图模式)
│ goal_state_machine │ │
└──────────┬───────────┘ │
▼ │
┌────────────────────────────────▼────────┐
│ NeuPAN 局部规划器 │
│ DUNE 距离场 + NRMP MPC │
│ → /cmd_vel (Twist) │
└──────────────────────┬───────────────────┘
│ /cmd_vel (linear.x + angular.z)
┌────────────────▼────────────────┐
│ 速度桥接层(按底盘选) │
│ yhs_can_control (YHS 轮式, CAN) │
│ tiji_bridge (FireDog, TCP) │
│ serial_cmd_vel (嵌入式, 串口) │
└────────────────┬─────────────────┘
│ CAN / TCP / UART
┌────────────────▼─────────────────┐
│ 机器人底盘(差速/阿克曼/四足) │
└──────────────────────────────────┘
```
**数据流一句话**：Odin1 点云 → 高度滤波 → 360° 障碍记忆 →（栅格地图下 A\* 出全局路径）→ NeuPAN 局部规划 → `/cmd_vel` → 桥接层 → 底盘。
| 模块 | 路径 | 作用 |
|---|---|---|
| Odin1 驱动 | `ros_ws/src/odin_ros_driver/` | 采集点云/里程计，SLAM 建图与重定位 |
| 点云→扫描 | `whole.launch` 内 `pc_to_scan` | 高度滤波，只留“会撞到且跨不过”的障碍带 |
| 障碍记忆 | `ros_ws/src/fake360/` | 把有限 FOV 扫描累积成 360° 记忆（占用格持续到再次扫到才更新） |
| 草坪检测 | `ros_ws/src/grass_detector/` | 识别绿色草坪并入障碍（可选，户外用） |
| 全局规划 | `ros_ws/src/map_planner/` | 栅格地图 A\*、目标状态机、路径平滑 |
| 局部规划 | `NeuPAN/` | NeuPAN 端到端神经规划（本栈核心） |
| YHS 底盘驱动 | `ros_ws/src/yhs_can_control/` | `/cmd_vel` → YHS 轮式底盘（SocketCAN），发布轮式里程计 `/odom` |
| 四足桥接 | `ros_ws/src/tiji_bridge/` | `/cmd_vel` → FireDog（tiji SDK，TCP） |
| 串口桥接 | `scripts/serial_cmd_vel_bridge.py` | `/cmd_vel` → 嵌入式底盘（UART ASCII） |
| 语义检测 | `ros_ws/src/yolo_ros/` | YOLO 物体检测 + 语音指令（可选） |
| VLM | `ros_ws/src/odin_vlm_terminal/` | 视觉语言模型场景描述（可选） |
| 仿真 | `ros_ws/src/neupan_ros2/` + `ros_ws/src/ddr_minimal_sim/` | ROS2 纯软件仿真 |
> **依赖已内联**：`NeuPAN`、`odin_ros_driver`、`yolov5` 等依赖已作为普通目录合入仓库，直接 `git clone` 即可，无需 `--recursive`。
---
## 支持的底盘与传感器
| 组件 | 说明 | 桥接层 | 关键参数 |
|---|---|---|---|
| **YHS 轮式底盘**（默认） | DT 差速 / FW 前转向 / FR 四轮 / MK 麦克纳姆 | `yhs_can_control`（SocketCAN） | `CHASSIS_TYPE`、`yhs_can_control.yaml` 的 `if_name`/`wheel_base` |
| FireDog 四足 | 1.174 × 0.7177 m，TCP 高层控制 | `tiji_bridge`（tiji SDK） | `TIJI_IP`、`tiji_bridge.launch` |
| Unitree Go2 | 0.70 × 0.35 m | `unitree_control`（参考实现） | 官方 SDK |
| 任意嵌入式底盘 | STM32 等 | `serial_cmd_vel_bridge.py`（UART） | `SERIAL_PORT`/`SERIAL_BAUD`/`SERIAL_RATE` |
| **Odin1 传感器**（可选） | 3D 建图 + 重定位 + 点云/里程计/IMU | `odin_ros_driver`（USB 3.0） | `control_command.yaml` |
> 底盘与传感器解耦：Odin1 负责“我在哪”，底盘负责“我怎么动”。YHS 底盘只有轮式里程计（`/odom`），可配合 Odin1 做定位（混合模式 `use_yhs=true + use_odin1=true`）；也可纯 YHS 跑（`ODIN1=0`，仅超声波感知）。
---
## 硬件与软件要求
| 项目 | 要求 |
|---|---|
| 传感器 | Odin1 空间感知模块（USB 3.0，可选） |
| 机器人 | 底盘无关：差速 / 阿克曼 / 四足。YHS 轮式（默认）或 FireDog 四足已实测 |
| 机载电脑 | NVIDIA Jetson Orin（JetPack 5.x），或 x86 主机 |
| 操作系统 | Ubuntu 20.04（实机 ROS1）/ Ubuntu 22.04（仿真 ROS2） |
| ROS | ROS1 Noetic（实机）/ ROS2 Humble（仿真） |
| Docker（可选） | 24.0+，Compose v2 |
---
## 仓库目录结构
```
Odin-Nav-Stack/
├── deploy.sh # 一键部署/启动入口（install/start/mapping/reloc/doctor/…）
├── start_slam.sh # 启动 SLAM 导航（免建图）
├── start_mapping.sh # 启动建图
├── start_relocalization.sh # 启动重定位导航（基于已建地图）
├── stop_nav.sh # 停止
├── setup_can.sh # 上电 SocketCAN（YHS 底盘，免密授权）
├── sim_test.sh # ROS2 仿真一键测试
├── train_dune.sh # DUNE 足迹模型训练
├── map_edit.sh # 栅格地图手工修补
├── build_image.sh # 构建 Docker 镜像
├── docker/
│ ├── Dockerfile.{global,cn,x86_64} # 三种镜像源/架构
│ ├── docker-compose.yml
│ ├── entrypoint.sh # 容器入口（launch/mapping/shell/save）
│ ├── configs/ # ★ 实机可调配置（bind-mount，改完重启脚本生效）
│ └── maps/ # ★ 地图持久化（grid / relocalization / pcd）
├── ros_ws/src/ # ROS1 工作空间（实机 + 仿真共用）
│ ├── odin_ros_driver/ # Odin1 驱动
│ ├── yhs_can_control/ # YHS 底盘 CAN 驱动
│ ├── robot_common/ # 共享 topic 名
│ ├── robot_msgs/ # 底盘消息定义
│ ├── map_planner/ # A* + 目标状态机
│ ├── fake360/ # 障碍记忆
│ ├── neupan_ros2/ # ROS2 仿真规划器
│ ├── ddr_minimal_sim/ # ROS2 仿真环境
│ └── …（grass_detector / pcd2pgm / tiji_bridge / yolo_ros 等）
├── NeuPAN/ # 神经规划内核
├── scripts/ # 辅助脚本（串口桥/录图/同步参数等）
├── docs/
│ ├── DOCKER_SETUP.md # Docker 部署详细说明
│ └── TUNING_GUIDE.md # ★ 完整调参手册
└── yolov5/ # 语义检测（子模块，可选）
```
---
## 新手上路：三条路径
| 你的情况 | 选择 |
|---|---|
| 没有机器人，想先了解 / 调参 / 验证算法 | **路径 A：仿真** |
| 有机器人，想最快跑起来 | **路径 B：Docker 部署** |
| 要改源码、深度开发 | **路径 C：源码编译** |
---
## 路径 A：仿真（ROS2，无硬件先跑通）
> 需要：Ubuntu 22.04 + ROS2 Humble + Python 依赖（torch / cvxpy 等）。
> 仿真用 ROS2 版规划器 `neupan_ros2`，与实机 NeuPAN **同核**，调参经验直接互通。
### A1. 编译仿真工作空间
```bash
cd ros_ws
source /opt/ros/humble/setup.bash
colcon build --symlink-install --packages-select neupan_ros2 ddr_minimal_sim
source install/setup.bash
```
依赖（若无）：
```bash
pip3 install "numpy<2.0" torch torchvision scipy matplotlib pyyaml
sudo apt install ros-humble-desktop-full # 已装 ROS2 可跳过
```
> `--symlink-install` 让配置目录以软链接方式安装——**之后改 yaml 场景/机器人配置都不用重新编译**，只有改 C++ 才需要 `colcon build`。
### A2. 一键启动仿真
在**仓库根目录**：
```bash
./sim_test.sh # 交互式菜单，无脑回车即可
./sim_test.sh -l # 列出全部场景
./sim_test.sh -s empty -r simulation -g 3 3 # empty 场景 + 仿真小车 + 自动发目标 (3,3)
./sim_test.sh -s maze --no-rviz # 无界面模式
```
内置场景（`ros_ws/src/ddr_minimal_sim/config/scenario_*.yaml`）：`empty` 空旷、`maze` 迷宫、`corridor` 走廊、`narrow_passage` 窄通道、`park_pedestrians` / `campus_pedestrians` 含行人、`polygon_random` 随机多边形、`u_trap` U 形陷阱。
内置机器人（`ros_ws/src/neupan_ros2/config/robots/<名>/`）：`simulation` 仿真小车（0.322×0.220 m，自带模型，开箱即用）、`odin_dog` 狗（1.174×0.7177 m）、`car` 实车（1.08×0.76 m）、`limo` / `ranger` / `scout` 等参考配置。
启动后在 RViz 工具栏 **「2D Goal Pose」** 点地图发目标，机器人自主避障导航过去。
### A3. 仿真里调参（免重启）
- **规划器 `adjust` 段**（`q_s` / `eta` / `d_max` / `p_u` …）改 `ros_ws/src/neupan_ros2/config/robots/<机器人>/planner.yaml`，节点 **每 1 秒热加载**，不用重启仿真。
- **场景**（障碍物/初始位姿）改 `ros_ws/src/ddr_minimal_sim/config/scenario_*.yaml`，Ctrl+C 重启脚本。
- **机器人尺寸**（`length`/`width`）改 planner.yaml 后重启，但**必须与 DUNE 模型训练几何一致**（改了尺寸要重训，见[适配新底盘](#适配新底盘--新机器人)）。
### A4. 在仿真里测你自己训练的模型
```bash
./train_dune.sh -l <长> -w <宽> -n <模型名> --bg # 后台训练，见"适配新底盘"
./train_dune.sh --status # 看进度
./sim_test.sh -s empty -r <模型名> # 训完直接测
```
---
## 路径 B：Docker 实机部署（推荐）
> 不用在主机装 ROS / PyTorch，容器内自带全部依赖。详细说明见 [docs/DOCKER_SETUP.md](docs/DOCKER_SETUP.md)。
### B1. 准备
```bash
# 1. 克隆仓库（依赖已内联，无需 --recursive）
git clone https://gitee.com/taochangbo123/Odin-Nav-Stack.git
cd Odin-Nav-Stack
# 2. Odin1 USB 规则（只需一次，无 Odin1 可跳过）
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="2207", ATTR{idProduct}=="0019", MODE="0666", GROUP="plugdev"' \
| sudo tee /etc/udev/rules.d/99-odin-usb.rules
sudo udevadm control --reload && sudo udevadm trigger
# 3. 构建镜像（三选一）
docker build -f docker/Dockerfile.x86_64 -t odin-nav:latest . # x86 主机
docker build -f docker/Dockerfile.global -t odin-nav:latest . # Jetson（JetPack 5.x）
docker build -f docker/Dockerfile.cn -t odin-nav:latest . # 国内镜像源加速
```
> **Jetson JetPack 6.x**：`docker build -f docker/Dockerfile.global --build-arg BASE_IMAGE=dustynv/ros:noetic-pytorch-l4t-r36.2.0 -t odin-nav:latest .`
也可以用一键脚本完成以上全部：`./deploy.sh install`（自动装 docker、写 udev、构建镜像）。
### B2. 一键使用
仓库根目录封装好了脚本，**不需要记 roslaunch 命令**：
```bash
./start_mapping.sh mymap # ① 建图
./start_relocalization.sh mymap # ② 基于地图重定位导航（常用）
./start_slam.sh # ② 或：免建图 SLAM 直接导航
./stop_nav.sh # ③ 停止
```
启动后 RViz 自动打开，**点工具栏「2D Nav Goal」发目标**即可。RViz 没弹出来？宿主机先执行 `xhost +local:` 允许容器访问 X server。
### B3. 选择底盘 / 传感器（环境变量）
容器入口按环境变量选择底盘与传感器（改 `docker/docker-compose.yml` 或启动时覆盖）：
| 环境变量 | 默认 | 说明 |
|---|---|---|
| `CHASSIS` | `yhs` | `yhs` = YHS 轮式底盘（SocketCAN）；`odin` = 四足（tiji/串口桥） |
| `CHASSIS_TYPE` | `DT` | YHS 型号：`DT` 差速 / `FW` 前转向 / `FR` 四轮 / `MK` 麦克纳姆 |
| `ODIN1` | `1` | `1` = 运行 Odin1 传感器驱动做定位；`0` = 纯底盘（仅轮式/超声波感知） |
| `TIJI_IP` | `192.168.29.112` | FireDog IP（`CHASSIS=odin`）；设 `none` 改用串口桥 |
| `SERIAL_PORT/BAUD/RATE` | `/dev/ttyUSB0` / `115200` / `20` | 串口桥参数 |
| `ENTRYPOINT_MODE` | `launch` | `launch` 导航 / `mapping` 建图（由 start 脚本覆盖） |
示例：
```bash
CHASSIS=yhs CHASSIS_TYPE=DT ./start_slam.sh # YHS 差速底盘（默认）
CHASSIS=yhs CHASSIS_TYPE=FW ./start_slam.sh # YHS 阿克曼底盘
CHASSIS=odin TIJI_IP=192.168.1.20 ./start_slam.sh # FireDog 换 IP
CHASSIS=odin TIJI_IP=none ./start_slam.sh # 嵌入式底盘走串口
ODIN1=0 ./start_slam.sh # 纯 YHS 底盘，不开 Odin1
```
> **YHS 底盘还需要先把 SocketCAN 拉起来**。`start_*.sh` 已自动调用 `setup_can.sh`（先 down → 设 bitrate 500000 → up）。首次使用前配置一次免密授权（一次性）：
```bash
# 用你的密码执行，之后 setup_can.sh 里的 sudo ip 命令不再弹密码
echo 'test ALL=(ALL) NOPASSWD: /usr/sbin/ip link set down can0, /usr/sbin/ip link set up can0, /usr/sbin/ip link set can0 type can bitrate 500000' \
| sudo tee /etc/sudoers.d/99-can0 && sudo chmod 0440 /etc/sudoers.d/99-can0
```
也可以手动：`sudo ip link set down can0 && sudo ip link set can0 type can bitrate 500000 && sudo ip link set up can0`。
### B4. 不改镜像改配置
所有可调配置都 bind-mount 在 `docker/configs/`（主机直接改，**重启脚本生效**；NeuPAN 的 `adjust` 参数热加载）。首次部署先把默认配置拷出来：
```bash
mkdir -p docker/configs docker/maps
cp ros_ws/src/odin_ros_driver/config/control_command.yaml docker/configs/
cp NeuPAN/neupan/ros/configs/config.yaml docker/configs/
cp NeuPAN/neupan/ros/configs/planner.yaml docker/configs/
cp ros_ws/src/map_planner/launch/whole.launch docker/configs/
cp ros_ws/src/yhs_can_control/config/yhs_can_control.yaml docker/configs/
cp ros_ws/src/yhs_can_control/launch/yhs_can_control.launch docker/configs/
```
| 文件 | 控制 |
|---|---|
| `control_command.yaml` | Odin1 驱动：模式（`custom_map_mode`）、地图路径、时钟、数据流开关 |
| `config.yaml` | NeuPAN：话题、坐标系、DUNE 模型路径、卡死脱困 |
| `planner.yaml` | NeuPAN：MPC 权重、机器人尺寸、`adjust` 调参段 |
| `whole.launch` | A\*、fake360、高度滤波、TF、底盘选择 |
| `yhs_can_control.yaml` | YHS 底盘：CAN 接口名、里程计 frame、轮距、超声波布局 |
| `yhs_can_control.launch` | YHS 底盘节点启动 |
| `maps/` | 地图持久化：`.bin` 重定位图 / `.pgm` 栅格图 / `.pcd` 点云 |
---
## 路径 C：源码编译（开发调试）
### C1. 克隆仓库
```bash
git clone https://gitee.com/taochangbo123/Odin-Nav-Stack.git
cd Odin-Nav-Stack
```
### C2. 安装系统依赖（ROS1 Noetic）
```bash
export ROS_DISTRO=noetic
sudo apt update
sudo apt install -y \
ros-${ROS_DISTRO}-tf2-ros ros-${ROS_DISTRO}-tf2-geometry-msgs \
ros-${ROS_DISTRO}-cv-bridge ros-${ROS_DISTRO}-tf2-eigen \
ros-${ROS_DISTRO}-pcl-ros ros-${ROS_DISTRO}-move-base \
ros-${ROS_DISTRO}-dwa-local-planner ros-${ROS_DISTRO}-can-msgs
```
### C3. 修改 Odin1 驱动（用 Odin1 时必需）
**配置**：打开 `ros_ws/src/odin_ros_driver/config/control_command.yaml`，确认 `use_host_ros_time: 1`。
> ⚠️ 必须为 1！Odin1 内部时钟是开机时长（uptime），与主机墙上时间差很远；不开启会导致 TF 时间戳错乱、导航异常。
**代码**：编辑 `ros_ws/src/odin_ros_driver/include/host_sdk_sample.h`（注意改 **ROS1** 段，不是 ROS2 段）：
1. `publishOdometry` 里**注释掉低频 TF 发布**（`OdometryType::STANDARD` 分支的 `tf_broadcaster->sendTransform(...)` 整段）；
2. `OdometryType::HIGHFREQ` 分支**添加高频 TF 发布**（发布 `odom → odin1_base_link`）。完整代码块见 `docs/DOCKER_SETUP.md`。
### C4. 创建 NeuPAN Python 环境
```bash
# 安装 miniconda 后:
conda install -n base -c conda-forge mamba
export ROS_DISTRO=noetic
mamba create -n neupan -y
mamba activate neupan
conda config --env --add channels conda-forge
conda config --env --remove channels defaults
conda config --env --add channels robostack-${ROS_DISTRO}
mamba install -n neupan ros-${ROS_DISTRO}-desktop colcon-common-extensions catkin_tools rosdep ros-dev-tools -y
mamba run -n neupan pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cpu
pip install -e NeuPAN
```
> **Jetson 用户**：把 PyTorch 换成 [NVIDIA 官方 Jetson wheel](https://forums.developer.nvidia.com/t/pytorch-for-jetson/72048)。
### C5. 编译 ROS 工作空间
**系统 ROS 编译**（推荐，先 `mamba deactivate` 退出 conda）：
```bash
cd ros_ws
source /opt/ros/${ROS_DISTRO}/setup.bash
catkin_make -DCMAKE_BUILD_TYPE=Release
source devel/setup.bash
```
**Conda ROS 编译**（无系统 ROS 时）：
```bash
mamba activate neupan
mamba install -c conda-forge -c robostack-noetic \
ros-noetic-pcl-ros ros-noetic-compressed-image-transport \
ros-noetic-compressed-depth-image-transport ros-noetic-image-transport
cd ros_ws
catkin_make -DCMAKE_POLICY_VERSION_MINIMUM=3.5 -DPCL_VISUALIZATION=OFF -DQT_HOST_PATH=$CONDA_PREFIX
```
### C6. 启动（源码方式）
```bash
# 终端 1：建图/导航 launch（等价于容器入口）
roslaunch map_planner whole.launch use_yhs:=true use_odin1:=true chassis_type:=DT
# 终端 2：NeuPAN 局部规划器
mamba activate neupan
python NeuPAN/neupan/ros/neupan_ros.py
```
---
## 实机工作流：建图 → 导航
> Docker 用户直接用根目录脚本；源码安装用户用括号里的等价命令。
### 第 1 步：建图
```bash
./start_mapping.sh mymap # Docker 一键
```
然后**推着 / 遛着机器人走遍要建图的区域**，按脚本提示依次执行：开始记录 → 走完 → 停止记录 → 保存转换。产物：
- `docker/maps/relocalization/mymap.bin` —— 重定位用的 SLAM 地图
- `docker/maps/grid/mymap.pgm` —— A\* 用的栅格地图（可用 GIMP / `./map_edit.sh` 手工修补）
- `docker/maps/pcd/mymap.pcd` —— 原始点云
### 第 2 步：导航（二选一）
**方式一：重定位导航（推荐，大场景）**
```bash
./start_relocalization.sh mymap
```
- 需在**原始建图轨迹 1m / ±10° 范围内**启动（自动重定位）；
- 重定位成功后 RViz Fixed Frame 设为 `map`，能看到 `map → odom → base_link` TF 树；
- 可选：`GRASS=1 ./start_relocalization.sh mymap` 开启草坪检测（户外避草坪）；
- 用空白栅格图测 A\*：`./start_relocalization.sh mymap empty`。
**方式二：SLAM 免建图导航（小场景 / 快速验证）**
```bash
./start_slam.sh
```
无需地图，驱动以里程计模式运行，NeuPAN 直接用实时 SLAM 点云避障。
### 第 3 步：发目标
RViz 工具栏 **「2D Nav Goal」** 点击地图 → A\* 全局规划 → NeuPAN 局部跟踪避障 → 到达后报告 `/neupan/arrive`。
---
## 接口参考（扩展用）
本节是本栈的**对外契约**——接入新底盘、新传感器、新规划器、新可视化都从这里入手。
### 1. ROS Topic 接口
| Topic | 类型 | 方向 | 生产者 → 消费者 | 说明 |
|---|---|---|---|---|
| `/odin1/cloud_slam` | `sensor_msgs/PointCloud2` | 输入 | odin_ros_driver → pc_to_scan / grass / fake360 | Odin1 SLAM 稠密点云 |
| `/odin1/odometry` | `nav_msgs/Odometry` | 输入 | odin_ros_driver → NeuPAN | Odin1 里程计 |
| `/scan` | `sensor_msgs/LaserScan` | 内部 | pc_to_scan → fake360 | 高度滤波后的 ±45° 扫描 |
| `/scan3` | `sensor_msgs/LaserScan` | 输入 | yhs_can_control → fake360 | YHS 超声波伪扫描（纯底盘模式用） |
| `/scan_360` | `sensor_msgs/LaserScan` | 内部 | fake360 → NeuPAN | 360° 障碍记忆扫描 |
| `/scan_360_grass` | `sensor_msgs/LaserScan` | 内部 | grass_detector → NeuPAN | 并入草坪障碍后的扫描（`GRASS=1`） |
| `/map` | `nav_msgs/OccupancyGrid` | 输入 | map_server → map_planner | 栅格地图（重定位模式） |
| `/inflated_map` | `nav_msgs/OccupancyGrid` | 输出 | map_planner → RViz | 膨胀后的地图 |
| `/move_base_simple/goal` | `geometry_msgs/PoseStamped` | 输入 | RViz → goal_state_machine | 导航目标（重定位模式） |
| `/neupan/goal` | `geometry_msgs/PoseStamped` | 输入 | 外部 → NeuPAN | 导航目标（SLAM 模式，NeuPAN 直连） |
| `/initial_path` | `nav_msgs/Path` | 内部 | map_planner → NeuPAN | A\* 全局参考路径 |
| `/waypoints` | `nav_msgs/Path` | 输入 | 外部 → NeuPAN | 路点输入（NeuPAN 自行插值） |
| **`/cmd_vel`** | `geometry_msgs/Twist` | **输出** | NeuPAN → 桥接层 | **核心输出**：`linear.x` 前进、`angular.z` 转向 |
| `/neupan/arrive` | 自定义 | 输出 | NeuPAN → goal_state_machine | 到达事件 |
| `/odom` | `nav_msgs/Odometry` | 输出 | yhs_can_control → 外部 | YHS 轮式里程计 |
| `/chassis_info_fb` | `robot_msgs/DgtChassisInfoFb` | 输出 | yhs_can_control → 外部 | YHS 底盘反馈（控制/IO/BMS） |
| `/yhs/control_mode` | `std_msgs/Bool` | 输出 | yhs_can_control → 外部 | 底盘控制模式（joypad/自动） |
| `/ultrasonic` | `robot_msgs/Ultrasonic` | 输出 | yhs_can_control → 外部 | YHS 超声波原始数据 |
> **跨 ROS1/ROS2**：容器内 `whole.launch` 自带 `foxglove_bridge`，把上述所有 ROS1 topic 以 WebSocket（`ws://:8765`）暴露，宿主机 ROS2 / Foxglove Studio 无需装 ROS1 即可订阅。也可用 `docs/DOCKER_SETUP.md` 里的 UDP 桥接 `/cmd_vel`。
### 2. TF 坐标接口
| 变换 | 来源 | 说明 |
|---|---|---|
| `odom → odin1_base_link` | odin_ros_driver（动态） | Odin1 里程计位姿 |
| `odom → map` | odin_ros_driver（重定位模式） | 重定位成功后发布 |
| `odin1_base_link → base_link` | `whole.launch` 静态 TF | **安装偏移**（换底盘要改） |
| `base_link → ul_link` | `yhs_can_control.launch` 静态 TF | 超声波传感器相对底盘 |
| `odom → base_link` | yhs_can_control（`tfUsed`） | YHS 轮式里程计（与 Odin1 二选一，避免 TF 冲突） |
### 3. 配置文件接口
| 文件 | 命名空间 / 段 | 关键项 |
|---|---|---|
| `config.yaml` | `topic.*` / `frame.*` / `odom_feedback` / `stuck_escape` / `prealign` / `adaptive_d_max` / `scan_range` | 话题名、坐标系、DUNE 路径、卡死脱困 |
| `planner.yaml` | `receding` / `robot.*` / `ipath.*` / `pan.*` / `adjust.*` | MPC、运动学、尺寸、路径、权重 |
| `whole.launch` | `
