Vehicle¶

The Vehicle object is the primary API surface for plugin developers. It provides access to telemetry, state, commands, and sub-systems of the connected vehicle.

Accessing the vehicle¶

import QGroundControl

property var vehicle: QGroundControl.multiVehicleManager.activeVehicle

Always null-check before accessing properties:

QGCLabel {
    text: vehicle ? vehicle.flightMode : "No vehicle"
}

Properties¶

Identity & Type¶

Property	Type	Writable	Description
`id`	`int`	No	Unique vehicle ID (constant)
`name`	`QString`	No	Vehicle name (derived from priority link)
`vehicleTypeString`	`QString`	No	Human-readable vehicle type
`firmwareTypeString`	`QString`	No	Human-readable firmware type
`fixedWing`	`bool`	No	True if fixed-wing aircraft
`multiRotor`	`bool`	No	True if multirotor
`vtol`	`bool`	No	True if VTOL
`rover`	`bool`	No	True if ground rover
`boat`	`bool`	No	True if boat/USV
`sub`	`bool`	No	True if submarine/ROV
`vector`	`bool`	No	True if vector-type vehicle
`scorpion`	`bool`	No	True if scorpion-type vehicle
`evom`	`bool`	No	True if EVOM vehicle
`evog`	`bool`	No	True if EVOG vehicle
`tethered`	`bool`	No	True if tethered vehicle
`dragonMulticopter`	`bool`	No	True if Dragon multicopter variant
`dragonFixedWing`	`bool`	No	True if Dragon fixed-wing variant
`px4Firmware`	`bool`	No	True if running PX4 firmware
`apmFirmware`	`bool`	No	True if running ArduPilot firmware
`genericFirmware`	`bool`	No	True if generic/unknown firmware
`isOfflineEditingVehicle`	`bool`	No	True if this is the offline editing vehicle
`makeModel`	`VehicleMakeModel*`	No	Vehicle make and model info (constant)

Property	Type	Writable	Description
`coordinate`	`QGeoCoordinate`	No	Current vehicle position
`vehicleCoordinateValid`	`bool`	No	True if current position is valid
`latitude`	`double`	No	Current latitude
`longitude`	`double`	No	Current longitude
`homePosition`	`QGeoCoordinate`	No	Home position
`homePositionValid`	`bool`	No	True if home position is valid
`armedPosition`	`QGeoCoordinate`	No	Position where the vehicle was armed
`takeoffPosition`	`QGeoCoordinate`	Yes	Takeoff position
`handrailGpCoord`	`QGeoCoordinate`	No	Handrail ground point coordinate
`beaconGpCoord`	`QGeoCoordinate`	No	Beacon ground point coordinate
`horizontalAccuracy`	`float`	No	Horizontal position accuracy (meters)
`horizontalVelocityValid`	`bool`	No	True if horizontal velocity data is valid
`isGpsGlobalOriginSet`	`bool`	No	True if GPS global origin is set
`externalSensorEstimateFused`	`bool`	No	True if external sensor estimate is fused

Flight State¶

Property	Type	Writable	Description
`armed`	`bool`	Yes	Arm state. Set to `true` to arm, `false` to disarm.
`autoDisarm`	`bool`	No	True if auto-disarm is active
`flightMode`	`QString`	Yes	Current flight mode. Set to change mode.
`flightModes`	`QStringList`	No	List of all available flight modes
`numberFlightModes`	`int`	No	Number of available flight modes
`joystickFlightModes`	`QStringList`	No	Flight modes available via joystick
`flightModeSetAvailable`	`bool`	No	True if flight mode can be changed
`connectionLost`	`bool`	No	True if connection to vehicle is lost
`connectionLostEnabled`	`bool`	Yes	Enable/disable connection-lost handling
`active`	`bool`	Yes	Whether this is the active vehicle
`prearmError`	`QString`	Yes	Current pre-arm error message
`isHoldFlightMode`	`bool`	No	True if currently in hold/loiter mode
`vehicleSystemStatus`	`VehicleSystemStatus`	No	Overall system status
`initialPlanRequestComplete`	`bool`	No	True when initial plan download is done

Telemetry Facts¶

These are Fact objects. Access the value with .value, display string with .valueString, and units with .units. See Fact System for details.

Property	Type	Description
`roll`	`Fact*`	Roll angle (degrees)
`pitch`	`Fact*`	Pitch angle (degrees)
`heading`	`Fact*`	Heading (degrees)
`rollRate`	`Fact*`	Roll rate (deg/s)
`pitchRate`	`Fact*`	Pitch rate (deg/s)
`yawRate`	`Fact*`	Yaw rate (deg/s)
`groundSpeed`	`Fact*`	Ground speed
`airSpeed`	`Fact*`	Airspeed
`airSpeedSetpoint`	`Fact*`	Airspeed setpoint
`climbRate`	`Fact*`	Vertical speed
`altitudeRelative`	`Fact*`	Altitude relative to home
`altitudeAMSL`	`Fact*`	Altitude above mean sea level
`altitudeAGL`	`Fact*`	Altitude above ground level
`altitudeTerrain`	`Fact*`	Terrain altitude
`flightDistance`	`Fact*`	Total flight distance
`flightTime`	`Fact*`	Total flight time
`distanceToHome`	`Fact*`	Distance to home position
`headingToNextWP`	`Fact*`	Heading to next waypoint
`headingToHome`	`Fact*`	Heading to home
`distanceToGCS`	`Fact*`	Distance to ground station
`missionItemIndex`	`Fact*`	Current mission item index
`hobbs`	`Fact*`	Hobbs meter (engine hours)

Sub-objects (Fact Groups)¶

Property	Type	Description
`gps`	`VehicleGPSFactGroup*`	Active GPS data (see Fact Groups)
`gps1`	`VehicleGPSFactGroup*`	GPS unit 1
`gps2`	`VehicleGPSFactGroup*`	GPS unit 2
`battery1`	`VehicleBatteryFactGroup*`	Battery 1 data (see Fact Groups)
`battery2`	`VehicleBatteryFactGroup*`	Battery 2 data
`wind`	`VehicleWindFactGroup*`	Wind data (see Fact Groups)
`vibration`	`VehicleVibrationFactGroup*`	Vibration data
`temperature`	`VehicleTemperatureFactGroup*`	Temperature data
`clock`	`VehicleClockFactGroup*`	Clock data
`setpoint`	`VehicleSetpointFactGroup*`	Setpoint data
`distanceSensor`	`VehicleDistanceSensorFactGroup*`	Distance sensor data
`cellularStatus`	`VehicleCellularStatusFactGroup*`	Cellular modem status
`terrain`	`TerrainFactGroup*`	Terrain data

Sub-objects (Managers)¶

Property	Type	Description
`gimbalManager`	`GimbalManager*`	Gimbal control (see Managers)
`dynamicCameras`	`QGCCameraManager*`	Camera management
`remoteIDManager`	`RemoteIDManager*`	Remote ID
`parameterManager`	`ParameterManager*`	Vehicle parameters
`parameterExtManager`	`ParameterExtManager*`	Extended parameters
`mavlinkMonitor`	`VehicleMavlinkMonitor*`	MAVLink monitoring
`messageHandler`	`VehicleMessageHandler*`	Vehicle messages
`objectAvoidance`	`VehicleObjectAvoidance*`	Object avoidance
`sensors`	`VehicleSensors*`	Sensor status
`radio`	`VehicleRadio*`	Primary radio link
`radios`	`QmlObjectListModel*`	All radio links
`fuel`	`VehicleFuel*`	Fuel level and tanks (see Fuel). Never `null`
`autotune`	`Autotune*`	Autotune controller
`actuators`	`Actuators*`	Actuator control
`generatorStatus`	`GeneratorStatus*`	Generator/power status
`compassUiAdapter`	`CompassUiAdapter*`	Compass UI helper
`winchStatusUiAdapter`	`WinchStatusUiAdapter*`	Winch status UI helper
`homeLandApproaches`	`SafePointLandApproaches*`	Safe landing approaches
`autopilot`	`AutoPilotPlugin*`	Autopilot plugin interface

Flight Mode Strings¶

These are constant string properties returning the mode name for each standard flight mode:

Property	Description
`missionFlightMode`	Mission mode
`pauseFlightMode`	Pause/Hold mode
`rtlFlightMode`	Return-to-launch mode
`smartRTLFlightMode`	Smart RTL mode
`landFlightMode`	Land mode
`orbitFlightMode`	Orbit mode
`takeoffFlightMode`	Takeoff mode
`vtolTakeoffFlightMode`	VTOL takeoff mode
`initFlightMode`	Initial/startup mode
`positionFlightMode`	Position hold mode
`altitudeFlightMode`	Altitude hold mode
`takeControlFlightMode`	Manual/take-control mode
`followFlightMode`	Follow mode
`slowFlightMode`	Slow/careful mode
`mcFollowMode`	Multicopter follow mode
`gpsFixedWingMode`	GPS fixed-wing mode
`visualFixedWingMode`	Visual fixed-wing mode
`trackerLandingMode`	Tracker-assisted landing mode
`supportsSmartRTL`	`bool` -- True if smart RTL is available

App Mode Availability¶

Property	Type	Description
`fwGpsModeAvailable`	`bool`	Fixed-wing GPS mode available
`fwVisualModeAvailable`	`bool`	Fixed-wing visual mode available
`mcFollowModeAvailable`	`bool`	Multicopter follow mode available

RC & Sensors¶

Property	Type	Description
`rcRSSI`	`int`	RC signal strength
`rcInputMode`	`RCInputMode`	Current RC input mode
`ekfHeightMode`	`EKFHeightMode`	EKF height source
`flowImageIndex`	`int`	Optical flow image index

VTOL¶

Property	Type	Description
`vtolInFwdFlight`	`bool`	VTOL is in forward flight (writable)
`vtolInTransition`	`bool`	VTOL is transitioning
`vtolInMulticopter`	`bool`	VTOL is in multicopter mode

Misc¶

Property	Type	Description
`highLatencyLink`	`bool`	Connected via high-latency link
`supportsTerrainFrame`	`bool`	Firmware supports terrain frame
`priorityLinkName`	`QString`	Name of the priority link (writable)
`handrailGpState`	`PositionState`	Handrail ground point state
`gpState`	`PositionState`	Ground point state
`toolIndicators`	`QVariantList`	Tool indicator components
`modeIndicators`	`QVariantList`	Mode indicator components
`staticCameraList`	`QVariantList`	List of static camera definitions
`hobbsMeter`	`QString`	Hobbs meter string
`brandImageIndoor`	`QString`	Brand image path (indoor)
`brandImageOutdoor`	`QString`	Brand image path (outdoor)
`trajectoryPoints`	`TrajectoryPoints*`	Trajectory point list
`cameraTriggerPoints`	`QmlObjectListModel*`	Camera trigger point list
`autoDisconnect`	`bool`	Auto-disconnect setting (writable)
`soloFirmware`	`bool`	Solo firmware flag (writable)
`motorCount`	`int`	Number of motors
`coaxialMotors`	`bool`	Coaxial motor configuration
`xConfigMotors`	`bool`	X-configuration motors
`supportsThrottleModeCenterZero`	`bool`	Throttle mode support
`supportsNegativeThrust`	`bool`	Negative thrust support
`supportsJSButton`	`bool`	Joystick button support
`supportsRadio`	`bool`	Radio calibration support
`supportsMotorInterference`	`bool`	Motor interference compensation

Boat-Specific Properties¶

These properties are available when vehicle.boat is true. Fuel is not boat-specific and lives in vehicle.fuel.

Property	Type	Writable	Description
`engineState`	`int`	Yes	Engine state enum
`gearboxState`	`int`	Yes	Gearbox state enum
`gearboxPos`	`float`	Yes	Gearbox position
`rudderState`	`int`	Yes	Rudder state enum
`rudderPos`	`float`	Yes	Rudder position (degrees)
`engineTrimState`	`int`	Yes	Engine trim state enum
`engineTrimPos`	`float`	Yes	Engine trim position
`throttlePos`	`float`	Yes	Throttle position (%)
`engineLoad`	`float`	Yes	Engine load (%)
`engineRPM`	`float`	Yes	Engine RPM
`engineTemp`	`float`	Yes	Engine temperature (C)
`oilPressure`	`float`	Yes	Oil pressure (kPa)
`usvHeading`	`float`	Yes	USV heading (degrees)
`usvCourse`	`float`	Yes	USV course (degrees)
`sog`	`float`	Yes	Speed over ground (m/s)

Fuel¶

vehicle.fuel is available on every vehicle type, fed by the MAVLink FUEL_STATUS message (and, for the consumption rate, by BOAT_ENGINE_STATUS_V2). All properties are read-only.

Property	Type	Description
`level`	`float`	Fuel remaining (L)
`maximum`	`float`	Total capacity (L)
`consumed`	`float`	Fuel consumed (L)
`consumptionRate`	`float`	Consumption rate (L/h)
`percentRemaining`	`float`	Fuel remaining (0–100 %)
`statusAvailable`	`bool`	`true` once any `FUEL_STATUS` has been received. Stays `true` after the stream stops
`tanks`	`QVariantList`	Per-tank breakdown, see below

Each entry in tanks is an object with tankId, percentRemaining (%), remaining (L), maximum (L) and temperature (°C). With more than one tank, the vehicle-level values are summed across tanks and percentRemaining is weighted by tank capacity. If the vehicle also reports tank 0, it is taken as the vehicle total: its values are used as-is and it is left out of tanks.

Unknown values are NaN, not 0

Every float above is NaN until the vehicle reports it, and a tank returns to NaN 10–20 s after its FUEL_STATUS stops. Check isNaN() before formatting, or you will display "NaN". Volumes are only reported for liquid fuel, and the rate for liquid and gas; other fuel types leave them NaN while percentRemaining still works. consumptionRate can also come from BOAT_ENGINE_STATUS_V2, so it may be set while statusAvailable is false.

Migrating from the flat fuel properties

Earlier AMC versions exposed fuel as boat properties on the vehicle itself. They are gone; use vehicle.fuel instead:

Removed	Replacement
`vehicle.fuelLevel`	`vehicle.fuel.level`
`vehicle.fuelMaximum`	`vehicle.fuel.maximum`
`vehicle.fuelConsumed`	`vehicle.fuel.consumed`
`vehicle.fuelConsumptionRate`	`vehicle.fuel.consumptionRate`

The old properties defaulted to 0.0; the new ones default to NaN.

Methods¶

Vehicle commands¶

Method	Parameters	Description
`emergencyStop()`	--	Trigger emergency stop (kills motors)
`startMission()`	--	Start the loaded mission
`rebootVehicle()`	--	Reboot the vehicle
`triggerCamera()`	--	Trigger camera shutter
`disconnectInactiveVehicle()`	--	Disconnect if inactive
`flashBootloader()`	--	Flash the bootloader

Flight mode¶

Method	Parameters	Description
`setFlightMode(mode)`	`QString mode`	Set flight mode by name
`setCurrentMissionSequence(seq)`	`int seq`	Jump to mission item
`abortLanding(climbOutAltitude)`	`double climbOutAltitude`	Abort landing and climb

Parameters¶

Method	Parameters	Returns	Description
`fetchParameter(name)`	`QString name`	`Fact*`	Get a vehicle parameter
`setParameter(name, value, cooked)`	`QString, QVariant, bool`	--	Set a vehicle parameter
`fetchAppsParameter(name)`	`QString name`	`Fact*`	Get an apps parameter
`setAppsParameter(name, value, cooked)`	`QString, QVariant, bool`	--	Set an apps parameter

Takeoff / VTOL¶

Method	Parameters	Description
`executeVtolTakeoff(altRel, loiterCoord)`	`double, QGeoCoordinate`	Execute VTOL takeoff
`setTakeoffPosition(coord)`	`QGeoCoordinate`	Set takeoff heading position

Testing & Tuning¶

Method	Parameters	Description
`motorTest(motor, percent, timeoutSecs)`	`int, int, int`	Run motor test
`actuatorTest(isTiltTest)`	`bool`	Run actuator test
`setPIDTuningTelemetryMode(pidTuning)`	`bool`	Enable/disable PID tuning telemetry

RC Mapping¶

Method	Parameters	Description
`sendParamMapRC(paramName, scale, centerValue, tuningID, minValue, maxValue)`	`QString, double, double, int, double, double`	Map RC channel to parameter
`clearAllParamMapRC()`	--	Clear all RC-to-parameter mappings

Communication¶

Method	Parameters	Description
`sendPlan(planFile)`	`QString planFile`	Upload plan file
`sendSpeedCommand(targetSpeed)`	`QVariant`	Send speed command
`setCommLinkAutoSelect()`	--	Set communication link to auto-select

Queries¶

Method	Parameters	Returns	Description
`isSystemDegraded()`	--	`bool`	Check if any system is degraded
`minimumTakeoffAltitude()`	--	`double`	Minimum safe takeoff altitude
`maximumHorizontalSpeedMultirotor()`	--	`double`	Max horizontal speed (multirotor)
`maximumEquivalentAirspeed()`	--	`double`	Max equivalent airspeed
`minimumEquivalentAirspeed()`	--	`double`	Min equivalent airspeed
`versionCompare(compare)`	`QString`	`int`	Compare firmware version
`versionCompare(major, minor, patch)`	`int, int, int`	`int`	Compare firmware version
`vehicleTypeName()`	--	`QString`	Vehicle type name
`isTiltrotor()`	--	`bool`	Check if tiltrotor

Payload device interface¶

Method	Parameters	Description
`sendPayloadDeviceInterfaceArmCmd()`	--	Arm payload device
`sendPayloadDeviceInterfaceDisarmCmd()`	--	Disarm payload device
`sendPayloadDeviceInterfaceActionCmd()`	--	Trigger payload action
`getPayloadDeviceInterfaceSettings()`	--	Get payload settings (`QVariantMap`)
`setPayloadDeviceInterfaceSettings(settings)`	`QVariantMap`	Set payload settings

Boat-specific methods¶

Method	Parameters	Description
`sendEngineIgnitionCommand(cmd, engineIndex)`	`quint8, quint8`	Engine ignition control
`sendEngineTrimCommand(cmd, engineIndex)`	`quint8, quint8`	Engine trim control
`sendControlTakeoverCommand()`	--	Take over vehicle control
`setHeadingHoldMode()`	--	Set heading hold mode

Enums¶

BatteryChargeState¶

Value	Description
`Vehicle.Normal`	Normal charge level
`Vehicle.Low`	Low battery
`Vehicle.Critical`	Critical battery
`Vehicle.Emergency`	Emergency battery
`Vehicle.Unknown`	Unknown state

VehicleSystemStatus¶

Value	Description
`Vehicle.VehicleSystemStatusIdle`	System idle
`Vehicle.VehicleSystemStatusHealthy`	System healthy
`Vehicle.VehicleSystemStatusFailure`	System failure

RCInputMode¶

Value	Description
`Vehicle.RCInputModeUnknown`	Unknown input
`Vehicle.RCInputModeRC`	Hardware RC transmitter
`Vehicle.RCInputModeJoystick`	Joystick/gamepad
`Vehicle.RCInputModeVirtual`	Virtual/software control

EKFHeightMode¶

Value	Description
`Vehicle.EKFHeightModeUnknown`	Unknown
`Vehicle.EKFHeightModeBarometricPressure`	Barometer
`Vehicle.EKFHeightModeGPS`	GPS
`Vehicle.EKFHeightModeRangeSensor`	Range sensor
`Vehicle.EKFHeightModeVision`	Vision

PositionState¶

Value	Description
`Vehicle.PositionActive`	Position data is current
`Vehicle.PositionStale`	Position data is stale
`Vehicle.PositionTimedOut`	Position data has timed out

CheckList¶

Value	Description
`Vehicle.CheckListNotSetup`	Checklist not configured
`Vehicle.CheckListPassed`	Checklist passed
`Vehicle.CheckListFailed`	Checklist failed

GuidanceSystemConfig¶

Value	Description
`Vehicle.GPS_AND_VISION`	GPS and vision
`Vehicle.GPS_ONLY`	GPS only
`Vehicle.VISION_ONLY`	Vision only
`Vehicle.INS_ONLY`	INS only

ENGINE_STATE (boat)¶

Value	Description
`Vehicle.ENGINE_NONE`	No state
`Vehicle.ENGINE_STOPPED`	Engine stopped
`Vehicle.ENGINE_STARTING`	Engine starting
`Vehicle.ENGINE_RUNNING`	Engine running
`Vehicle.ENGINE_FAULT`	Engine fault

PAYLOAD_DEVICE_INTERFACE_CMD¶

Value	Description
`Vehicle.PAYLOAD_DEVICE_DISARM`	Disarm payload
`Vehicle.PAYLOAD_DEVICE_ARM`	Arm payload
`Vehicle.PAYLOAD_DEVICE_TRIGGER`	Trigger payload
`Vehicle.PAYLOAD_DEVICE_ABORT`	Abort payload action

Usage examples¶

Display flight mode and speed¶

import QGroundControl
import QGroundControl.Controls

Column {
    property var vehicle: QGroundControl.multiVehicleManager.activeVehicle

    QGCLabel {
        text: vehicle ? "Mode: " + vehicle.flightMode : "No vehicle"
    }
    QGCLabel {
        text: vehicle ? "Speed: " + vehicle.groundSpeed.valueString : "--"
    }
    QGCLabel {
        text: vehicle ? "Alt: " + vehicle.altitudeRelative.valueString : "--"
    }
}

Check vehicle type¶

QGCLabel {
    text: {
        if (!vehicle) return "No vehicle"
        if (vehicle.multiRotor) return "Multirotor"
        if (vehicle.fixedWing) return "Fixed Wing"
        if (vehicle.vtol) return "VTOL"
        if (vehicle.boat) return "Boat"
        return vehicle.vehicleTypeString
    }
}

Show fuel remaining¶

QGCLabel {
    visible: !!vehicle && vehicle.fuel.statusAvailable
    text: vehicle && !isNaN(vehicle.fuel.percentRemaining)
        ? "Fuel: " + vehicle.fuel.percentRemaining.toFixed(0) + " %"
        : "Fuel: N/A"
}

Read a parameter¶

Component.onCompleted: {
    if (vehicle) {
        var param = vehicle.fetchParameter("MPC_XY_VEL_MAX")
        if (param) {
            PluginManager.log("Max XY velocity: " + param.valueString)
        }
    }
}