- Autonomous Drone Racing Project Course
To get you started with the drone racing project, you can head over to our documentation page.
To run the LSY Autonomous Drone Racing project, you will need 2 repositories:
- pycffirmware -
drone_racingbranch: A simulator for the on-board controller response of the drones we are using to accurately model their behavior. - lsy_drone_racing -
mainbranch: This repository contains the drone simulation, environments, and scripts to simulate and deploy the drones in the racing challenge
The first step is to fork the lsy_drone_racing repository for your own group. This has two purposes: You automatically have your own repository with git version control, and it sets you up for taking part in the online competition and automated testing (see competition).
If you have never worked with GitHub before, see the docs on forking.
The following assumes that you have a functional installation of either conda or mamba.
First, clone the new fork from your own account and create a new environment with Python 3.8 by running
mkdir -p ~/repos && cd repos
git clone https://github.com/<YOUR-USERNAME>/lsy_drone_racing.git
conda create -n race python=3.8
conda activate raceNote: It is important you stick with Python 3.8. Yes, it is outdated. Yes, we'd also like to upgrade. However, there are serious issues beyond our control when deploying the code on the real drones with any other version.
Now you can install the lsy_drone_racing package in editable mode from the repository root
cd ~/repos/lsy_drone_racing
pip install --upgrade pip
pip install -e .In addition, you also need to install the pycffirmware package from source with
cd ~/repos
git clone -b drone_racing https://github.com/utiasDSL/pycffirmware.git
cd pycffirmware
git submodule update --init --recursive
sudo apt update
sudo apt install build-essential
./wrapper/build_linux.shFinally, you can test if the installation was successful by running
cd ~/repos/lsy_drone_racing
python scripts/sim.pyIf everything is installed correctly, this opens the simulator and simulates a drone flying through four gates.
You can also install the extended dependencies with
conda activate race
cd ~/repos/lsy_drone_racing
pip install -e .[rl, test]and check if all tests complete with
cd ~/repos/lsy_drone_racing
pytest testsYou can also run the simulation with Docker, albeit without the GUI at the moment. To test this, install docker with docker compose on your system, and then run
docker compose build
docker compose upAfter building, running the container should produce the following output:
sim-1 | INFO:__main__:Flight time (s): 8.466666666666667
sim-1 | Reason for termination: Task completed
sim-1 | Gates passed: 4
sim-1 |
sim-1 | 8.466666666666667The complete problem is specified by a TOML file, e.g. level0.toml
The config folder contains settings for progressively harder scenarios:
| Evaluation Scenario | Constraints | Rand. Inertial Properties | Randomized Obstacles, Gates | Rand. Between Episodes | Notes |
|---|---|---|---|---|---|
| Level 0 | Yes | No | No | No | Perfect knowledge |
| Level 1 | Yes | Yes | No | No | Adaptive |
| Level 2 | Yes | Yes | Yes | No | Learning, re-planning |
| Level 3 | Yes | Yes | Yes | Yes | Robustness |
| sim2real | Yes | Real-life hardware | Yes | No | Sim2real transfer |
Note: "Rand. Between Episodes" (governed by argument
reseed_on_reset) states whether randomized properties and positions vary or are kept constant (by re-seeding the random number generator on eachenv.reset()) across episodes
You can choose which configuration to use by changing the --config command line option. To e.g. run the example controller on the hardest scenario, you can use the following command
python scripts/sim.py --config config/level3.tomlDuring the semester, you will compete with the other teams on who's the fastest to complete the drone race. You can see the current standings on the competition page in Kaggle, a popular ML competition website. The results of the competition will NOT influence your grade directly. However, it gives you a sense of how performant and robust your approach is compared to others. In addition, the competition is an easy way for you to check if your code is running correctly. If there are errors in the automated testing, chances are your project also doesn't run on our systems. The competition will always use difficulty level 3.
To take part in the competition, you first have to create an account on Kaggle. Next, use this invite link to join the competition, go to the drone racing competition, click on "Rules", and accept the competition conditions. This step is necessary to allow submissions from your account.
The competition submission to Kaggle is fully automated. However, to make the automation work with your Kaggle account, you first have to save your credentials in GitHub. GitHub offers a way to safely store this information without giving anyone else access to it via its secrets. Start by opening your account settings on Kaggle, go to the API section and click on Create New Token. This will download a json file containing two keys: Your account username and an API key. Next, open your lsy_drone_racing GitHub repository in the browser and go to Settings -> Secrets and variables -> Actions
Note: You have to select the repository settings, not your account settings
Here you add two new repository secrets using the information from the json file you downloaded:
- Name: KaggleUsername Secret: INSERT_YOUR_USERNAME
- Name: KaggleKey Secret: INSERT_YOUR_KEY
The whole point of the steps you just took was to set you up to use the GitHub action defined in your repository's .github folder. This workflow runs every time you push changes to your repository's main or master branch. To prevent submitting every iteration of your code, you can create new branches and only merge them into the main branch once you finished your changes. However, we recommend regularly updating your main branch to see how fast you are and if the code runs without problems.
Note: The competition will count your fastest average lap time. If a submission performed worse than a previous iteration, it won't update your standing.
Note: The first time the test runs on your account, it will take longer than usual because it has to install all dependencies in GitHub. We cache this environment, so subsequent runs should be faster.
Warning: Kaggle only accepts 100 submissions per day. While we really hope you don't make 100 commits in a single day, we do mention it just in case.
Once you have pushed your latest iteration, a GitHub action runner will start testing your implementation. You can check the progress by clicking on the Actions tab of your repository. If the submission fails, you can check the errors. Please let us know if something is not working as intended. If you need additional packages for your project, please make sure to update the environment.yaml file accordingly. Otherwise, the tests will fail. If you want to get a more detailed summary of your performance, you can have a look at the test output directly:
To implement your own controller, have a look at the example implementation. We recommend altering the existing example controller instead of creating your own file to not break the testing pipeline. Please also read through the documentation of the controller. You must not alter its function signatures. If you encounter problems implementing something with the given interface, contact one of the lecturers.
If you were able to install everything without any issues, but the simulation crashes when running the sim script, you should check the error messages for any errors related to LIBGL and GLIBCXX_3.4.30. If you don't find any conclusive evidence about what has happened, you might also want to run the simulation in verbose mode for LIBGL with
LIBGL_DEBUG=verbose python scripts/sim.pyNext, you should check if your system has the required library installed
strings /usr/lib/x86_64-linux-gnu/libstdc++.so.6 | grep GLIBCXX_3.4.30or if it is installed in your conda environment
strings /path-to-your-conda/envs/your-env-name/lib/libstdc++.so.6 | grep GLIBCXX_3.4.30If neither of those yield any results, you are missing this library and can install it with
conda install -c conda-forge gcc=12.1.0If the program still crashes and complains about not finding GLIBCXX_3.4.30, please update your LD_LIBRARY_PATH variable to point to your conda environment's lib folder.
To deploy the controllers on real drones you must install ROS Noetic and the crazyswarm package.
Clone the crazyswarm repository and follow its build steps.
cd ~/repos
git clone https://github.com/USC-ACTLab/crazyswarm
...Next, paste the following block into your terminal
cat <<EOF | sudo tee /etc/udev/rules.d/99-bitcraze.rules > /dev/null
# Crazyradio (normal operation)
SUBSYSTEM=="usb", ATTRS{idVendor}=="1915", ATTRS{idProduct}=="7777", MODE="0664", GROUP="plugdev"
# Bootloader
SUBSYSTEM=="usb", ATTRS{idVendor}=="1915", ATTRS{idProduct}=="0101", MODE="0664", GROUP="plugdev"
# Crazyflie (over USB)
SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="5740", MODE="0664", GROUP="plugdev"
EOF
# USB preparation for crazyradio
sudo groupadd plugdev
sudo usermod -a -G plugdev $USER
# Apply changes
sudo udevadm control --reload-rules
sudo udevadm triggerWe also need to install the Vicon bridge package to get access to the Vicon positions etc in ROS.
# Install Vicon bridge nodelet
cd <path/to/catkin_ws>/src/
git clone https://github.com/ethz-asl/vicon_bridge
cd ..
catkin_make
source <path/to/catkin_ws>/devel/setup.bashTo start the Vicon bridge by default, you may want to include it in the crazyswarm launchfile.
Optionally, you can also install cfclient to debug issues with the drones and configure IDs etc.
# (optional) Install cfclient
sudo apt install libxcb-xinerama0
conda create -n cfclient python=3.7
conda activate cfclient
pip install --upgrade pip # note: we are using a conda python3.7 env
pip install cfclient
conda deactivateIf libNatNet is missing either during compiling crazyswarm or launching hover_swarm.launch, one option is to manually install it. Download the library from its github repo, follow the build instructions, and then add the library to your LIBRARY_PATH and LD_LIBRARY_PATH variables.
Change the USB access permissions with
sudo chmod -R 777 /dev/bus/usb/
Make sure you are familiar with the configuration files. Not all options are relevant depending on the motion capture setup. For more info, see the official documentation.
The important config files are located in the crazyswarm ROS package:
- Crazyflies types — includes controller properties and marker configurations, etc.
- In-use Crazyflies — includes ID, radio channel, types, etc.
As well as the main launch file hover_swarm.launch.
Note: The following is NOT within a conda environment, but has to run directly on the system's Python 3.8 installation. ROS has never heard of these best practices you speak of.
In a terminal, launch the ROS node for the crazyflies. Change the settings in <path/to/crazyswarm/package>/launch/crazyflies.yaml as necessary.
roslaunch crazyswarm hover_swarm.launchIn a second terminal:
python scripts/deploy.py --controller <your_controller.py> --config level3.tomlwhere <your_controller.py> implements a controller that inherits from lsy_drone_racing.control.BaseController