# cangel18/lsy_drone_racing architecture

> Architecture diagram of the GitHub repository cangel18/lsy_drone_racing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cangel18/lsy_drone_racing
- Repository: https://github.com/cangel18/lsy_drone_racing

## Overview

LSY Autonomous Drone Racing provides Gymnasium race environments, controller implementations, simulation/training workflows, and deployment to Crazyflie hardware. The principal workflow is to load a race configuration, run a controller against a single- or multi-drone environment, and evaluate race progress; deployment substitutes real motion-capture observations and hardware commands. The graph retains the documented simulation-to-real and difficulty/randomization capabilities. Some links are limited to README or source-index evidence because several implementation excerpts are partial.

Main entry points: [`lsy_drone_racing/control/controller.py`](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/control/controller.py) (Controller interface), [`lsy_drone_racing/envs/real_race_env.py`](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/envs/real_race_env.py) (Hardware race env), [`scripts/sim.py`](https://github.com/cangel18/lsy_drone_racing/blob/main/scripts/sim.py) (Simulation runner), [`lsy_drone_racing/envs/race_core.py`](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/envs/race_core.py) (Race simulation core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_race["Race Environments"]
  node_single_env["Single-drone env<br/>[drone_race.py]"]
  node_multi_env["Multi-drone env"]
  node_race_core["Race simulation core<br/>[race_core.py]"]
  node_randomize["Track randomization<br/>[randomize.py]"]
end

subgraph group_control["Control and Learning"]
  node_controller_base["Controller interface<br/>[controller.py]"]
  node_attitude["Attitude control"]
  node_mpcc["MPCC racing<br/>[pp_racer_mpccpp.py]"]
  node_rl_racer["RL racing policy<br/>[rl_racer.py]"]
  node_train_rl["RL training<br/>[train_rl.py]"]
  node_train_racer["Racer training<br/>[train_rl_racer.py]"]
end

subgraph group_hardware["Real-World Deployment"]
  node_real_env["Hardware race env<br/>[real_race_env.py]"]
  node_checks["Deployment checks<br/>[checks.py]"]
  node_crazyflie["Crazyflie interface<br/>[crazyflie.py]"]
  node_ros["ROS / mocap access<br/>[ros.py]"]
  node_viewer["Deployment viewer<br/>[deploy_viewer.py]"]
end

subgraph group_workflow["Run and Evaluate"]
  node_sim_script["Simulation runner<br/>[sim.py]"]
  node_eval_script["Evaluation runner<br/>[evaluate.py]"]
  node_deploy_script["Deployment runner<br/>[deploy.py]"]
  node_multi_sim["Multi-drone runner<br/>[multi_sim.py]"]
  node_multi_deploy["Multi-drone deployment<br/>[multi_deploy.py]"]
  node_config["Config and loading<br/>[utils.py]"]
end

node_user(("Engineer / racer"))
node_simulator["Crazyflow simulator"]
node_drone["Crazyflie drone"]
node_mocap["Motion capture"]

node_user -->|"runs simulation"| node_sim_script
node_sim_script -->|"loads settings"| node_config
node_sim_script -->|"runs environment"| node_single_env
node_sim_script -->|"loads controller"| node_controller_base
node_eval_script -->|"invokes runs"| node_sim_script
node_user -->|"starts deployment"| node_deploy_script
node_deploy_script -->|"loads settings"| node_config
node_deploy_script -->|"creates environment"| node_real_env
node_deploy_script -->|"uses viewer"| node_viewer
node_user -->|"runs multi-drone"| node_multi_sim
node_multi_sim -->|"runs environment"| node_multi_env
node_multi_sim -->|"loads controller"| node_controller_base
node_user -->|"starts deployment"| node_multi_deploy
node_multi_deploy -->|"creates environment"| node_real_env
node_single_env -->|"inherits core"| node_race_core
node_multi_env -->|"inherits core"| node_race_core
node_race_core -->|"builds randomizers"| node_randomize
node_attitude -->|"extends interface"| node_controller_base
node_train_racer -->|"uses policy"| node_rl_racer
node_train_racer -->|"trains in env"| node_single_env
node_train_rl -->|"trains in core env"| node_race_core
node_real_env -->|"validates setup"| node_checks
node_real_env -->|"commands hardware"| node_crazyflie
node_real_env -->|"reads track poses"| node_ros
node_crazyflie -->|"sends setpoints"| node_drone
node_crazyflie -->|"gets estimates"| node_mocap
node_ros -->|"reads poses"| node_mocap
node_race_core -->|"wraps simulation"| node_simulator
node_train_rl -.->|"trains controller"| node_controller_base
node_mpcc -.->|"implements controller"| node_controller_base
node_rl_racer -.->|"implements controller"| node_controller_base

click node_sim_script "https://github.com/cangel18/lsy_drone_racing/blob/main/scripts/sim.py"
click node_eval_script "https://github.com/cangel18/lsy_drone_racing/blob/main/scripts/evaluate.py"
click node_deploy_script "https://github.com/cangel18/lsy_drone_racing/blob/main/scripts/deploy.py"
click node_multi_sim "https://github.com/cangel18/lsy_drone_racing/blob/main/scripts/multi_sim.py"
click node_multi_deploy "https://github.com/cangel18/lsy_drone_racing/blob/main/scripts/multi_deploy.py"
click node_config "https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/utils/utils.py"
click node_controller_base "https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/control/controller.py"
click node_attitude "https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/control/attitude_controller.py"
click node_mpcc "https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/control/pp_racer_mpccpp.py"
click node_rl_racer "https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/control/rl_racer.py"
click node_train_rl "https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/control/train_rl.py"
click node_train_racer "https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/control/train_rl_racer.py"
click node_single_env "https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/envs/drone_race.py"
click node_multi_env "https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/envs/multi_drone_race.py"
click node_race_core "https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/envs/race_core.py"
click node_randomize "https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/envs/randomize.py"
click node_real_env "https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/envs/real_race_env.py"
click node_checks "https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/utils/checks.py"
click node_crazyflie "https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/utils/crazyflie.py"
click node_ros "https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/utils/ros.py"
click node_viewer "https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/utils/deploy_viewer.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_single_env,node_multi_env,node_race_core,node_randomize toneBlue
class node_controller_base,node_attitude,node_mpcc,node_rl_racer,node_train_rl,node_train_racer toneAmber
class node_real_env,node_checks,node_crazyflie,node_ros,node_viewer toneMint
class node_sim_script,node_eval_script,node_deploy_script,node_multi_sim,node_multi_deploy,node_config toneRose
class node_user,node_simulator,node_drone,node_mocap toneIndigo
```

## Components

### Race Environments

- [Single-drone env](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/envs/drone_race.py): `lsy_drone_racing/envs/drone_race.py`
- [Multi-drone env](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/envs/multi_drone_race.py): `lsy_drone_racing/envs/multi_drone_race.py`
- [Race simulation core](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/envs/race_core.py): `lsy_drone_racing/envs/race_core.py`
- [Track randomization](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/envs/randomize.py): `lsy_drone_racing/envs/randomize.py`

### Control and Learning

- [Controller interface](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/control/controller.py): `lsy_drone_racing/control/controller.py`
- [Attitude control](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/control/attitude_controller.py): `lsy_drone_racing/control/attitude_controller.py`
- [MPCC racing](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/control/pp_racer_mpccpp.py): `lsy_drone_racing/control/pp_racer_mpccpp.py`
- [RL racing policy](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/control/rl_racer.py): `lsy_drone_racing/control/rl_racer.py`
- [RL training](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/control/train_rl.py): `lsy_drone_racing/control/train_rl.py`
- [Racer training](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/control/train_rl_racer.py): `lsy_drone_racing/control/train_rl_racer.py`

### Real-World Deployment

- [Hardware race env](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/envs/real_race_env.py): `lsy_drone_racing/envs/real_race_env.py`
- [Deployment checks](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/utils/checks.py): `lsy_drone_racing/utils/checks.py`
- [Crazyflie interface](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/utils/crazyflie.py): `lsy_drone_racing/utils/crazyflie.py`
- [ROS / mocap access](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/utils/ros.py): `lsy_drone_racing/utils/ros.py`
- [Deployment viewer](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/utils/deploy_viewer.py): `lsy_drone_racing/utils/deploy_viewer.py`

### Run and Evaluate

- [Simulation runner](https://github.com/cangel18/lsy_drone_racing/blob/main/scripts/sim.py): `scripts/sim.py`
- [Evaluation runner](https://github.com/cangel18/lsy_drone_racing/blob/main/scripts/evaluate.py): `scripts/evaluate.py`
- [Deployment runner](https://github.com/cangel18/lsy_drone_racing/blob/main/scripts/deploy.py): `scripts/deploy.py`
- [Multi-drone runner](https://github.com/cangel18/lsy_drone_racing/blob/main/scripts/multi_sim.py): `scripts/multi_sim.py`
- [Multi-drone deployment](https://github.com/cangel18/lsy_drone_racing/blob/main/scripts/multi_deploy.py): `scripts/multi_deploy.py`
- [Config and loading](https://github.com/cangel18/lsy_drone_racing/blob/main/lsy_drone_racing/utils/utils.py): `lsy_drone_racing/utils/utils.py`

### Other components

- **Engineer / racer**
- **Crazyflow simulator**
- **Crazyflie drone**
- **Motion capture**

## Connections

- Engineer / racer → Simulation runner: runs simulation (evidence: `scripts/sim.py`)
- Simulation runner → Config and loading: loads settings (evidence: `scripts/sim.py`)
- Simulation runner → Single-drone env: runs environment (evidence: `scripts/sim.py`)
- Simulation runner → Controller interface: loads controller (evidence: `scripts/sim.py`)
- Evaluation runner → Simulation runner: invokes runs (evidence: `scripts/evaluate.py`)
- Engineer / racer → Deployment runner: starts deployment (evidence: `scripts/deploy.py`)
- Deployment runner → Config and loading: loads settings (evidence: `scripts/deploy.py`)
- Deployment runner → Hardware race env: creates environment (evidence: `scripts/deploy.py`)
- Deployment runner → Deployment viewer: uses viewer (evidence: `scripts/deploy.py`)
- Engineer / racer → Multi-drone runner: runs multi-drone (evidence: `scripts/multi_sim.py`)
- Multi-drone runner → Multi-drone env: runs environment (evidence: `scripts/multi_sim.py`)
- Multi-drone runner → Controller interface: loads controller (evidence: `scripts/multi_sim.py`)
- Engineer / racer → Multi-drone deployment: starts deployment (evidence: `scripts/multi_deploy.py`)
- Multi-drone deployment → Hardware race env: creates environment (evidence: `scripts/multi_deploy.py`)
- Single-drone env → Race simulation core: inherits core (evidence: `lsy_drone_racing/envs/drone_race.py`)
- Multi-drone env → Race simulation core: inherits core (evidence: `lsy_drone_racing/envs/multi_drone_race.py`)
- Race simulation core → Track randomization: builds randomizers (evidence: `lsy_drone_racing/envs/race_core.py`)
- Attitude control → Controller interface: extends interface (evidence: `lsy_drone_racing/control/attitude_controller.py`)
- Racer training → RL racing policy: uses policy (evidence: `lsy_drone_racing/control/train_rl_racer.py`)
- Racer training → Single-drone env: trains in env (evidence: `lsy_drone_racing/control/train_rl_racer.py`)
- RL training → Race simulation core: trains in core env (evidence: `lsy_drone_racing/control/train_rl.py`)
- Hardware race env → Deployment checks: validates setup (evidence: `lsy_drone_racing/envs/real_race_env.py`)
- Hardware race env → Crazyflie interface: commands hardware (evidence: `lsy_drone_racing/envs/real_race_env.py`)
- Hardware race env → ROS / mocap access: reads track poses (evidence: `lsy_drone_racing/envs/real_race_env.py`)
- Crazyflie interface → Crazyflie drone: sends setpoints (evidence: `lsy_drone_racing/utils/crazyflie.py`)
- Crazyflie interface → Motion capture: gets estimates (evidence: `lsy_drone_racing/utils/crazyflie.py`)
- ROS / mocap access → Motion capture: reads poses (evidence: `lsy_drone_racing/utils/ros.py`)
- Race simulation core → Crazyflow simulator: wraps simulation (evidence: `README.md`)
- RL training → Controller interface: trains controller
- MPCC racing → Controller interface: implements controller
- RL racing policy → Controller interface: implements controller
