QGCCtrlAPI 接口文档

简介

简述：该文件实现了与QGroundControl地面站交互的控制接口，同时提供了先进先出缓存工具类，支持PX4飞控无人机任务中通过QGroundControl完成下发控制指令、获取状态信息的交互工作。

在RflySim无人机仿真任务开发流程中，QGroundControl是常用的地面站交互工具，负责提供无人机可视化监控、任务指令下发、飞行参数调试的入口。本模块封装了适配RflySim仿真环境的QGroundControl通信交互逻辑，可以帮助开发者便捷地实现仿真任务对地面站控制功能的调用，同时内置的fifo缓存类可以稳定处理交互过程中的流式数据，保障通信时序的正确性。

该模块适用于需要和QGroundControl地面站联动的仿真任务开发场景，比如第三方算法接入仿真时的指令中转、地面站手动参与仿真控制、飞行状态可视化调试等场景，是RflySimSDK中完成地面站交互功能的核心基础模块。

快速开始

以下示例请求 QGroundControl 下载 1 号无人机的最新飞行日志。下载完成后返回日志文件名，超时或失败时返回空字符串。

参考例程：[RflySim安装路径]\RflySimAPIs\7.RflySimPHM\0.ApiExps\e16_QGCLoadExp

import QGCCtrlAPI


qgc = QGCCtrlAPI.QGCCtrlAPI()
logName = qgc.ReqQgcLog(CopterID=1)

if logName != "":
    print("下载完成:", logName)
else:
    print("日志下载超时或失败")

环境与依赖

• Python 环境：>= 3.8.10
• 依赖库：copy、math、os、pymavlink.dialects.v20、shutil、socket、struct、sys、threading、time
• 前置准备：调用此接口前，必须先完成RflySimSDK的安装，并且提前启动PX4飞控、QGroundControl地面站相关仿真环境。

核心接口说明

该模块 QGCCtrlAPI.py 包含了配置变量、辅助函数及核心业务类。

全局常量与枚举定义

本节列出模块中所有可直接引用的全局常量和枚举定义。

独立常量

无

---

全局/独立函数

无

---

QGCCtrlAPI 类

该类用于与QGroundControl地面站通信，实现发送PX4长命令、获取日志文本内容、复制日志文件以及请求QGC日志功能，适用于RflySim仿真中对无人机进行地面站控制和日志采集场景。

__init__(ID=1)

功能说明：初始化QGCCtrlAPI对象，绑定目标无人机ID 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
ID	任意	否	1	目标无人机的ID编号

返回值 (Returns)：

• QGCCtrlAPI 实例对象

异常 (Raises)：

• 无

---

SendQgcCmdLong(command, param1=0, param2=0, param3=0, param4=0, param5=0, param6=0, param7=0)

功能说明：向QGroundControl发送PX4格式的长命令，实现对无人机的指令控制 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
command	任意	是	-	PX4命令ID，指定要发送的指令类型
param1	任意	否	0	命令参数1
param2	任意	否	0	命令参数2
param3	任意	否	0	命令参数3
param4	任意	否	0	命令参数4
param5	任意	否	0	命令参数5
param6	任意	否	0	命令参数6
param7	任意	否	0	命令参数7

返回值 (Returns)：

• 无

异常 (Raises)：

• 无

示例：

# 初始化ID为1的无人机QGC控制对象
qgc_ctrl = QGCCtrlAPI(ID=1)
# 发送解锁命令（示例command为对应PX4解锁命令ID）
qgc_ctrl.SendQgcCmdLong(400, 1, 0, 0, 0, 0, 0, 0)

---

getTxtContent(flagFilePath)

功能说明：读取指定路径下文本文件的内容，通常用于读取QGC生成的标记文件或日志文本 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
flagFilePath	任意	是	-	待读取文本文件的路径

返回值 (Returns)：

• str: 读取到的文本文件内容

异常 (Raises)：

• 无

---

copyLogFile(source, target)

功能说明：将QGC生成的日志文件从源路径复制到目标路径，用于日志备份保存 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
source	任意	是	-	日志文件源路径
target	任意	是	-	日志文件目标路径

返回值 (Returns)：

• 无

异常 (Raises)：

• 无

---

ReqQgcLog(timeout=180, CopterID=1)

功能说明：向QGroundControl请求获取指定无人机的飞行日志，设置超时等待时间 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
timeout	任意	否	180	获取日志的最大等待超时时间，单位为秒
CopterID	任意	否	1	需要获取日志的无人机ID

返回值 (Returns)：

• 无

异常 (Raises)：

• 无

示例：

qgc_ctrl = QGCCtrlAPI(ID=1)
# 请求无人机1的日志，等待最长3分钟
qgc_ctrl.ReqQgcLog(timeout=180, CopterID=1)
# 复制日志到指定路径
qgc_ctrl.copyLogFile("qgc_default_log_path/log.txt", "my_experiment/log_20240101.txt")
# 读取日志内容
log_content = qgc_ctrl.getTxtContent("my_experiment/log_20240101.txt")

---

fifo 类

先进先出（FIFO）队列数据结构，用于存储和管理按顺序进出的数据元素，符合先写入先读取的访问规则。

__init__()

功能说明：初始化一个空的先进先出队列对象 参数列表 (Args)： 无 返回值 (Returns)：

• fifo 实例对象

异常 (Raises)： 无

---

write(data)

功能说明：向队列尾部写入一个数据元素 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
data	任意类型	是	-	待写入队列的数据元素

返回值 (Returns)： 无 异常 (Raises)： 无

---

read()

功能说明：从队列头部读取并移除最早写入的数据元素 参数列表 (Args)： 无 返回值 (Returns)：

• 任意类型: 队列头部最早写入的数据元素

异常 (Raises)： 无

示例：

from RflySimSDK.phm import fifo
# 初始化FIFO队列
fifo_queue = fifo()
# 写入数据
fifo_queue.write(10)
fifo_queue.write("hello")
# 按顺序读取数据
first_data = fifo_queue.read()
second_data = fifo_queue.read()
# 输出结果: first_data为10, second_data为"hello"

---

进阶用法示例

以下示例延长下载超时时间，并将 QGC 日志目录中的结果复制到当前程序目录。

参考例程：[RflySim安装路径]\RflySimAPIs\7.RflySimPHM\0.ApiExps\e16_QGCLoadExp

import os
import shutil

import QGCCtrlAPI


qgc = QGCCtrlAPI.QGCCtrlAPI()
logName = qgc.ReqQgcLog(timeout=300, CopterID=1)

if logName != "":
    source = os.path.join(qgc.QGCPath, logName)
    target = os.path.join(os.path.dirname(__file__), logName)
    shutil.copyfile(source, target)
    print("日志已复制到:", target)

注意事项与避坑指南

• SendQgcCmdLong长指令发送限制：该方法单条指令长度受QGC地面站通信协议限制，请勿发送长度超过1024字节的指令，过长指令会被地面站直接丢弃且无返回错误提示。
• fifo管道读写顺序依赖：使用fifo类进行进程间数据传输时，必须先完成写入操作再执行读取，空管道调用read方法会导致线程永久阻塞，无法响应其他操作。
• 日志拉取的时序要求：调用ReqQgcLog请求日志后，需要等待至少0.3秒再调用getTxtContent获取内容，未等待完成直接读取会得到空内容或者不完整的日志片段。
• copyLogFile路径格式要求：该方法要求传入的存储路径必须以斜线/结尾，若路径格式错误会导致日志文件存储失败，不会自动创建目标文件夹。

更新日志

• 2024-08-02: chore:为生成html格式API添加代码注释
• 2024-07-18: fix:更新API主页索引
• 2023-11-10: feat: 新增通过QGC下载日志的接口，适用于硬件在环和软件在环