Fact System¶

The Fact system is the primary way vehicle telemetry is exposed to QML. A Fact wraps a single value with metadata -- units, min/max bounds, enum mappings, and human-readable descriptions.

What is a Fact?¶

A Fact is a QML object that represents a named value. Most telemetry on the Vehicle object (speed, altitude, heading, GPS data, battery levels, etc.) is exposed as Fact* properties.

property var vehicle: QGroundControl.multiVehicleManager.activeVehicle

// vehicle.groundSpeed is a Fact
// vehicle.groundSpeed.value is the raw numeric value
// vehicle.groundSpeed.valueString is "12.3 m/s"

Accessing values¶

Every Fact offers several ways to read its data:

Property	Type	Description
`value`	`QVariant`	Cooked (unit-converted) value
`rawValue`	`QVariant`	Raw value before unit conversion
`valueString`	`QString`	Formatted string including units
`enumOrValueString`	`QString`	Enum label if applicable, otherwise value string

Example¶

QGCLabel {
    // Shows "142.5" (numeric)
    text: vehicle.altitudeRelative.value.toFixed(1)
}

QGCLabel {
    // Shows "142.5 m" (formatted with units)
    text: vehicle.altitudeRelative.valueString
}

Writing values¶

Some Facts are writable (typically vehicle parameters). Use the value property setter or the rawValue setter:

// Set a cooked (display-unit) value
myFact.value = 15.0

// Set a raw (native-unit) value
myFact.rawValue = 15.0

Warning

Most telemetry Facts are read-only. Only vehicle parameters and certain settings Facts are writable.

Metadata properties¶

Property	Type	Description
`name`	`QString`	Parameter/fact name
`shortDescription`	`QString`	Short description
`longDescription`	`QString`	Detailed description
`units`	`QString`	Display units string
`min`	`QVariant`	Minimum allowed value (cooked)
`max`	`QVariant`	Maximum allowed value (cooked)
`rawMin`	`QVariant`	Minimum allowed value (raw)
`rawMax`	`QVariant`	Maximum allowed value (raw)
`defaultValue`	`QVariant`	Default value
`defaultValueString`	`QString`	Default value as string
`defaultValueAvailable`	`bool`	True if a default is defined
`increment`	`double`	Recommended value increment
`decimalPlaces`	`int`	Number of decimal places for display
`category`	`QString`	Parameter category
`group`	`QString`	Parameter group

Type information¶

Property	Type	Description
`typeIsString`	`bool`	True if the fact holds a string
`typeIsBool`	`bool`	True if the fact holds a boolean
`readOnly`	`bool`	True if the fact is read-only
`writeOnly`	`bool`	True if the fact is write-only
`volatileValue`	`bool`	True if value changes frequently

Enum support¶

Some Facts map numeric values to named labels (e.g., flight modes, sensor states):

Property	Type	Description
`enumStrings`	`QStringList`	List of enum label strings
`enumValues`	`QVariantList`	List of corresponding enum values
`enumIndex`	`int`	Current value's index in the enum list (read/write)
`enumStringValue`	`QString`	Current value's enum label (read/write)

Example: Populating a combo box from an enum Fact¶

QGCComboBox {
    model: myFact.enumStrings
    currentIndex: myFact.enumIndex
    onActivated: (index) => { myFact.enumIndex = index }
}

Bitmask support¶

Some Facts represent bitmask values:

Property	Type	Description
`bitmaskStrings`	`QStringList`	Labels for each bit
`bitmaskValues`	`QVariantList`	Numeric value for each bit
`selectedBitmaskStrings`	`QStringList`	Labels for currently set bits

Validation¶

Method	Parameters	Returns	Description
`validate(cookedValue, convertOnly)`	`QString, bool`	`QString`	Validate and optionally convert a value. Returns empty string on success, error message on failure.
`clamp(cookedValue)`	`QString`	`QVariant`	Clamp a value to min/max bounds

Methods¶

Method	Parameters	Description
`setMin(value)`	`QVariant`	Override minimum bound
`setMax(value)`	`QVariant`	Override maximum bound
`setDefault(value)`	`QVariant`	Override default value
`setUnits(units)`	`QString`	Override units string
`setRawValue(value)`	`QVariant`	Set raw value programmatically
`valueSliderModel()`	--	Returns `FactValueSliderListModel*` for slider UI

Signals¶

Signal	Description
`valueChanged()`	Emitted when the cooked value changes
`rawValueChanged()`	Emitted when the raw value changes

Binding to value changes¶

Connections {
    target: vehicle ? vehicle.groundSpeed : null
    function onValueChanged() {
        PluginManager.log("Speed changed: " + vehicle.groundSpeed.valueString)
    }
}

Common patterns¶

Storing Fact references¶

When you store a reference to a Fact in a property, use property Fact instead of property var:

import QGroundControl.FactSystem

property Fact altFact: vehicle ? vehicle.altitudeRelative : null
property Fact speedUnitsFact: QGroundControl.settingsManager.unitsSettings.speedUnits

Null-safe telemetry display¶

QGCLabel {
    property var vehicle: QGroundControl.multiVehicleManager.activeVehicle
    text: vehicle ? vehicle.altitudeRelative.valueString : "--"
}

Chaining through fact groups¶

// GPS horizontal dilution of precision
text: vehicle ? vehicle.gps.hdop.valueString : "--"

// Battery voltage
text: vehicle ? vehicle.battery1.voltage.valueString : "--"

// Wind speed
text: vehicle ? vehicle.wind.speed.valueString : "--"

Displaying with custom formatting¶

QGCLabel {
    text: {
        if (!vehicle) return "--"
        var speed = vehicle.groundSpeed.value
        return speed.toFixed(1) + " " + vehicle.groundSpeed.units
    }
}