SUPER: Safety-assured High-speed Navigation for MAVs
Science Robotics' 25Yunfan REN, Fangcheng Zhu, Guozheng Lu, Yixi Cai, Longji Yin, Fanze Kong, Jiarong Lin, Nan Chen, and Fu Zhang
# 2 Quick Start
## 2.1 Installation
Install dependencies
```bash
# for MARSIM example
sudo apt-get install libglfw3-dev libglew-dev libncurses5-dev libncursesw5-dev
# Eigen [version testd: 3.3.7-2] and soft link
sudo apt-get install libeigen3-dev
sudo ln -s /usr/include/eigen3/Eigen /usr/include/Eigen
# dw for backward cpp
sudo apt-get install libdw-dev
# for ROS dependency
sudo apt-get install ros-${YOUR-ROS-VERSION}-mavros* ros-${YOUR-ROS-VERSION}-pcl* ros-${YOUR-ROS-VERSION}-rosfmt
```
Before building the code, select the appropriate ROS version:
```bash
# Use ROS1-noetic
bash ${PATH-TO-SUPER}/SUPER/scripts/select_ros_version.sh ROS1
# Use ROS2
bash ${PATH-TO-SUPER}/SUPER/scripts/select_ros_version.sh ROS2
```
Tested Environments:
* Ubuntu 20.04 + ROS1 Noetic
* Ubuntu 20.04 + ROS2 foxy
* ...
Currently, **ROS1 Noetic** serves as the **Tier 1** supported platform for SUPER. The ROS2 version is still under development and may be unstable, with some issues such as imperfect visualization. We are actively working on improvements.
### Known Build issues
* ...
## 2.2 ROS1 (Noetic) Installation
```bash
mkdir -p super_ws/src && cd super_ws/src
git clone https://github.com/hku-mars/SUPER.git
cd ..
catkin_make -DBUILD_TYPE=Release
```
To test, use one of the following commands:
1. **High-Speed Navigation**
```bash
cd ${PATH-TO-WS}
source devel/setup.bash
roslaunch mission_planner benchmark_high_speed.launch
```
2. **Agile Flight in Dense Environments**
```bash
cd ${PATH-TO-WS}
source devel/setup.bash
roslaunch mission_planner benchmark_dense.launch
```
3. **Click and Go Demo**
```
roslaunch mission_planner click_demo.launch
```
In the click demo, press `G` to enable the `2D Goal Pose` plugin, then click a position in RViz to set the goal.
## 2.3 ROS2
```bash
mkdir -p super_ws/src && cd super_ws/src
git clone https://github.com/hku-mars/SUPER.git
cd ..
colcon build --symlink-install
# add to debug: --event-handlers console_direct+
```
To test, run:
1. **High-speed Navigation**
```bash
cd ${PATH-TO-WS}
source install/local_setup.bash
ros2 launch mission_planner benchmark_high_speed.launch.py
```
2. **Agile flights in dense enviroment**
```bash
cd ${PATH-TO-WS}
source install/local_setup.bash
ros2 launch mission_planner benchmark_dense.launch.py
```
3. **Click demo**
```
ros2 launch mission_planner click_demo.launch.py
```
### Real-world deployment
A detailed guide for deploying SUPER on real-world hardware will be available soon. In the meantime, you can refer to [issue #5](https://github.com/hku-mars/SUPER/issues/5) for some helpful hints.
## 2.4 Use Your Own Map
SUPER allows users to load their own **.pcd** maps as simulation environments. To do so:
1. Place your **.pcd** file in:
**[./mars_uav_sim/perfect_drone_sim/pcd/](./mars_uav_sim/perfect_drone_sim/pcd)**
2. Modify the `pcd_name` parameter in the corresponding YAML file located at:
**[./mars_uav_sim/perfect_drone_sim/config](./mars_uav_sim/perfect_drone_sim/config)**
This enables seamless integration of custom maps for simulation.
## 2.5 Logging System
SUPER includes a built-in logging system that records each run automatically. Logs are saved in:
- **[./super_planner/log/cmd_logs](./super_planner/log/cmd_logs)**
- **[./super_planner/log/replan_logs](./super_planner/log/replan_logs)**
After stopping the program with `Ctrl + C`, the latest log will be saved. Users can evaluate **trajectory quality** by running:
```bash
# Install dependencies
pip3 install numpy pandas matplotlib
# Plot the command log
python3 plotCmdLog.py
```
For advanced usage, refer to:
- **[read_replan_log.cpp](super_planner/Apps/read_replan_log.cpp)**
- **[traj_opt_tuning.cpp](super_planner/Apps/traj_opt_tuning.cpp)**
We are actively working on improving the logging system, and updates will be available soon!
## 2.6 Tuning
To maximize performance, parameter tuning is crucial. The current version of SUPER has a large number of parameters (maybe TOOOO MUCH), requiring careful adjustment. Users can refer to the provided examples for guidance. We plan to provide detailed tuning instructions soon. In the meantime, feedback and issue reports are welcome.
## 2.7 Notable Known Issues
* [#10]: When using SUPER with your own simulator (e.g., Gazebo) or a LiDAR odometry system other than FAST-LIO2, ensure that the input point cloud is provided in the world frame. ROG-Map does not utilize `frame_id` or `/tf` information and assumes by default that all input point clouds are in the world frame rather than the body frame.
# 3 TODO
* Add a demo for autonomous exploration (SUPER is well-suited as a local planner for point-to-point navigation).
* Provide examples for using standalone tools in SUPER, such as:
- **CIRI** - Generates safe flight corridors in C-space.
- **ROG-Map** - An efficient occupancy grid map supporting both ROS1 and ROS2.
* Introduce the hardware components of SUPER.
* Detail the control module of SUPER.
* Develop a tutorial.
# 4. Acknowledgments
SUPER is built upon several outstanding open-source projects. We extend our gratitude to the developers of the following repositories:
* **[FAST_LIO](https://github.com/hku-mars/FAST_LIO)**, **[Swarm-LIO2](https://github.com/hku-mars/Swarm-LIO2)** and **[LiDAR_IMU_Init](https://github.com/hku-mars/LiDAR_IMU_Init)** for their excellent localization solutions.
* **[ROG-Map](https://github.com/hku-mars/ROG-Map)** - A high-performance mapping framework that influenced our approach to map representation and optimization.
* **[MARSIM](https://github.com/hku-mars/MARSIM)** - A simulation environment that played a key role in testing and evaluating our algorithms in virtual scenarios.
* **[GCOPTER](https://github.com/ZJU-FAST-Lab/GCOPTER)** – A valuable resource that efficiently performs differentiable trajectory optimization and serves as the foundation of our trajectory optimization method.
**[FIRI](https://github.com/ZJU-FAST-Lab/GCOPTER/blob/main/gcopter/include/gcopter/firi.hpp)** – An extremely efficient safe flight corridor generation method upon which our CIRI is built.
* [**FASTER**](https://github.com/mit-acl/faster) - Introduces the initial concept of a two-trajectory optimization framework.
* **[DecompUtil](https://github.com/sikang/DecompUtil)** - A convex decomposition tool that was instrumental in implementing our algorithms.
* **[Mockamap](https://github.com/HKUST-Aerial-Robotics/mockamap)** - A simple ROS-based map generator that assisted in our development and testing.
* [**Nxt-FC**](https://github.com/HKUST-Aerial-Robotics/Nxt-FC) – A compact yet powerful hardware platform for the PX4 flight controller.
We sincerely appreciate the efforts of these communities in advancing robotics research.