mrs-brubotics/droneswarm_brubotics

The entry point to the Brubotics droneswarm project, based on MRS UAV system platform.

droneswarm_brubotics system

• TODO[give overview picture rviz, sim, reality]
• TODO[give overview of what this syste allows]
• TODO check symbolic link explanation

The droneswarm_brubotics system is a software framework for fundamental and applied research in robotics, automation, control, and AI with a focus on multi-robot systems composed of Unmanned Aerial vehicles (UAVs).

It is mainly developed at the Robotics and Multibody Mechanics (R&MM) research group of the Vrije Universiteit Brussel (VUB), Belgium, which is a member of VUB's Brussels Human Robotics Research Center (BruBotics) consortium. Several of the packages were developed in collaboration with the Robotics, Optimization, and Constrained Control (ROCC) lab of the University of Colorado Boulder, USA.

The main project owners and collaborators are:

• Bryan Convens (bryan.convens@vub.be): project owner, postdoc at R&MM;
• Kelly Merckaert: project co-owner, postdoc student at R&MM;
• Marco M. Nicotra: project collaborator, Assistant Professor at ROCC responsible for providing several ideas related to the implemented navigation and control algorithms;
• Bram Vanderborght: project collaborator, Professor at R&MM reponsible for obtaining funding to support this project;
• Several MA2 students and interns at R&MM have contributed to this project.

This project would not have been possible without the funding from:

• FWO
• imec
• Flanders AI Research

All packages are extensions or alternatives to those provided by the Multi-robot Systems (MRS) Group of the CTU in Prague and are organized in the same way. We mostly work with multi-rotor UAVs, and for them specifically, we developed this navigation, control, and estimation software. This can be tested both in simulation and on real-world robotic platforms. We believe that real-world and replicable experiments should support excellent research and science in robotics. Our platform is built to allow safe verification of these approaches in planning, control, estimation, computer vision, tracking, and more.

Meta-repositories

These meta-repositories aggregate related packages. TODO do similar as ctu

System properties

For a list of main features see the list provided by CTU. Additionally, we provide distributed control algorithms that have stronger correctness (i.e., safety, performance, computational efficiency, robustness) guarantees compared to several of the control algorithms provided by CTU as the latter rely heavily on more failure-prone user-tuned heuristics.

Documentation

The primary source of documentation of this project is explained here documentation package, but we also recommend going through CTU's documentation. We advise all new users to read through all tutorials and README files of all packages before using this system. Take a 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. If issues arise related to the brubotics systems open an issue here, if it is related to CTU's mrs_uav_system then open an issue here. The system follows a description presented in the article: TODO[add link to tutorial style article similar as ctu]

Unmanned Aerial Vehicles

The droneswarm_brubotics system is currently pre-configured for the following UAV platforms, operated by R&MM. The platforms are ordered by the size/payload capacity. TODO[add pictures similar as ctu]

• f450
• t650

Related packages

TODO[add those similar as ctu] The following packages are not necessarily part of our automatic installation. Therefore, you might need to clone some of them by yourself and place them in your ROS workspace. Some of those are forks of third-party repositories.

• controllers_brubotics: ROS
• trackers_brubotics: ROS
• planners_brubotics: ROS
• testing_brubotics: ROS
• visualization_brubotics: ROS
• documentation_brubotics

Backwards (in)compatibility and updates

We do not guarantee backward compatibility at any time. The platform is evolving according to the needs of the R&MM group. Updates can be made that are not going to 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:

• WIP: the mrs_uav_system version 1.5 underwent many changes which makes that this system needs to be updated. We advise also to take a look at backwards compatibility and updates of CTU.

Installation

Singularity and Docker

TODO[do similar as ctu]

Native installation

Prerequisites

• Install Ubuntu 20.04 LTS desktop on a sufficiently powerful machine inteded to be used a simulation desktop (most demanding due to Gazebo simulation) or as on-board UAV computer. Note that most cheaper laptops give poor performance when running this framework. Follow these instructions, boot from USB flash drive by creating a bootable memory stick as explained in this tutorial. Download the Ubutnu .iso desktop image here. Note TODO[move to tutorial chapter explaining the ubuntu settings]: (re)installing Ubuntu on the lab desktop is is not trivial. Contact the responsible of this package in case Ubuntu needs to be reinstalled on that machine.
• We recommend to configure the Ubuntu machine as explained in this tutorial in order to use all its functionalities.
• We assume the user regularly updates and upgrades the packages on the Ubuntu machine to the most recent version by running the Software Updater or by:

  sudo apt-get update

  sudo apt-get upgrade

  If there are packages which are failed to be updated or upgraded, first resolve this issue.

Installation of the droneswarm_brubotics system dependancies

• DO NOT DO THIS ANYMORE!!! If this machine needs a first installation of the the mrs_uav_system and the droneswarm_brubotics we advice to first install the latest version of cmake as explained at the end of this section and then continue with the native installation of the mrs_uav_system.
• If on this machine the mrs_uav_system and the droneswarm_brubotics needs to be reinstalled then follow these steps.

Installation of the mrs_uav_system

• Refer yourself to the mrs_uav_system and their tutorial to natively install and build the software. We do not require you to install ctu's linux environment. Before installation, check here that the build status of the mrs_uav_system is passing (green). If the build status is failing (red), you can copy their default install commands but replace the line

  git checkout master

  by the latest stable commit

  git checkout ba528c5e89aaf109731fb3bda5dc53219d513952

  which basically downgrades the mrs_uav_system as to ensure compatibility with the droneswarm_brubotics system.
• If not all packages are built correctly, try the multiple times catkin build in the mrs_workspace folder or the full installation in a new terminal.
• If too much RAM memory is required during the building process your screen will freeze, try catkin build -j2 which ensures not more than two processes are used in parallel for building the software. Repeat catkin build until there are no errors and no warnings any more.
• If successful, this installation process creates the git, mrs_workspace and workspace folders in your home directory.
• It also automatically updates your ./bashrc file that is loaded each time you open a new terminal. You can find the ./bashrc in the Home directory by clicking on the three bars and checking the "Show Hidden Files" box.
• To test if the installation was successful, launch the following shell script

  cd ~/mrs_workspace/src/simulation/example_tmux_scripts/one_drone_gps
  ./start.sh
  

  The gazebo simulator should launch, together with rviz and a UAV should be taking off.

  cd ~/mrs_workspace/src/simulation/example_tmux_scripts/one_drone_rtk
  ./start.sh
  

  Now the same should happen, but odometry should be set to RTK instead of normal GPS.
• Avoid changing any code in any of ctu's packages, unless there is no other way to implement your functionality. If your application requires custum settings in ctu's packages, document clearly where these changes are required since these will need to be (un)done manually each time the software is reisntalled or used for other purposes.
• Regularly reinstall ctu's mrs_uav_system as it is evolving continuously and update the commits of all packages for which the droneswarm_brubotics codes works in this readme.
• If after installtion of the mrs_uav_system you cannot updated your machine anymore as described above and when shutting down, the ubutnu loader displays forever, there might be this known and solved issue wiuth the google-guest-agent service. Follow the steps here and use htop to kill the google-guest processes. After these steps make sure you can update yuor system. If you cannot, go to Ubutnu's Software Updater and follow the steps.
• Regularly check ctu's "Backwards compatibility and updates" section and see if it affects your code.

Downgrading of default mrs_uav_system packages

Below we prove the commits of the standard mrs_uav_sytem packages that guarantee functionality of the droneswarm_brubotics system. mrs_package_to_downgrade:

cd ~/mrs_workspace/src/.../mrs_package_to_downgrade
git pull origin master
git checkout commit_to_downgrade

Rebuild the mrs_uav_system:

cd ~/mrs_workspace
catkin build 

Test a .sh script.

  cd ~/mrs_workspace/src/simulation/example_tmux_scripts/.../
  ./start.sh

Installation of some non-standard ctu packages

These packages are required dependancies of droneswarm_brubotics which have to be installed to obtain full functionality:

• mrs_gazebo_extras_resources
• trajectory_loader
• mrs_serial
• nimbro_network

However, these will be automatically installed with the droneswarm_brubotics via this install script.

Only for onboard UAV computers: for the nimbro_network to work follow the Automatic Installation steps listed in the README and when requested say yes 'y' to permanantly enable multicast. TODO REFER TO DETAILED STEPS OF NIMBRO

Regularly update the commits in this install script for which functionality with droneswarm_brubotics is guaranteed.

Installation of other dependancies

None for now.

Native installation of the droneswarm_brubotics system

We provide installation scripts that set everything up for you. Our automated installation will:

• clone droneswarm_brubotics into your git folder;
• source our shell_brubotics_additions.sh script;
• link it to yourworkspace folder;
• install depedencies for the ROS packages controllers_brubotics, trackers_brubotics, planners_brubotics, testing_brubotics, and visualization_brubotics into droneswarm_brubotics/ros_packages;
• install the package documentation_brubotics which contains the Read the Docs tutorial;
• build theworkspace

To start the automatic installation, please paste the following code into your terminal and press enter

cd /tmp
echo '
GIT_PATH=~/git
mkdir -p $GIT_PATH
cd $GIT_PATH
git clone https://github.com/mrs-brubotics/droneswarm_brubotics.git
cd droneswarm_brubotics/script/
./install.sh -g $GIT_PATH
'> clone.sh && source clone.sh

• Follow the output generated during the installation process. There are no issues if during the 'Installing dependencies...' all repos are cloned and checked out sucessfully (e.g., no uncommitted changes). You should now see these cloned repos in the git folder and in the workspace folder.
• Installing the first time on a new machine will throw the error: git@github.com: Permission denied (publickey).
  • First, you need to setup your ssh keys correctly by following these steps. This needs to be done for each machine you use. The current ssh keys can be found in home/.shh. Make sure you enables "Show Hidden Files" in the Home directory.
  • Since August 2021 developers are required to use personel access tokens. Follow these steps to generate these tokens.
• Some packages require manual installation of the following dependencies once on each new machine:
  • documentation_brubotics for python3 and sphinx-rtd-theme

Manual changes to be made after installation

Colorblind mode of the status window

If you are NOT colorblind, set colorblind_mode: False in the ~/mrs_workspace/src/uav_core/ros_packages/mrs_uav_status/config/default.yaml.

Simulating and experimenting with mass and motor parameters that resemble those found on our UAV hardware

Some of ctu's default UAV mass (and inertia) and motor parameters (and actuator constraints) were found to be quite different from the real values estimated on the UAV hardware platforms we have built. Therefore it is important to know where, how, and in which cases these parameters can be changed. Mass: In order to simulate with a hardware UAV mass (2.40 kg for f450, TODO??kg for t650) some manual changes are required in the mrs_uav_system (explained for the f450):

• Open ~/mrs_workspace/src/simulation/ros_packages/mrs_simulation/models/mrs_robots_description/urdf/f450.xacro and adjust the mass: <xacro:property name="mass" value="${2.40-0.005*4.0-0.015-0.00001}" /> <!-- [kg] 2.40--> . This ensures that Gazebo simulates a UAV model with the hardware mass. Note that the xacro has slight offset from 2.4kg since afterwards some small masses (of motors, sensors) are added to the uav so we subtract them before they are added.
• Open ~/mrs_workspace/src/uav_core/ros_packages/mrs_uav_managers/config/simulation/f450/mass.yaml and adjust the mass: uav_mass: 2.40 #2.00 # [kg]. This ensures that the controllers and trackers that use mass (e.g., for feedforward actions) use th hardware mass.
• Catkin build the mrs_worspace (although not strcitly necessary if you only change configs, make a habit to catkin build more than too less)
• Do not forget to do the above steps each time you reinstall the mrs_uav_system! For hardware experiments the UAV mass used in the controllers and trackers is the one set in the ~/.bashrc, hence the above changes do not effect operation on hardware.
• For UAVs with payload, you need to do the same for what concerns mass of only the UAV (excluding payload mass), but you also need to ensure that the xacro of the payload has the same payload mass as the one you use in the controller and tracker. For 2 UAVs each UAV offcourse compensates for half of the bar's mass instead of the total payload mass in the case of one UAV with cable suspended load. Motor parameters: In order to simulate and experiment with correct motor parameters that resemble hardware operation please take a look at regulation_control_predictions_one_drone_rtk for what concerns the thrust_saturation value in custom_configs/gains and the motor_params in custom configs/motor_params_hardware.yaml and in custom configs/motor_params_simulation.yaml. These are configred for the f450 UAV, the values for the t650 UAV are TODO.

Reinstalling mrs_uav_system and droneswarm_brubotics

We advice to regularly reinstall the mrs_uav_system and droneswarm_brubotics to check if everything still installs correctly. Before reinstalling, delete the mrs_uav_system and/or droneswarm_brubotics folder inside the git folder and inside the workspace folder. If you would like to reinstall everything just delete the git, the mrs_workspace and the worksapce folder. This procedure is the same for each installed package. If there are installation or building problems which you cannot solve, please open an issue immediately.

Matlab Plots

• For data processing and plotting Matlab and Simulink version 2021a is at least required with the following toolboxes installed:

  • ROS toolbox
  • TODO add all toolboxes

  In order to be able run the Matlab scripts that generate plots based on custom ctu mrs and/or brubotics ROS messages, first run the corresponding section of the script ~/workspace/src/droneswarm_brubotics/useful_files/matlab/custom_msgs.m and perform the resulting Matlab instructions. Don't forget to include the matlab_msg_gen_ros1 folder into the matlab path. Do this each time you reinstall droneswarm_brubotics. Note: DO NOT DO THIS ANYMORE!!! if matlab throws an error that a newer version of cmake is required to generate the ROS msgs and srvs (this error <https://nl.mathworks.com/matlabcentral/answers/623103-matlab-2020b-rosgenmsg-can-t-find-cmake>__), first check your version of cmake by

  cmake --version

  you can install the newest version of cmake by following these steps (https://apt.kitware.com/) (strongly advised). Another non-advised, but working procedure is to build any cmake version from source as explained in Installing the Latest CMake on Ubuntu Linux. The installation procedure can take a few minutes. Do not forget to execute the last command sudo make install since it is not automatically launched when copying the code block. When you have not deleted the old version of cmake you won't automatically find a new version and an error is reported in the terminal when checking the cmake version (this problem: https://discourse.cmake.org/t/could-not-find-cmake-root/216/13). Either now you follow the first approach or you delete the old version and remove the old version (described on the top of Installing the Latest CMake on Ubuntu Linux), and reinstall. The catkin build command will not work anymore. Then reinstall everything starting from the top of this page.

  You could first also try

   sudo apt-get install cmake

  but it will not necessarily install the newest cmake vesion.g the code block. When you have not deleted the old version of cmake you won't automatically find a new version and an error is reported in the terminal when checking the cmake version (this problem: https://discourse.cmake.org/t/could-not-find-cmake-root/216/13). Either now you follow the first approach or you delete the old version and remove the old version (described on the top of Installing the Latest CMake on Ubuntu Linux), and reinstall. The catkin build command will not work anymore. Then reinstall everything starting from the top of this page.

  You could first also try

   sudo apt-get install cmake

  but it will not necessarily install the newest cmake vesion.

Documentation

ros_packages

See related-packages section.

script

• install.sh : will source shell_brubotics_additions, add specific purpose .bashrc configs, link the to be installed (ROS) packages to ~/workspace/src, installs these packages defined in .gitman.yml, and automatically builds all the packages in mrs_workspace and workspace.
• NOT USED CURRENTLY pull_all.sh : will pull files from this github but also it will pull files for the mrs_uav_core and for mrs_simulation.
• NOT USED CURRENTLY overwrite_mrs_files : will overwrite mrs_workspace files in favour of files that you can find into useful_files/mrs_files/.
• NOT USED CURRENTLY restore_mrs_files : will restore mrs_workspace files from the previous overwriting.

shell_additions

Contains shell_additions.sh : which contains the definitions of used shell functions used in the testing_brubotics pacakge.

useful_files

• matlab : link to the github which contains a script that makes our custom ROS messages interpretable by Matlab.
• NOT USED CURRENTLY mrs_files : Contains modified files that we have to implement into mrs_workspace. In the control_manager.cpp file, disable_safety features are implemented.

Adding a new repository under the default installed repositories of droneswarm_brubotics

• Update the gitman.yaml.
• Create a symbolic link to a directory as is explained here and here.
• First create a directory with the same name as the repo name you used in the gitman.yaml. The symbolic link is created by:

  ln -s symLinkFolderName/ relativepathto/.gitman/repo_name_used_in_gitman.yaml

  For example: make sure .gitman/fbstab.yaml does not exist yet and droneswarm_brubotics/fbstab contains the latest version of fbstab

  cd ~
  ln -s .gitman/fbstab/ ~/workspace/src/droneswarm_brubotics/fbstab

  This creates the symbolic link .gitman/fbstab
• Put ROS packages in the ros_packages directory and other repositories elsewhere in droneswarm_brubotics.
• You should push the changes in droneswarm_brubotics such that the symbolic link (e.g., example for documentation_brubotics) is git version controlled.

Running the simulation

If you have successfully installed the system, you can continue with starting the simulation. TODO[addhardware specific links]