├── .github └── workflows │ └── Ubuntu20.04-build.yaml ├── .gitmodules ├── LICENSE ├── README.md └── ignore-me.cpp /.github/workflows/Ubuntu20.04-build.yaml: -------------------------------------------------------------------------------- 1 | name: Ubuntu 20.04 ROS Noetic 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | paths-ignore: 8 | - '**/README.md' 9 | pull_request: 10 | branches: 11 | - main 12 | paths-ignore: 13 | - '**/README.md' 14 | 15 | jobs: 16 | build: 17 | runs-on: ubuntu-20.04 18 | env: 19 | ROS_CI_DESKTOP: "`lsb_release -cs`" 20 | ROS_DISTRO: noetic 21 | steps: 22 | - uses: actions/checkout@v2 23 | with: 24 | submodules: recursive 25 | - name: Install ROS Noetic 26 | run: | 27 | sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list' 28 | sudo apt install curl 29 | curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add - 30 | sudo apt update 31 | sudo apt install ros-noetic-desktop-full 32 | source /opt/ros/${ROS_DISTRO}/setup.bash 33 | - name: Install ROS packages with rosdep 34 | run: | 35 | sudo apt install python3-rosdep python3-rosinstall python3-rosinstall-generator python3-wstool build-essential 36 | sudo apt install python3-rosdep 37 | sudo rosdep init 38 | rosdep update 39 | - name: Install dependencies 40 | run: | 41 | sudo apt install -y ros-${ROS_DISTRO}-octomap* ros-${ROS_DISTRO}-mavros* ros-${ROS_DISTRO}-vision-msgs 42 | - name: catkin make 43 | run: | 44 | mkdir -p ~/catkin_ws/src 45 | ln -s $GITHUB_WORKSPACE ~/catkin_ws/src/ 46 | cd ~/catkin_ws 47 | source /opt/ros/${ROS_DISTRO}/setup.bash 48 | catkin_make 49 | -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "autonomous_flight"] 2 | path = autonomous_flight 3 | url = https://github.com/Zhefan-Xu/autonomous_flight.git 4 | [submodule "global_planner"] 5 | path = global_planner 6 | url = https://github.com/Zhefan-Xu/global_planner.git 7 | [submodule "uav_simulator"] 8 | path = uav_simulator 9 | url = https://github.com/Zhefan-Xu/uav_simulator.git 10 | [submodule "trajectory_planner"] 11 | path = trajectory_planner 12 | url = https://github.com/Zhefan-Xu/trajectory_planner.git 13 | [submodule "map_manager"] 14 | path = map_manager 15 | url = https://github.com/Zhefan-Xu/map_manager.git 16 | [submodule "time_optimizer"] 17 | path = time_optimizer 18 | url = https://github.com/Zhefan-Xu/time_optimizer.git 19 | [submodule "tracking_controller"] 20 | path = tracking_controller 21 | url = https://github.com/Zhefan-Xu/tracking_controller.git 22 | [submodule "onboard_detector"] 23 | path = onboard_detector 24 | url = https://github.com/Zhefan-Xu/onboard_detector.git 25 | [submodule "remote_control"] 26 | path = remote_control 27 | url = https://github.com/Zhefan-Xu/remote_control.git 28 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2023 Zhefan Xu 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # CERLAB UAV Autonomy Framework 2 | [![Releases](https://img.shields.io/github/release/Zhefan-Xu/CERLAB-UAV-Autonomy.svg)](https://github.com/Zhefan-Xu/CERLAB-UAV-Autonomy/releases) 3 | ![Noetic Ubuntu 20.04](https://github.com/Zhefan-Xu/CERLAB-UAV-Autonomy/actions/workflows/Ubuntu20.04-build.yaml/badge.svg) 4 | [![license](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) 5 | [![Linux platform](https://img.shields.io/badge/platform-linux--64-orange.svg)](https://releases.ubuntu.com/20.04/) 6 | [![Linux platform](https://img.shields.io/badge/platform-linux--arm-brown.svg)](https://releases.ubuntu.com/20.04/) 7 | 8 | 9 | Welcome to the **CERLAB UAV Autonomy Framework**, a versatile and modular framework for autonomous unmanned aerial vehicles (UAVs). This framework comprises distinct components (simulator, perception, mapping, planning, and control) to achieve autonomous navigation, unknown exploration, and target inspection. 10 | 11 | **Author**: [Zhefan Xu](https://zhefanxu.com/), Computational Engineering & Robotics Lab (CERLAB) at Carnegie Mellon University (CMU). 12 | 13 | **Contact Email**: zhefanx@andrew.cmu.edu 14 | 15 | **Video Tutorial**: [YouTube](https://youtu.be/sWTQ4cnQCIE?si=809MQPjWSI2Bq4rj), [BiliBili](https://www.bilibili.com/video/BV1KN4y1i7FV/?share_source=copy_web&vd_source=1333db331406abb1b5d4cece1e253427&t=0) (for China mainland) 16 | 17 | If you find this work helpful, kindly show your support by giving us a free ⭐️. Your recognition is truly valued. 18 | 19 | ![intro](https://github.com/Zhefan-Xu/CERLAB-UAV-Autonomy/assets/55560905/23a78d4f-a7a3-4c68-b80f-c6dbf6b0f090) 20 | 21 | ## News 22 | 23 | * **2024-01-10:** The GitHub code, video demos, video tutorials and relavant papers for our autonomous UAV framework are released. The authors will actively maintain and update this repo! 24 | 25 | ## Table of Contents 26 | 1. [The Autonomy Modules Introduction](#I-The-Autonomy-Modules-Introduction) 27 | 2. [Installation Guide](#II-Installation-Guide) 28 | 3. [Run Autonomy DEMO](#III-Run-Autonomy-DEMO) 29 | 4. [PX4 Simulation & Real Flight](#IV-PX4-Simulation--Real-Flight) 30 | 5. [Citation and Reference](#V-Citation-and-Reference) 31 | 6. [Acknowledgement](#VI-Acknowledgement) 32 | 7. [Write at the End](#VII-Write-at-the-End) 33 | 34 | ## I. The Autonomy Modules Introduction 35 | The funtionality of each autonomy module included in this framework in alphabetical order: 36 | - ```autonomous_flight```: The autonomous flight package integrating all other modules for various tasks. [details](https://github.com/Zhefan-Xu/autonomous_flight) 37 | - ```global_planner```: The global waypoint planner library for autonomous robots. [details](https://github.com/Zhefan-Xu/global_planner) 38 | - ```map_manager```: The 3D mapping library for autonomous robots. [details](https://github.com/Zhefan-Xu/map_manager) 39 | - ```onboard_detector```: The dynamic obstacle detection and tracking algorithm for autonomous robots. [details](https://github.com/Zhefan-Xu/onboard_detector) 40 | - ```remote_control```: The Rviz configuration and launch files for easy visualization. [details](https://github.com/Zhefan-Xu/remote_control) 41 | - ```time_optimizer```: The optimal trajectory time allocation library for autonomous robots. [details](https://github.com/Zhefan-Xu/time_optimizer) 42 | - ```tracking_controller```: The trajectory tracking controller for autonomous robots. [details](https://github.com/Zhefan-Xu/tracking_controller) 43 | - ```trajectory_planner```: The trajectory olanning library for autonomous robots. [details](https://github.com/Zhefan-Xu/trajectory_planner) 44 | - ```uav_simulator```: The lightweight Gazebo/ROS-based simulator for unmanned aerial vehicles. [details](https://github.com/Zhefan-Xu/uav_simulator) 45 | 46 | 47 | ## II. Installation Guide 48 | This repo has been tested on ROS Melodic with Ubuntu 18.04 and ROS Noetic with Ubuntu 20.04 and it depends on the ROS packages: [octomap](https://wiki.ros.org/octomap), [mavros](https://wiki.ros.org/mavros), and [vision_msgs](https://wiki.ros.org/vision_msgs). Installing the package with the following commands: 49 | 50 | ``` 51 | # step1: install dependencies 52 | sudo apt install ros-${ROS_DISTRO}-octomap* && sudo apt install ros-${ROS_DISTRO}-mavros* && sudo apt install ros-${ROS_DISTRO}-vision-msgs 53 | 54 | # step 2: clone this repo to your workspace 55 | cd ~/catkin_ws/src 56 | git clone --recursive https://github.com/Zhefan-Xu/CERLAB-UAV-Autonomy.git 57 | 58 | # optional: switch to simulation branch for autonomous_flight 59 | # the default branch is for real flight and PX4 simulation 60 | cd path/to/autonomous_flight 61 | git checkout simulation 62 | 63 | # step 3: follow the standard catkin_make procedure 64 | cd ~/catkin_ws 65 | catkin_make 66 | ``` 67 | setup environment variable. Add following to your ```~/.bashrc``` 68 | ``` 69 | source path/to/uav_simulator/gazeboSetup.bash 70 | ``` 71 | ## III. Run Autonomy DEMO 72 | This section shows the most typical ones: **navigation**, **exploration**, and **inspection**. Note that the default environment and the flight parameters might be different from the demos shown as below. Please check [uav_simulator](https://github.com/Zhefan-Xu/uav_simulator) for changing the simulation environments and [autonomous_flight](https://github.com/Zhefan-Xu/autonomous_flight) for adjusting flight parameters. 73 | 74 | Before getting started, please make sure you are in the ```simulation``` branch of the submodule [autonomous_flight](https://github.com/Zhefan-Xu/autonomous_flight) for the following demos (please check the link for detailed explanations): 75 | ``` 76 | cd path/to/autonomous_flight 77 | git branch 78 | 79 | # if the output says you are not in the simulation branch, please run the following (otherwise please ignore): 80 | git checkout simulation 81 | cd ~/catkin_ws 82 | catkin_make clean # if you switch the branch for autonomous_flight 83 | catkin_make 84 | ``` 85 | 86 | ### a. **Autonomous Navigation:** Navigating to a given goal position and avoiding collisions. 87 | 88 | ``` 89 | # start simulator 90 | roslaunch uav_simulator start.launch # recommand to use the corridor env for your first trial 91 | 92 | # open the Rviz visualization 93 | roslaunch remote_control dynamic_navigation_rviz.launch # if your test env has dynamic obstacles 94 | 95 | # run the navigation program 96 | roslaunch autonomous_flight dynamic_navigation.launch # if your test env has dynamic obstacles 97 | 98 | # -------------------------------------------------------------------------------------- 99 | # (alternatively, if your test env is purely static, you can run the following instead) 100 | # open the Rviz visualization 101 | roslaunch remote_control navigation_rviz.launch # if your test env only has static obstacles 102 | 103 | # run the navigation program 104 | roslaunch autonomous_flight navigation.launch # if your test env only has static obstacles 105 | ``` 106 | 107 | Once the robot is hovering at the predefined height (check the terminal output messages), you can use the ```2D Nav Goal``` to click a goal point in ```Rviz``` and you can see example results shown below: 108 | 109 | https://github.com/Zhefan-Xu/CERLAB-UAV-Autonomy/assets/55560905/31f4e6eb-857c-43d0-a02c-8defa8eea12c 110 | 111 | 112 | ### b. **Autonomous Exploration: Exploraing an unknown environments and create a map.** 113 | 114 | ``` 115 | # start simulator 116 | roslaunch uav_simulator start.launch # recommand to use the floorplan2 env for your first trial 117 | 118 | # open the Rviz visualization 119 | roslaunch remote_control exploration_rviz.launch 120 | 121 | # run the navigation program 122 | roslaunch autonomous_flight dynamic_exploration.launch 123 | ``` 124 | 125 | The example exploration process is shown in the video demo as below: 126 | 127 | https://github.com/Zhefan-Xu/CERLAB-UAV-Autonomy/assets/55560905/e0d953de-a542-49c3-86ca-b44d77ff7653 128 | 129 | 130 | ### c. **Autonomous Inspection: Navigating to the target and inspecting it with a zig-zag path.** 131 | 132 | ``` 133 | # start simulator 134 | roslaunch uav_simulator start.launch # # recommand to use the tunnel_dynamic_1 env for your first trial 135 | 136 | # open the Rviz visualization 137 | roslaunch remote_control inspection_rviz.launch 138 | 139 | # run the navigation program 140 | roslaunch autonomous_flight dynamic_inspection.launch 141 | ``` 142 | 143 | The example inspection process is shown in the video demo as below: 144 | 145 | https://github.com/Zhefan-Xu/CERLAB-UAV-Autonomy/assets/55560905/0e580d08-7003-4732-a5b0-5d4041f7d3fd 146 | 147 | 148 | ## IV. PX4 Simulation & Real Flight 149 | This section talks about running this framework in the PX4-based simulation or conducting real flight experiments. Please first follow the PX4 simulation installation guide as provided in [uav_simulator](https://github.com/Zhefan-Xu/uav_simulator). 150 | 151 | Before getting started, please make sure you are in the ```px4``` branch of the submodule [autonomous_flight](https://github.com/Zhefan-Xu/autonomous_flight) for the following demos (please check the link for detailed explanations): 152 | ``` 153 | cd path/to/autonomous_flight 154 | git branch 155 | 156 | # if the output says you are not in the px4 branch, please run the following (otherwise please ignore): 157 | git checkout px4 158 | cd ~/catkin_ws 159 | catkin_make clean # if you switch the branch for autonomous_flight 160 | catkin_make 161 | ``` 162 | 163 | ### a. PX4 Simulation Experiments 164 | The purpose of having another PX4 simulation (besides the simulator we have shown in the previous section) is to simulate **ALL** behaviors that we might encounter in the real flight. To run the same demos in the previous section, the only change we need to do is to run the following command to start the simulator instead. 165 | ``` 166 | # start PX4 simulator 167 | roslaunch uav_simulator px4_start.launch 168 | ``` 169 | 170 | ### b. Real Flight Experiments 171 | Once you have tested the flight in the PX4 simulation, the real flight experiments will have exactly the same behavior as you saw in the simulation. The inputs required for this framework in the real flight experiments are: 172 | - ```The robot pose/odometry```: The framework requires a SLAM/VIO system that can estimate the robot states. 173 | - ```The depth image```: The framework expects the depth image to detect objects and construct the map. 174 | 175 | Check all the parameters in the [autonomous_flight](https://github.com/Zhefan-Xu/autonomous_flight) accordingly before the actual flight!!! 176 | 177 | ### c. Examples of Real Flight Experiments 178 | a. The example of real flight experiment for **autonomous navigation**: 179 | 180 | https://github.com/Zhefan-Xu/CERLAB-UAV-Autonomy/assets/55560905/f635a4c9-6996-44d2-85fe-5fecaed33054 181 | 182 | b. The example of real flight experiment for **autonomous exploration**: 183 | 184 | https://github.com/Zhefan-Xu/CERLAB-UAV-Autonomy/assets/55560905/ea838535-b052-4713-b1b2-4690bf4a7369 185 | 186 | c. The example of real flight experiment for **autonomous inspection**: 187 | 188 | https://github.com/Zhefan-Xu/CERLAB-UAV-Autonomy/assets/55560905/4878fc3a-528d-4c82-a621-71ffadc092ab 189 | 190 | 191 | 192 | ## V. Citation and Reference 193 | If you find this work useful, please consider to cite our papers: 194 | - Zhefan Xu\*, Christopher Suzuki\*, Xiaoyang Zhan, Kenji Shimada, "Heuristic-based Incremental Probabilistic Roadmap for Efficient UAV Exploration in Dynamic Environments”, IEEE International Conference on Robotics and Automation (ICRA), 2024. [\[paper\]](https://arxiv.org/pdf/2303.00132.pdf) [\[video\]](https://youtu.be/fjVJCgDemjc?si=9nsWhReMeJH5JC3Q). 195 | - Zhefan Xu and Kenji Shimada, “Quadcopter Trajectory Time Minimization and Robust Collision Avoidance via Optimal Time Allocation”, IEEE International Conference on Robotics and Automation (ICRA), 2024. [\[paper\]](https://arxiv.org/abs/2309.08544) [\[video\]](https://youtu.be/wI8KGcxsyMI?si=1QfDPrm8s6Hfv8vf) 196 | - Zhefan Xu\*, Xiaoyang Zhan\*, Yumeng Xiu, Christopher Suzuki, Kenji Shimada, "Onboard dynamic-object detection and tracking for autonomous robot navigation with RGB-D camera”, IEEE Robotics and Automation Letters (RA-L), 2024. [\[paper\]](https://ieeexplore.ieee.org/document/10323166) [\[video\]](https://youtu.be/9dKX3BRnxyw). 197 | - Zhefan Xu, Baihan Chen, Xiaoyang Zhan, Yumeng Xiu, Christopher Suzuki, and Kenji Shimada, “A Vision-Based Autonomous UAV Inspection Framework for Unknown Tunnel Construction Sites With Dynamic Obstacles”, IEEE Robotics and Automation Letters (RA-L), 2023. [\[paper\]](https://ieeexplore.ieee.org/document/10167713) [\[video\]](https://youtu.be/MSNp-hg9RCQ?si=VQ1Yl3OWrw9MfNe1) 198 | - Zhefan Xu\*, Xiaoyang Zhan\*, Baihan Chen, Yumeng Xiu, Chenhao Yang, and Kenji Shimada, "A real-time dynamic obstacle tracking and mapping system for UAV navigation and collision avoidance with an RGB-D camera”, IEEE International Conference on Robotics and Automation (ICRA), 2023. [\[paper\]](https://ieeexplore.ieee.org/abstract/document/10161194) [\[video\]](https://youtu.be/u5zblVx8KRc?si=3c2AC9mc6pZBUypd). 199 | - Zhefan Xu, Yumeng Xiu, Xiaoyang Zhan, Baihan Chen, and Kenji Shimada, “Vision-aided UAV Navigation and Dynamic Obstacle Avoidance using Gradient-based B-spline Trajectory Optimization”, IEEE International Conference on Robotics and Automation (ICRA), 2023. [\[paper\]](https://ieeexplore.ieee.org/abstract/document/10160638) [\[video\]](https://youtu.be/xlMAL8aBHHg?si=4E5vShz7spxZDzps) 200 | - Zhefan Xu, Di Deng, and Kenji Shimada, “Autonomous UAV Exploration of Dynamic Environments via Incremental Sampling and Probabilistic Roadmap”, IEEE Robotics and Automation Letters (RA-L), 2021. [\[paper\]](https://ieeexplore.ieee.org/document/9362184) [\[video\]](https://youtu.be/ileyP4DRBjU?si=KFJLt-rLCa3tFaRH) 201 | 202 | ## VI. Acknowledgement 203 | The author would like to express his sincere gratitude to Professor Kenji Shimada for his great support and all CERLAB UAV team members who contribute to the development of this research. 204 | 205 | ## VII. Write at the End 206 | This repository concludes my first two-year Ph.D. work at CMU, and I would like to share it to contribute to the autonomous UAV research community. At the beginning, I truly felt the frustration as an autonomous robot researcher due to the lack of a comprehensive development framework. As a result, I hope my code can provide researchers a comprehensive and easy-to-understand platform and let them focus on algorithm/theory design instead of the software pipeline. In the meanwhile, this research and developed framework are not perfect and can be further improved; **thus, I am actively looking for collaborators in research and development to improve the UAV/robot autonomy level. Please don't hesitate to reach out for potential collaboration!** 207 | 208 | -------------------------------------------------------------------------------- /ignore-me.cpp: -------------------------------------------------------------------------------- 1 | // This file is used ONLY for GitHub language tag. You just wasted 10 seconds. Please close this file and do whatever. 2 | #include 3 | 4 | // Define functions representing components of the CERLAB UAV Autonomy Framework 5 | void simulator() { 6 | std::cout << "Simulator: Simulating UAV environment.\n"; 7 | } 8 | 9 | void perception() { 10 | std::cout << "Perception: Detecting obstacles and targets.\n"; 11 | } 12 | 13 | void mapping() { 14 | std::cout << "Mapping: Creating a map of the environment.\n"; 15 | } 16 | 17 | void planning() { 18 | std::cout << "Planning: Generating a flight path.\n"; 19 | } 20 | 21 | void control() { 22 | std::cout << "Control: Executing the flight path.\n"; 23 | } 24 | 25 | int main() { 26 | // Print introduction 27 | std::cout << "Welcome to the CERLAB UAV Autonomy Framework, a versatile and modular framework for autonomous unmanned aerial vehicles (UAVs).\n"; 28 | std::cout << "This framework comprises distinct components (simulator, perception, mapping, planning, and control) to achieve autonomous navigation, unknown exploration, and target inspection.\n\n"; 29 | 30 | // Perform some interesting stuff with the framework 31 | std::cout << "Let's do some interesting stuff with the framework:\n"; 32 | 33 | // Simulate UAV environment 34 | simulator(); 35 | 36 | // Detect obstacles and targets 37 | perception(); 38 | 39 | // Create a map of the environment 40 | mapping(); 41 | 42 | // Generate a flight path 43 | planning(); 44 | 45 | // Execute the flight path 46 | control(); 47 | 48 | return 0; 49 | } 50 | --------------------------------------------------------------------------------