QGCCtrlAPI 接口文档¶
简介¶
简述：该文件实现了与QGroundControl地面站交互的控制接口，同时提供了先进先出缓存工具类，支持PX4飞控无人机任务中通过QGroundControl完成下发控制指令、获取状态信息的交互工作。
在RflySim无人机仿真任务开发流程中，QGroundControl是常用的地面站交互工具，负责提供无人机可视化监控、任务指令下发、飞行参数调试的入口。本模块封装了适配RflySim仿真环境的QGroundControl通信交互逻辑，可以帮助开发者便捷地实现仿真任务对地面站控制功能的调用，同时内置的fifo缓存类可以稳定处理交互过程中的流式数据，保障通信时序的正确性。
该模块适用于需要和QGroundControl地面站联动的仿真任务开发场景，比如第三方算法接入仿真时的指令中转、地面站手动参与仿真控制、飞行状态可视化调试等场景，是RflySimSDK中完成地面站交互功能的核心基础模块。
快速开始¶
最简可用示例，复制后修改最少配置即可运行。
from RflySimSDK.phm import QGCCtrlAPI
import time
# 1. 初始化QGC控制API，指定无人机ID为1
qgc_ctrl = QGCCtrlAPI(ID=1)
# 2. 发送解锁指令给QGC（MAV_CMD_COMPONENT_ARM_DISARM=400，param1=1表示解锁）
qgc_ctrl.SendQgcCmdLong(command=400, param1=1)
print("已发送无人机解锁指令")
time.sleep(2) # 等待解锁完成
# 3. 发送起飞指令（MAV_CMD_NAV_TAKEOFF=22，param1是目标高度，设置为5米）
qgc_ctrl.SendQgcCmdLong(command=22, param1=5)
print("已发送起飞指令，目标高度5米")
# 4. 获取QGC输出的文本内容（示例，修改为你的实际flag文件路径）
flag_file_path = "C:/RflySim/WorkSpace/qgc_flag.txt"
content = qgc_ctrl.getTxtContent(flag_file_path)
print(f"获取到QGC文本内容: {content}")
# 5. 复制QGC日志文件到目标位置（示例，修改为你自己的源和目标路径）
# source_log = "C:/Program Files/QGroundGroundControl/log.txt"
# target_log = "./my_flight_log.txt"
# qgc_ctrl.copyLogFile(source_log, target_log)
# 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"
进阶用法示例¶
展示复杂组合场景（如多类协作、异步控制、批量操作）
import RflySimSDK.phm as phm
import threading
import time
# 实现多线程异步日志获取与批量存储：多任务协作场景
def async_log_worker(qgc_api, fifo, req_ids):
# 批量请求多架无人机日志
for req_id in req_ids:
qgc_api.ReqQgcLog(req_id)
time.sleep(0.5)
# 获取所有日志内容后写入管道供主线程处理
all_log = qgc_api.getTxtContent()
fifo.write(all_log.encode('utf-8'))
# 初始化接口对象
qgc_ctrl = phm.QGCCtrlAPI()
log_fifo = phm.fifo()
# 需要拉取日志的无人机编号列表
target_uav_ids = [1, 3, 5, 7]
# 启动异步线程处理日志请求，避免阻塞主控制流程
log_thread = threading.Thread(target=async_log_worker, args=(qgc_ctrl, log_fifo, target_uav_ids))
log_thread.start()
# 主任务继续执行无人机飞行控制，同时异步获取日志
qgc_ctrl.SendQgcCmdLong("mode takeoff")
# 从管道读取异步获取到的批量日志
raw_log = log_fifo.read()
parsed_log = raw_log.decode('utf-8')
# 将日志批量拷贝到本地指定目录备份
qgc_ctrl.copyLogFile("./uav_batch_log_backup/")
注意事项与避坑指南¶
- 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下载日志的接口，适用于硬件在环和软件在环