PyFlyt UAV Flight Simulator

PyFlyt provides several default Unmanned Aerial Vehicle (UAV) platforms for simulation. The available platforms are:

• Fixed-wing (drones/fixedwing)
• Rocket (drones/rocket)
• QuadX (drones/quadx)

The QuadX UAV follows the Quad-X configuration used by ArduPilot and PX4. You can select between two different model implementations using the drone_model parameter when initializing the drone:

• cf2x (default): The standard model.
• primitive_drone: A simplified model variant.

# Example of selecting a specific model variant
drone = QuadX(drone_model='primitive_drone')

PyFlyt allows decoupling the physics simulation frequency from the drone control looprate.

Physics Frequency: Set via physics_hz in Aviary. The default is 240 Hz. Changing this is not recommended as it may cause instability.

Control Looprate: Set via control_hz inside the drone_options dictionary.

Constraints:

1. Single Drone: The control_hz must be a common denominator of the physics_hz (i.e., physics_hz % control_hz == 0).
2. Multi-Drone: If drones have different looprates, when arranged in ascending order, each subsequent looprate must be a round multiple of the previous one (e.g., [30, 60, 120] is valid, but [30, 40, 120] is invalid because 40/30 is not an integer).

The drone_type argument in Aviary defines the type of UAV(s) to spawn. It accepts a lowercase string for a single type or a list of strings for multiple drones with different types.

Built-in drone types:

• fixedwing
• rocket
• quadx

Spawning Custom Drones: To use a custom drone class, provide a mapping via drone_type_mappings where the key is the string name and the value is the class (not an instance).

# Spawning a custom drone
from my_module import MyCustomDrone

drone_type_mappings = {"mycustomdrone": MyCustomDrone}

env = Aviary(
    ..., 
    drone_type="mycustomdrone", 
    drone_type_mappings=drone_type_mappings
)

The Camera component simulates a camera attached to a specific link on a drone. It can be configured with a gimbal to achieve a horizon lock effect.

When an image is captured, the camera returns three distinct data outputs:

1. RGBA image: The visual color representation.
2. Depth map: A map representing distance information.
3. Segmentation map: A map where pixel values correspond to the IDs of objects in the environment.

Configurable parameters include:

• Field-of-view (FOV)
• Tilt angle
• Resolution
• Offset distance from the main link
• Gimbal settings (for horizon lock)

The DroneClass is the fundamental abstraction for all UAVs in PyFlyt. It serves as the base class for defining drone behavior, physics, and state. When implementing a custom drone, you must satisfy the required attributes and methods to ensure compatibility with the simulator's physics and control loops.

Core Mental Model

• Physics vs. Control: The drone operates on two distinct timescales defined by physics_period and control_period.
• State Management: The drone maintains its physical state, an aux_state for additional information, and a setpoint which represents the target state or command.
• Controllers: Drones can have controllers registered and instantiated to manage flight dynamics.

PyFlyt is structured around a hierarchical relationship between environments and agents:

• Aviary: The top-level domain/environment that manages the physics and the collection of drones.
• Drones: Individual agents defined by Python classes. Drones can be custom-built from scratch or composed using various component abstractions.

This modular design allows users to define new drone types by combining existing abstractions or implementing new ones.

The PyFlyt.core.abstractions.Gimbals component simulates a series of servo-actuated gimbals. It is used to redirect thrust from Motors or Boosters components by providing rotation about two different, arbitrary axes on a link.

Each gimbal setup consists of two units, gimbal_unit_1 and gimbal_unit_2. Rotation follows the right-handed rotation rule.

The Motors component simulates a series of brushless electric motor-driven propellers. Unlike Boosters, Motors feature more linear dynamics and support for reversed thrust.

Physics Model

The simulation follows these steps:

1. Duty Cycle: The actual_duty_cycle ramps toward the target_duty_cycle based on a time constant tau and the physics frequency (physics_hz).
2. RPM: The motor RPM is calculated from the actual_duty_cycle and max_rpm, subject to Gaussian noise.
3. Thrust and Torque: Both thrust and torque are linearly proportional to the RPM, scaled by thrust_coef and torque_coef respectively.

Redirecting Thrust

You can redirect the thrust direction by passing a rotation matrix to the physics_update method. This is particularly useful when integrating with the Gimbals component, which outputs the required rotation matrix.