NeuPAN ROS2 Workspace

English | 中文

---

Overview

NeuPAN ROS2 Workspace is a complete ROS2-based navigation system that combines:

• NeuPAN Planner (src/neupan_ros2): Neural Proximal Alternating Network for end-to-end navigation planning
• DDR Minimal Sim (src/ddr_minimal_sim): Lightweight differential-drive robot simulator

Key Features

• 🤖 End-to-End Learning: Direct laser scan to velocity command mapping using neural networks
• 🎯 Real-Time Planning: Fast neural network inference for responsive navigation
• 🔄 Sim-to-Real: Seamless transition between simulation and physical robots (e.g., Limo)
• 🛠️ Easy Testing: Pre-configured scenarios for algorithm validation
• 📦 Modular Design: Independent packages for flexibility
• 🔒 Thread-Safe: Multi-threaded architecture with state protection for robust performance
• 🎨 Optional Visualization: Configurable RViz markers for performance tuning on embedded platforms
• ⚙️ CI/CD Ready: Automated testing and build verification with Docker-based workflows

Demo

NeuPAN navigating autonomously through a complex maze scenario

Quick Start

1. Prerequisites

• ROS2: Humble or later
• System: Ubuntu 22.04 (recommended)
• Hardware: CPU (GPU optional)

2. Install Dependencies

# Navigate to workspace root
git clone https://github.com/KevinLADLee/neupan_ros2.git
cd neupan_ros2

# Run setup script (installs ROS2 and C++ dependencies only)
chmod +x setup.sh
./setup.sh

Or install manually

ROS2 Dependencies:

sudo apt update
sudo apt install -y \
    ros-humble-tf2-tools \
    ros-humble-tf2-ros \
    ros-humble-nav-msgs \
    ros-humble-sensor-msgs \
    ros-humble-geometry-msgs \
    ros-humble-visualization-msgs \
    libeigen3-dev \
    libyaml-cpp-dev

Python Dependencies:

⚠️ Important: NeuPAN requires numpy < 2.0

Please refer to the official NeuPAN repository for detailed installation: https://github.com/hanruihua/NeuPAN

Typical installation:

# Install PyTorch (choose CPU or GPU version from https://pytorch.org)
pip3 install torch torchvision

# Install NeuPAN and dependencies
pip3 install neupan
pip3 install "numpy<2.0" scipy matplotlib pyyaml

3. Build Workspace

# Use build script
chmod +x build.sh
./build.sh

# Or build manually
colcon build --symlink-install
source install/setup.bash

4. Run Demo

Simulation with NeuPAN:

source install/setup.bash
ros2 launch neupan_ros2 sim_diff_launch.py sim_env_config:=scenario_corridor.yaml

Alternative scenarios: See ddr_minimal_sim scenarios for complete list (corridor, maze, narrow_passage, u_trap, polygon_random, empty)

Usage Scenarios

Scenario 1: Real Robot Deployment (Limo)

Deploy NeuPAN on physical Limo robot:

# Make sure Limo drivers are running
ros2 launch neupan_ros2 limo_diff_launch.py

Scenario 2: Complete Simulation

Full system with simulator + NeuPAN planner:

ros2 launch neupan_ros2 sim_diff_launch.py

ros2 launch neupan_ros2 sim_diff_launch.py sim_env_config:=scenario_maze.yaml

Package Details

📦 src/neupan_ros2

ROS2 implementation of NeuPAN-ROS neural navigation planner. → Documentation

📦 src/ddr_minimal_sim

Lightweight differential-drive robot simulator with laser scanning and pre-configured test scenarios. → Documentation

Development

Building

# Build all packages
colcon build --symlink-install

# Build specific package
colcon build --packages-select neupan_ros2
colcon build --packages-select ddr_minimal_sim

Customization

• Simulator scenarios: See ddr_minimal_sim development guide for custom scenarios
• NeuPAN parameters: Modify src/neupan_ros2/config/neupan_config/neupan_sim_diff.yaml

Continuous Integration

Automated testing on every push and pull request:

• Build Verification: Compiles workspace on Ubuntu 22.04 + ROS2 Humble
• Code Quality: flake8 and pep257 linting with GitHub annotations
• Docker-based: Reproducible builds using official ROS2 containers
• Optimized Caching: Fast CI runs (~30sec with cache hits)
• Workspace Validation: Detects duplicate packages and workspace issues

See CI/CD Documentation for detailed workflow information.

Citation

If you find this code or paper helpful, please kindly star ⭐ this repository and cite our paper:

@ARTICLE{10938329,
  author={Han, Ruihua and Wang, Shuai and Wang, Shuaijun and Zhang, Zeqing and Chen, Jianjun and Lin, Shijie and Li, Chengyang and Xu, Chengzhong and Eldar, Yonina C. and Hao, Qi and Pan, Jia},
  journal={IEEE Transactions on Robotics}, 
  title={NeuPAN: Direct Point Robot Navigation With End-to-End Model-Based Learning}, 
  year={2025},
  volume={41},
  number={},
  pages={2804-2824},
  doi={10.1109/TRO.2025.3554252}}

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

This maintains consistency with NeuPAN-ROS (ROS1 version).

Troubleshooting

Build errors

• Ensure all dependencies are installed: ./setup.sh
• Check ROS2 sourced: source /opt/ros/humble/setup.bash
• Clean build: rm -rf build install log && colcon build

Runtime errors

• Verify package discovery: ros2 pkg list | grep -E "neupan|ddr"
• Check topics: ros2 topic list
• Review logs: ros2 run rqt_console rqt_console

NeuPAN model not found

• Check model file exists: src/neupan_ros2/config/dune_checkpoint/model_5000.pth
• Download from repository if missing

Contributing

Contributions welcome! Submit issues or pull requests on GitHub.

Acknowledgments

• NeuPAN & NeuPAN-ROS - Original algorithm
• DDR-opt - Simulator reference
• ROS2 integration optimized for AgileX Limo by HiveMatrix Limited
  • Interested in Limo robots or technical support? Contact HiveMatrix - your commercial support empowers continued open-source development

---

Author: KevinLADLee ([email protected])