{"id":13472210,"url":"https://github.com/utiasDSL/gym-pybullet-drones","last_synced_at":"2025-03-26T15:31:43.279Z","repository":{"id":37956342,"uuid":"286408558","full_name":"utiasDSL/gym-pybullet-drones","owner":"utiasDSL","description":"PyBullet Gymnasium environments for single and multi-agent reinforcement learning of quadcopter control","archived":false,"fork":false,"pushed_at":"2025-02-11T05:33:37.000Z","size":121595,"stargazers_count":1419,"open_issues_count":105,"forks_count":409,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-03-22T09:04:26.674Z","etag":null,"topics":["betaflight","control","crazyflie","gym","gymnasium","multi-agent","pybullet","quadcopter","quadrotor","reinforcement-learning","robotics","sitl","stable-baselines3","uav"],"latest_commit_sha":null,"homepage":"https://utiasDSL.github.io/gym-pybullet-drones/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/utiasDSL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-10T07:38:09.000Z","updated_at":"2025-03-21T16:09:37.000Z","dependencies_parsed_at":"2024-06-02T16:00:27.573Z","dependency_job_id":"1c4e26b0-fca1-4b5f-9276-45f4ab654476","html_url":"https://github.com/utiasDSL/gym-pybullet-drones","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utiasDSL%2Fgym-pybullet-drones","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utiasDSL%2Fgym-pybullet-drones/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utiasDSL%2Fgym-pybullet-drones/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utiasDSL%2Fgym-pybullet-drones/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/utiasDSL","download_url":"https://codeload.github.com/utiasDSL/gym-pybullet-drones/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245681357,"owners_count":20655177,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["betaflight","control","crazyflie","gym","gymnasium","multi-agent","pybullet","quadcopter","quadrotor","reinforcement-learning","robotics","sitl","stable-baselines3","uav"],"created_at":"2024-07-31T16:00:52.948Z","updated_at":"2025-03-26T15:31:43.263Z","avatar_url":"https://github.com/utiasDSL.png","language":"Python","funding_links":[],"categories":["Python","Simulation","AI \u0026 Reinforcement Learning Environments","[PyBullet](https://github.com/bulletphysics/bullet3)"],"sub_categories":["Version Control"],"readme":"# gym-pybullet-drones\n\nThis is a minimalist refactoring of the original `gym-pybullet-drones` repository, designed for compatibility with [`gymnasium`](https://github.com/Farama-Foundation/Gymnasium), [`stable-baselines3` 2.0](https://github.com/DLR-RM/stable-baselines3/pull/1327), and SITL [`betaflight`](https://github.com/betaflight/betaflight)/[`crazyflie-firmware`](https://github.com/bitcraze/crazyflie-firmware/).\n\n\u003e **NOTE**: if you prefer to access the original codebase, presented at IROS in 2021, please `git checkout [paper|master]` after cloning the repo, and refer to the corresponding `README.md`'s.\n\n\u003cimg src=\"gym_pybullet_drones/assets/helix.gif\" alt=\"formation flight\" width=\"325\"\u003e \u003cimg src=\"gym_pybullet_drones/assets/helix.png\" alt=\"control info\" width=\"425\"\u003e\n\n## Installation\n\nTested on Intel x64/Ubuntu 22.04 and Apple Silicon/macOS 14.1.\n\n```sh\ngit clone https://github.com/utiasDSL/gym-pybullet-drones.git\ncd gym-pybullet-drones/\n\nconda create -n drones python=3.10\nconda activate drones\n\npip3 install --upgrade pip\npip3 install -e . # if needed, `sudo apt install build-essential` to install `gcc` and build `pybullet`\n\n```\n\n## Use\n\n### PID control examples\n\n```sh\ncd gym_pybullet_drones/examples/\npython3 pid.py # position and velocity reference\npython3 pid_velocity.py # desired velocity reference\n```\n\n### Downwash effect example\n\n```sh\ncd gym_pybullet_drones/examples/\npython3 downwash.py\n```\n\n### Reinforcement learning examples (SB3's PPO)\n\n```sh\ncd gym_pybullet_drones/examples/\npython learn.py # task: single drone hover at z == 1.0\npython learn.py --multiagent true # task: 2-drone hover at z == 1.2 and 0.7\n```\n\n\u003cimg src=\"gym_pybullet_drones/assets/rl.gif\" alt=\"rl example\" width=\"375\"\u003e \u003cimg src=\"gym_pybullet_drones/assets/marl.gif\" alt=\"marl example\" width=\"375\"\u003e\n\n### utiasDSL `pycffirmware` Python Bindings example (multiplatform, single-drone)\n\nInstall [`pycffirmware`](https://github.com/utiasDSL/pycffirmware?tab=readme-ov-file#installation) for Ubuntu, macOS, or Windows\n\n```sh\ncd gym_pybullet_drones/examples/\npython3 cff-dsl.py\n```\n\n### Betaflight SITL example (Ubuntu only)\n\n```sh\ngit clone https://github.com/betaflight/betaflight \ncd betaflight/\ngit checkout cafe727 # `master` branch head at the time of writing (future release 4.5)\nmake arm_sdk_install # if needed, `apt install curl``\nmake TARGET=SITL # comment out line: https://github.com/betaflight/betaflight/blob/master/src/main/main.c#L52\ncp ~/gym-pybullet-drones/gym_pybullet_drones/assets/eeprom.bin ~/betaflight/ # assuming both gym-pybullet-drones/ and betaflight/ were cloned in ~/\nbetaflight/obj/main/betaflight_SITL.elf\n```\n\nIn another terminal, run the example\n\n```sh\nconda activate drones\ncd gym_pybullet_drones/examples/\npython3 beta.py --num_drones 1 # check the steps in the file's docstrings to use multiple drones\n```\n\n## Citation\n\nIf you wish, please cite our [IROS 2021 paper](https://arxiv.org/abs/2103.02142) ([and original codebase](https://github.com/utiasDSL/gym-pybullet-drones/tree/paper)) as\n\n```bibtex\n@INPROCEEDINGS{panerati2021learning,\n      title={Learning to Fly---a Gym Environment with PyBullet Physics for Reinforcement Learning of Multi-agent Quadcopter Control}, \n      author={Jacopo Panerati and Hehui Zheng and SiQi Zhou and James Xu and Amanda Prorok and Angela P. Schoellig},\n      booktitle={2021 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},\n      year={2021},\n      volume={},\n      number={},\n      pages={7512-7519},\n      doi={10.1109/IROS51168.2021.9635857}\n}\n```\n\n## References\n\n- Carlos Luis and Jeroome Le Ny (2016) [*Design of a Trajectory Tracking Controller for a Nanoquadcopter*](https://arxiv.org/pdf/1608.05786.pdf)\n- Nathan Michael, Daniel Mellinger, Quentin Lindsey, Vijay Kumar (2010) [*The GRASP Multiple Micro UAV Testbed*](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.169.1687\u0026rep=rep1\u0026type=pdf)\n- Benoit Landry (2014) [*Planning and Control for Quadrotor Flight through Cluttered Environments*](http://groups.csail.mit.edu/robotics-center/public_papers/Landry15)\n- Julian Forster (2015) [*System Identification of the Crazyflie 2.0 Nano Quadrocopter*](https://www.research-collection.ethz.ch/handle/20.500.11850/214143)\n- Antonin Raffin, Ashley Hill, Maximilian Ernestus, Adam Gleave, Anssi Kanervisto, and Noah Dormann (2019) [*Stable Baselines3*](https://github.com/DLR-RM/stable-baselines3)\n- Guanya Shi, Xichen Shi, Michael O’Connell, Rose Yu, Kamyar Azizzadenesheli, Animashree Anandkumar, Yisong Yue, and Soon-Jo Chung (2019)\n[*Neural Lander: Stable Drone Landing Control Using Learned Dynamics*](https://arxiv.org/pdf/1811.08027.pdf)\n- C. Karen Liu and Dan Negrut (2020) [*The Role of Physics-Based Simulators in Robotics*](https://www.annualreviews.org/doi/pdf/10.1146/annurev-control-072220-093055)\n- Yunlong Song, Selim Naji, Elia Kaufmann, Antonio Loquercio, and Davide Scaramuzza (2020) [*Flightmare: A Flexible Quadrotor Simulator*](https://arxiv.org/pdf/2009.00563.pdf)\n\n## Core Team WIP\n\n- [ ] Multi-drone `crazyflie-firmware` SITL support (@spencerteetaert, @JacopoPan)\n- [ ] Use SITL services with steppable simulation (@JacopoPan)\n\n## Desired Contributions/PRs\n\n- [ ] Add motor delay, advanced ESC modeling by implementing a buffer in `BaseAviary._dynamics()`\n- [ ] Replace `rpy` with quaternions (and `ang_vel` with body rates) by editing `BaseAviary._updateAndStoreKinematicInformation()`, `BaseAviary._getDroneStateVector()`, and the `.computeObs()` methods of relevant subclasses\n\n## Troubleshooting\n\n- On Ubuntu, with an NVIDIA card, if you receive a \"Failed to create and OpenGL context\" message, launch `nvidia-settings` and under \"PRIME Profiles\" select \"NVIDIA (Performance Mode)\", reboot and try again.\n\nRun all tests from the top folder with\n\n```sh\npytest tests/\n```\n\n-----\n\u003e University of Toronto's [Dynamic Systems Lab](https://github.com/utiasDSL) / [Vector Institute](https://github.com/VectorInstitute) / University of Cambridge's [Prorok Lab](https://github.com/proroklab)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FutiasDSL%2Fgym-pybullet-drones","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FutiasDSL%2Fgym-pybullet-drones","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FutiasDSL%2Fgym-pybullet-drones/lists"}