envs.real_drone_race

Real-world drone racing environments.

This module contains the environments for controlling a single or multiple drones in a real-world race track. It mirrors the drone_race module as closely as possible, but uses data from real-world observations from motion capture systems and sends actions to the real drones.

class EnvData(target_gate: NDArray, gates_visited: NDArray, obstacles_visited: NDArray, last_drone_pos: NDArray[np.float32], taken_off: bool = False, drone_connected: bool = False)

Struct holding the data of all auxiliary variables for the environment.

classmethod create(n_drones: int, n_gates: int, n_obstacles: int) → EnvData

Create an instance of the EnvData class.

reset(last_drone_pos: NDArray[np.float32])

Reset the environment data.

class RealRaceCoreEnv(drones: list[dict[str, int]], rank: int, freq: int, track: ConfigDict, randomizations: ConfigDict, sensor_range: float = 0.5, control_mode: Literal['state', 'attitude'] = 'state')

Deployable version of the (multi-agent) drone racing environments.

This class acts as a generic core implementation of the environment logic that can be reused for both single-agent and multi-agent deployments.

obs() → dict[str, NDArray]

Return the observation of the environment.

reward() → float

Compute the reward for the current state.

Note

The current sparse reward function will most likely not work directly for training an agent. If you want to use reinforcement learning, you will need to define your own reward function.

Returns:

Reward for the current state.

terminated() → NDArray

Check if the episode is terminated.

truncated() → NDArray

Check if the episode is truncated.

info() → dict

Return an info dictionary containing additional information about the environment.

send_action(action: NDArray)

Send the action to the drone.

close()

Close the environment.

If the drone has finished the track, it will try to return to the start position. Irrespective of succeeding or not, the drone will be stopped immediately afterwards or in case of errors, and close the connections to the ROSConnector.

class RealDroneRaceEnv(drones: list[dict[str, int]], freq: int, track: ConfigDict, randomizations: ConfigDict, sensor_range: float = 0.5, control_mode: Literal['state', 'attitude'] = 'state')

A Gymnasium environment for controlling a real Crazyflie drone in a physical race track.

This environment provides a standardized interface for deploying drone racing algorithms on physical hardware. It handles communication with the drone through the cflib library and tracks the drone’s position using a motion capture system via ROS2.

The environment maintains the same observation and action space as its simulation counterpart, allowing for seamless transition from simulation to real-world deployment. It processes sensor data, handles gate passing detection, and manages the drone’s state throughout the race.

Features: - Interfaces with physical Crazyflie drones through radio communication - Tracks drone position and orientation using motion capture data via ROS2 - Supports both state-based and attitude-based control modes - Provides sensor range simulation for gates and obstacles - Handles automatic return-to-home behavior when the race is completed

Note

This environment is designed for single-drone racing. For multi-drone racing, use the RealMultiDroneRaceEnv class instead.

reset(*, seed: int | None = None, options: dict | None = None) → tuple[dict, dict]

Reset the environment and return the initial observation and info.

step(action: NDArray) → tuple[dict, float, bool, bool, dict]

Perform a step in the environment.

Parameters:

action – Action to be taken by the drone.

Returns:

Observation, reward, terminated, truncated, and info.

class RealMultiDroneRaceEnv(drones: list[dict[str, int]], rank: int, freq: int, track: ConfigDict, randomizations: ConfigDict, sensor_range: float = 0.5, control_mode: Literal['state', 'attitude'] = 'state')

A Gymnasium environment for controlling a specific drone in a multi-drone physical race.

This environment extends the functionality of RealRaceCoreEnv to support multi-drone racing scenarios. Each instance of this environment controls a single drone identified by its rank, but maintains awareness of all drones in the race. This allows for coordinated multi-drone deployments where each drone runs in a separate process with its own controller.

The environment handles communication with the specific drone through cflib and tracks all drones’ positions using a motion capture system via ROS2. It provides observations that include the state of all drones, allowing controllers to implement collision avoidance or cooperative strategies.

Features: - Controls a specific drone in a multi-drone race based on its rank - Tracks all drones’ positions and states via ROS2 - Supports both state-based and attitude-based control modes - Provides sensor range simulation for gates and obstacles - Handles automatic return-to-home behavior when the race is completed

Action space:

The action space is a single action vector for the drone with the environment rank. See RealRaceCoreEnv for more information.

Warning

The action space differs from the action space of the simulated counterpart. This deviation is necessary to run different controller types at different frequencies that asynchronously publish ther commands to the drone.

Observation space:

The observation space is a dictionary containing the state of all drones in the race. It mimics exactly the observation space of lsy_drone_racing.envs.multi_drone_race.MultiDroneRaceEnv.

Note

Each instance of this environment controls only one drone (specified by rank), but provides observations for all drones in the race. This allows us to run controllers at different frequencies for different drones. Consequently the step method applies actions only to the

reset(*, seed: int | None = None, options: dict | None = None) → tuple[dict, dict]

Reset the environment and return the initial observation and info.

step(action: NDArray) → tuple[dict, float, bool, bool, dict]

Perform a step in the environment.

Note

The action is applied only to the drone with the environment rank!

Parameters:

action – Action to be taken by the drone.

Returns:

Observation, reward, terminated, truncated, and info.