Control API¶

control ¶

Nectar SDK - Control module.

MAVLINK_SITL_CONFIG `module-attribute` ¶

MAVLINK_SITL_CONFIG = MavlinkConfig(name='sitl_drone', pose_source=PoseSource.GPS, connection_string='tcp:127.0.0.1:5760', expect_lidar=False)

MavlinkConfig preset for ArduPilot SITL over a direct pymavlink TCP link.

MAVLINK_SITL_GAZEBO_CONFIG `module-attribute` ¶

MAVLINK_SITL_GAZEBO_CONFIG = MavlinkConfig(name='sitl_drone', pose_source=PoseSource.GPS, connection_string='tcp:127.0.0.1:5762', expect_lidar=False)

MavlinkConfig preset for SITL + Gazebo over the SITL secondary MAVLink port.

MAVLINK_SITL_VISION_CONFIG `module-attribute` ¶

MAVLINK_SITL_VISION_CONFIG = MavlinkConfig(name='sitl_drone', pose_source=PoseSource.VISION, connection_string='tcp:127.0.0.1:5762', expect_lidar=False, vision_pose_topic='/visual_slam/tracking/vo_pose_covariance')

MavlinkConfig preset for SITL + Gazebo indoor (vision pose).

PX4_DDS_SITL_CONFIG `module-attribute` ¶

PX4_DDS_SITL_CONFIG = Px4DdsConfig(name='px4_dds_sitl_drone', pose_source=PoseSource.GPS, pid_config_file=os.path.join(_PX4_CONFIG_DIR, 'position_sim_outdoor.yaml'))

Px4DdsConfig preset for PX4 SITL over native uXRCE-DDS (MicroXRCEAgent on 8888).

PX4_MAVLINK_SITL_CONFIG `module-attribute` ¶

PX4_MAVLINK_SITL_CONFIG = Px4MavlinkConfig(name='px4_mavlink_sitl_drone', pose_source=PoseSource.GPS, expect_lidar=False)

Px4MavlinkConfig preset for PX4 SITL over direct pymavlink (headless, GPS, no lidar).

PX4_MAVLINK_SITL_GAZEBO_CONFIG `module-attribute` ¶

PX4_MAVLINK_SITL_GAZEBO_CONFIG = Px4MavlinkConfig(name='px4_mavlink_sitl_drone', pose_source=PoseSource.GPS, expect_lidar=True, pid_config_file=os.path.join(_PX4_CONFIG_DIR, 'position_sim_outdoor.yaml'), setpoint_config_file=os.path.join(_PX4_CONFIG_DIR, 'setpoint_sim_outdoor.yaml'), apply_setpoint_params=True)

Px4MavlinkConfig preset for PX4 SITL + Gazebo over direct pymavlink (x500_nectar outdoor).

The downward rangefinder arrives as MAVLink DISTANCE_SENSOR on the offboard link (no MAVROS needed).

PX4_MAVLINK_SITL_VISION_CONFIG `module-attribute` ¶

PX4_MAVLINK_SITL_VISION_CONFIG = Px4MavlinkConfig(name='px4_mavlink_sitl_drone', pose_source=PoseSource.VISION, expect_lidar=False, pid_config_file=os.path.join(_PX4_CONFIG_DIR, 'position_sim_indoor.yaml'), setpoint_config_file=os.path.join(_PX4_CONFIG_DIR, 'setpoint_sim_indoor.yaml'), apply_setpoint_params=True)

Px4MavlinkConfig preset for PX4 SITL indoor over direct pymavlink (VISION_POSITION_ESTIMATE).

PX4_SITL_CONFIG `module-attribute` ¶

PX4_SITL_CONFIG = Px4MavrosConfig(name='px4_sitl_drone', pose_source=PoseSource.GPS, expect_lidar=False)

Px4MavrosConfig preset for PX4 SITL (headless, GPS, no lidar).

PX4_SITL_GAZEBO_CONFIG `module-attribute` ¶

PX4_SITL_GAZEBO_CONFIG = Px4MavrosConfig(name='px4_sitl_drone', pose_source=PoseSource.GPS, expect_lidar=True, pid_config_file=os.path.join(_PX4_CONFIG_DIR, 'position_sim_outdoor.yaml'), setpoint_config_file=os.path.join(_PX4_CONFIG_DIR, 'setpoint_sim_outdoor.yaml'), apply_setpoint_params=True)

Px4MavrosConfig preset for PX4 SITL + Gazebo (x500_nectar outdoor, GPS + rangefinder).

The downward lidar reaches the SDK as /mavros/rangefinder/rangefinder: PX4 fuses the gz gpu_lidar into a distance_sensor and streams DISTANCE_SENSOR, which MAVROS republishes (see simulation/config/px4_config_sitl.yaml).

PX4_SITL_VISION_CONFIG `module-attribute` ¶

PX4_SITL_VISION_CONFIG = Px4MavrosConfig(name='px4_sitl_drone', pose_source=PoseSource.VISION, expect_lidar=False, pid_config_file=os.path.join(_PX4_CONFIG_DIR, 'position_sim_indoor.yaml'), setpoint_config_file=os.path.join(_PX4_CONFIG_DIR, 'setpoint_sim_indoor.yaml'), apply_setpoint_params=True)

Px4MavrosConfig preset for PX4 SITL + Gazebo indoor (EKF2 external vision).

SITL_CONFIG `module-attribute` ¶

SITL_CONFIG = MavrosConfig(name='sitl_drone', connection_string='tcp://127.0.0.1:5760', expect_lidar=False)

MavrosConfig preset for ArduPilot SITL (headless, no lidar).

SITL_GAZEBO_CONFIG `module-attribute` ¶

SITL_GAZEBO_CONFIG = MavrosConfig(name='sitl_drone', pose_source=PoseSource.GPS, connection_string='tcp://127.0.0.1:5760', expect_lidar=True, pid_config_file=os.path.join(_ARDUPILOT_CONFIG_DIR, 'position_sim_outdoor.yaml'), setpoint_config_file=os.path.join(_ARDUPILOT_CONFIG_DIR, 'setpoint_sim_outdoor.yaml'), apply_setpoint_params=True)

MavrosConfig preset for SITL + Gazebo (ardupilot_gazebo iris model, rangefinder enabled).

SITL_GPS_CONFIG `module-attribute` ¶

SITL_GPS_CONFIG = MavrosConfig(name='sitl_drone', pose_source=PoseSource.GPS, connection_string='tcp://127.0.0.1:5760', expect_lidar=False)

MavrosConfig preset for SITL with GPS pose source (outdoor simulation).

SITL_VISION_CONFIG `module-attribute` ¶

SITL_VISION_CONFIG = MavrosConfig(name='sitl_drone', pose_source=PoseSource.VISION, connection_string='tcp://127.0.0.1:5760', expect_lidar=True, pid_config_file=os.path.join(_ARDUPILOT_CONFIG_DIR, 'position_sim_indoor.yaml'), setpoint_config_file=os.path.join(_ARDUPILOT_CONFIG_DIR, 'setpoint_sim_indoor.yaml'), apply_setpoint_params=True)

MavrosConfig preset for SITL indoor (no GPS, EKF3 ExternalNav, rangefinder enabled).

SetpointNavConfig `dataclass` ¶

SetpointNavConfig(guid_options: int = 1, speed: float = 2.0, speed_up: float = 1.5, speed_down: float = 1.5, accel: float = 1.0, radius: float = 0.2, jerk: float = 1.0, psc_jerk: float = 5.0, rfnd_use: int = 1)

Bases: SetpointConfig

Configuration for ArduPilot setpoint navigation parameters.

All speed/distance values in SI units (m/s, m). Conversion to ArduPilot units (cm/s, cm) happens internally when setting FCU parameters.

Parameters:

Name	Type	Description	Default
`guid_options`	`int`	Bitmask for GUID_OPTIONS parameter. Controls GUIDED mode behavior. Bit 0 (1): Allow arming from TX. Bit 6 (64): WPNav S-curve path planning for position targets. Bit 7 (128): Weathervaning. Default 1 = bit 0 (arm from TX, AC_PosControl). See https://ardupilot.org/copter/docs/ac2_guidedmode.html#guided-mode-options	`1`
`speed`	`float`	Horizontal speed limit in m/s (maps to WPNAV_SPEED in cm/s).	`2.0`
`speed_up`	`float`	Climb speed limit in m/s (maps to WPNAV_SPEED_UP in cm/s).	`1.5`
`speed_down`	`float`	Descent speed limit in m/s (maps to WPNAV_SPEED_DN in cm/s).	`1.5`
`accel`	`float`	Horizontal acceleration in m/s/s (maps to WPNAV_ACCEL in cm/s/s).	`1.0`
`radius`	`float`	Arrival radius in m (maps to WPNAV_RADIUS in cm). Only used in WPNav mode for trajectory deceleration planning.	`0.2`
`jerk`	`float`	WPNav horizontal jerk limit in m/s³ (maps to WPNAV_JERK). Controls S-curve trajectory smoothness in WPNav mode (bit 6). ArduPilot default 1.0, range 1–20.	`1.0`
`psc_jerk`	`float`	Position controller horizontal jerk limit in m/s³ (PSC_JERK_XY in 4.6.3, PSC_JERK_NE in 4.8+). Affects AC_PosControl (SubMode::Pos) response speed. ArduPilot default 5.0, range 1–20. SITL typically needs higher values (e.g. 50) for usable response.	`5.0`
`rfnd_use`	`int`	Rangefinder terrain following for WPNav (maps to WPNAV_RFND_USE). 0 = disabled, 1 = enabled. ArduPilot default 1.	`1`

use_wpnav `property` ¶

use_wpnav: bool

True if GUID_OPTIONS bit 6 (WPNav S-curve) is enabled.

to_fcu_params ¶

to_fcu_params() -> dict

Return ArduPilot parameter names and values in FCU units.

Speed/accel/radius are converted to cm/s and cm. Jerk values are already in m/s³. Uses stable WPNAV_* names as primary. Use PARAM_ALIASES to get fallback names for ArduPilot v4.8+.

BaseDrone ¶

BaseDrone(config: DroneConfig, executor: Optional[Executor] = None)

Bases: ABC

Abstract base class for drone implementations.

Each drone owns its own ROS 2 Node, which is registered with the SDK-wide executor at construction time (see :mod:nectar.runtime). Callers may pass an explicit executor to share an existing one (e.g. the GUI's or Yasmin's). All blocking methods rely on that executor to spin in the background.

Parameters:

Name	Type	Description	Default
`config`	`DroneConfig`	Drone configuration dataclass.	required
`executor`	`Executor`	Executor to register this drone's node with. Defaults to the shared SDK executor from :func:`nectar.runtime.get_executor`.	`None`

config `property` ¶

config: DroneConfig

Drone configuration object.

node `property` ¶

node: Node

ROS2 node instance used for communication.

is_ready `property` ¶

is_ready: bool

Check if drone is ready for operation (connected and driver running).

driver_running `property` ¶

driver_running: bool

Whether the driver process is currently running.

is_armed `property` ¶

is_armed: Optional[bool]

Check if motors are armed.

Returns:

Type	Description
`Optional[bool]`	True if armed, False if disarmed, None if not supported.

flight_mode `property` ¶

flight_mode: Optional[str]

Current flight mode.

Returns:

Type	Description
`Optional[str]`	Flight mode name, or None if not available.

is_fcu_connected `property` ¶

is_fcu_connected: Optional[bool]

Check if FCU/autopilot is connected.

Returns:

Type	Description
`Optional[bool]`	True if connected, False otherwise, None if not applicable.

driver_session_name `property` ¶

driver_session_name: str

Tmux session name used for the driver process.

obstacle_manager `property` ¶

obstacle_manager: ObstacleManager

Obstacle detection manager for this drone instance.

capabilities `property` ¶

capabilities: frozenset[Capability]

Set of features this drone supports.

Override in subclasses to declare the supported :class:Capability set. The base implementation declares none.

supports ¶

supports(capability: Capability) -> bool

Return whether this drone declares capability.

add_obstacle_detector ¶

add_obstacle_detector(name: str, detector: ObstacleDetector, strategy, config: Optional[ObstacleHandlerConfig] = None) -> None

Add obstacle detector with avoidance strategy.

Creates handler with independent timer for detection updates. Strategy determines how drone responds to detected obstacles during navigation.

Parameters:

Name	Type	Description	Default
`name`	`str`	Unique identifier for this detector.	required
`detector`	`ObstacleDetector`	Detector implementation (e.g., DepthObstacleDetector).	required
`strategy`	`AvoidanceStrategy`	Strategy for obstacle response (e.g., PauseStrategy, SequenceStrategy).	required
`config`	`ObstacleHandlerConfig`	Handler configuration including update rate. If None, uses defaults.	`None`

remove_obstacle_detector ¶

remove_obstacle_detector(name: str) -> None

Remove obstacle detector and cleanup resources.

Parameters:

Name	Type	Description	Default
`name`	`str`	Detector identifier.	required

enable_obstacle_detector ¶

enable_obstacle_detector(name: str) -> None

Enable obstacle detector.

Starts timer-based updates and activates avoidance strategy during navigation.

Parameters:

Name	Type	Description	Default
`name`	`str`	Detector identifier.	required

disable_obstacle_detector ¶

disable_obstacle_detector(name: str) -> None

Disable obstacle detector.

Stops timer-based updates and deactivates avoidance strategy.

Parameters:

Name	Type	Description	Default
`name`	`str`	Detector identifier.	required

enable_all_obstacle_detectors ¶

enable_all_obstacle_detectors() -> None

Enable all registered obstacle detectors.

disable_all_obstacle_detectors ¶

disable_all_obstacle_detectors() -> None

Disable all registered obstacle detectors.

connect `abstractmethod` ¶

connect() -> bool

Establish connection to drone hardware or driver.

Returns:

Type	Description
`bool`	True if connection successful.

disconnect `abstractmethod` ¶

disconnect() -> None

Close connection and cleanup resources.

arm `abstractmethod` ¶

arm() -> bool

Arm motors for flight.

Returns:

Type	Description
`bool`	True if arming successful.

disarm `abstractmethod` ¶

disarm() -> bool

Force disarm motors.

Always sends force disarm command to bypass safety checks.

Returns:

Type	Description
`bool`	True if disarming successful.

takeoff `abstractmethod` ¶

takeoff(altitude: float) -> bool

Execute takeoff to specified altitude.

Parameters:

Name	Type	Description	Default
`altitude`	`float`	Target altitude in meters.	required

Returns:

Type	Description
`bool`	True if takeoff successful.

land `abstractmethod` ¶

land(timeout: float = 30.0) -> bool

Execute landing at current position.

Parameters:

Name	Type	Description	Default
`timeout`	`float`	Maximum time for operation in seconds.	`30.0`

Returns:

Type	Description
`bool`	True if landing successful (motors disarmed).

move_velocity `abstractmethod` ¶

move_velocity(vx: float = 0.0, vy: float = 0.0, vz: float = 0.0, vyaw: float = 0.0, duration: Optional[float] = None, reference: MoveReference = BODY) -> None

Command velocity-based movement.

Parameters:

Name	Type	Description	Default
`vx`	`float(m / s)`	(+) Move forward (-) Move backward	`0.0`
`vy`	`float(m / s)`	(+) Move left (-) Move right	`0.0`
`vz`	`float(m / s)`	(+) Move up (-) Move down	`0.0`
`vyaw`	`float(rad / s)`	(+) Rotate counter clockwise (-) Rotate clockwise	`0.0`
`duration`	`float(s)`	Execution time. If None, command is continuous.	`None`
`reference`	`MoveReference(enum)`	BODY: relative to current orientation WORLD: absolute world frame (ENU directions) TAKEOFF: relative to takeoff position	`BODY`

move_to `abstractmethod` ¶

move_to(x: Optional[float] = None, y: Optional[float] = None, z: Optional[float] = None, yaw: Optional[float] = None, reference: MoveReference = BODY, timeout: Optional[float] = 60.0, precision: float = 0.2, method: NavigationMethod = POSITION, altitude_source: AltitudeSource = AUTO) -> bool

Navigate to target position.

The movement is relative to the drone's current orientation: - x-axis: forward/backward relative to drone's heading - y-axis: right/left relative to drone's heading - z-axis: up/down relative to current altitude

Parameters:

Name	Type	Description	Default
`x`	`Optional[float]`	Distance to move forward (+) or backward (-) in meters. If None, disables movement in x direction.	`None`
`y`	`Optional[float]`	Distance to move left (+) or right (-) in meters. If None, disables movement in y direction.	`None`
`z`	`Optional[float]`	Distance to move up (+) or down (-) in meters. If None altitude control is disabled.	`None`
`yaw`	`Optional[float]`	Target yaw in degrees. If None, disables yaw control.	`None`
`reference`	`MoveReference(enum)`	Reference frame for movement: - BODY: relative to current orientation - WORLD: absolute world frame (ENU directions) - TAKEOFF: relative to takeoff position	`BODY`
`timeout`	`Optional[float]`	Maximum navigation time in seconds. None for no timeout.	`60.0`
`precision`	`float`	Arrival threshold in meters.	`0.2`
`method`	`NavigationMethod(enum)`	Navigation algorithm: - POSITION: onboard position controller (FCU setpoint / goTo) - POSITION_GLOBAL: onboard GPS position controller (outdoor only) - PID: companion-side velocity PID with raw sensors - PID_EKF: companion-side velocity PID with EKF-fused position	`POSITION`
`altitude_source`	`AltitudeSource(enum)`	Altitude sensor source for PID navigation: AUTO: best available (lidar > vision Z > relative altitude). LIDAR: lidar rangefinder for ground-relative altitude control. VISION: vision pose Z component. REL_ALT: GPS-based relative altitude.	`AUTO`

Returns:

Type	Description
`bool`	True if target reached within precision, False on timeout.

Raises:

Type	Description
`TakeoffPositionNotSetError`	If reference=TAKEOFF but takeoff position not set.
`SensorNotAvailableError`	If altitude_source=LIDAR but lidar is not available.
`CapabilityNotSupportedError`	If the requested method is not supported by this drone.

move_to_gps ¶

move_to_gps(latitude: float, longitude: float, altitude: Optional[float] = None, heading: Optional[float] = None, timeout: Optional[float] = 60.0, precision: float = 0.5, method: NavigationMethod = PID) -> bool

Navigate to GPS coordinates.

Parameters:

Name	Type	Description	Default
`latitude`	`float`	Target latitude in degrees (WGS84).	required
`longitude`	`float`	Target longitude in degrees (WGS84).	required
`altitude`	`float`	Target altitude above ground in meters. None uses current altitude.	`None`
`heading`	`float`	Target heading in degrees (0 = North, clockwise). None uses current heading.	`None`
`timeout`	`float`	Maximum navigation time in seconds.	`60.0`
`precision`	`float`	Arrival threshold in meters.	`0.5`
`method`	`NavigationMethod`	Navigation algorithm.	`PID`

Returns:

Type	Description
`bool`	True if waypoint reached.

Raises:

Type	Description
`CapabilityNotSupportedError`	If drone doesn't support GPS navigation.

emergency_stop `abstractmethod` ¶

emergency_stop() -> None

Execute emergency stop (force motor shutdown).

set_home ¶

set_home() -> bool

Set current position as home.

Returns:

Type	Description
`bool`	True if successful.

rtl ¶

rtl(altitude: Optional[float] = None, precision: float = 0.2, method: RTLMethod = NAVIGATE, land: bool = True) -> bool

Return to launch position.

Parameters:

Name	Type	Description	Default
`altitude`	`float`	Transit altitude in meters. None uses current altitude.	`None`
`precision`	`float`	Arrival threshold in meters (used by NAVIGATE method).	`0.2`
`method`	`RTLMethod`	RTL algorithm: - NAVIGATE: SDK navigates to takeoff position using position control. - NATIVE: drone's built-in RTL mode (ArduPilot RTL, Bebop navigate_home).	`NAVIGATE`
`land`	`bool`	Execute landing after reaching home.	`True`

Returns:

Type	Description
`bool`	True if RTL successful.

check_driver_status ¶

check_driver_status() -> bool

Check if driver node is running in ROS2 graph.

Uses ProcessUtils for efficient node checking without blocking.

Returns:

Type	Description
`bool`	True if driver node found in ROS2 graph.

start_driver_process ¶

start_driver_process() -> bool

Start the driver process.

Convenience method that starts the driver and waits for it to be ready.

Returns:

Type	Description
`bool`	True if driver started successfully.

stop_driver_process ¶

stop_driver_process() -> bool

Stop the driver process.

Kills the tmux session running the driver.

Returns:

Type	Description
`bool`	True if driver stopped successfully.

delay ¶

delay(seconds: float) -> None

Sleep for seconds. SDK executor keeps spinning in the background.

cleanup ¶

cleanup() -> None

Destroy all ROS resources and unregister the drone's node.

Capability ¶

Bases: Enum

A discrete feature a drone may or may not support.

GPS_NAV `class-attribute` `instance-attribute` ¶

GPS_NAV = auto()

Navigate to global (lat/lon) waypoints.

LOCAL_SETPOINT `class-attribute` `instance-attribute` ¶

LOCAL_SETPOINT = auto()

Onboard local position controller (FRAME_LOCAL_NED setpoints).

GLOBAL_SETPOINT `class-attribute` `instance-attribute` ¶

GLOBAL_SETPOINT = auto()

Onboard global position controller (GPS setpoints).

PID_NAV `class-attribute` `instance-attribute` ¶

PID_NAV = auto()

Companion-side velocity PID navigation.

VELOCITY_BODY `class-attribute` `instance-attribute` ¶

VELOCITY_BODY = auto()

Velocity commands in the body frame.

VELOCITY_WORLD `class-attribute` `instance-attribute` ¶

VELOCITY_WORLD = auto()

Velocity commands in the world/local frame.

VELOCITY_TAKEOFF `class-attribute` `instance-attribute` ¶

VELOCITY_TAKEOFF = auto()

Velocity commands relative to the takeoff frame.

SERVO `class-attribute` `instance-attribute` ¶

SERVO = auto()

Per-channel PWM servo control (ArduPilot DO_SET_SERVO).

ACTUATOR `class-attribute` `instance-attribute` ¶

ACTUATOR = auto()

Normalized payload actuator output (DO_SET_ACTUATOR).

GRIPPER `class-attribute` `instance-attribute` ¶

GRIPPER = auto()

Gripper open/close (DO_GRIPPER).

PARAMS `class-attribute` `instance-attribute` ¶

PARAMS = auto()

Read/write autopilot parameters.

RANGEFINDER `class-attribute` `instance-attribute` ¶

RANGEFINDER = auto()

Downward rangefinder altitude source.

DISTANCE_SENSORS `class-attribute` `instance-attribute` ¶

DISTANCE_SENSORS = auto()

All-orientation distance sensor telemetry.

VISION_POSE `class-attribute` `instance-attribute` ¶

VISION_POSE = auto()

External-vision pose estimate (indoor / non-GPS).

NATIVE_RTL `class-attribute` `instance-attribute` ¶

NATIVE_RTL = auto()

Autopilot-native return-to-launch.

OBSTACLE_AVOIDANCE `class-attribute` `instance-attribute` ¶

OBSTACLE_AVOIDANCE = auto()

Companion-side obstacle detection / avoidance.

Px4MavlinkConfig `dataclass` ¶

Px4MavlinkConfig(name: str = 'px4_mavlink_drone', start_driver: bool = False, pose_source: PoseSource = GPS, expect_lidar: bool = True, sensor_timeout: float = 10.0, baud: int = 921600, source_system: int = 1, source_component: int = 191, heartbeat_timeout: float = 30.0, rx_rate_hz: float = 100.0, heartbeat_hz: float = 1.0, stream_rates: Optional[Dict[str, float]] = None, vision_pose_topic: str = '/visual_slam/tracking/vo_pose_covariance', pid_config_file: Optional[str] = None, setpoint_config_file: Optional[str] = None, apply_setpoint_params: bool = False, connection_string: str = 'udp:0.0.0.0:14540', offboard_rate_hz: float = 20.0)

Bases: _MavlinkLinkConfig

PX4 over a direct pymavlink link (no MAVROS).

Mirrors :class:MavlinkConfig (pymavlink endpoint + stream settings) and adds offboard_rate_hz for the PX4 offboard setpoint pump.

DriverInfo `dataclass` ¶

DriverInfo(name: str, node_patterns: List[str], session_name: str, topic_patterns: List[str] = list(), driverless: bool = False, detect_via: str = 'node')

Information about a drone driver.

Attributes:

Name	Type	Description
`name`	`str`	Human-readable driver name.
`node_patterns`	`List[str]`	ROS2 node name patterns to check for driver status.
`session_name`	`str`	Tmux session name for the driver process.
`topic_patterns`	`List[str]`	ROS2 topic name patterns that signal the driver is up, used when `detect_via == "topic"` (e.g. PX4's `/fmu/*` once the uXRCE-DDS agent and the FCU client have connected).
`driverless`	`bool, default=False`	True when the transport opens the FCU link inside the drone instance (no separate driver process), e.g. the direct pymavlink backends.
`detect_via`	`str, default="node"`	How to detect a running driver: `"node"` queries the ROS 2 node graph for `node_patterns`; `"topic"` queries the topic graph for `topic_patterns` (for processes exposed only through their data topics, e.g. the Micro XRCE-DDS Agent, which is not a ROS 2 node).

DriverMonitor ¶

DriverMonitor(driver_type: str)

Monitor and manage drone driver processes.

Provides utilities for checking driver status using ROS2 node graph and managing driver lifecycle through ProcessUtils.

Parameters:

Name	Type	Description	Default
`driver_type`	`str`	Type of driver to monitor ('mavros' or 'bebop').	required

Attributes:

Name	Type	Description
`status`	`DriverStatus`	Current driver status.
`last_error`	`Optional[str]`	Last error message if status is ERROR.

add_status_callback ¶

add_status_callback(callback: Callable[[DriverStatus], None]) -> None

Register callback for status changes.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[DriverStatus], None]`	Function called when driver status changes.	required

remove_status_callback ¶

remove_status_callback(callback: Callable[[DriverStatus], None]) -> None

Remove registered status callback.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[DriverStatus], None]`	Previously registered callback.	required

check_status ¶

check_status() -> DriverStatus

Check current driver status by querying ROS2 node graph.

Returns:

Type	Description
`DriverStatus`	Current driver status.

start_driver ¶

start_driver(command: str) -> bool

Start driver process.

Parameters:

Name	Type	Description	Default
`command`	`str`	Shell command to start the driver.	required

Returns:

Type	Description
`bool`	True if driver started successfully.

stop_driver ¶

stop_driver() -> bool

Stop driver process.

Returns:

Type	Description
`bool`	True if driver stopped successfully.

restart_driver ¶

restart_driver(command: str) -> bool

Restart driver process.

Parameters:

Name	Type	Description	Default
`command`	`str`	Shell command to start the driver.	required

Returns:

Type	Description
`bool`	True if driver restarted successfully.

get_available_drivers `staticmethod` ¶

get_available_drivers() -> List[str]

Get list of supported driver types.

Returns:

Type	Description
`List[str]`	Available driver type identifiers.

is_ros2_available `staticmethod` ¶

is_ros2_available() -> bool

Check if ROS2 environment is available.

Returns:

Type	Description
`bool`	True if ROS2 commands are accessible.

CapabilityNotSupportedError ¶

CapabilityNotSupportedError(capability: str, drone_type: str)

Bases: DroneError

Raised when attempting to use a capability not supported by the drone.

DriverNotFoundError ¶

DriverNotFoundError(driver_name: str)

Bases: DroneError

Raised when drone driver is not found or not running.

DroneError ¶

Bases: Exception

Base exception for all drone-related errors.

SensorNotAvailableError ¶

SensorNotAvailableError(sensor: str, mode: str = '')

Bases: DroneError

Raised when accessing a sensor that is not available in current mode.

TakeoffPositionNotSetError ¶

TakeoffPositionNotSetError(operation: str = 'operation')

Bases: DroneError

Raised when operation requires takeoff position but it hasn't been set.

DroneFactory ¶

Factory for creating drone instances using registry pattern.

register `classmethod` ¶

register(drone_type: str, builder: BuilderFunc) -> None

Register drone type with factory.

Parameters:

Name	Type	Description	Default
`drone_type`	`str`	Unique identifier for drone type (case-insensitive).	required
`builder`	`BuilderFunc`	Factory function with signature (DroneConfig, Node) -> Drone.	required

create `classmethod` ¶

create(drone_type: str, config: DroneConfig, executor: Optional[Executor] = None) -> Drone

Create drone instance of specified type.

Parameters:

Name	Type	Description	Default
`drone_type`	`str`	Drone type identifier (e.g., 'mavros', 'bebop').	required
`config`	`DroneConfig`	Type-specific configuration dataclass.	required
`executor`	`Executor`	ROS 2 executor to register the drone's internal node with. Defaults to the shared :mod:`nectar.runtime` executor.	`None`

Returns:

Type	Description
`Drone`	Concrete drone implementation.

Raises:

Type	Description
`ValueError`	If drone_type not registered.

available_types `classmethod` ¶

available_types() -> list[str]

Get list of registered drone types.

Returns:

Type	Description
`list[str]`	Available drone type identifiers, including built-ins that have not been imported yet.

is_registered `classmethod` ¶

is_registered(drone_type: str) -> bool

Check if drone type is registered.

Parameters:

Name	Type	Description	Default
`drone_type`	`str`	Drone type identifier.	required

Returns:

Type	Description
`bool`	True if type is registered (explicitly or as a built-in).

BaseObstacleDetector ¶

BaseObstacleDetector()

Bases: ABC

Thread-safe base class for obstacle detectors. Subclasses must implement _detect() for platform-specific detection logic.

is_enabled `property` ¶

is_enabled: bool

Get enabled state.

Returns:

Type	Description
`bool`	Enabled state.

enable ¶

enable() -> None

Enable detector

disable ¶

disable() -> None

Disable detector and call lifecycle hook.

Calls _on_disable() for resource cleanup.

update ¶

update() -> ObstacleInfo

Update detection state.

Thread-safe. Returns cached result if disabled.

Returns:

Type	Description
`ObstacleInfo`	Detection result.

get_last_info ¶

get_last_info() -> ObstacleInfo

Get last detection result.

Returns:

Type	Description
`ObstacleInfo`	Last detection result.

reset ¶

reset() -> None

Reset detection state

ObstacleHandler ¶

ObstacleHandler(detector: ObstacleDetector, strategy: AvoidanceStrategy, node: Node, config: Optional[ObstacleHandlerConfig] = None)

Combines obstacle detector with avoidance strategy.

Parameters:

Name	Type	Description	Default
`detector`	`ObstacleDetector`	Detector implementation.	required
`strategy`	`AvoidanceStrategy`	Avoidance strategy implementation.	required
`node`	`Node`	ROS2 node for timer creation.	required
`config`	`ObstacleHandlerConfig`	Handler configuration. If None, uses defaults.	`None`

should_continue ¶

should_continue(drone: BaseDrone) -> bool

Query if navigation should continue based on obstacle state.

Executes strategy's decision logic. Thread-safe access to detection state.

Parameters:

Name	Type	Description	Default
`drone`	`BaseDrone`	Drone instance for strategy execution.	required

Returns:

Type	Description
`bool`	True if navigation should continue, False to pause.

get_axis_modifiers ¶

get_axis_modifiers() -> tuple[bool, bool, bool]

Get axis disable flags from strategy.

Returns:

Type	Description
`tuple of (bool, bool, bool)`	(disable_x, disable_y, disable_z) flags.

reset ¶

reset() -> None

Reset detector and strategy state.

cleanup ¶

cleanup() -> None

Disable detector and cancel timer.

ObstacleManager ¶

ObstacleManager()

Manages multiple obstacle handlers for a drone.

handlers `property` ¶

handlers: dict[str, ObstacleHandler]

Dictionary of all registered handlers.

add ¶

add(name: str, handler: ObstacleHandler) -> None

Add obstacle handler.

Parameters:

Name	Type	Description	Default
`name`	`str`	Unique identifier.	required
`handler`	`ObstacleHandler`	Handler instance.	required

remove ¶

remove(name: str) -> Optional[ObstacleHandler]

Remove and cleanup obstacle handler.

Parameters:

Name	Type	Description	Default
`name`	`str`	Handler identifier.	required

Returns:

Type	Description
`(ObstacleHandler, optional)`	Removed handler, or None if not found.

get ¶

get(name: str) -> Optional[ObstacleHandler]

Get handler by name.

enable ¶

enable(name: str) -> None

Enable handler by name.

disable ¶

disable(name: str) -> None

Disable handler by name.

enable_all ¶

enable_all() -> None

Enable all registered handlers.

disable_all ¶

disable_all() -> None

Disable all registered handlers.

should_continue_navigation ¶

should_continue_navigation(drone: BaseDrone) -> bool

Check if navigation should continue.

Queries all enabled handlers. If any returns False, navigation pauses.

Parameters:

Name	Type	Description	Default
`drone`	`BaseDrone`	Drone instance for strategy execution.	required

Returns:

Type	Description
`bool`	True if all handlers allow navigation, False to pause.

get_axis_control ¶

get_axis_control() -> tuple[bool, bool, bool]

Get combined axis disable flags from all handlers.

Returns:

Type	Description
`tuple of (bool, bool, bool)`	(disable_x, disable_y, disable_z). True if any handler requests disable.

reset_all ¶

reset_all() -> None

Reset all handlers.

cleanup ¶

cleanup() -> None

Cleanup all handlers and clear registry.

PIDConfig `dataclass` ¶

PIDConfig(kp: float = 0.0, ki: float = 0.0, kd: float = 0.0, setpoint: float = 0.0, output_min: float = -1.0, output_max: float = 1.0, integral_min: float = -1.0, integral_max: float = 1.0)

PID controller configuration.

from_yaml `classmethod` ¶

from_yaml(file_path: str | Path) -> PIDConfig

Load PID configuration from YAML file.

Parameters:

Name	Type	Description	Default
`file_path`	`str or Path`	Path to YAML configuration file.	required

Returns:

Type	Description
`PIDConfig`	PID configuration object.

from_dict `classmethod` ¶

from_dict(config_dict: dict) -> PIDConfig

Create PIDConfig from dictionary.

Parameters:

Name	Type	Description	Default
`config_dict`	`dict`	Dictionary with PID parameters.	required

Returns:

Type	Description
`PIDConfig`	PID configuration object.

to_dict ¶

to_dict() -> dict

Convert configuration to dictionary.

Returns:

Type	Description
`dict`	Configuration as dictionary.

get_output_limits ¶

get_output_limits() -> tuple[float, float]

Get output limits as tuple.

get_integral_limits ¶

get_integral_limits() -> tuple[float, float]

Get integral limits as tuple.

PIDController ¶

PIDController(kp: float = 0.0, ki: float = 0.0, kd: float = 0.0, setpoint: float = 0.0, output_limits: tuple[float, float] = (-1.0, 1.0), integral_limits: tuple[float, float] = (-1.0, 1.0), output_deadband: float = 0.0)

PID Controller with anti-windup and output limits.

Initialize PID controller.

Parameters:

Name	Type	Description	Default
`kp`	`float`	Proportional gain.	`0.0`
`ki`	`float`	Integral gain.	`0.0`
`kd`	`float`	Derivative gain.	`0.0`
`setpoint`	`float`	Desired target value.	`0.0`
`output_limits`	`tuple[float, float]`	Min and max output values (min, max).	`(-1.0, 1.0)`
`integral_limits`	`tuple[float, float]`	Min and max integral term values for anti-windup (min, max).	`(-1.0, 1.0)`
`output_deadband`	`float`	Symmetric deadband applied to the final output. Suppresses sub-noise commands that would otherwise be sent to the actuator and cause hover micro-jitter. Set to 0 to disable.	`0.0`

update ¶

update(current_value: float) -> float

Update PID controller with current value.

Parameters:

Name	Type	Description	Default
`current_value`	`float`	Current measured value.	required

Returns:

Type	Description
`float`	Control effort output.

reset ¶

reset()

Reset PID controller internal state.

set_setpoint ¶

set_setpoint(setpoint: float)

Set new setpoint.

Parameters:

Name	Type	Description	Default
`setpoint`	`float`	New target value.	required

tune ¶

tune(kp: float, ki: float, kd: float)

Update PID gains.

Parameters:

Name	Type	Description	Default
`kp`	`float`	Proportional gain.	required
`ki`	`float`	Integral gain.	required
`kd`	`float`	Derivative gain.	required

get_components ¶

get_components() -> dict

Get individual PID components for debugging.

Returns:

Type	Description
`dict`	Dictionary with P, I, D components and output.

PositionPIDConfig `dataclass` ¶

PositionPIDConfig(x: PIDConfig = PIDConfig(), y: PIDConfig = PIDConfig(), z: PIDConfig = PIDConfig(), yaw: PIDConfig = PIDConfig())

Configuration for position controller PIDs (X, Y, Z, Yaw axes).

from_yaml `classmethod` ¶

from_yaml(file_path: str | Path) -> PositionPIDConfig

Load position PID configuration from YAML file.

Parameters:

Name	Type	Description	Default
`file_path`	`str or Path`	Path to YAML configuration file.	required

Returns:

Type	Description
`PositionPIDConfig`	Position PID configuration object.

to_dict ¶

to_dict() -> dict

Convert configuration to dictionary.

Px4SetpointConfig `dataclass` ¶

Px4SetpointConfig(speed: float = 5.0, vel_max: float = 12.0, speed_up: float = 3.0, speed_down: float = 1.5, accel: float = 3.0, accel_up: float = 4.0, accel_down: float = 3.0, jerk: float = 4.0, yaw_rate: float = 45.0, takeoff_speed: float = 1.5)

Bases: SetpointConfig

Configuration for PX4 setpoint navigation (MPC_* parameters).

All values in SI units (m/s, m/s/s, m/s³) except yaw_rate (deg/s, to match PX4's MPC_YAWRAUTO_MAX). Unlike ArduPilot there is no GUID_OPTIONS/arrival-radius equivalent — PX4 offboard arrival is judged by the SDK navigator, so only kinematic limits are configured here.

Parameters:

Name	Type	Description	Default
`speed`	`float`	Desired horizontal cruise speed in m/s (maps to `MPC_XY_CRUISE`).	`5.0`
`vel_max`	`float`	Maximum horizontal speed in m/s (maps to `MPC_XY_VEL_MAX`, the hard saturation). Raised to at least `speed` so the cruise is never capped.	`12.0`
`speed_up`	`float`	Maximum climb speed in m/s (maps to `MPC_Z_VEL_MAX_UP`).	`3.0`
`speed_down`	`float`	Maximum descent speed in m/s (maps to `MPC_Z_VEL_MAX_DN`).	`1.5`
`accel`	`float`	Horizontal acceleration in m/s/s (maps to `MPC_ACC_HOR`).	`3.0`
`accel_up`	`float`	Maximum upward acceleration in m/s/s (maps to `MPC_ACC_UP_MAX`).	`4.0`
`accel_down`	`float`	Maximum downward acceleration in m/s/s (maps to `MPC_ACC_DOWN_MAX`).	`3.0`
`jerk`	`float`	Auto-mode jerk limit in m/s³ (maps to `MPC_JERK_AUTO`). Controls the smoothness of the jerk-limited trajectory generator.	`4.0`
`yaw_rate`	`float`	Maximum auto yaw rate in deg/s (maps to `MPC_YAWRAUTO_MAX`).	`45.0`
`takeoff_speed`	`float`	Takeoff climb speed in m/s (maps to `MPC_TKO_SPEED`).	`1.5`

to_fcu_params ¶

to_fcu_params() -> dict

Return PX4 parameter names and values in FCU units.

PX4 parameters are already in SI units, so values pass through directly (yaw_rate stays in deg/s). MPC_XY_VEL_MAX is raised to at least the cruise speed so the cruise is never clamped by the cap.

SetpointConfig `dataclass` ¶

SetpointConfig()

Bases: ABC

Firmware-agnostic setpoint-navigation configuration base.

Subclasses declare SI-unit fields (m/s, m/s/s, m/s³), a _RANGES map of field -> (min, max) used to clamp values in :meth:__post_init__, an optional PARAM_ALIASES map (primary FCU name -> firmware alias), and implement :meth:to_fcu_params.

to_fcu_params `abstractmethod` ¶

to_fcu_params() -> Dict[str, Union[int, float]]

Return autopilot parameter name -> value in FCU units.

from_yaml `classmethod` ¶

from_yaml(file_path: Union[str, Path]) -> SetpointConfig

Load configuration from a YAML mapping file.

Raises:

Type	Description
`ValueError`	If the YAML content is not a mapping.

from_dict `classmethod` ¶

from_dict(config_dict: dict) -> SetpointConfig

Create from a dict, ignoring keys that are not declared fields.

to_dict ¶

to_dict() -> dict

Serialize the configuration fields to a plain dict.

DistanceReading `dataclass` ¶

DistanceReading(distance: float = 0.0, orientation: SensorOrientation = OTHER, min_distance: float = 0.0, max_distance: float = 0.0, sensor_id: int = 0, sensor_type: int = 0, signal_quality: Optional[int] = None, raw_orientation: int = 0, timestamp: float = 0.0)

A single distance-sensor measurement reported by the FCU.

Parameters:

Name	Type	Description	Default
`distance`	`float`	Measured distance in meters.	`0.0`
`orientation`	`SensorOrientation`	Direction the sensor faces in the body frame.	`OTHER`
`min_distance`	`float`	Sensor range limits in meters.	`0.0`
`max_distance`	`float`	Sensor range limits in meters.	`0.0`
`sensor_id`	`int`	MAVLink sensor id; the key under which the reading is stored.	`0`
`sensor_type`	`int`	`MAV_DISTANCE_SENSOR <https://mavlink.io/en/messages/common.html#MAV_DISTANCE_SENSOR>`_ kind (laser, ultrasound, ...).	`0`
`signal_quality`	`int`	Quality 0-100, or `None` when the source does not report it.	`None`
`raw_orientation`	`int`	Original MAV_SENSOR_ORIENTATION value (useful when `OTHER`).	`0`
`timestamp`	`float`	Monotonic seconds when the reading was received.	`0.0`

SensorOrientation ¶

Bases: Enum

Mounting direction of a distance sensor in the body frame.

Mirrors the subset of MAV_SENSOR_ORIENTATION <https://mavlink.io/en/messages/common.html#MAV_SENSOR_ORIENTATION>_ that ArduPilot reports for rangefinders and proximity sectors. Yaw values are measured clockwise from forward (0 = forward, 90 = right). OTHER covers any value outside this set.

from_mavlink `classmethod` ¶

from_mavlink(value: int) -> SensorOrientation

Map a raw MAV_SENSOR_ORIENTATION value, falling back to OTHER.

BebopDrone ¶

BebopDrone(config: BebopConfig, executor: Optional[Executor] = None)

Bases: BaseDrone

Parrot Bebop 2 drone implementation.

Parameters:

Name	Type	Description	Default
`config`	`BebopConfig`	Bebop-specific configuration.	required
`executor`	`Executor`	ROS 2 executor to register this drone's node with. Defaults to the shared :mod:`nectar.runtime` executor.	`None`

capabilities `property` ¶

capabilities: frozenset[Capability]

Movement and control features supported by the Bebop.

Body-frame velocity (cmd_vel) and autopilot-native return-to-home. No position control, parameters, GPS, or companion navigation.

from_config `classmethod` ¶

from_config(config: DroneConfig, executor: Optional[Executor] = None) -> BebopDrone

Factory entry point for :class:DroneFactory.

connect ¶

connect() -> bool

Check Bebop driver connection status.

Returns:

Type	Description
`bool`	True if the bebop_driver node is running.

disconnect ¶

disconnect() -> None

Disconnect and cleanup resources.

arm ¶

arm() -> bool

Arm motors (no-op for Bebop).

Bebop arms automatically on takeoff.

Returns:

Type	Description
`bool`	Always True.

disarm ¶

disarm() -> bool

Force disarm motors via emergency stop.

Returns:

Type	Description
`bool`	True if command sent.

takeoff ¶

takeoff(altitude: float) -> bool

Execute takeoff.

Parameters:

Name	Type	Description	Default
`altitude`	`float`	Target altitude in meters (ignored by Bebop, uses default hover altitude).	required

Returns:

Type	Description
`bool`	True if takeoff command sent.

land ¶

land(timeout: float = 30.0) -> bool

Execute landing at current position.

Parameters:

Name	Type	Description	Default
`timeout`	`float`	Maximum time for operation (unused, Bebop lands asynchronously).	`30.0`

Returns:

Type	Description
`bool`	True if land command sent.

move_velocity ¶

move_velocity(vx: float = 0.0, vy: float = 0.0, vz: float = 0.0, vyaw: float = 0.0, duration: Optional[float] = None, reference: MoveReference = BODY) -> None

Command velocity-based movement.

Bebop uses normalized velocities (-1.0 to 1.0). Values are clamped.

Parameters:

Name	Type	Description	Default
`vx`	`float`	Forward/backward velocity (-1.0 to 1.0).	`0.0`
`vy`	`float`	Left/right velocity (-1.0 to 1.0).	`0.0`
`vz`	`float`	Up/down velocity (-1.0 to 1.0).	`0.0`
`vyaw`	`float`	Yaw rotation velocity (-1.0 to 1.0).	`0.0`
`duration`	`float`	If specified, sends command for this duration.	`None`
`reference`	`MoveReference`	Reference frame (only BODY supported, others ignored).	`BODY`

Notes

Bebop only supports BODY frame. WORLD and TAKEOFF references are ignored.

emergency_stop ¶

emergency_stop() -> None

Execute emergency stop (immediate motor shutdown).

flip ¶

flip(direction: int) -> None

Execute acrobatic flip maneuver.

Parameters:

Name	Type	Description	Default
`direction`	`int`	Flip direction: 0=Front, 1=Back, 2=Right, 3=Left.	required

camera_control ¶

camera_control(tilt: float, pan: float) -> None

Control camera gimbal.

Parameters:

Name	Type	Description	Default
`tilt`	`float`	Tilt angle in degrees (positive=down, negative=up).	required
`pan`	`float`	Pan angle in degrees (positive=left, negative=right).	required

snapshot ¶

snapshot() -> None

Capture photo with onboard camera.

flat_trim ¶

flat_trim() -> None

Calibrate IMU.

Drone must be on flat, level surface before calling.

CrazyflieDrone ¶

CrazyflieDrone(config: CrazyflieConfig, executor: Optional[Executor] = None)

Bases: BaseDrone

Crazyflie 2.x drone implementation via Crazyswarm2.

Communicates with the Crazyflie through the crazyflie_server ROS 2 node, which handles radio communication, parameter syncing, and logging. Supports the high-level commander (takeoff, land, goTo) and streaming setpoints (cmdFullState, cmdPosition).

Parameters:

Name	Type	Description	Default
`config`	`CrazyflieConfig`	Crazyflie-specific configuration.	required
`executor`	`Executor`	ROS 2 executor to register this drone's node with. Defaults to the shared :mod:`nectar.runtime` executor.	`None`

capabilities `property` ¶

capabilities: frozenset[Capability]

Movement and control features supported by the Crazyflie.

Onboard local position control (move_to POSITION via goTo), body/world/takeoff velocity streaming, and firmware parameter access. No GPS, companion PID, vision pose, rangefinder, servo, or native RTL.

is_armed `property` ¶

is_armed: Optional[bool]

Check if motors are armed.

is_flying `property` ¶

is_flying: bool

Whether the Crazyflie is currently in flight.

is_tumbled `property` ¶

is_tumbled: bool

Whether the Crazyflie has detected a tumble (crash).

can_fly `property` ¶

can_fly: bool

Whether the Crazyflie is ready for flight commands.

battery_voltage `property` ¶

battery_voltage: Optional[float]

Battery voltage in volts.

rssi `property` ¶

rssi: Optional[int]

Radio signal strength indicator (dBm).

pose `property` ¶

pose: Optional[PoseStamped]

Current estimated pose from the Crazyflie's state estimator.

position `property` ¶

position: List[float]

Current position as [x, y, z] in meters.

height `property` ¶

height: float

Current height above ground in meters.

from_config `classmethod` ¶

from_config(config: DroneConfig, executor: Optional[Executor] = None) -> CrazyflieDrone

Factory entry point for :class:DroneFactory.

connect ¶

connect() -> bool

Verify connection to the Crazyflie via the server.

Waits for status messages to confirm the server is communicating with the Crazyflie hardware.

Returns:

Type	Description
`bool`	True if status messages are being received.

disconnect ¶

disconnect() -> None

Disconnect and cleanup resources.

arm ¶

arm() -> bool

Arm the Crazyflie.

For CF 2.1 (brushed), arming happens automatically on takeoff. For Bolt-based (brushless), this starts the motors.

Returns:

Type	Description
`bool`	True if arm command sent.

disarm ¶

disarm() -> bool

Disarm the Crazyflie.

Returns:

Type	Description
`bool`	True if disarm command sent.

takeoff ¶

takeoff(altitude: float, duration: Optional[float] = None, timeout: float = 30.0, precision: float = 0.12) -> bool

Execute takeoff to specified altitude.

Parameters:

Name	Type	Description	Default
`altitude`	`float`	Target height in meters (must be > 0).	required
`duration`	`float`	Time to reach target height in seconds. If None, estimated from altitude and default_velocity.	`None`
`timeout`	`float`	Maximum time to wait for altitude convergence.	`30.0`
`precision`	`float`	Altitude precision in meters. Takeoff succeeds when height >= altitude - precision.	`0.12`

Returns:

Type	Description
`bool`	True if takeoff command sent and altitude reached.

land ¶

land(timeout: float = 30.0, duration: Optional[float] = None) -> bool

Execute landing at current position.

Parameters:

Name	Type	Description	Default
`timeout`	`float`	Maximum time for operation in seconds.	`30.0`
`duration`	`float`	Time for descent in seconds. If None, estimated from current height and default_velocity.	`None`

Returns:

Type	Description
`bool`	True if landing completed (height near ground).

move_velocity ¶

move_velocity(vx: float = 0.0, vy: float = 0.0, vz: float = 0.0, vyaw: float = 0.0, duration: Optional[float] = None, reference: MoveReference = BODY) -> None

Command velocity-based movement via full-state streaming setpoints.

Publishes to cmd_full_state with the desired velocity. Switches the Crazyflie to low-level streaming mode. Call notify_setpoints_stop() before using high-level commands (takeoff, land, goTo) again.

Parameters:

Name	Type	Description	Default
`vx`	`float(m / s)`	Forward (+) / backward (-) velocity.	`0.0`
`vy`	`float(m / s)`	Left (+) / right (-) velocity.	`0.0`
`vz`	`float(m / s)`	Up (+) / down (-) velocity.	`0.0`
`vyaw`	`float(rad / s)`	Yaw rate. Counter-clockwise positive.	`0.0`
`duration`	`float(s)`	If specified, sends commands for this duration at ~50Hz. If None, publishes a single command.	`None`
`reference`	`MoveReference`	BODY: velocities relative to current heading. TAKEOFF: velocities in takeoff heading frame. WORLD: velocities in world frame.	`BODY`

move_to ¶

move_to(x: Optional[float] = None, y: Optional[float] = None, z: Optional[float] = None, yaw: Optional[float] = None, reference: MoveReference = BODY, timeout: Optional[float] = 60.0, precision: float = 0.1, method: NavigationMethod = POSITION, altitude_source: AltitudeSource = AUTO) -> bool

Navigate to target position using the onboard high-level commander.

Uses the Crazyflie's goTo service which plans a smooth degree-7 polynomial trajectory from current state to target.

Coordinate semantics:

BODY: offsets relative to current position and heading. x/y=None disables that axis (no offset). z=None maintains current height. yaw is degrees relative to current heading.
TAKEOFF: offsets relative to takeoff position and heading. x/y=None preserves current position on that axis (does NOT go to takeoff position). z is absolute height above ground (z=None maintains current height, z <= 0 is rejected for safety). yaw is degrees relative to takeoff heading.
WORLD: absolute world-frame coordinates. None values preserve current position/yaw on that axis.

Parameters:

Name	Type	Description	Default
`x`	`float`	Forward (+) / backward (-) offset in meters.	`None`
`y`	`float`	Left (+) / right (-) offset in meters.	`None`
`z`	`float`	Up (+) / down (-) offset in meters (BODY) or absolute height (TAKEOFF).	`None`
`yaw`	`float`	Target yaw in degrees relative to reference heading. None maintains current yaw.	`None`
`reference`	`MoveReference`	Reference frame for movement.	`BODY`
`timeout`	`float`	Maximum time for navigation.	`60.0`
`precision`	`float`	Arrival threshold in meters.	`0.1`
`method`	`NavigationMethod`	Only POSITION is supported (onboard polynomial planner). PID, PID_EKF, POSITION_GLOBAL raise CapabilityNotSupportedError.	`POSITION`
`altitude_source`	`AltitudeSource`	Ignored -- Crazyflie uses fused ToF/flow altitude.	`AUTO`

Returns:

Type	Description
`bool`	True if target reached within precision.

Raises:

Type	Description
`TakeoffPositionNotSetError`	If reference=TAKEOFF but takeoff position not set.
`CapabilityNotSupportedError`	If method is not POSITION.

emergency_stop ¶

emergency_stop() -> None

Emergency stop. Cuts power and locks the Crazyflie.

After emergency stop, the Crazyflie must be physically rebooted. All future commands are ignored until reboot.

rtl ¶

rtl(altitude: Optional[float] = None, precision: float = 0.2, method: RTLMethod = NAVIGATE, land: bool = True) -> bool

Return to takeoff position.

Parameters:

Name	Type	Description	Default
`altitude`	`float`	Transit height in meters. If specified, adjusts height first.	`None`
`precision`	`float`	Arrival threshold in meters.	`0.2`
`method`	`RTLMethod`	Only NAVIGATE supported. NATIVE raises CapabilityNotSupportedError.	`NAVIGATE`
`land`	`bool`	Execute landing after reaching takeoff position.	`True`

Returns:

Type	Description
`bool`	True if RTL successful.

go_to ¶

go_to(goal: List[float], yaw: float, duration: float, relative: bool = False) -> None

Direct access to the Crazyflie goTo high-level command.

Plans a smooth polynomial trajectory to the goal position.

Parameters:

Name	Type	Description	Default
`goal`	`list of 3 floats`	Target position [x, y, z] in meters.	required
`yaw`	`float`	Target yaw angle in radians.	required
`duration`	`float`	Time to reach the goal in seconds.	required
`relative`	`bool`	If True, goal is relative to current position.	`False`

cmd_full_state ¶

cmd_full_state(pos: List[float], vel: List[float], acc: List[float], yaw: float, omega: List[float]) -> None

Send a streaming full-state setpoint.

Switches to low-level mode. Call notify_setpoints_stop() before using high-level commands again.

Parameters:

Name	Type	Description	Default
`pos`	`list of 3 floats`	Position [x, y, z] in meters.	required
`vel`	`list of 3 floats`	Velocity [vx, vy, vz] in m/s.	required
`acc`	`list of 3 floats`	Acceleration [ax, ay, az] in m/s^2.	required
`yaw`	`float`	Yaw angle in radians.	required
`omega`	`list of 3 floats`	Angular velocity [wx, wy, wz] in rad/s.	required

cmd_position ¶

cmd_position(pos: List[float], yaw: float = 0.0) -> None

Send a streaming position setpoint.

Switches to low-level mode. Call notify_setpoints_stop() before using high-level commands again.

Parameters:

Name	Type	Description	Default
`pos`	`list of 3 floats`	Position [x, y, z] in meters.	required
`yaw`	`float`	Yaw angle in radians.	`0.0`

notify_setpoints_stop ¶

notify_setpoints_stop(remain_valid_ms: int = 100) -> None

Signal end of streaming setpoints.

Must be called after streaming commands (cmd_full_state, cmd_position, move_velocity) and before using high-level commands (takeoff, land, move_to, go_to).

Parameters:

Name	Type	Description	Default
`remain_valid_ms`	`int`	Milliseconds the last setpoint remains valid.	`100`

upload_trajectory ¶

upload_trajectory(trajectory_id: int, pieces: list) -> None

Upload a piecewise polynomial trajectory.

Parameters:

Name	Type	Description	Default
`trajectory_id`	`int`	ID number for this trajectory.	required
`pieces`	`list`	List of TrajectoryPolynomialPiece messages.	required

start_trajectory ¶

start_trajectory(trajectory_id: int, timescale: float = 1.0, reverse: bool = False, relative: bool = True) -> None

Begin executing a previously uploaded trajectory.

Parameters:

Name	Type	Description	Default
`trajectory_id`	`int`	ID number from upload_trajectory().	required
`timescale`	`float`	Duration scale factor (2.0 = twice as slow).	`1.0`
`reverse`	`bool`	Execute trajectory backwards in time.	`False`
`relative`	`bool`	Shift trajectory to begin at current position.	`True`

set_firmware_param ¶

set_firmware_param(name: str, value) -> None

Set a Crazyflie firmware parameter via the server.

Parameters:

Name	Type	Description	Default
`name`	`str`	Parameter name (e.g., "stabilizer.controller", "ring.effect").	required
`value`	`int or float`	Parameter value.	required

get_firmware_param ¶

get_firmware_param(name: str)

Get a Crazyflie firmware parameter value.

Parameters:

Name	Type	Description	Default
`name`	`str`	Parameter name (e.g., "stabilizer.controller").	required

Returns:

Type	Description
`int or float or None`	Parameter value, or None on failure.

set_group_mask ¶

set_group_mask(group_mask: int) -> None

Set group mask for broadcast commands (swarm coordination).

Parameters:

Name	Type	Description	Default
`group_mask`	`int`	8-bit bitmask for group membership (0 = respond to all broadcasts).	required

MavlinkConnection ¶

MavlinkConnection(*, source_system: int = 1, source_component: int = MAV_COMP_ID_ONBOARD_COMPUTER, heartbeat_timeout: float = 30.0)

Thin wrapper around pymavlink.mavutil.mavlink_connection.

The connection string and baud rate are passed to :meth:connect, not the constructor.

Parameters:

Name	Type	Description	Default
`source_system`	`int`	MAVLink system ID this connection presents itself as. Default 1 (same system as the FCU; ArduPilot accepts companion-computer messages from the same system ID).	`1`
`source_component`	`int`	MAVLink component ID. Default `MAV_COMP_ID_ONBOARD_COMPUTER` (191), the ArduPilot convention for companion computers.	`MAV_COMP_ID_ONBOARD_COMPUTER`
`heartbeat_timeout`	`float`	Maximum seconds to wait for the first FCU heartbeat during :meth:`connect`. Default 30.	`30.0`

Attributes:

Name	Type	Description
`master`	`mavfile`	Underlying pymavlink connection. Use `master.mav.<message>_send(...)` to transmit. `None` until :meth:`connect` succeeds.

Notes

A single endpoint must have one RX reader (only the owning transport calls recv_match) but may have many senders (setpoints, heartbeat, rangefinder, vision bridge). pymavlink's mav.*_send is not thread-safe, so every sender must serialize through :attr:send_lock.

send_lock `property` ¶

send_lock: Lock

Mutex serializing all transmits on this endpoint.

is_connected `property` ¶

is_connected: bool

Whether the heartbeat handshake completed.

connect ¶

connect(device: str, baud: int = 921600) -> None

Open the MAVLink endpoint and complete the heartbeat handshake.

Blocks until the first non-GCS heartbeat arrives or until heartbeat_timeout elapses.

Parameters:

Name	Type	Description	Default
`device`	`str`	Connection string. Both `tcp:host:port` (pymavlink) and `tcp://host:port` (URL form) are accepted; serial uses a device path such as `/dev/ttyUSB0`.	required
`baud`	`int`	Serial baud rate. Ignored for non-serial connections.	`921600`

Raises:

Type	Description
`TimeoutError`	If no FCU heartbeat is received within `heartbeat_timeout`.

close ¶

close() -> None

Close the underlying pymavlink connection.

MavlinkDrone ¶

MavlinkDrone(config: MavlinkConfig, executor: Optional[Executor] = None, connection: Optional[MavlinkConnection] = None)

Bases: ArduPilotDrone

Direct-pymavlink ArduPilot drone.

Parameters:

Name	Type	Description	Default
`config`	`MavlinkConfig`	MAVLink-specific configuration (pymavlink connection string, baud, ...).	required
`executor`	`Executor`	ROS 2 executor to register this drone's node with. Defaults to the shared :mod:`nectar.runtime` executor.	`None`
`connection`	`MavlinkConnection`	Pre-built endpoint to share (e.g. when a rangefinder publisher already owns the link). When `None`, the transport builds one from `config`.	`None`

connection `property` ¶

connection: MavlinkConnection

The underlying MAVLink endpoint (shareable with sensor publishers).

from_config `classmethod` ¶

from_config(config: DroneConfig, executor: Optional[Executor] = None) -> MavlinkDrone

Factory entry point for :class:DroneFactory.

MavrosDrone ¶

MavrosDrone(config: MavrosConfig, executor: Optional[Executor] = None)

Bases: ArduPilotDrone

MAVROS drone implementation for ArduPilot/PX4 flight controllers.

Parameters:

Name	Type	Description	Default
`config`	`MavrosConfig`	MAVROS-specific configuration.	required
`executor`	`Executor`	ROS 2 executor to register this drone's node with. Defaults to the shared :mod:`nectar.runtime` executor.	`None`

from_config `classmethod` ¶

from_config(config: DroneConfig, executor: Optional[Executor] = None) -> MavrosDrone

Factory entry point for :class:DroneFactory.

DepthObstacleDetector ¶

DepthObstacleDetector(min_distance_mm: float = 100, max_distance_mm: float = 1500, cluster_eps: float = 20, cluster_min_samples: int = 20, min_cluster_pixels: int = 50, depth_threshold_mm: float = 1300, color_topic: str = '/camera/color/image_raw', depth_topic: str = '/camera/depth/image_rect_raw')

Bases: BaseObstacleDetector

RealSense D435i depth camera obstacle detector using DBSCAN clustering.

Processes depth frames to identify obstacle clusters, determines direction (LEFT, RIGHT, FRONT) from cluster position relative to image center, and returns the closest obstacle distance.

The internal :class:ImageHandler owns its own ROS 2 node, registered with :mod:nectar.runtime.

Parameters:

Name	Type	Description	Default
`min_distance_mm`	`float`	Valid depth range. Pixels outside are ignored.	`100`
`max_distance_mm`	`float`	Valid depth range. Pixels outside are ignored.	`100`
`cluster_eps`	`float`	DBSCAN clustering parameters.	`20`
`cluster_min_samples`	`float`	DBSCAN clustering parameters.	`20`
`min_cluster_pixels`	`int`	Minimum total valid pixels to attempt clustering.	`50`
`depth_threshold_mm`	`float`	Maximum cluster mean depth to consider as obstacle.	`1300`
`color_topic`	`str`	RealSense color and aligned-depth topics.	`'/camera/color/image_raw'`
`depth_topic`	`str`	RealSense color and aligned-depth topics.	`'/camera/color/image_raw'`

detection_event `property` ¶

detection_event: Event

Threading event set when obstacle detected, cleared when path clear.

Px4DdsDrone ¶

Px4DdsDrone(config: Px4DdsConfig, executor: Optional[Executor] = None)

Bases: Px4Drone

PX4 drone over the native uXRCE-DDS bridge.

Parameters:

Name	Type	Description	Default
`config`	`Px4DdsConfig`	PX4/uXRCE-DDS-specific configuration.	required
`executor`	`Executor`	ROS 2 executor to register this drone's node with. Defaults to the shared :mod:`nectar.runtime` executor.	`None`

from_config `classmethod` ¶

from_config(config: DroneConfig, executor: Optional[Executor] = None) -> Px4DdsDrone

Factory entry point for :class:DroneFactory.

Px4MavlinkDrone ¶

Px4MavlinkDrone(config: Px4MavlinkConfig, executor: Optional[Executor] = None, connection: Optional[MavlinkConnection] = None)

Bases: Px4Drone

PX4 drone over a direct pymavlink.

connection `property` ¶

connection: MavlinkConnection

The underlying MAVLink endpoint (shareable with sensor publishers).

from_config `classmethod` ¶

from_config(config: DroneConfig, executor: Optional[Executor] = None) -> Px4MavlinkDrone

Factory entry point for :class:DroneFactory.

Px4MavrosDrone ¶

Px4MavrosDrone(config: Px4MavrosConfig, executor: Optional[Executor] = None)

Bases: Px4Drone

PX4 drone implementation over MAVROS.

Parameters:

Name	Type	Description	Default
`config`	`Px4MavrosConfig`	PX4/MAVROS-specific configuration.	required
`executor`	`Executor`	ROS 2 executor to register this drone's node with. Defaults to the shared :mod:`nectar.runtime` executor.	`None`

from_config `classmethod` ¶

from_config(config: DroneConfig, executor: Optional[Executor] = None) -> Px4MavrosDrone

Factory entry point for :class:DroneFactory.

VehicleDrone ¶

VehicleDrone(config: DroneConfig, transport: VehicleTransport, executor: Optional[Executor] = None)

Bases: BaseDrone

Firmware-agnostic multicopter drone implementing shared flight behavior.

Holds navigation, takeoff/land sequencing, PID/setpoint movement, GPS handling, and telemetry access common to every FCU. Firmware-specific behavior (arm sequence, flight-mode names, native RTL, setpoint parameters) is delegated to overridable hooks implemented by :class:~nectar.control.ardupilot.drone.ArduPilotDrone and :class:~nectar.control.px4.drone.Px4Drone.

Parameters:

Name	Type	Description	Default
`config`	`DroneConfig`	Configuration; subclasses pass the firmware/transport-specific config.	required
`transport`	`VehicleTransport`	Concrete transport (constructed by the subclass).	required
`executor`	`Executor`	ROS 2 executor to register this drone's node with.	`None`

capabilities `abstractmethod` `property` ¶

capabilities: frozenset[Capability]

Set of features this drone supports (declared per firmware).

is_indoor `property` ¶

is_indoor: bool

True if configured for vision-based indoor navigation.

is_armed `property` ¶

is_armed: Optional[bool]

Check if motors are armed.

flight_mode `property` ¶

flight_mode: Optional[str]

Current FCU flight mode (firmware-specific name).

is_fcu_connected `property` ¶

is_fcu_connected: Optional[bool]

Check if FCU link is up.

gps `property` ¶

gps: GeoPoint

GPS fix as a plain :class:GeoPoint.

Raises:

Type	Description
`SensorNotAvailableError`	If pose_source is VISION (indoor mode).

heading `property` ¶

heading: float

Compass heading in degrees.

Raises:

Type	Description
`SensorNotAvailableError`	If pose_source is VISION (indoor mode).

rel_alt `property` ¶

rel_alt: float

Relative altitude above home position.

Raises:

Type	Description
`SensorNotAvailableError`	If pose_source is VISION (indoor mode).

vision_pose `property` ¶

vision_pose: Optional[LocalPose]

Vision-based pose estimate (ENU) as a plain :class:LocalPose.

local_pose `property` ¶

local_pose: Optional[LocalPose]

EKF-fused local position (ENU) as a plain :class:LocalPose.

lidar_available `property` ¶

lidar_available: bool

Whether rangefinder data has been received.

pid_config `property` ¶

pid_config: Optional[PositionPIDConfig]

Current PID configuration for position control.

setpoint_config `property` ¶

setpoint_config: Optional[SetpointConfig]

Current setpoint navigation configuration, or None if unsupported.

distance_sensors `property` ¶

distance_sensors: Dict[int, DistanceReading]

All distance-sensor readings the FCU reports, keyed by sensor id.

Covers every orientation (forward, the yaw sectors, up, down) and id, for obstacle detection, redundancy, or verification. The downward sensor used for altitude is also available through :meth:get_altitude with AltitudeSource.LIDAR.

position `property` ¶

position: Union[LocalPose, GeoPoint]

Current position: vision pose (indoor) or GPS (outdoor).

position_as_target `property` ¶

position_as_target: Optional[Union[LocalTarget, GlobalTarget]]

Current position converted to a plain setpoint target.

arm `abstractmethod` ¶

arm() -> bool

Arm the motors in the firmware's offboard/guided control mode.

get_altitude ¶

get_altitude(source: AltitudeSource = AUTO) -> Optional[float]

Get altitude from a specific sensor source.

Parameters:

Name	Type	Description	Default
`source`	`AltitudeSource`	Sensor source to read altitude from: AUTO: best available (lidar > vision Z > relative altitude). LIDAR: lidar rangefinder reading. VISION: vision pose Z component. REL_ALT: GPS-based relative altitude.	`AUTO`

Returns:

Type	Description
`float or None`	Altitude in meters, or None if the requested source is unavailable.

get_distance ¶

get_distance(orientation: SensorOrientation) -> Optional[DistanceReading]

Most recent reading facing orientation, or None if none.

When several sensors share an orientation, the latest one is returned.

connect ¶

connect() -> bool

Wait for the FCU link to come up (up to sensor_timeout).

disconnect ¶

disconnect() -> None

Disconnect and cleanup resources.

cleanup ¶

cleanup() -> None

Close the transport, then tear down ROS resources.

disarm ¶

disarm() -> bool

Force disarm motors.

Sends MAV_CMD_COMPONENT_ARM_DISARM (400) with the force flag (param2=21196) to bypass safety checks.

Returns:

Type	Description
`bool`	True if disarming successful, False on failure or timeout.

takeoff ¶

takeoff(altitude: float, max_retries: int = 2, adjust_altitude: bool = True, precision: float = 0.12, timeout: float = 25.0) -> bool

Execute takeoff with event-driven completion detection.

Per attempt: arm (state-polled) -> spin-up delay -> set takeoff position (first attempt) -> takeoff command -> wait for liftoff and altitude settling -> optional altitude adjustment. Skips entirely if already airborne. Retries only on failed liftoff.

Parameters:

Name	Type	Description	Default
`altitude`	`float`	Target altitude in meters.	required
`max_retries`	`int`	Maximum number of takeoff attempts.	`2`
`adjust_altitude`	`bool`	If True, fine-tune altitude using move_to after settling.	`True`
`precision`	`float`	Altitude precision in meters for adjustment.	`0.12`
`timeout`	`float`	Maximum seconds to wait for altitude settling and for adjustment.	`25.0`

Returns:

Type	Description
`bool`	True if takeoff successful, False if all retries exhausted.

land ¶

land(timeout: float = 60.0) -> bool

Execute landing at current position.

Sends the land command and waits for touchdown (descent velocity has settled) or full disarm, whichever happens first. Returning on touchdown avoids blocking for ArduPilot's DISARM_DELAY.

Parameters:

Name	Type	Description	Default
`timeout`	`float`	Maximum time to wait for landing completion. Defaults are generous for slow SITL descents; real drones return early.	`60.0`

Returns:

Type	Description
`bool`	True on touchdown or disarm, False on command failure or timeout.

publish_setpoint ¶

publish_setpoint(target: Union[LocalTarget, GlobalTarget]) -> None

Send a navigation target to the transport's setpoint egress.

move_velocity ¶

move_velocity(vx: float = 0.0, vy: float = 0.0, vz: float = 0.0, vyaw: float = 0.0, duration: Optional[float] = None, reference: MoveReference = BODY) -> None

Move the drone by sending velocity commands.

Parameters:

Name	Type	Description	Default
`vx`	`float(m / s)`	BODY/TAKEOFF: forward (+) / backward (-). WORLD: east (+) / west (-).	`0.0`
`vy`	`float(m / s)`	BODY/TAKEOFF: left (+) / right (-). WORLD: north (+) / south (-).	`0.0`
`vz`	`float(m / s)`	Up (+) / down (-).	`0.0`
`vyaw`	`float(rad / s)`	Counter-clockwise (+) / clockwise (-).	`0.0`
`duration`	`float(s)`	Movement time. If None, publishes a single command (continuous mode, caller must re-publish).	`None`
`reference`	`MoveReference`	Velocity reference frame: BODY: heading-relative (FLU: vx=forward, vy=left, vz=up). Sent in the BODY frame; the transport converts FLU to FRD. WORLD: absolute directions (ENU: vx=east, vy=north, vz=up). Sent in the LOCAL frame; the transport converts ENU to NED. TAKEOFF: velocities in the takeoff heading, rotated into the current body frame. Requires the takeoff position to be set.	`BODY`

Raises:

Type	Description
`TakeoffPositionNotSetError`	If reference=TAKEOFF but the takeoff position is not set.
`SensorNotAvailableError`	If required position sensors are not available.

move_to ¶

move_to(x: Optional[float] = None, y: Optional[float] = None, z: Optional[float] = None, yaw: Optional[float] = None, reference: MoveReference = BODY, timeout: Optional[float] = 60.0, precision: float = 0.2, method: NavigationMethod = PID_EKF, altitude_source: AltitudeSource = AUTO) -> bool

Move the drone to a position relative to its current location and heading.

Parameters:

Name	Type	Description	Default
`x`	`float`	Forward (+) / backward (-) in meters. For PID methods, None disables X-axis control; for POSITION methods, None means zero offset.	`None`
`y`	`float`	Left (+) / right (-) in meters. For PID methods, None disables Y-axis control; for POSITION methods, None means zero offset.	`None`
`z`	`float`	Up (+) / down (-) in meters. For PID methods, None disables altitude control; for POSITION methods, None means zero offset.	`None`
`yaw`	`float`	Yaw angle in degrees. None maintains the current yaw.	`None`
`reference`	`MoveReference`	BODY: relative to current position/heading. TAKEOFF: absolute from the takeoff position/heading.	`BODY`
`timeout`	`float`	Maximum navigation time in seconds.	`60.0`
`precision`	`float`	Arrival threshold in meters.	`0.2`
`method`	`NavigationMethod`	PID_EKF: companion-side velocity PID with EKF-fused position. PID: companion-side velocity PID with raw sensors (vision/GPS). POSITION: onboard position controller (local setpoint). POSITION_GLOBAL: onboard GPS position controller (outdoor only).	`PID_EKF`
`altitude_source`	`AltitudeSource`	Altitude source for PID navigation: AUTO: best available (lidar > vision Z > relative altitude). LIDAR: rangefinder for ground-relative altitude. With BODY reference z is a relative offset from the current lidar reading; with TAKEOFF reference z is absolute altitude above ground.	`AUTO`

Returns:

Type	Description
`bool`	True if the target is reached within precision.

Raises:

Type	Description
`TakeoffPositionNotSetError`	If reference=TAKEOFF but the takeoff position is not set.
`CapabilityNotSupportedError`	If reference=WORLD, or POSITION_GLOBAL indoors.
`SensorNotAvailableError`	If required position or altitude sensors are not available.

move_to_gps ¶

move_to_gps(latitude: float, longitude: float, altitude: Optional[float] = None, heading: Optional[float] = None, timeout: Optional[float] = 60.0, precision: float = 0.5, method: NavigationMethod = PID) -> bool

Move the drone to a GPS coordinate.

Parameters:

Name	Type	Description	Default
`latitude`	`float`	Target latitude in degrees (WGS84).	required
`longitude`	`float`	Target longitude in degrees (WGS84).	required
`altitude`	`float`	Target altitude above ground in meters (relative). None keeps current.	`None`
`heading`	`float`	Heading in degrees (0=North). None keeps current.	`None`
`timeout`	`float`	Maximum navigation time in seconds.	`60.0`
`precision`	`float`	Arrival threshold in meters.	`0.5`
`method`	`NavigationMethod`	PID: companion-side velocity PID with raw GPS. PID_EKF: companion-side velocity PID with EKF local position. POSITION_GLOBAL: onboard GPS position controller.	`PID`

Returns:

Type	Description
`bool`	True if the target is reached within precision.

Raises:

Type	Description
`CapabilityNotSupportedError`	If indoor mode, or POSITION (local) is used with GPS coordinates.

set_takeoff_position ¶

set_takeoff_position(pose: Optional[Union[LocalPose, GeoPoint, LocalTarget, GlobalTarget]] = None, heading: Optional[float] = None) -> None

Manually set the takeoff position for TAKEOFF reference frame and RTL.

Parameters:

Name	Type	Description	Default
`pose`	`LocalPose \| GeoPoint \| LocalTarget \| GlobalTarget`	Position to use. If None, uses the current position.	`None`
`heading`	`float`	Heading in degrees. Required if `pose` is a :class:`GeoPoint`.	`None`

Raises:

Type	Description
`ValueError`	If the pose type is not supported.

set_pid_config ¶

set_pid_config(config) -> None

Update PID configuration.

Parameters:

Name	Type	Description	Default
`config`	`str \| dict \| PositionPIDConfig`	YAML file path, configuration dictionary, or PositionPIDConfig.	required

Raises:

Type	Description
`TypeError`	If the config type is not supported.

set_setpoint_config ¶

set_setpoint_config(config, apply: bool = True) -> None

Update setpoint navigation configuration.

When apply=True (default) the parameters are pushed to the FCU via set_param (persisted to the autopilot's storage). Use apply=False to update the SDK-side config only.

Parameters:

Name	Type	Description	Default
`config`	`str \| Path \| dict \| SetpointConfig`	YAML file path, configuration dictionary, or a setpoint config of this firmware's type.	required
`apply`	`bool`	If True, push the parameters to the FCU.	`True`

Raises:

Type	Description
`CapabilityNotSupportedError`	If this firmware exposes no setpoint configuration.
`TypeError`	If the config type is not supported.

emergency_stop ¶

emergency_stop() -> None

Execute emergency stop via force disarm.

set_home ¶

set_home() -> bool

Set the current GPS position as home.

Returns:

Type	Description
`bool`	True if the home position was set, False on failure or timeout.

set_mode ¶

set_mode(mode: str) -> bool

Set the FCU flight mode.

Parameters:

Name	Type	Description	Default
`mode`	`str`	Flight mode name (e.g. 'GUIDED', 'STABILIZE', 'LOITER', 'RTL', 'LAND').	required

Returns:

Type	Description
`bool`	True only once the FCU reports the requested mode. False if the transport rejects the request or the mode is not confirmed within the timeout.

set_param ¶

set_param(param_id: str, param_value: Union[int, float]) -> bool

Set an autopilot parameter.

Parameters:

Name	Type	Description	Default
`param_id`	`str`	Parameter name (e.g. 'RTL_ALT', 'WPNAV_SPEED', 'RTL_RETURN_ALT').	required
`param_value`	`int or float`	Parameter value. Integers are sent as int, floats as double.	required

Returns:

Type	Description
`bool`	True if the parameter was set, False on failure or timeout.

set_speed ¶

set_speed(speed: float, speed_type: str = 'horizontal') -> bool

Change the speed limit at runtime.

Updates the firmware's position-controller speed limit on the given axis. ArduPilot issues MAV_CMD_DO_CHANGE_SPEED (active immediately); PX4 updates the matching MPC_* parameter. See the firmware specializations for the exact semantics.

Parameters:

Name	Type	Description	Default
`speed`	`float`	Speed in m/s.	required
`speed_type`	`str`	Speed axis: "horizontal", "climb", or "descent".	`"horizontal"`

Returns:

Type	Description
`bool`	True if the change was accepted, False on failure or timeout.

set_actuator ¶

set_actuator(index: int, value: float, group: int = 0) -> bool

Drive a payload actuator output via MAV_CMD_DO_SET_ACTUATOR.

Firmware-neutral normalized actuator control: ArduPilot routes it to the servo output assigned the matching actuator function, PX4 to the Peripheral Actuator Set outputs (see the PX4 generic actuator control docs). Untargeted actuators are left unchanged (NaN).

Parameters:

Name	Type	Description	Default
`index`	`int`	Actuator number within the group, 1-6.	required
`value`	`float`	Normalized output in [-1, 1].	required
`group`	`int`	Actuator set/group index (param7); 0 = first set of 6 outputs.	`0`

Returns:

Type	Description
`bool`	True if the command was accepted, False on failure or timeout.

Raises:

Type	Description
`CapabilityNotSupportedError`	If the drone does not declare `Capability.ACTUATOR`.
`ValueError`	If `index` is outside 1-6.

set_gripper ¶

set_gripper(grab: bool, instance: int = 1) -> bool

Open or close a gripper via MAV_CMD_DO_GRIPPER.

Firmware-neutral gripper control supported by both ArduPilot (Gripper library) and PX4 (Gripper output function). Ideal for payload release (e.g. a hook): grab=False releases, grab=True grabs/holds.

Parameters:

Name	Type	Description	Default
`grab`	`bool`	True to grab/close, False to release/open.	required
`instance`	`int`	Gripper instance id.	`1`

Returns:

Type	Description
`bool`	True if the command was accepted, False on failure or timeout.

Raises:

Type	Description
`CapabilityNotSupportedError`	If the drone does not declare `Capability.GRIPPER`.

rtl ¶

rtl(altitude: Optional[float] = None, precision: float = 0.2, method: RTLMethod = NAVIGATE, land: bool = True) -> bool

Return to launch position.

Parameters:

Name	Type	Description	Default
`altitude`	`float`	Transit altitude in meters. If set, climbs/descends before navigating.	`None`
`precision`	`float`	Arrival threshold in meters (used by the NAVIGATE method).	`0.2`
`method`	`RTLMethod`	NAVIGATE: SDK navigates to the takeoff position using position control. NATIVE: trigger the autopilot's native RTL mode.	`NAVIGATE`
`land`	`bool`	Execute landing after reaching home.	`True`

Returns:

Type	Description
`bool`	True if RTL was successful.

Raises:

Type	Description
`TakeoffPositionNotSetError`	If method=NAVIGATE but the takeoff position is not set.

GPSUtils ¶

GPS utilities for vehicle navigation.

geoid_height `classmethod` ¶

geoid_height(latitude: float, longitude: float) -> float

Calculate geoid height for AMSL-to-ellipsoid conversion.

Uses EGM96 geoid model with 5' grid and cubic interpolation.

Parameters:

Name	Type	Description	Default
`latitude`	`float`	Latitude in degrees.	required
`longitude`	`float`	Longitude in degrees.	required

Returns:

Type	Description
`float`	Geoid height in meters. Subtract from ellipsoid height to get AMSL.

create_global_target `classmethod` ¶

create_global_target(latitude: float, longitude: float, altitude_rel: float, heading: float, initial_altitude: float) -> GlobalTarget

Create a global setpoint with EGM96 altitude correction.

Converts relative altitude to AMSL using the initial GPS altitude and geoid height. Yaw is stored in ENU radians (matching the local-frame convention), converted from the NED heading.

Parameters:

Name	Type	Description	Default
`latitude`	`float`	Target coordinates in degrees.	required
`longitude`	`float`	Target coordinates in degrees.	required
`altitude_rel`	`float`	Target altitude above ground in meters.	required
`heading`	`float`	Target heading in degrees (0 = North, clockwise).	required
`initial_altitude`	`float`	Initial GPS altitude for the AMSL offset.	required

Returns:

Type	Description
`GlobalTarget`	With AMSL `altitude` and ENU `yaw`.

check_reached `classmethod` ¶

check_reached(current_lat: float, current_lon: float, current_alt: float, target_lat: float, target_lon: float, target_alt: float, precision_radius: float = 0.5, alt_threshold: float = 0.5) -> Tuple[bool, float, float]

Check if a GPS waypoint has been reached (geodesic horizontal distance).

Returns:

Type	Description
`tuple of (bool, float, float)`	(reached, horizontal_distance, altitude_difference)

local_offset `staticmethod` ¶

local_offset(current_lat: float, current_lon: float, target_lat: float, target_lon: float) -> Tuple[float, float]

East/north offset in meters from current to target position.

Equirectangular approximation for display and per-axis error reporting; arrival checks use the geodesic distance from :meth:check_reached.

Returns:

Type	Description
`tuple of (float, float)`	(east, north) offset in meters.

VehicleNavigator ¶

VehicleNavigator(drone: 'VehicleDrone')

Navigation controller for :class:VehicleDrone.

Handles PID velocity-based and FCU setpoint navigation for both local (:class:LocalTarget) and global (:class:GlobalTarget) targets.

Parameters:

Name	Type	Description	Default
`drone`	`VehicleDrone`	Drone instance providing telemetry, setpoint egress, and configuration.	required

navigate_pid ¶

navigate_pid(target: Union[LocalTarget, GlobalTarget], active_axes: tuple[bool, bool, bool], yaw: Optional[float], timeout: Optional[float], precision: float, altitude_source: AltitudeSource = AUTO, altitude_target: Optional[float] = None, use_local: bool = False) -> bool

PID velocity-based navigation loop.

Computes body-frame errors, feeds them into per-axis PID controllers, and publishes velocity commands until the target is reached or timeout.

Returns:

Type	Description
`bool`	True if target reached within precision, False on timeout.

navigate_setpoint ¶

navigate_setpoint(target: Union[LocalTarget, GlobalTarget], timeout: Optional[float], precision: float, check_alt: Optional[float] = None) -> bool

Direct setpoint navigation loop.

Sends the target to the transport and monitors distance until reached.

For :class:LocalTarget: checks Euclidean distance using EKF local position. For :class:GlobalTarget: checks geodesic distance using GPS and relative altitude.

Returns:

Type	Description
`bool`	True if target reached within precision, False on timeout.

resolve_altitude_target ¶

resolve_altitude_target(z: Optional[float], reference: MoveReference, altitude_source: AltitudeSource) -> Optional[float]

Compute the absolute altitude target for the given source and reference.

Returns:

Type	Description
`float or None`	Absolute target value, or None for default position-based altitude.

Raises:

Type	Description
`SensorNotAvailableError`	If LIDAR source requested but lidar data is not available.

build_driver_command ¶

build_driver_command(drone_type: str, *, connection_string: str = '', ip: str = '', backend: str = '', mocap: bool = False, agent_port: int = 8888) -> str

Build the shell command that launches a drone's driver process.

Single source of truth for the driver launch commands shared by the SDK and the GUI.

Parameters:

Name	Type	Description	Default
`drone_type`	`str`	Drone type identifier (e.g. `"mavros"`, `"px4"`, `"px4_dds"`).	required
`connection_string`	`str`	FCU connection string / `fcu_url` for the MAVROS backends.	`''`
`ip`	`str`	Drone IP address (Bebop).	`''`
`backend`	`str`	Crazyswarm2 backend (Crazyflie).	`''`
`mocap`	`bool`	Whether to enable motion capture (Crazyflie).	`False`
`agent_port`	`int`	UDP port for the Micro XRCE-DDS Agent (`px4_dds`).	`8888`

Returns:

Type	Description
`str`	Command to run in a tmux session.

Raises:

Type	Description
`ValueError`	If the drone type has no driver process (driverless or unknown).

is_driver_running ¶

is_driver_running(drone_type: str, timeout: float = 2.0) -> bool

Check whether a drone's driver is currently up.

Dispatches on the driver's detect_via strategy: a ROS 2 node-graph lookup for node-based drivers, or a topic-graph lookup for transports that surface only through their data topics (e.g. the Micro XRCE-DDS Agent, detected by PX4's /fmu/* topics). Topic detection is independent of how the agent was launched (GUI, make sim-bridge PROTOCOL=dds, or manually), so an externally started agent is recognized too.

Parameters:

Name	Type	Description	Default
`drone_type`	`str`	Drone type identifier.	required
`timeout`	`float`	Maximum time for the ROS 2 graph query.	`2.0`

Returns:

Type	Description
`bool`	True if the driver is running. Always False for driverless or unknown types.

Control API¶

control ¶

MAVLINK_SITL_CONFIG module-attribute ¶

MAVLINK_SITL_GAZEBO_CONFIG module-attribute ¶

MAVLINK_SITL_VISION_CONFIG module-attribute ¶

PX4_DDS_SITL_CONFIG module-attribute ¶

PX4_MAVLINK_SITL_CONFIG module-attribute ¶

PX4_MAVLINK_SITL_GAZEBO_CONFIG module-attribute ¶

PX4_MAVLINK_SITL_VISION_CONFIG module-attribute ¶

PX4_SITL_CONFIG module-attribute ¶

PX4_SITL_GAZEBO_CONFIG module-attribute ¶

PX4_SITL_VISION_CONFIG module-attribute ¶

SITL_CONFIG module-attribute ¶

SITL_GAZEBO_CONFIG module-attribute ¶

SITL_GPS_CONFIG module-attribute ¶

SITL_VISION_CONFIG module-attribute ¶

SetpointNavConfig dataclass ¶

use_wpnav property ¶

to_fcu_params ¶

BaseDrone ¶

config property ¶

node property ¶

is_ready property ¶

driver_running property ¶

is_armed property ¶

flight_mode property ¶

is_fcu_connected property ¶

driver_session_name property ¶

obstacle_manager property ¶

capabilities property ¶

supports ¶

add_obstacle_detector ¶

remove_obstacle_detector ¶

enable_obstacle_detector ¶

disable_obstacle_detector ¶

enable_all_obstacle_detectors ¶

disable_all_obstacle_detectors ¶

connect abstractmethod ¶

disconnect abstractmethod ¶

arm abstractmethod ¶

disarm abstractmethod ¶

takeoff abstractmethod ¶

land abstractmethod ¶

move_velocity abstractmethod ¶

move_to abstractmethod ¶

move_to_gps ¶

emergency_stop abstractmethod ¶

set_home ¶

rtl ¶

check_driver_status ¶

start_driver_process ¶

stop_driver_process ¶

delay ¶

cleanup ¶

Capability ¶

GPS_NAV class-attribute instance-attribute ¶

LOCAL_SETPOINT class-attribute instance-attribute ¶

GLOBAL_SETPOINT class-attribute instance-attribute ¶

PID_NAV class-attribute instance-attribute ¶

VELOCITY_BODY class-attribute instance-attribute ¶

VELOCITY_WORLD class-attribute instance-attribute ¶

VELOCITY_TAKEOFF class-attribute instance-attribute ¶

SERVO class-attribute instance-attribute ¶

ACTUATOR class-attribute instance-attribute ¶

GRIPPER class-attribute instance-attribute ¶

PARAMS class-attribute instance-attribute ¶

RANGEFINDER class-attribute instance-attribute ¶

DISTANCE_SENSORS class-attribute instance-attribute ¶

VISION_POSE class-attribute instance-attribute ¶

NATIVE_RTL class-attribute instance-attribute ¶

OBSTACLE_AVOIDANCE class-attribute instance-attribute ¶

Px4MavlinkConfig dataclass ¶

DriverInfo dataclass ¶

DriverMonitor ¶

add_status_callback ¶

remove_status_callback ¶

check_status ¶

start_driver ¶

stop_driver ¶

restart_driver ¶

MAVLINK_SITL_CONFIG `module-attribute` ¶

MAVLINK_SITL_GAZEBO_CONFIG `module-attribute` ¶

MAVLINK_SITL_VISION_CONFIG `module-attribute` ¶

PX4_DDS_SITL_CONFIG `module-attribute` ¶

PX4_MAVLINK_SITL_CONFIG `module-attribute` ¶

PX4_MAVLINK_SITL_GAZEBO_CONFIG `module-attribute` ¶

PX4_MAVLINK_SITL_VISION_CONFIG `module-attribute` ¶

PX4_SITL_CONFIG `module-attribute` ¶

PX4_SITL_GAZEBO_CONFIG `module-attribute` ¶

PX4_SITL_VISION_CONFIG `module-attribute` ¶

SITL_CONFIG `module-attribute` ¶

SITL_GAZEBO_CONFIG `module-attribute` ¶

SITL_GPS_CONFIG `module-attribute` ¶

SITL_VISION_CONFIG `module-attribute` ¶

SetpointNavConfig `dataclass` ¶

use_wpnav `property` ¶

config `property` ¶

node `property` ¶

is_ready `property` ¶

driver_running `property` ¶

is_armed `property` ¶

flight_mode `property` ¶

is_fcu_connected `property` ¶

driver_session_name `property` ¶

obstacle_manager `property` ¶

capabilities `property` ¶

connect `abstractmethod` ¶

disconnect `abstractmethod` ¶

arm `abstractmethod` ¶

disarm `abstractmethod` ¶

takeoff `abstractmethod` ¶

land `abstractmethod` ¶

move_velocity `abstractmethod` ¶

move_to `abstractmethod` ¶

emergency_stop `abstractmethod` ¶

GPS_NAV `class-attribute` `instance-attribute` ¶

LOCAL_SETPOINT `class-attribute` `instance-attribute` ¶

GLOBAL_SETPOINT `class-attribute` `instance-attribute` ¶

PID_NAV `class-attribute` `instance-attribute` ¶

VELOCITY_BODY `class-attribute` `instance-attribute` ¶

VELOCITY_WORLD `class-attribute` `instance-attribute` ¶

VELOCITY_TAKEOFF `class-attribute` `instance-attribute` ¶

SERVO `class-attribute` `instance-attribute` ¶

ACTUATOR `class-attribute` `instance-attribute` ¶

GRIPPER `class-attribute` `instance-attribute` ¶

PARAMS `class-attribute` `instance-attribute` ¶

RANGEFINDER `class-attribute` `instance-attribute` ¶

DISTANCE_SENSORS `class-attribute` `instance-attribute` ¶

VISION_POSE `class-attribute` `instance-attribute` ¶

NATIVE_RTL `class-attribute` `instance-attribute` ¶

OBSTACLE_AVOIDANCE `class-attribute` `instance-attribute` ¶

Px4MavlinkConfig `dataclass` ¶

DriverInfo `dataclass` ¶

get_available_drivers `staticmethod` ¶

is_ros2_available `staticmethod` ¶

register `classmethod` ¶

create `classmethod` ¶

available_types `classmethod` ¶

is_registered `classmethod` ¶

is_enabled `property` ¶

handlers `property` ¶

PIDConfig `dataclass` ¶

from_yaml `classmethod` ¶

from_dict `classmethod` ¶

PositionPIDConfig `dataclass` ¶

from_yaml `classmethod` ¶

Px4SetpointConfig `dataclass` ¶

SetpointConfig `dataclass` ¶

to_fcu_params `abstractmethod` ¶

from_yaml `classmethod` ¶

from_dict `classmethod` ¶

DistanceReading `dataclass` ¶

from_mavlink `classmethod` ¶

capabilities `property` ¶

from_config `classmethod` ¶