Project Awesome project awesome
♥

gym-pybullet-drones

PyBullet-based Gym environments for single and multi-agent reinforcement learning of quadcopter control.

Package 2.0k stars GitHub

[!TIP] For research work with symbolic dynamics and constraints, also try safe-control-gym

For GPU-accelerated, differentiable, JAX-based simulation, also try crazyflow

For production-grade deployment of ROS2 + PX4/ArduPilot + YOLO/LiDAR, use aerial-autonomy-stack

gym-pybullet-drones

This is a minimalist refactoring of the original gym-pybullet-drones repository, designed for compatibility with gymnasium, stable-baselines3 2.0, and betaflight/crazyflie-firmware SITL.

NOTE: if you want to access the original codebase, presented at IROS in 2021, please git checkout [paper|master]

formation flight control info

Installation

Tested on Intel x64/Ubuntu 22.04 and Apple Silicon/macOS 26.2.

git clone https://github.com/learnsyslab/gym-pybullet-drones.git
cd gym-pybullet-drones/

conda create -n drones python=3.10
conda activate drones

pip3 install -e . # if needed, `sudo apt install build-essential` to install `gcc` and build `pybullet`

# check installed packages with `conda list`, deactivate with `conda deactivate`, remove with `conda remove -n drones --all`

Use

PID control examples

cd gym_pybullet_drones/examples/
python3 pid.py # position and velocity reference
python3 pid_velocity.py # desired velocity reference

Downwash effect example

cd gym_pybullet_drones/examples/
python3 downwash.py

Reinforcement learning examples (SB3's PPO)

cd gym_pybullet_drones/examples/
python learn.py # task: single drone hover at z == 1.0
python learn.py --multiagent true # task: 2-drone hover at z == 1.2 and 0.7

LATEST_MODEL=$(ls -t results | head -n 1) && python play.py --model_path "results/${LATEST_MODEL}/best_model.zip" # play and visualize the most recent learned policy after training

rl example marl example

Run all tests

# from the repo's top folder
cd gym-pybullet-drones/
pytest tests/

Betaflight SITL example (Ubuntu only)

git clone https://github.com/betaflight/betaflight 
cd betaflight/
git checkout cafe727 # `master` branch head at the time of writing (future release 4.5)
make arm_sdk_install # if needed, `apt install curl``
make TARGET=SITL # comment out line: https://github.com/betaflight/betaflight/blob/master/src/main/main.c#L52
cp ~/gym-pybullet-drones/gym_pybullet_drones/assets/eeprom.bin ~/betaflight/ # assuming both gym-pybullet-drones/ and betaflight/ were cloned in ~/
betaflight/obj/main/betaflight_SITL.elf

In another terminal, run the example

conda activate drones
cd gym_pybullet_drones/examples/
python3 beta.py --num_drones 1 # check the steps in the file's docstrings to use multiple drones

pycffirmware Python Bindings example (multiplatform, single-drone)

First, install pycffirmware for Ubuntu, macOS, or Windows, then

cd gym_pybullet_drones/examples/
python3 cf.py

Citation

If you wish, please cite our IROS 2021 paper (and original codebase) as

@INPROCEEDINGS{panerati2021learning,
      title={Learning to Fly---a Gym Environment with PyBullet Physics for Reinforcement Learning of Multi-agent Quadcopter Control}, 
      author={Jacopo Panerati and Hehui Zheng and SiQi Zhou and James Xu and Amanda Prorok and Angela P. Schoellig},
      booktitle={2021 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},
      year={2021},
      volume={},
      number={},
      pages={7512-7519},
      doi={10.1109/IROS51168.2021.9635857}
}

References

UTIAS / Learning Systems and Robotics Lab / Vector Institute / University of Cambridge's Prorok Lab

Back to Robotic Tooling