Core Models

models

Pydantic models for Drone API inputs and outputs.

All models use Pydantic v2 for runtime validation and serialization.

Vector3

Bases: BaseModel

3D vector for position, velocity, or acceleration.

Units depend on context:

• Position: centimeters (cm)
• Velocity: cm/s
• Acceleration: cm/s^2

model_config class-attribute instance-attribute

model_config = ConfigDict(frozen=True)

x instance-attribute

x: float

y instance-attribute

y: float

z instance-attribute

z: float

magnitude

magnitude() -> float

Calculate vector magnitude.

Orientation

Bases: BaseModel

Orientation angles in degrees.

Yaw: rotation around vertical axis (0-360) Pitch: nose up/down (-90 to 90) Roll: wing tilt (-180 to 180)

model_config class-attribute instance-attribute

model_config = ConfigDict(frozen=True)

yaw instance-attribute

yaw: float

pitch instance-attribute

pitch: float

roll instance-attribute

roll: float

LEDConfig

Bases: BaseModel

LED configuration for flight commands.

Replaces the untyped dict {'r': 0, 'g': 0, 'b': 0, 'mode': 1} pattern.

Usage:

# Using predefined colors
from pypack.core import LEDColor
led = LEDColor.RED
led = LEDColor.BLUE.with_mode(LEDMode.BLINK)

# Using custom RGB
led = LEDConfig.rgb(128, 64, 255)
led = LEDConfig(r=255, g=128, b=0, mode=LEDMode.BREATHING)

model_config class-attribute instance-attribute

model_config = ConfigDict(frozen=True)

r class-attribute instance-attribute

r: int = Field(default=0, ge=0, le=255, description='Red channel (0-255)')

g class-attribute instance-attribute

g: int = Field(default=0, ge=0, le=255, description='Green channel (0-255)')

b class-attribute instance-attribute

b: int = Field(default=0, ge=0, le=255, description='Blue channel (0-255)')

mode class-attribute instance-attribute

mode: LEDMode = Field(default=CONSTANT, description='LED mode')

to_param4

to_param4() -> int

Convert to MAVLink param4 format for formation_cmd_encode().

Bit layout: [mode:8][b:8][g:8][r:8]

with_mode

with_mode(mode: LEDMode) -> LEDConfig

Return new LEDConfig with different mode, keeping same color.

off classmethod

off() -> LEDConfig

Create LED-off configuration.

rgb classmethod

rgb(r: int, g: int, b: int, mode: LEDMode = CONSTANT) -> LEDConfig

Create custom RGB LED configuration.

LEDColor

Predefined LED colors for convenience.

Usage:

from pypack.core import LEDColor, LEDMode

# Use directly
drone.move(Direction.FORWARD, 100, led=LEDColor.RED)

# With different mode
drone.takeoff(led=LEDColor.GREEN.with_mode(LEDMode.BLINK))

# Custom RGB still available
drone.land(led=LEDConfig.rgb(128, 64, 255))

RED class-attribute instance-attribute

RED = LEDConfig(r=255, g=0, b=0)

GREEN class-attribute instance-attribute

GREEN = LEDConfig(r=0, g=255, b=0)

BLUE class-attribute instance-attribute

BLUE = LEDConfig(r=0, g=0, b=255)

YELLOW class-attribute instance-attribute

YELLOW = LEDConfig(r=255, g=255, b=0)

CYAN class-attribute instance-attribute

CYAN = LEDConfig(r=0, g=255, b=255)

MAGENTA class-attribute instance-attribute

MAGENTA = LEDConfig(r=255, g=0, b=255)

WHITE class-attribute instance-attribute

WHITE = LEDConfig(r=255, g=255, b=255)

ORANGE class-attribute instance-attribute

ORANGE = LEDConfig(r=255, g=128, b=0)

PURPLE class-attribute instance-attribute

PURPLE = LEDConfig(r=128, g=0, b=255)

PINK class-attribute instance-attribute

PINK = LEDConfig(r=255, g=105, b=180)

LIME class-attribute instance-attribute

LIME = LEDConfig(r=50, g=255, b=50)

SKY_BLUE class-attribute instance-attribute

SKY_BLUE = LEDConfig(r=135, g=206, b=235)

WARM_WHITE class-attribute instance-attribute

WARM_WHITE = LEDConfig(r=255, g=244, b=229)

GOLD class-attribute instance-attribute

GOLD = LEDConfig(r=255, g=215, b=0)

CORAL class-attribute instance-attribute

CORAL = LEDConfig(r=255, g=127, b=80)

TURQUOISE class-attribute instance-attribute

TURQUOISE = LEDConfig(r=64, g=224, b=208)

OFF class-attribute instance-attribute

OFF = LEDConfig(r=0, g=0, b=0, mode=OFF)

FlightData

Bases: BaseModel

Complete flight telemetry snapshot.

Parsed from MAVLink REPORT_FLIGHT_DATA (msg ID 206).

position class-attribute instance-attribute

position: Vector3 = Field(description='Position in cm')

velocity class-attribute instance-attribute

velocity: Vector3 = Field(description='Velocity in cm/s')

acceleration class-attribute instance-attribute

acceleration: Vector3 = Field(description='Acceleration in cm/s^2')

orientation class-attribute instance-attribute

orientation: Orientation = Field(description='Orientation in degrees')

altitude_tof class-attribute instance-attribute

altitude_tof: float = Field(description='ToF sensor altitude in cm')

altitude_baro class-attribute instance-attribute

altitude_baro: float = Field(default=0.0, description='Barometer altitude in m')

battery_percent class-attribute instance-attribute

battery_percent: int = Field(ge=0, le=100, description='Battery percentage')

barrier class-attribute instance-attribute

barrier: int = Field(default=0, description='Obstacle detection bitmask')

timestamp class-attribute instance-attribute

timestamp: datetime = Field(default_factory=now)

from_mavlink classmethod

from_mavlink(msg) -> FlightData

Create FlightData from MAVLink report_flight_data message.

Obstacles

Bases: BaseModel

Obstacle detection state from barrier sensors.

Parsed from the barrier bitmask in REPORT_FLIGHT_DATA.

model_config class-attribute instance-attribute

model_config = ConfigDict(frozen=True)

forward class-attribute instance-attribute

forward: bool = False

back class-attribute instance-attribute

back: bool = False

left class-attribute instance-attribute

left: bool = False

right class-attribute instance-attribute

right: bool = False

down class-attribute instance-attribute

down: bool = False

from_bitmask classmethod

from_bitmask(barrier: int) -> Obstacles

Create Obstacles from barrier bitmask.

Bit mapping:

• Bit 0: forward
• Bit 1: back
• Bit 2: left
• Bit 3: right
• Bit 4: down

any_obstacle

any_obstacle() -> bool

Check if any obstacle is detected.

DroneState

Bases: BaseModel

Complete drone state snapshot.

Combines connection status, telemetry, and obstacle detection.

status class-attribute instance-attribute

status: DroneStatus = Field(description='Current drone status')

flight_data class-attribute instance-attribute

flight_data: FlightData | None = Field(default=None, description='Latest telemetry')

obstacles class-attribute instance-attribute

obstacles: Obstacles = Field(default_factory=Obstacles, description='Obstacle detection')

drone_id class-attribute instance-attribute

drone_id: int | None = Field(default=None, description='Drone ID')

is_connected class-attribute instance-attribute

is_connected: bool = Field(default=False, description='Connection status')

last_heartbeat class-attribute instance-attribute

last_heartbeat: datetime | None = Field(default=None, description='Last heartbeat time')

AIResult

Bases: BaseModel

Result from AI/vision recognition operations.

Used for digit/arrow recognition, QR code detection, etc.

success class-attribute instance-attribute

success: bool = Field(description='Whether recognition succeeded')

target_type class-attribute instance-attribute

target_type: int = Field(default=0, description='Recognized target type/value')

position class-attribute instance-attribute

position: Vector3 | None = Field(default=None, description='Target position if found')

angle class-attribute instance-attribute

angle: float | None = Field(default=None, description='Target angle in degrees')

qr_id class-attribute instance-attribute

qr_id: int | None = Field(default=None, description='QR code ID if applicable')

from_dict classmethod

from_dict(data: dict) -> AIResult

Create AIResult from legacy dict response.

ColorResult

Bases: BaseModel

Result from color recognition.

Returns the dominant color detected by the camera.

model_config class-attribute instance-attribute

model_config = ConfigDict(frozen=True)

success class-attribute instance-attribute

success: bool = Field(description='Whether color detection succeeded')

r class-attribute instance-attribute

r: int = Field(default=0, ge=0, le=255, description='Red channel')

g class-attribute instance-attribute

g: int = Field(default=0, ge=0, le=255, description='Green channel')

b class-attribute instance-attribute

b: int = Field(default=0, ge=0, le=255, description='Blue channel')

from_response classmethod

from_response(r: int, g: int, b: int, state: int) -> ColorResult

Create ColorResult from legacy response values.

SystemStats

Bases: BaseModel

Extended system statistics from REPORT_STATS (msg ID 207).

Contains comprehensive drone status beyond basic telemetry.

drone_id class-attribute instance-attribute

drone_id: int = Field(description='Drone ID')

firmware_version class-attribute instance-attribute

firmware_version: int = Field(default=0, description='Firmware version (raw 2-byte value)')

system_version class-attribute instance-attribute

system_version: int = Field(default=0, description='System version (raw 2-byte value)')

flight_time class-attribute instance-attribute

flight_time: int = Field(default=0, description='Total flight time in ms')

utc_timestamp class-attribute instance-attribute

utc_timestamp: int = Field(default=0, description='UTC timestamp')

gps_lat class-attribute instance-attribute

gps_lat: float | None = Field(default=None, description='GPS latitude')

gps_lon class-attribute instance-attribute

gps_lon: float | None = Field(default=None, description='GPS longitude')

sensors_present class-attribute instance-attribute

sensors_present: int = Field(default=0, description='Sensor presence bitmask')

sensors_health class-attribute instance-attribute

sensors_health: int = Field(default=0, description='Sensor health bitmask')

temperature class-attribute instance-attribute

temperature: int = Field(default=0, description='Internal temperature in C')

drone_status class-attribute instance-attribute

drone_status: int = Field(default=0, description='Drone status flags')

block_status class-attribute instance-attribute

block_status: int = Field(default=0, description='Block/safety status')

rgb_status class-attribute instance-attribute

rgb_status: int = Field(default=0, description='RGB LED status')

battery_percent class-attribute instance-attribute

battery_percent: int = Field(default=0, description='Battery percentage')

firmware_version_str property

firmware_version_str: str

Get firmware version as dotted string (e.g., '1.1.7.0').

system_version_str property

system_version_str: str

Get system version as dotted string (e.g., '1.9.0.3').

full_version_str property

full_version_str: str

Get combined version string (system.firmware).

parse_version staticmethod

parse_version(value: int) -> str

Parse 2-byte version value to dotted string.

The version is encoded as a 4-digit decimal where each digit represents a version component (major.minor.patch.revision).

Examples:

1170 -> "1.1.7.0" 1903 -> "1.9.0.3"

MediaFile

Bases: BaseModel

Media file metadata from drone storage.

Represents a photo, video, or log file stored on the drone. Retrieved via HTTP CGI API at port 12346.

name class-attribute instance-attribute

name: str = Field(description='Filename (e.g., 20251111_102056_1.jpg)')

path class-attribute instance-attribute

path: str = Field(description='Full path on drone storage')

thumb_path class-attribute instance-attribute

thumb_path: str | None = Field(default=None, description='Thumbnail path (photos/videos only)')

date class-attribute instance-attribute

date: str = Field(description='Creation date (e.g., 2025-11-11 10:20:56)')

size class-attribute instance-attribute

size: str = Field(description='File size (e.g., 0.10MB)')

media_type class-attribute instance-attribute

media_type: MediaType = Field(default=PHOTO, description='Type of media file')

from_snap_info classmethod

from_snap_info(data: dict, media_type: MediaType = PHOTO) -> MediaFile

Create MediaFile from drone's snaplist JSON response.

get_download_url

get_download_url(drone_ip: str, port: int = 12346) -> str

Get HTTP URL for downloading this file.

get_thumb_url

get_thumb_url(drone_ip: str, port: int = 12346) -> str | None

Get HTTP URL for downloading thumbnail.