Skip to content

DroneAPI Reference

DroneAPI is the main high-level SDK class.

Import:

from droneapi import DroneAPI

Related config types:

from droneapi import DroneConfig, MediaConfig, NetworkConfig

Construction

DroneAPI(
    config: DroneConfig | None = None,
    enable_logging: bool = True,
    flight_logger: FlightLogger | None = None,
    battery_threshold: int | None = None,
    media_dir: Path | str | None = None,
    enable_file_logging: bool = True,
    file_log_dir: str = "logs",
    enable_command_logging: bool = True,
    command_log_dir: str = "logs",
)

Important properties:

  • is_connected
  • config
  • default_ip

Context manager support:

with DroneAPI() as drone:
    drone.connect()

Connection and Lifecycle

Typical usage:

drone = DroneAPI(config=config)
drone.connect()

Connection flow adapted from the calibration and challenge scripts:

from droneapi import DroneAPI, DroneConfig, NetworkConfig

config = DroneConfig(
    network=NetworkConfig(drone_ip="192.168.100.1")
)

with DroneAPI(config=config) as drone:
    if not drone.robust_connect(verbose=True):
        raise SystemExit("Failed to connect to drone")

    battery = drone.get_battery()
    print(f"Connected. Battery: {battery}%")

Flight and Movement

Basic movement:

Core flight lifecycle:

Typical flight block:

from pypack.core import Direction, VelocityLevel

with DroneAPI() as drone:
    drone.connect()
    drone.set_barrier_mode(enabled=True)
    drone.set_qr_localization(enabled=True)

    try:
        drone.takeoff(height_cm=100)
        drone.move(Direction.FORWARD, 100, speed=VelocityLevel.ZOOM)
        drone.rotate(90)
        drone.move_to(50, 100, 100)
        drone.hover()
    finally:
        drone.land()

Acrobatic and motion helpers:

State and Telemetry

Telemetry snapshot pattern:

flight = drone.get_flight_data()
state = drone.get_state()

print(flight.position)
print(flight.orientation.yaw)
print(state.obstacles)
print(drone.get_drone_id())

Vision, Color, and QR

LED, Sensors, and Payload

Camera, Video, and Imaging

Localization and Autonomy

System and Firmware

Wi-Fi and Radio

Safety and Parameters

Media Management

Listing:

Download:

Delete:

URL helpers:

Photo capture respects DroneConfig.media for default storage, and take_photo(save_path=...) can override the destination per call. If save_path points to a directory, the drone filename is preserved. If it points to a file path such as captures/latest.jpg, the download is renamed to that exact path.

Typical photo and stream usage:

from pypack.core import VideoResolution

with DroneAPI() as drone:
    drone.connect()
    drone.set_video_resolution(VideoResolution.LOW)

    stream = drone.start_video_stream(display=False, web_server=True)
    try:
        print(drone.take_photo(save_path="captures/latest.jpg"))
        stream.wait()
    finally:
        stream.stop()

Manual Control

Use set_app_mode(1) before takeoff if you intend to drive the drone with MANUAL_CONTROL.

Manual-control startup pattern:

drone.set_app_mode(1)
drone.set_velocity_level(200)
drone.set_qr_localization(enabled=True)
drone.set_barrier_mode(enabled=True)

Closed-Loop Flight Controller

This returns the PD controller from pypack.control.

Example:

ctrl = drone.create_flight_controller()
result = ctrl.fly_to(x=100, y=150, z=120, yaw=90)
print(result.success, result.reason)

This is the same control pattern used by the solver scripts, just without the maze layer:

from pypack.control import ControllerConfig

controller = drone.create_flight_controller(
    ControllerConfig(kp_xy=2.5, kp_z=3.5)
)

try:
    drone.takeoff(height_cm=100)
    result = controller.fly_to(x=120, y=0, z=100, yaw=0)
    print(result.success, result.error_position_cm)
finally:
    controller.stop()
    drone.land()

Return Types and Errors

Most command-style methods return CommandResult.

Telemetry and state methods return typed models from pypack.core.models.

Common exceptions:

Notes