The Multi-robot Systems Group is a robotics lab at the Czech Technical University in Prague. We specialize in multi-rotor helicopters, and for them specifically, we develop this control, estimation, and simulation system. We think real-world and replicable experiments should support excellent research and science in robotics. Thus, our platform is built to allow safe real-world experimental validation of approaches in planning, control, estimation, computer vision, tracking, and more.
⚠️ Attention please: This README needs work.The MRS UAV System 1.5 is being released, and this page needs updating. Please remember that the information on this page might not be valid. Check this WIP Google Document for the latest news and changes.
Note: The MRS UAV system v1.5 is still a Work-In-Progress and the documentation is undergoing maintanance (Issue#169). You can find the changes and new instructions in here WIP Google Document. Any feedback is welcome (you can use the issues in this repo or comment on the Google Doc)!
The system is
- built on the Robot Operating System Noetic,
- meant to be executed entirely onboard on a companion computer,
- can control underactuated multirotor helicopters,
- contains control, state estimation, mapping, and planning pipelines.
The primary documentation source is here: https://ctu-mrs.github.io/. However, the website only scratches the surface of what it should contain (and we know it). Our system is a research-oriented platform, and it evolves rapidly. Most of our users are either researchers (who already know the platform) or freshmen students (who might not know ROS). Maintaining up-to-date documentation for such an audience is hard work since we mostly develop the system while using it for our research. So, instead, we aim at educating our students to look around the packages (each contains its own README), explore the launch files, and be able to read the code, which we strive to keep readable.
The control and estimation system are described in the article doi.org/10.1007/s10846-021-01383-5, pdf:
Baca, T., Petrlik, M., Vrba, M., Spurny, V., Penicka, R., Hert, D., and Saska, M.,
"The MRS UAV System: Pushing the Frontiers of Reproducible Research, Real-world Deployment, and
Education with Autonomous Unmanned Aerial Vehicles", J Intell Robot Syst 102, 26 (2021).
- Install the Robot Operating System (Noetic):
curl https://ctu-mrs.github.io/ppa-stable/add_ros_ppa.sh | bash
sudo apt install ros-noetic-desktop-full-
Configure your ROS environment according to http://wiki.ros.org/ROS/Tutorials/InstallingandConfiguringROSEnvironment
-
Add the stable PPA into your apt-get repository:
curl https://ctu-mrs.github.io/ppa-stable/add_ppa.sh | bash-
>>> Special instructions for the MRS System developers <<<
- Instead of the stable PPA, you can add the unstable PPA, for which the packages are build immediatelly after being pushed to master.
- If you have both PPAs, the unstable has a priority.
- Beware! The unstable PPA might be internally inconsistent, buggy and dangerous!
- Install the MRS UAV System:
sudo apt install ros-noetic-mrs-uav-system-full- Start the example Gazebo simulation session:
roscd mrs_uav_gazebo_simulation/tmux/one_drone
./start.shPlease follow this link to learn how to run our system using Apptainer.
Please follow this link to learn how to run our system using Apptainer.
This tutorial assumes you've installed the MRS UAV System natively or are running a Apptainer container.
- Setup a catkin workspace:
source /opt/ros/noetic/setup.bash # source the general ROS workspace so that the local one will extend it and see all the packages
mkdir -p ~/workspace/src && cd ~/workspace # create the workspace folder in home and cd to it
catkin init -w ~/workspace # initialize the new workspace
# setup basic compilation profiles
catkin config --profile debug --cmake-args -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_FLAGS='-std=c++17 -Og' -DCMAKE_C_FLAGS='-Og'
catkin config --profile release --cmake-args -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_FLAGS='-std=c++17'
catkin config --profile reldeb --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_CXX_FLAGS='-std=c++17'
catkin profile set reldeb # set the reldeb profile as active
- You can repurpose one of our examples as a starting point (optional):
# it is good practice to not clone ROS packages directly into a workspace, so let's use a separate directory for this
git clone git@github.com:ctu-mrs/mrs_core_examples.git ~/git/mrs_core_examples # clone this repository (recommended, requires private key on Github)
# git clone https://github.com/ctu-mrs/mrs_core_examples.git ~/git/mrs_core_examples # if you do not have a private key set up on Github, you can use https instead of ssh
export NEW_PACKAGE=replaceme # fill the NEW_NAME variable with your desired name of the new package (no spaces)
cp -r ~/git/mrs_core_examples/cpp/waypoint_flier ~/git/$NEW_PACKAGE # copy an example package (e.g. the waypoint_flier)
cp ~/git/mrs_core_examples/repurpose_package.sh ~/git/$NEW_PACKAGE # copy the repurpose_package.sh script to the new package
cd ~/git/$NEW_PACKAGE && ./repurpose_package.sh example_waypoint_flier $NEW_PACKAGE --camel-case # use the script to replace all occurences of the old name
- Link your package to the workspace and build it (the code below assumes you set the
NEW_PACKAGEvariable):
ln -s ~/git/$NEW_PACKAGE ~/workspace/src # create a symbolic link of the package to the workspace
cd ~/workspace/src && catkin build $NEW_PACKAGE # build the package within the workspace
- Now, you can use the new package:
source ~/workspace/devel/setup.bash # source the workspace to see the packages within (if you don't use bash, source the appropriate script instead)
roscd $NEW_PACKAGE # now ROS knows about your new package and you can roscd to it
Note: It is recommended to add the source ~/workspace/devel/setup.bash command to your ~/.bashrc to be executed automatically with every new workspace.
- Create a remote for your new package (depends on your git server) and push to it:
cd ~/workspace/src/$NEW_PACKAGE && git add . && git commit -m "initial commit" # create the first commit in the new repository
git remote add origin <your-new-remote> # replace <your-new-remote>
git push --set-upstream origin master # push your initial commit
Note: Do not forget to git commit git push regularly during development!
| Main metapackages | Contents | Repository | Package |
|---|---|---|---|
| MRS UAV System | UAV Core & UAV Modules | mrs_uav_system | ros-noetic-mrs-uav-system |
| MRS UAV System - Full | All of the bellow | mrs_uav_system | ros-noetic-mrs-uav-system-full |
| Optional Modules & metapackages | Repository | Package |
|---|---|---|
| UAV Core | mrs_uav_core | ros-noetic-mrs-uav-core |
| UAV Modules | mrs_uav_modules | ros-noetic-mrs-uav-modules |
| Octomap Mapping+Planning | mrs_octomap_mapping_planning | ros-noetic-mrs-octomap-mapping-planning |
| ALOAM Core | mrs_aloam_core | ros-noetic-mrs-aloam-core |
| LIO-SAM Core | mrs_liosam_core | ros-noetic-mrs-liosam-core |
| Hector Core | mrs_hector_core | ros-noetic-mrs-hector-core |
| OpenVINS Core | mrs_open_vins_core | ros-noetic-mrs-open-vins-core |
| Precise Landing | mrs_precise_landing | ros-noetic-mrs-precise-landing |
| Simulators | Repository | Package |
|---|---|---|
| Gazebo Simulation | mrs_uav_gazebo_simulation | ros-noetic-mrs-uav-gazebo-simulation |
| MRS Simulation | mrs_multirotor_simulator | ros-noetic-mrs-multirotor-simulator |
| Coppelia Simulation | mrs_uav_coppelia_simulation | ros-noetic-mrs-uav-coppelia-simulation |
| Unreal Simulation | mrs_uav_unreal_simulation | ros-noetic-mrs-uav-unreal-simulation |
| Hardware API plugins | Repository | Package |
|---|---|---|
| PX4 API | mrs_uav_px4_api | ros-noetic-mrs-uav-px4-api |
| DJI Tello API | mrs_uav_dji_tello_api | ros-noetic-mrs-uav-dji-tello-api |
| Examples | Repository | Build status |
|---|---|---|
| Core examples | mrs_core_examples |  |
| Computer Vision examples | mrs_computer_vision_examples |  |
| Gazebo Custom Drone example | mrs_gazebo_custom_drone_example |  |
Build status (Buildfarm)
We utilize acceptance tests to determine the releasaiblity of the system and to release the system automatically. The stable version of our system should be installable and working allways regardless of the state of the tests and red flags below.
The multiarch docker image contains the ros-noetic-mrs-uav-system-full.
See the MRS Docker repository for information on how to run the MRS UAV System using docker.
| Stable | Testing | Unstable |
|---|---|---|
 |
 |
 |
| Rel. candidate | Unstable | Test coverage | |
|---|---|---|---|
 |
 |
 |
| Stable | Release Candidate | Unstable | |
|---|---|---|---|
| MRS ROS Packages |  |
|
 |
| Thirdparty ROS packages |  |
 |
 |
| Non-ROS packages |  |
 |
 |
| Stable | Unstable | |
|---|---|---|
| MRS ROS Packages |  |
 |
| Thirdparty ROS packages |  |
 |
| Non-ROS packages |  |
 |
The MRS UAV system is pre-configured for the following UAV platforms operated by the MRS. The UAV platforms can be purchased from our partner company Fly4Future.
| Model | Simulation | Real UAV |
|---|---|---|
| DJI f330 |  |
 |
| DJI f450 |  |
 |
| Holybro x500 |  |
 |
| DJI f550 |  |
 |
| Tarot t650 |  |
 |
| T-Drones m690 |  |
 |
| NAKI II |  |
 |
We do not guarantee backward compatibility at any time. The platform is evolving according to the needs of the MRS group. Updates can be made that will not be compatible with users' local configs, simulation worlds, tmux sessions, etc. However, when we change something that requires user action to maintain compatibility, we will create an issue in this repository labeled users-read-me. Subscribe to this repository updates and issues by clicking the Watch button in the top-right corner of this page. Recent changes requiring user action:
- now: Work-in-Progress MRS UAV System 1.5: many changes
- January 17, 2023: Updates for px4 firmware v1.13.2
- March 8, 2022: mrs_lib::Transformer interface updated
- December 09, 2021: not building with --march=native anymore
- December 25, 2020: Updated controller interface, updated thrust curve parametrization
- December 15, 2020: Rework of simulation UAV spawning mechanism, Noetic update
- November 12, 2020: GPS coordinates within Gazebo world need changing
- November 12, 2020: Rangefinder fusion needs enabling in simulation sessions
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
