Types, Models, and Errors¶

The SDK is designed around typed enums, Pydantic models, and explicit exceptions.

Most of these live in pypack.core.

Import Pattern¶

from pypack.core import (
    Direction,
    FlipDirection,
    LEDMode,
    CommandResult,
    VelocityLevel,
    WiFiMode,
    MediaType,
    Vector3,
    Orientation,
    LEDConfig,
    FlightData,
    Obstacles,
    DroneState,
    AIResult,
    ColorResult,
    MediaFile,
    DroneConnectionError,
    NotReady,
    LowBattery,
    TelemetryUnavailable,
)

Key Enums¶

Movement and control:

LED and payload:

Vision and camera:

Navigation and environment:

System:

Key Models¶

Geometry and State¶

Visual Results¶

LED¶

LEDConfig
LEDColor

Common Model Usage¶

from pypack.core import LEDConfig, LEDMode, Direction

led = LEDConfig.rgb(255, 0, 0, mode=LEDMode.BLINK)
drone.move(Direction.FORWARD, 100, led=led)

state = drone.get_state()
print(state.position.x, state.position.y, state.battery_percent)

Telemetry model access:

flight = drone.get_flight_data()

print(flight.position.x, flight.position.y, flight.position.z)
print(flight.velocity)
print(flight.orientation.yaw)
print(flight.altitude_tof)

LED patterns from a real wheel smoke test:

from pypack.core import LEDConfig, LEDMode

takeoff_led = LEDConfig(r=125, g=125, b=125, mode=LEDMode.BLINK)
hover_led = LEDConfig(r=255, g=0, b=0, mode=LEDMode.CONSTANT)
land_led = LEDConfig(r=0, g=0, b=255, mode=LEDMode.CONSTANT)

drone.takeoff(led=takeoff_led)
drone.hover(led=hover_led)
drone.land(led=land_led)

Exceptions¶

Base class:

DroneError

Operational exceptions:

Typical exception handling:

from droneapi import DroneAPI
from pypack.core import DroneConnectionError, LowBattery, NotReady

try:
    with DroneAPI() as drone:
        drone.connect()
        drone.takeoff()
except DroneConnectionError:
    print("Connection failed")
except LowBattery:
    print("Battery too low to continue")
except NotReady:
    print("Drone rejected the command")

Additional validation exceptions exist in pypack.core.exceptions:

Controller Types¶

pypack.control exports:

Typical usage:

from pypack.control import ControllerConfig

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

And then:

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

Video Types¶

pypack.video exports core stream data types even without optional backends:

These become especially useful once the video, vision, or web extras are installed.

Example callback signature:

from pypack.video import Frame

def annotate(frame: Frame) -> Frame:
    frame.metadata["pipeline"] = "demo"
    return frame