<p align="center"> <img src="docs/crazysim_logo.svg" alt="CrazySim Logo" width="440"/> </p>

CrazySim: A Software-in-the-Loop Simulator for the Crazyflie Nano Quadrotor

This code accompanies the work in the ICRA 2024 paper "CrazySim: A Software-in-the-Loop Simulator for the Crazyflie Nano Quadrotor" [1]. CrazySim is a simulator platform that runs Crazyflie firmware in a simulation state on a desktop machine with integrated communication with Gazebo sensors and physics engine. The simulated Crazyflie firmware is intended to communicate with crazyflie-lib-python (cflib). This enables simulating the behavior of CFLib scripts that are intended to control single or multiple Crazyflies in a real hardware demonstration. With CFLib communication capabilities, users can choose to use CrazySwarm2 with CFLib as the backend for a ROS 2 interface with the simulator.

References

[1] C. Llanes, Z. Kakish, K. Williams, and S. Coogan, “CrazySim: A Software-in-the-Loop Simulator for the Crazyflie Nano Quadrotor,” 2024 IEEE International Conference on Robotics and Automation (ICRA), 2024.

@INPROCEEDINGS{LlanesICRA2024,
  author={Llanes, Christian and Kakish, Zahi and Williams, Kyle and Coogan, Samuel},
  booktitle={2024 IEEE International Conference on Robotics and Automation (ICRA)}, 
  title={CrazySim: A Software-in-the-Loop Simulator for the Crazyflie Nano Quadrotor}, 
  year={2024},
  volume={},
  number={},
  pages={12248-12254},
  keywords={Sockets;Prediction algorithms;Hardware;Robustness;Sensors;Trajectory;Task analysis},
  doi={10.1109/ICRA57147.2024.10610906}}

CrazySim Setup

Installation

To install this repository use the recursive command as shown below for HTTPS:

git clone https://github.com/gtfactslab/CrazySim.git --recursive

crazyflie-lib-python

The official cflib now supports our udpdriver implementation as of 99ad0e3. Install the official cflib from source using the official install instructions. For now source is the only option because pip install will install the latest release which is 0.1.31 which was before this implementation was pushed.

crazyflie-clients-python [Optional]

If you want to test a single Crazyflie with crazyflie-clients-python for SITL, then run the following commands in your terminal to install the cfclient.

We have verified success with commit d649b66.

git clone https://github.com/bitcraze/crazyflie-clients-python
cd crazyflie-clients-python
pip install -e .

crazyflie-firmware

[WARNING] This is a modified version of the crazyflie-firmware for software-in-the-loop. At this time do not use this firmware for your hardware. SITL integration with Kbuild is being developed for cross-platform building.

The installation instructions and usage are referenced in the documentation file.

Dependencies

Run the following commands to install dependencies.

sudo apt install cmake build-essential
pip install Jinja2

Building the firmware

cd crazyflie-firmware
mkdir -p sitl_make/build && cd $_
cmake ..
make all

How to use

CrazySim supports two physics backends: Gazebo and MuJoCo. Both use the same SITL firmware and CFLib interface.

Open a terminal and run

cd crazyflie-firmware

Then follow the instructions for your chosen backend below.

Connect with CFLib using URI udp://127.0.0.1:19850. For drone swarms increment the port for each additional drone.

You can also test a single crazyflie using the cfclient if you installed it from the crazyflie-clients-python section. Click on the SITL checkbox, scan, and connect.

---

Gazebo

Install Gazebo Garden before building the firmware.

Gazebo Models

| Model | Description | | --- | --- | | crazyflie | The default Crazyflie 2.1. | | crazyflie_thrust_upgrade | The Crazyflie 2.1 with thrust upgrade bundle (cf2x_T350 parameters). |

Option 1: Single agent

bash tools/crazyflie-simulation/simulator_files/gazebo/launch/sitl_singleagent.sh -m crazyflie -x 0 -y 0

Option 2: Multiple agents in a square formation

bash tools/crazyflie-simulation/simulator_files/gazebo/launch/sitl_multiagent_square.sh -n 8 -m crazyflie

Option 3: Multiple agents from a coordinates file

bash tools/crazyflie-simulation/simulator_files/gazebo/launch/sitl_multiagent_text.sh -m crazyflie -f single_origin.txt

---

MuJoCo

MuJoCo does not require Gazebo and tends to run with better real-time performance. Drone models and parameters are provided by the drone-models submodule.

The MuJoCo backend includes aerodynamic effects from the drone-models first_principles model:

• Rotor drag: velocity-dependent drag force using the drag_matrix from params.toml
• Gyroscopic precession: torque from body angular velocity and net rotor angular momentum

MuJoCo Dependencies

pip install mujoco numpy

If on Python < 3.11, also install tomli:

pip install tomli

Initialize the drone-models submodule for mesh assets:

git submodule update --init tools/crazyflie-simulation/simulator_files/mujoco/drone-models

MuJoCo Models

| Model | Description | | --- | --- | | cf2x_T350 | Crazyflie 2.x with Thrust upgrade kit (default) | | cf2x_L250 | Crazyflie 2.x Standard Configuration | | cf2x_P250 | Crazyflie 2.x Performance variant | | cf21B_500 | Crazyflie 2.1B Brushless |

Launch Scripts

Several launch scripts are included to simplify startup.

Option 1: Single agent

bash tools/crazyflie-simulation/simulator_files/mujoco/launch/sitl_singleagent.sh -m cf2x_T350 -x 0 -y 0

Option 2: Multiple agents in a square formation

bash tools/crazyflie-simulation/simulator_files/mujoco/launch/sitl_multiagent_square.sh -n 8 -m cf2x_T350

Option 3: Multiple agents from a coordinates file

bash tools/crazyflie-simulation/simulator_files/mujoco/launch/sitl_multiagent_text.sh -m cf2x_T350 -f single_origin.txt

---

Coordinates File Format

The -f flag specifies a coordinates file from crazyflie-firmware/tools/crazyflie-simulation/drone_spawn_list/. Each line contains an X,Y spawn position in CSV format:

0.0,0.0
1.0,0.0
0.0,1.0
1.0,1.0

A default single_origin.txt file is included. To create your own, add a new .txt file to the drone_spawn_list/ directory.

---

Color LEDs (Top & Bottom)

The SITL firmware includes color LED deck drivers (bcColorLedTop and bcColorLedBot) that send RGB data to the simulator independently for the top and bottom LEDs. The MuJoCo backend renders these colors in real-time on the drone's led_top and led_bot materials and adds point light sources so the LEDs illuminate the surrounding scene. A headlight is also supported and rendered as a forward-facing spot light. LED RGB values set from cflib or cfclient are reflected in the simulation. A scene_dark.xml scene is provided to best visualize the LED lighting effects.

---

8-Drone Circling Demo (MuJoCo)

Launch 8 drones using the circling_square.txt spawn file:

bash tools/crazyflie-simulation/simulator_files/mujoco/launch/sitl_multiagent_text.sh -m cf2x_T350 -f circling_square.txt -M 0.0379

Then in another terminal, run the circling square demo script:

cd crazyflie-lib-python/examples/autonomy
python3 circling_square_demo.py

Before running, update the uris list in the script to use SITL UDP URIs (udp://127.0.0.1:19850 through udp://127.0.0.1:19857 for 8 drones).

https://github.com/user-attachments/assets/c5d08c86-e879-4121-aecf-5adb6c083b6c

---

Multiranger

The MuJoCo backend supports the Multi-ranger deck, providing simulated ToF range sensors (front, back, left, right, up). An obstacle scene is included and can be loaded with the -s flag:

bash tools/crazyflie-simulation/simulator_files/mujoco/launch/sitl_singleagent.sh -m cf2x_T350 -x 0 -y 0 -s scene_obstacles.xml

This can be demonstrated using the multiranger_pointcloud.py example from crazyflie-lib-python, which renders a real-time 3D point cloud while allowing manual flight control via keyboard. To use it with SITL, change the URI to udp://127.0.0.1:19850 as with the other examples.

https://github.com/user-attachments/assets/f1377d12-ce14-4be9-8d28-07209eee7b6c

---

AI-Deck Camera (MuJoCo)

The MuJoCo backend supports simulated AI-deck camera streaming using the CPX protocol. A companion script crazysim_cpx.py emulates the ESP32 WiFi bridge, allowing unmodified cflib AI-deck scripts (e.g. fpv.py) to receive camera frames from the simulator exactly as they would from real hardware.

How it works:

• crazysim.py renders the drone's FPV camera using MuJoCo's offscreen renderer, converts to grayscale (matching the Himax HM01B0 sensor), and sends frames via UDP to crazysim_cpx.py
• crazysim_cpx.py wraps frames in CPX APP packets with the 0xBC image header and bridges CRTP commands between cflib and the firmware — acting as the ESP32
• cflib clients connect via TCP and see the same