简介面向QGC二次开发入门者这份资源以轻量项目代码形式呈现适合拥有少量C与QT基础、希望快速上手无人机地面站定制改造的开发者解决从零阅读QGC源码时不知从何下手的困惑。压缩包共3个文件以inscode示例、html说明和gitignore配置为主打包后仅5KB结构简洁便于直接查看演示逻辑。教程覆盖软件汉化与BUG修复、信号与槽添加、QML与C交互、MAVLINK解析与发送、地图更换、自定义MAVLINK消息添加、主工具栏图标定制以及多机轨迹同屏显示等核心扩展点既有修改思路也配套可运行的代码片段并同步给出环境配置说明。目前已有421人学习可作为系统二次开发前的快速预览帮助读者建立QGC工程结构认知、明确后续深入方向减少盲目翻阅源码的时间成本。无论是想调整软件品牌标识还是接入自定义通信协议都能从中获得可落地的参考。资源虽小却把二次开发中最常见的拦路虎拆解成可读性强的示例便于举一反三。 QGC全称QGroundControl是目前开源无人机领域用得最多的一款跨平台地面站基于Qt/C编写界面层用QML支持PX4和ArduPilot两大飞控体系。它做二次开发的门槛不算高但坑确实不少尤其是不熟悉Qt工程结构和QML动态加载机制的人经常会在编译阶段就卡上两三天。这篇文章我基于实际跑通的“QGC二次开发入门教程[项目代码]”这套代码把环境准备、源码结构、扩展点、核心改法以及我踩过的坑一次说完适合刚接触QGC源码、想在官方地面站基础上加自己功能模块的开发者参考。1. 环境准备Ubuntu 22.04下最省心的编译方案1.1 Qt版本和依赖库先统一再动手QGC对Qt版本很挑剔官方长期用的是Qt 5.15系列我实测在Ubuntu 22.04上直接用apt装Qt 5.12会直接编译失败原因是QGC 4.2以上大量使用了Qt 5.15才有的QML特性。所以第一步就是把Qt 5.15.2装好。去Qt官网下载在线安装器安装时注意勾选这几个组件Qt 5.15.2GCC 64-bitQt ChartsQt LocationQt WebEngineQt MultimediaQt Serial Port这几个是QGC编译的强依赖。其中Qt Location特别容易漏漏了之后编译到中途会报一些“QtLocation/QGeoServiceProvider not found”之类的错。Qt WebEngine体积比较大下载时间长但这个东西不能省QGC的视频显示和部分内置网页功能依赖它。Ubuntu系统层面还需要装一些库sudo apt update sudo apt install -y build-essential git cmake ninja-build \ libgl1-mesa-dev libglu1-mesa-dev libsqlite3-dev \ libudev-dev libsdl2-dev libgstreamer1.0-dev \ libgstreamer-plugins-base1.0-dev libssl-dev这些库对应QGC的串口通信、USB热插拔、视频流处理等功能。如果漏了libudev-dev编译串口模块时会报找不到libudev.h这类错误信息比较明确缺哪个装哪个就行。1.2 源码目录结构先看这几个关键模块源码拉下来之后不要急着改先把目录结构过一遍。QGC的代码量不小但二次开发真正频繁接触的其实就几个目录目录作用src/ui主界面、工具栏、设置页等QML定义src/MissionManager航线规划、任务上传下载相关逻辑src/Vehicle飞行器对象封装含状态、参数、指令接口src/AutoPilotPlugin飞控插件PX4和ArduPilot各自独立实现src/Comm通信链路MAVLink收发、串口、UDP、TCPsrc/qml全局QML组件比如QGCButton、QGCFileDialog等src/FlightDisplay飞行界面、地图、HUDsrc/Analyzer日志分析模块二次开发有个基本判断标准凡是界面改动基本都在src/ui和src/qml下做凡是逻辑功能改动90%会和src/Vehicle、src/MissionManager、src/AutoPilotPlugin这三个目录打交道如果要做自定义通信协议那src/Comm和mavlink子模块才是主战场。2. 二次开发的核心扩展点改哪里才能不白干2.1 QGC的“QML C”架构到底怎么理解不少人有误解以为QGC完全靠QML写界面、C只做底层。实际它用的是Qt的“C定义业务对象 QML做界面绑定”这套混编模式。业务层飞控指令、状态机、参数解析全部是C对象然后通过qmlRegisterType或qmlRegisterSingletonType把对象注册进QML引擎界面里直接用属性绑定、信号槽调用。举个例子界面上显示飞行高度QML里写的是Text { text: vehicle.coordinate.altitude.toFixed(1) m }这个vehicle对象是C的Vehicle类的实例通过qmlRegistration注册到全局上下文。所以二次开发时你想加一个新的业务逻辑最推荐的方式不是在QML里用JavaScript硬写而是在C里做一个业务对象用Q_INVOKABLE暴露接口再在QML里调用。这个思路最大的好处是你可以在不破坏QGC原有代码的前提下以“增量插件”的方式加功能后续升级QGC官方版本时核心改动不会被覆盖。2.2 三个最常用的扩展点工具条、主界面、MAVLink消息工具条扩展是最高频的改法。QGC主界面顶部有一条工具条对应源码是src/ui/toolbar/MainToolBar.qml。里面的按钮基本都是ToolStripButton组件新增一个按钮只需要照着写ToolStripButton { id: customRtlButton text: qsTr(Custom RTL) iconSource: /qmlimages/customRtlIcon.svg onClicked: { mainWindow.showCustomRTLDialog() } }当然mainWindow.showCustomRTLDialog()这个方法得你自己加或者你在某个C对象里写好然后在QML里创建实例调用。第二个扩展点是主界面独立页面。QGC的规划界面PlanView、飞行界面FlyView都是单独的QML页面由MainRootWindow.qml通过栈式窗口管理。如果你想加一个“数据回放”或“设备校准”的独立页面可以去src/ui下新建一个XxxView.qml然后在MainRootWindow.qml里注册把它挂到导航栏上。第三个扩展点是MAVLink自定义消息。如果你用的飞控端自己也改了协议需要在QGC接收和解析自定义MAVLink消息那就要在mavlink子模块里添加自己的消息定义XML再用mavgen重新生成C语言代码。这块经常被忽略很多人直接在C里手动解析数据流其实官方MAVLink工具链已经把这些重复工作自动化了。3. 项目代码实战做一个“自定义返航”功能并加入界面3.1 在工具条上增加一个按钮入口我这里用一套能直接编译跑的简化代码来演示。这套“QGC二次开发入门教程[项目代码]”做的事很简单在飞行界面顶部工具条加一个“返航”按钮点击后弹出一个自定义对话框确认后发送自定义MAVLink消息给飞控。先改MainToolBar.qml。在文件末尾的某个ToolStrip下添加按钮项ToolStripButton { id: customRtlBtn text: qsTr(My RTL) iconSource: /qmlimages/MapRTL.svg visible: mainWindow.isFlyView onClicked: { customActionController.showRtlConfirmDialog() } }这里customActionController是一个C对象我们在下一步创建。3.2 用C注册一个业务控制器新建一个CustomActionController类继承QObject声明一个Q_INVOKABLE方法showRtlConfirmDialog()然后在里面用QML对话框组件弹出确认框。class CustomActionController : public QObject { Q_OBJECT public: explicit CustomActionController(QObject* parent nullptr); public slots: void showRtlConfirmDialog() { QmlObjectListModel* model ...; // 这里通过QML引擎创建对话框 qmlPlacedObject qmlContext(this)-createObjWithContext(...); } // 这里真正发送MAVLink指令 Q_INVOKABLE void sendCustomRtlCommand() { if (_vehicle) { _vehicle-sendCommand(MAV_CMD_DO_SET_MODE, MAV_COMP_ID_AUTOPILOT1, params); } } };这种方式的好处是C只负责提供能力界面交互完全交给QML职责分离也方便后续替换UI。然后需要在QGC启动时把这个控制器注册到QML环境。在QGCApplication.cc或者MainRootWindow.qml里最方便的做法是qmlRegisterTypeCustomActionController(CustomLib, 1, 0, CustomActionController);在QML里直接import CustomLib 1.0 CustomActionController { id: customActionController }3.3 自定义MAVLink消息的添加和解析上面发送的MAV_CMD_DO_SET_MODE是标准指令但如果你想要一个真正属于自己的指令可以定义自定义MAVLink消息。操作方法是编辑mavlink/message_definitions/v1.0/common.xml为了不影响官方文件建议复制成custom.xml并引用message id42000 nameMAV_CMD_CUSTOM_RTL descriptionCustom return-to-launch command/description param index1Reserved/param param index2RTL altitude/param /message然后在飞行器固件侧也要同步生成并解析。这套做法在PX4社区比较成熟ArduPilot侧则需要写自定义MAVLink handler因为QGC和固件之间必须用同一套消息定义。如果不想动MAVLink体系也可以直接用现成的MAV_CMD_DO_SET_MODE加自定义参数组合但那样扩展性差稍微改个字段就要同步改两头的代码长期维护起来很累。3.4 编译验证qmake还是CMakeQGC从4.2版本开始两者都支持但我建议直接用Qt Creator打开项目根目录的QGroundControl.pro让它生成Shadow Build目录用qmake方式构建。原因是QGC的cmake配置流程相对复杂容易出现依赖探测问题qmake路径遇到问题的概率小很多。编译命令mkdir build cd build qmake ../QGroundControl.pro make -j$(nproc)整个编译过程在i7处理器、16G内存的机器上大概需要10到15分钟。首次编译会拉取mavlink子模块和部分第三方库如果网络不稳定会卡住建议提前把子模块更新完git submodule update --init --recursive编译成功后运行./build/QGroundControl如果工具条和自定义对话框都能正常显示说明整套垂二次开发链路已经完整跑通。这一步对你后续做任何功能开发都是最重要的地基。4. 常见问题与排查技巧实录4.1 编译期最常见的三类错误第一类是缺Qt模块。报错通常是Project ERROR: Unknown module(s) in QT: charts这类。解决方式是回到Qt安装器里把缺的组件补上或者检查Qt Creator的Kit是否指向了正确的Qt版本。这个错误90%是Kit选错导致的有时候系统里有多个Qt版本Qt Creator自动选了5.12而不是5.15。第二类是依赖库缺失。比如fatal error: libudev.h: No such file or directory直接sudo apt install libudev-dev就能解决。但要注意的是QGC源码里有些模块是可选编译的比如OpenCV相关的图像处理少装一个库可能导致整个编译中断此时可以通过qmake的CONFIG选项关闭对应模块比如qmake CONFIGnoOpenCV ../QGroundControl.pro第三类是自定义QML组件找不到。这种报错一般在运行时出现比如qrc:/qml/MainToolBar.qml:5 Cannot load module QtQuick.Layouts。这种问题集中在Qt版本不匹配或者你没有把自定义QML文件加进qrc资源文件。QGC几乎所有QML都是编译进qrc的你新增的QML文件必须手动添加进.qrc列表里这个操作经常被忽略。4.2 运行时程序启动即崩溃的排查思路启动即崩溃的情况多半是C插件注册时访问了空对象。比如我们上面写的CustomActionController的构造函数里如果直接调用了qgcApp()-toolbox()-multiVehicleManager()-activeVehicle()此时飞行器对象还没创建返回的就是nullptr解引用直接段错误。排查方法很简单在Qt Creator里以Debug模式跑崩溃后看堆栈会定位到具体哪一行C代码出了问题。我遇到过一种特殊情况崩溃发生在QML首次加载阶段堆栈显示是在QQmlEngine::load里但这种问题往往不是QML语法错误而是QML里调用了不存在的方法或属性。这时候建议用QML_IMPORT_TRACE1环境变量启动程序它会打印所有QML模块的加载过程很容易看出是哪个自定义模块没找到、哪个组件的依赖没解析成功。4.3 版本管理和代码合并的两个心得QGC版本更新过快自己改过的代码很容易在pull上游代码时出现冲突。我的做法是把二次开发都集中到一个独立的git分支上而且在代码里做统一标记。比如所有新增的C类文件都在文件头加三行注释// CUSTOM BEGIN // Second development module // CUSTOM END 这样即使冲突也能通过搜索CUSTOM标记快速定位到自己的代码。还有一个经验是尽量少直接修改QGC原生QML文件改用加载“外部覆盖层”的方式。QGC本身支持在命令行指定额外的QML路径把你自己的QML文件放到一个独立目录用-qml-dir参数加载这样升级上游代码时不需要处理QML层冲突只需要保证C接口不变。这个方法在官方文档里提过但实际用的人不多实际操作时对代码组织能力要求比较高适合功能模块比较大的团队项目使用。4.4 运行时高频报错速查表报错现象常见原因解决思路QML模块未找到缺少对应Qt模块检查Qt Kit版本安装Qt Charts / Location工具条按钮不出现QML文件未加入qrc打开.qrc文件确认新文件已添加点击按钮无反应QML回调未绑定到C方法检查Q_INVOKABLE声明和对象是否已注册MAVLink消息发送失败mavlink子模块未更新执行git submodule update --init --recursive启动后无地图显示Qt Location配置缺失检查系统网络部分地图源需联网加载自定义页面显示空白页面缺少StackView加载参数在MainRootWindow.qml中正确注册页面并传参这些坑大部分是我自己在做“QGC二次开发入门教程[项目代码]”时趟过的交叉检验过不同Ubuntu版本、不同Qt版本最终稳定跑通的就是上面这套组合。你按照这套流程走第一天到第二天基本能把编译环境搞定第三天开始就能专心写自己的功能模块了。本文还有配套的精品资源点击获取