DOCSEARCHbyAlgolia
Submit Docs

QGroundControl (QGC)

repository·master·Indexed 26 days ago

https://github.com/mavlink/qgroundcontrol

A comprehensive Ground Control Station (GCS) for UAVs supporting MAVLink-enabled drones like PX4 and ArduPilot. QGC provides mission planning, vehicle configuration, telemetry visualization, and GStreamer-based video streaming across Windows, macOS, Linux, Android, and iOS. The project includes tools for custom branding, static analysis for C++ code, and developer guides for creating custom builds.

Tokens
142K
Snippets
196
Records
863
Agent score
84%

What's inside QGroundControl

  1. Overview of QGroundControl (QGC)

    master

    QGroundControl (QGC) is a Ground Control Station (GCS) designed for UAVs. It provides full flight control and mission planning capabilities for any MAVLink-enabled drone, including platforms such as PX4 and ArduPilot.

    Key features include:

    • Mission planning: Plan, edit, and execute autonomous waypoint, survey, and structure-scan missions.
    • Live Fly View: Real-time flight telemetry, instruments, and map display.
    • Vehicle setup: Guided wizards for sensor calibration, radio configuration, flight modes, and power management.
    • Parameter tuning: Inspect and edit vehicle parameters via the Fact System.
    • Video streaming: GStreamer-based UDP RTP / RTSP video streaming with recording capabilities.
    • Multi-vehicle support: Simultaneous connection and monitoring of multiple vehicles.
    • MAVLink tooling: Built-in MAVLink Inspector, console, and log download/analysis tools.
    • Cross-platform: Available on Windows, macOS, Linux, Android, and iOS.

  2. Understand the QGC Plugin Architecture

    master
    QGroundControl (QGC) utilizes a plugin architecture to isolate firmware-specific logic from generic ground station code. This prevents the codebase from becoming cluttered with conditional statements (if/else) when handling different MAVLink implementations, varying command subsets, or non-standardized vehicle configurations and parameter sets. This architecture also allows custom builds to extend or modify QGC functionality.

  3. Understand the QGC Multi-Device Design Pattern

    master

    QGroundControl (QGC) uses a single codebase to support multiple device types (Desktop, Laptop, Tablet, and Phone) by utilizing a hybrid UI design pattern. Instead of maintaining separate UIs for different form factors, QGC relies on Qt QML layout reflow and a centralized data model to adapt a single set of UI code to various screen sizes and input methods (mouse and touch).

    Design Priorities

    When making UI/UX decisions, QGC follows this priority order:

    1. Tablet (Primary target: ~10" screen, touch-optimized)
    2. Laptop
    3. Desktop
    4. Phone (Lowest priority: functional but may have usability sacrifices in Setup/Plan views)

    Core Architectural Components

    • Qt Layout controls: Uses QML capabilities to reflow UI elements to fit different form factors.
    • FactSystem: An internal data management system that holds all individual pieces of data. This data model is connected directly to UI controls.
    • Reusable Controls: The UI is built from a base set of reusable elements. These controls connect to FactSystem Facts to automatically provide the appropriate UI, ensuring feature updates propagate throughout the entire application.

  5. Use the Qt QML Profiler Skill

    master

    The qt-qml-profiler skill is used to investigate QML / Qt Quick performance issues such as UI lag, frame drops, or stuttering. It runs qmlprofiler on a 2D QML application, parses the resulting .qtd trace, and analyzes hotspots against the source code, providing summaries for frame-time, memory, and pixmap-cache.

    Note: This skill does not support Qt Quick 3D. While 2D results remain valid for apps using Qt Quick 3D, 3D-specific bottlenecks (like mesh batching or shader variants) will not be detected. For 3D profiling, use Qt Creator's profiler UI.

  6. Analyze CSV telemetry data

    master

    The CSV telemetry file provides a simplified dataset for quick analysis, containing relevant vehicle data such as GPS position, attitude, and battery status.

    Key Characteristics:

    • Frequency: Data is populated at 1 Hz.
    • Comparison to .tlog: It is less detailed than a standard telemetry log but significantly easier to extract data from and process.
    • Compatibility: The files can be opened using common spreadsheet software like Microsoft Excel, Google Sheets, LibreOffice Calc, or OpenOffice Calc.

  7. Understand the Qt QML Code Review workflow

    master

    The review process operates in four distinct phases:

    1. Linter (Phase 1): A single-pass Python script checking 47+ rules across 13 categories (imports, ordering, bindings, layout, loaders, delegates, states, images, performance, style, signals, errors, and JavaScript quality).
    2. System qmllint (Phase 1b, optional): Runs qmllint if present on the system to provide type-level checks.
    3. Deep analysis (Phase 2): Six parallel agents analyze specific areas (bindings/properties, layout/anchoring, component lifecycle, ListView/delegates, states/transitions, and performance/quality). Agents only report findings with >80/100 confidence.
    4. Consolidated report (Phase 3): Produces a deduplicated, scored report containing file paths, line numbers, traces, and mitigations.

  8. Understand QGroundControl data collection and usage

    master

    QGroundControl collects certain personal and sensitive data to provide core functionality. This data is used exclusively within the app and is not shared externally except as described in the privacy policy.

    Key data usage examples:

    • Camera sensor: Used to overlay video feeds with flight telemetry data.
    • Location: Used to track and display the current user position on the map.

    In the event of an app error, Log Data may be collected via third-party products. This includes your IP address, device name, operating system version, app configuration, and usage timestamps.

  9. Understand the Generated Vehicle Config Pages architecture

    master

    Vehicle Setup pages (e.g., Power, Safety) are dynamically generated from JSON definitions. The pipeline follows these steps:

    1. JSON Definitions: Located in src/AutoPilotPlugins/{APM,PX4}/VehicleConfig/*.VehicleConfig.json.
    2. Python Generation: The tools/generators/config_qml/page_generator.py script processes the JSON.
    3. Generated QML: Output files are placed in build/src/AutoPilotPlugins/{APM,PX4}/generated/.
    4. C++ Integration: A C++ component class (e.g., APMPowerComponent) loads the generated QML using setupSource().

    At build time, CMake runs the generator for each firmware plugin, and the resulting QML files are compiled into the corresponding QGroundControl.AutoPilotPlugins.* QML module.

  10. Navigate Settings Pages in QGroundControl

    master

    The Settings View allows you to configure application-wide settings for QGroundControl without requiring a vehicle connection. You can navigate between different configuration categories using the buttons in the left-hand sidebar. Available settings pages include:

    • General: Core application options like display units, autoconnection devices, language, and color schemes.
    • Fly View: Behavior for preflight checklists, guided modes, virtual joysticks, and instrument panels.
    • 3D View: Configuration for the 3D map view.
    • Plan View: Defaults for mission altitude, VTOL transition distance, and landing patterns.
    • ADSB Server: Connection settings for ADS-B traffic tracking.
    • Comm Links: Manual creation of communication links and auto-connect options.
    • Logging: Application log capture for diagnostics.
    • Maps: Map provider selection, offline tiles, API tokens, custom tile servers, and cache settings.
    • NTRIP / RTK: Configuration for the built-in NTRIP client to stream RTK correction data.
    • PX4 Log Transfer: Settings for downloading and uploading PX4 logs.
    • Remote ID: Drone registration, region, and operator information.
    • Telemetry: MAVLink connection settings for vehicles.
    • Video: Video source, stream URLs, recording options, and decoder settings.
    • Help: Access to user guides, forums, and support.

  11. Understand the vehicle auto-connect communication flow

    master

    When a vehicle auto-connects to QGroundControl, the following high-level communication sequence occurs:

    1. Link Detection: LinkManager maintains an open UDP port. When a known device type (e.g., Pixhawk, SiK Radio, PX4 Flow) makes a UDP connection, LinkManager creates a new SerialLink between the computer and the device.
    2. Protocol Processing: Incoming bytes from the SerialLink are passed to MAVLinkProtocol, which converts them into MAVLink messages.
    3. Vehicle Instantiation: If a HEARTBEAT message is detected, MultiVehicleManager is notified and creates a new vehicle object based on the HEARTBEAT data.
    4. Plugin Initialization: The new vehicle object instantiates plugins matching the specific vehicle type.
    5. Parameter Loading: The vehicle's ParameterLoader sends a PARAM_REQUEST_LIST to the device to load parameters via the parameter protocol.
    6. Mission Loading: After parameter loading completes, the vehicle's MissionManager requests mission items using the mission protocol.
    7. UI Availability: Once parameters are fully loaded, VehicleComponents display their respective UI in the Setup view.

  12. Understand the QGC communication architecture

    master

    QGC uses a hierarchical communication model to manage vehicle connections:

    1. LinkInterface: The base class for all communication pipes (e.g., Serial, UDP over WiFi). Each link runs in its own thread and sends raw bytes to the MAVLinkProtocol.
    2. LinkManager: Manages all open links and handles automatic connections via serial and UDP.
    3. MAVLinkProtocol: A singleton object that translates incoming bytes from links into MAVLink messages. It routes HEARTBEAT messages to the MultiVehicleManager and other messages to the appropriate Vehicle objects.
    4. MultiVehicleManager: A singleton that manages all Vehicle objects. It creates a new Vehicle when a new HEARTBEAT is detected on a link and handles switching between active vehicles or removing them.
    5. Vehicle: The primary interface for communicating with a physical vehicle.

    Note: The UAS class is deprecated; all functionality is moving to the Vehicle class. Do not use UAS for new code.