Python API Reference
This reference covers the PteroSim Python SDK.
Classes
- class PteroSim(address='localhost:10010')
Client for PteroSim flight simulator.
Manages the connection to the simulation server and provides methods to control simulation state, spawn aircraft, and query status.
- Parameters:
address – gRPC server address.
- class Aircraft
Handle to a spawned aircraft.
Connection
- PteroSim.close()
Close the gRPC channel without shutting down the simulator.
- PteroSim.shutdown()
Shut down the simulator application and close the connection.
Context manager support: __enter__ / __exit__ call close(), not shutdown().
Simulation lifecycle
- PteroSim.start()
Start simulation (physics running).
- PteroSim.hold()
Pause simulation.
- PteroSim.resume()
Resume simulation after hold.
- PteroSim.step_once()
Execute a single simulation step then hold. Simulation must be started.
- PteroSim.stop()
Stop simulation.
Simulation status
- PteroSim.status()
Returns simulation status.
- Returns:
is_running (bool): Whether the simulation is currently running.
time_scale (float): Current time scale multiplier.
physics_frequency_hz (float): Physics update rate in Hz.
aircraft_count (int): Number of spawned aircraft.
- Return type:
- PteroSim.clock()
Get simulation clock state.
- Returns:
simulation_time (float): Current simulation time in seconds.
step_number (int): Current simulation step number.
target_frequency_hz (float): Target physics frequency.
actual_frequency_hz (float): Actual achieved frequency.
clock_state (str): “holding”, “running”, or “step_once”.
time_scale (float): Current time scale.
- Return type:
Simulation settings
- PteroSim.set_time_scale(scale)
Sets simulation time multiplier (e.g. 2.0 = 2x real time).
- Parameters:
scale – Time scale factor.
- PteroSim.set_physics_frequency(hz)
Sets physics update rate in Hz.
- Parameters:
hz – Frequency in Hz.
- PteroSim.set_mavlink_bind_address(address)
Set MAVLink bind address for telemetry. Simulation must not be running.
- Parameters:
address – Bind address (e.g. “127.0.0.1”).
- PteroSim.get_mavlink_bind_address()
Returns current MAVLink bind address.
Aircraft management
- PteroSim.list_aircraft_classes()
Returns available aircraft types.
- Returns:
name (str): Aircraft class name (e.g. “F450”, “DeltaQuad”).
description (str): Human-readable description.
- Return type:
List of AircraftClass
- PteroSim.spawn(aircraft_class, *, lat=None, lon=None, alt=None, x=None, y=None, z=None, yaw=0.0, pitch=0.0, roll=0.0)
Spawn an aircraft.
Use lat/lon/alt for geographic coordinates or x/y/z for Unreal Engine coordinates. Returns an Aircraft handle with instance_id, mavlink_port, remove() and camera() methods.
- Parameters:
aircraft_class – Aircraft type name (e.g. “F450”, “DeltaQuad”).
lat – Latitude in degrees.
lon – Longitude in degrees.
alt – Altitude in meters.
x – X coordinate in UE units.
y – Y coordinate in UE units.
z – Z coordinate in UE units.
yaw – Yaw rotation in degrees (default 0.0).
pitch – Pitch rotation in degrees (default 0.0).
roll – Roll rotation in degrees (default 0.0).
- Returns:
Handle to the spawned aircraft.
- PteroSim.aircraft_status()
Get status of all spawned aircraft.
- Returns:
instance_id (int): Unique identifier of the aircraft.
aircraft_name (str): Aircraft class name.
run_state (str): “running”, “holding”, or “step_once”.
actual_frequency_hz (float): Actual physics frequency.
target_frequency_hz (float): Target physics frequency.
step_count (int): Number of simulation steps executed.
crashed (bool): Whether the aircraft has crashed.
time_scale (float): Current time scale.
mavlink_port (int): MAVLink TCP port.
- Return type:
List of AircraftStatus
- Aircraft.remove()
Destroy this aircraft. Returns remaining aircraft count.
Sensors
- PteroSim.get_imu(instance_id)
Get IMU reading for an aircraft.
- Parameters:
instance_id – Aircraft instance ID.
- Returns:
acceleration (tuple[float, float, float]): Specific force in m/s².
angular_velocity (tuple[float, float, float]): Angular rates in rad/s.
magnetic_field (tuple[float, float, float]): Magnetic field in µT.
timestamp_simulation_s (float): Simulation timestamp in seconds.
- Return type:
IMU sample in body FRD frame
- Aircraft.imu()
Get IMU sensor reading for this aircraft.
- Returns:
IMUReading with acceleration (m/s²), angular_velocity (rad/s), and magnetic_field (µT) in body FRD frame.
- Raises:
grpc.RpcError – NOT_FOUND if aircraft has no IMU sensor.
- Aircraft.camera(sensor_name='Camera', *, width=0, height=0, timeout=10)
Capture a camera frame from this aircraft (on-demand, blocks until GPU readback completes).
- Parameters:
sensor_name – Name of the camera sensor component (default “Camera”).
width – Requested width in pixels (0 = component default).
height – Requested height in pixels (0 = component default). Both width and height must be set, or both 0.
timeout – gRPC timeout in seconds (default 10.0).
- Returns:
image (numpy.ndarray): BGR array (H, W, 3), dtype=uint8.
width (int): Frame width in pixels.
height (int): Frame height in pixels.
timestamp (float): SimClock time when frame was captured.
sequence_number (int): Monotonically increasing frame counter.
- Return type:
Actuator control
- PteroSim.set_actuator_controls(instance_id, controls, timestamp_usec=0)
Send normalized actuator channel values directly to the aircraft.
This bypasses autopilot control and is commonly used in RL motor-control loops.
- Parameters:
instance_id – Aircraft instance ID.
controls – Actuator channel values (mapping depends on aircraft configuration).
timestamp_usec – Optional command timestamp in microseconds.
- Aircraft.set_controls(controls, timestamp_usec=0)
Send actuator controls to this aircraft (bypasses autopilot).
- Parameters:
controls – Normalized channel values. Use actuator_config() to learn layout.
timestamp_usec – Timestamp in microseconds (0 = use current time).
- PteroSim.get_actuator_configuration(instance_id)
Get actuator channel layout for an aircraft.
- Parameters:
instance_id – Aircraft instance ID.
- Returns:
instance_id (int): Aircraft instance ID.
channel_count (int): Number of required control channels.
mappings (list[ActuatorMapping]): Per-channel descriptors.
Each ActuatorMapping has channel, type (e.g. motor, elevator, rudder), component_index, input_min, input_max, name.
- Return type:
Actuator mapping and channel count. ActuatorConfiguration fields
- Aircraft.actuator_config()
Get actuator configuration for this aircraft.
- PteroSim.set_attitude_command(instance_id, roll_rad=0.0, pitch_rad=0.0, yaw_rate_rad_sec=0.0, throttle=0.0, enabled=True)
Send attitude command to the QuadX attitude controller running in C++ at physics rate.
When enabled, this controller overrides motor throttles from set_actuator_controls().
- Parameters:
instance_id – Aircraft instance ID.
roll_rad – Desired roll angle in radians.
pitch_rad – Desired pitch angle in radians.
yaw_rate_rad_sec – Desired yaw rate in radians per second.
throttle – Base thrust in range [0, 1].
enabled – Enable or disable the attitude controller.
Racing
Methods for drone racing: track configuration, gate queries, and per-aircraft race progress tracking. Requires an ARaceTrack actor in the level (created automatically by set_track_gates() if none exists).
- PteroSim.set_track_gates(gates)
Create or update a race track with the given gate definitions.
If no ARaceTrack exists in the world, one is spawned automatically. After setting gates, all existing aircraft are registered with the track.
Each gate is a dict with position keys (x, y, z) and optional rotation keys (yaw, pitch, roll, default 0).
- Parameters:
gates – List of gate definition dicts.
- Returns:
Resulting track info with actual gate center positions.
- PteroSim.get_track_info()
Get the race track layout (gate positions and forward vectors).
- Returns:
gate_count (int): Number of gates on the track.
gates (list[GatePose]): List of gate poses.
Each GatePose has gate_index, x/y/z (UE cm), forward_x/y/z.
- Return type:
- PteroSim.get_race_state(instance_id)
Get race progress for a specific aircraft.
- Parameters:
instance_id – Aircraft instance ID.
- Returns:
instance_id (int): Aircraft instance ID.
next_gate_index (int): Index of the next gate to pass.
gates_passed (int): Total number of gates passed.
laps_completed (int): Number of complete laps.
last_gate_passed_time (float): Simulation time (seconds) when the last gate was passed. 0.0 if no gate passed yet.
- Return type:
- PteroSim.get_next_gate_pose(instance_id)
Get the pose of the next gate for an aircraft.
Shortcut for RL observation — avoids separate get_track_info() + get_race_state() calls.
- Parameters:
instance_id – Aircraft instance ID.
- Returns:
Pose of the next gate.
- PteroSim.reset_race(instance_id)
Reset race tracking for one aircraft (next gate, gates passed, laps, timing).
Use at the start of each RL episode.
- Parameters:
instance_id – Aircraft instance ID.
- PteroSim.reset_all_races()
Reset race tracking for all registered aircraft.
Useful for multi-agent RL episode resets.
- PteroSim.remove_track()
Remove current race track and all configured gates from the world.
Data types
Values returned by the methods above. You do not construct these.
- class SimStatus
Simulation status from status().
- class ClockInfo
Simulation clock from clock().
- class AircraftStatus
Status of a spawned aircraft.
Raises grpc.RpcError (FAILED_PRECONDITION) if the world lacks a GeoReferencingSystem.
- class GatePose
Position and forward direction of a race gate (UE engine coords, cm).
- class RaceState
Per-aircraft race progress.
- class IMUReading
IMU sensor reading (body FRD: X=forward, Y=right, Z=down).
- class ActuatorConfiguration
Actuator layout for an aircraft.
- mappings: list[ActuatorMapping]