/agilicious

Agile flight done right!

Primary LanguageTeXGNU General Public License v3.0GPL-3.0


Agilicious: Open-Source and Open-Hardware Agile Quadrotor for Vision-Based Flight


Agile flight done right!


Read the Paper!
Watch the full Video!

Agilicious is a co-designed hardware and software framework tailored to autonomous, agile quadrotor flight, which has been developed and used since 2016 at the Robotics and Perception Group (RPG) of the University of Zurich. Agilicious is described in this Science Robotics 2022 paper. It is completely open-source and open-hardware and supports both model-based and neural-network-based controllers. Also, it provides high thrust-to-weight and torque-to-inertia ratios for agility, onboard vision sensors, GPU-accelerated compute hardware for real-time perception and neural-network inference, a real-time flight controller, and a versatile software stack. In contrast to existing frameworks, Agilicious offers a unique combination of flexible software and high-performance hardware. Agilicious has been used in over 30 scientific papers at our lab, including trajectory tracking for drone racing scenarios at up to 5g and 70km/h (SciRob21_Foehn, Video), vision-based acrobatic flight (RSS20 Kaufmann, Video), obstacle avoidance in both structured and unstructured environments using solely onboard perception (SciRob21_Loquercio, Video), and hardware-in-the-loop simulation in virtual-reality environments. Thanks to its versatility, we believe that Agilicious supports the next generation of scientific and industrial quadrotor research. The full list of publications using Agilicious can be found here.

Credits

If you use the code in the academic context, please cite:

Additionally, please cite the following papers for the specific extensions you make use of:

What's in it for you?

Agilicious is split in two parts, agilib and agiros.

agilib contains base classes and module implementations providing the base functionality necessary for agile flight. It contains controllers, estimators, and logic, but with minimal dependencies (mainly Eigen). It allows users to integrate Agilicious into their own infrastructure and can easily be extended with new modules. Meanwhile, agiros provides bindings to common ROS interfaces, which make it easy and quick to set up and get flying, both in simulation and real world.

In summary, this library offers the following modules:

  • Pipelines provide a modular way to combine controllers, estimators, reference trajectories into a complete control system. It is posible to create multiple pipelines and switch between them at runtime, allowing rapid prototyping.
  • Controllers
  • Estimators
    • A standard EKF using a pose estimate and propagating with IMU measurements.
    • An EKF that uses a constant acceleration model and the Pose + IMU measurements.
    • A feedthrough module that provides a simple way to pipe in your own estimate sources.
    • A mock estimator that can corrupt an estimate with noise and bias to simulate real-world properties.
  • References
    • Hover
    • Velocity Commands
    • Sampled Trajectories
    • Polynomial Trajectories
  • Samplers
    • Time-based sampling along a given reference.
    • Positional sampling along a given reference which allows to robustly handle large disturbances.
  • Bridges
    • RotorS interface
    • Serial bridge to interface with our own flight control software
    • Serial bridge to interface through LAIRD wireless modules.
    • Serial bridge to interface with BetaFlight controllers.
  • Pilot which handles all logic and interfacing.
  • Guard A safety guard implementation that can use a secondary estimate (e.g. motion capture) and take over if some criteria are invalidated. The guard can use a secondary pipeline configuration without relying on the user-defined modules. This allows for rapid prototyping with a virtual "safety net".
  • Simulator A sophisticated and configurable simulation that runs magnitudes faster than real time and optionally provides aerodynamic BEM models as described in Bauersfeld RSS'21.

License

The code is licensed under GPLv3. The official license file can be found here.

For commercial use, please contact sdavide [at] ifi [dot] uzh [dot] ch

Getting Started

If you use ROS, simply clone agilicious into your catkin workspace and catkin build:

# Create new catkin workspace.
cd catkin_ws/src

git clone https://github.com/catkin/catkin_simple
git clone git@github.com:uzh-rpg/agilicious.git

catkin build

If you want to use the library standalone, you can always

cd agilib/build
cmake ..
make

It is highly recommended to run agilicious inside a docker container, instructions are available here.

Launch your first simulation:

For launching simulations you need ROS. Once your compilation using catkin build has been successful, you can then source your catkin workspace and launch two different types of simulation:

  • Agisim simulation, by running the command roslaunch agiros agisim.launch. This simulation environment has been written by us and supports different levels of complexity. These levels of complexity can be configured in the file agiros/agiros/parameters/simulation.yaml, where, for example, if we would comment the lines with "ModelRotorSimple" and uncomment the lines with "ModelRotorBEM", then a BEM simulation will be launched.
  • Gazebo RotorS simulation, by running the command roslaunch agiros simulation.launch

These simulation environments allow the user to test their code by offering a user friendly GUI. The simplest task would be a "Go to pose", which can directly be executed by pressing buttons in the GUI. More complex maneuvers can also be performed, like trajectory tracking. For this, the trajectory can be loaded from a .csv file

How do I change the characteristics of my simulation?

Everything is structured in .yaml files. The most important of these .yaml files is the so-called "Pilot" file. For example, when launching the Agisim simulation, the agiros/agiros/parameters/simple_sim_pilot.yaml file is used. Here, the user can define which controller to use, which estimator to use, which quadrotor model to use, etc. If one were to change the mass of the quadrotor, for example, one would in this case need to modify the agiros/agiros/parameters/quads/kingfisher.yaml file.

Documentation

For documentation, we now use Doxygen!

At the moment, the documentation files are not provided and have to be built locally:

  1. Install doxygen sudo apt install doxygen
  2. Run doxygen in the root folder agilicious/ by simply issuing the doxygen command.
  3. Open the documentation in your favourite browser by clicking agilicious/docs/html/index.html!

Dependencies

Strictly necessary dependencies:

Dependencies to use all provides functionalities

Optional dependencies: