AutoMavCtrl 接口文档¶

简介¶

简述：AutoMavCtrl.py 是 RflySimSDK 平台中用于无人机集群自动化控制的核心模块，提供从环境初始化、仿真监控到多机协同控制的完整闭环管理能力。

本模块专为复杂无人机集群仿真任务设计，整合了环境配置注册、仿真状态监控与自动化控制三大功能层级。InitMavAutoEnv 类负责初始化多机仿真环境并与底层通信协议对接；AutoMavMonitor 与 AutoMavCtrler 分别实现状态监视线程和独立控制线程的托管，支持通过 MavMonitor 与 SimMonitor 两级监控机制对仿真软件实例及无人机线程进行生命周期管理。该模块适用于需要高可靠性、可扩展集群控制的研究与工程场景，如编队飞行、协同避障及分布式任务规划等。

环境与依赖¶

Python 环境：>= 3.8.10
依赖库：Ass、AutoMavCmd、AutoMavDB、AutoREG、AutoVisConf、PX4MavCtrlV4、UE4CtrlAPI、cv2、numpy、os、re、subprocess、sys、threading、time、tkinter、tkinter.messagebox
前置准备：调用此接口前，必须先确保仿真环境已初始化并建立与 MAVLink 飞控的通信连接。

核心接口说明¶

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

全局常量与枚举定义¶

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

独立常量¶

无

枚举定义¶

`MAV_COMMON_REG`¶

名称	类型	值	说明
`AutoMavThreadsContainer`	`unknown`	`[]`	-
`SimProcessStartContainer`	`unknown`	`[]`	-
`SimProcessEndContainer`	`unknown`	`[]`	-
`Lock`	`str`	`threading.Lock()`	-
`DataRecordThreadsContainer`	`unknown`	`[]`	-
`SimProcessObj`	`unknown`	`None`	-

全局/独立函数¶

`MavMonitor()`¶

功能说明：监控所有无人机实例线程 AutoMavCtrler.AutoMavThread。当所有无人机初始化完成后，启动所有线程 AutoMavCtrler.AutoMavRun。 参数列表：无 返回值：无异常：无

`SimMonitor()`¶

功能说明：监控所有仿真软件对象，仅打开机架序号最小的 bat 脚本。 参数列表：无 返回值：无异常：无

`ReSetREG()`¶

功能说明：（功能描述待补充） 参数列表：无 返回值：无异常：无

`InitMavAutoEnv` 类¶

用于初始化多无人机自动化仿真环境的配置类，支持多种机型配置、地图加载和Bat环境参数设置。

`init(mav, conf, map)`¶

功能说明：初始化无人机自动化仿真环境配置器 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`mav`	`object`	是	-	无人机控制对象
`conf`	`object`	是	-	环境配置对象
`map`	`object`	是	-	地图配置对象

返回值 (Returns)：

InitMavAutoEnv 实例对象

异常 (Raises)：

无

`InitMAVEnv()`¶

功能说明：初始化MAV环境 参数列表 (Args)：

无

返回值 (Returns)：

无

异常 (Raises)：

无

`BInfo()`¶

功能说明：配置无人机信息，包括无人机数量、机型框架、机型框架数量、机型框架字典和测试模式等参数 参数列表 (Args)：

无

返回值 (Returns)：

无

异常 (Raises)：

无

`BReset()`¶

功能说明：将Bat环境重置为原始状态 参数列表 (Args)：

无

返回值 (Returns)：

无

异常 (Raises)：

无

`BatEnvConf()`¶

功能说明：在多机场景下修改Bat环境的启动参数、索引和飞机数量，仅保留一个Bat软件环境的启动配置、起始索引和飞机数量 参数列表 (Args)：

无

返回值 (Returns)：

无

异常 (Raises)：

无

`BSingle(Path)`¶

功能说明：配置单机路径 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`Path`	`str`	是	-	路径字符串

返回值 (Returns)：

无

异常 (Raises)：

无

`GetPath(Frame)`¶

功能说明：获取指定机型的路径配置 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`Frame`	`str`	是	-	机型框架名称

返回值 (Returns)：

str: 对应机型的路径配置

异常 (Raises)：

无

`BVNum(path, num)`¶

功能说明：设置路径对应的飞机数量 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`path`	`str`	是	-	路径字符串
`num`	`int`	是	-	飞机数量

返回值 (Returns)：

无

异常 (Raises)：

无

`BEnv(Path, Index, Num)`¶

功能说明：配置Bat环境的路径、起始索引和飞机数量 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`Path`	`str`	是	-	环境路径
`Index`	`int`	是	-	起始索引
`Num`	`int`	是	-	飞机数量

返回值 (Returns)：

无

异常 (Raises)：

无

`BEMap(path)`¶

功能说明：设置环境地图，支持草地(Grasslands)、旧工厂(OldFactory)、真实森林湖(RealForestBLake)、社区公园(NeighborhoodPark)等场景 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`path`	`str`	是	-	地图场景路径

返回值 (Returns)：

无

异常 (Raises)：

无

`BMap()`¶

功能说明：配置地图环境 参数列表 (Args)：

无

返回值 (Returns)：

无

异常 (Raises)：

无

`AutoMavMonitor` 类¶

无人机自动监控类，用于多线程监控仿真进程状态、数据记录及仿真生命周期管理。

`init()`¶

功能说明：初始化监控器实例 参数列表 (Args)：无参数

返回值 (Returns)：

AutoMavMonitor 实例对象

异常 (Raises)：

无

`AutoMavThreadMonitor()`¶

功能说明：自动多旋翼线程监控方法，用于监控自动多旋翼相关线程的运行状态。 参数列表 (Args)：无参数

返回值 (Returns)：

无

异常 (Raises)：

无

`SimProcessStartThreadMonitor()`¶

功能说明：仿真进程启动线程监控方法。将序列号最小的机型（Frame type）设置为主控批处理（main Bat），即为此批处理启动所有仿真软件。因此需要打开序列号最小的批处理——四旋翼（AutoREG.MAV_FRAME [1,2,3]）。 参数列表 (Args)：无参数

返回值 (Returns)：

无

异常 (Raises)：

无

示例：

monitor = AutoMavMonitor()
monitor.SimProcessStartThreadMonitor()  # 启动最小序列号机型的仿真进程监控

`SimProcessEndThreadMonitor()`¶

功能说明：仿真进程结束线程监控方法。将序列号最小的机型（Frame type）设置为主控批处理（main Bat），即为此批处理启动所有仿真软件。因此需要打开序列号最小的批处理——四旋翼（AutoREG.MAV_FRAME [1,2,3]）。 参数列表 (Args)：无参数

返回值 (Returns)：

无

异常 (Raises)：

无

示例：

monitor = AutoMavMonitor()
monitor.SimProcessEndThreadMonitor()  # 结束最小序列号机型的仿真进程监控

`DataRecordThreadMonitor()`¶

功能说明：数据记录线程监控方法，用于监控数据记录线程的运行状态。 参数列表 (Args)：无参数

返回值 (Returns)：

无

异常 (Raises)：

无

`AutoMavCtrler` 类¶

无人机自动化控制器类，用于实现对多旋翼飞行器的自动化控制。

`init(mav, conf)`¶

功能说明：初始化 AutoMavCtrler 控制器实例，配置仿真环境与载具类型。

参数列表 (Args)：

参数	类型	说明
`mav`	`object`	MAVLink 连接对象或仿真接口实例
`conf`	`list`	配置列表，格式为 `['Quadcopter', 'SITL', 3]`，分别表示载具类型、仿真模式、数量等配置

返回值 (Returns)：无

异常 (Raises)：无

`InitModelConf()`¶

功能说明：初始化自定义模型框架和配置路径。支持多种飞行器类型：

1: 四旋翼（Quadrotor）
2: 固定翼（Fixedwing）
3: 无人船/水面艇（USV）

参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`ctrlseq`	任意类型	是	`None`	控制序列，用于指定要执行的 MAV 命令序列

返回值 (Returns)：无返回值说明

异常 (Raises)：无

`is_alive()`¶

功能说明：检查控制器是否处于活动状态。 参数列表 (Args)：无参数

返回值 (Returns)：bool - 控制器活动状态，True表示活跃，False表示非活跃。 异常 (Raises)：无

`calculate_flight_status(angular_velocity_data)`¶

功能说明：根据角速度数据计算飞行状态。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
angular_velocity_data	-	是	-	角速度数据，用于计算飞行状态

返回值 (Returns)：计算得到的飞行状态信息。 异常 (Raises)：无

`GetDesiredPV()`¶

功能说明：获取期望的位置和速度（Position and Velocity）。 参数列表 (Args)：无参数

返回值 (Returns)：期望的位置和速度信息。 异常 (Raises)：无

`Deviation(desired, true)`¶

功能说明：计算期望值与实际值之间的偏差。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
desired	-	是	-	期望的目标值
true	-	是	-	实际的真实值

返回值 (Returns)：期望值与实际值之间的偏差量。 异常 (Raises)：无

`CMDANA(cmd)`¶

功能说明：对控制指令进行分析处理（Command Analysis）。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
cmd	-	是	-	待分析的控制指令

返回值 (Returns)：指令分析结果。 异常 (Raises)：无

`Get_TestResult(test_result)`¶

功能说明：获取或处理测试结果。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
test_result	-	是	-	测试产生的原始结果数据

返回值 (Returns)：处理后的测试结果。 异常 (Raises)：无

进阶用法示例¶

展示复杂组合场景（如多类协作、异步控制、批量操作）

from RflySimSDK.phm.AutoMavCtrl import InitMavAutoEnv, AutoMavCtrler, AutoMavMonitor
import threading
import time

# 场景：批量初始化多架无人机并异步监控
class BatchMavController:
    def __init__(self, mav_num=5):
        self.mav_env = InitMavAutoEnv()
        self.controllers = []
        self.monitors = []
        self.mav_num = mav_num

    def batch_init(self):
        """批量初始化多机环境"""
        # 配置环境参数
        self.mav_env.BatEnvConf(mavNum=self.mav_num)
        self.mav_env.BEnv()  # 启用环境

        for i in range(self.mav_num):
            # 为每架飞机创建独立控制器
            ctrl = AutoMavCtrler()
            ctrl.InitMavEnv(mavID=i)
            ctrl.InitMavComm()  # 初始化通信

            # 创建监控器
            mon = AutoMavMonitor()

            self.controllers.append(ctrl)
            self.monitors.append(mon)

    def async_start_all(self):
        """异步启动所有仿真进程"""
        threads = []
        for i, (ctrl, mon) in enumerate(zip(self.controllers, self.monitors)):
            t = threading.Thread(
                target=self._single_mav_process,
                args=(i, ctrl, mon)
            )
            threads.append(t)
            t.start()

        return threads

    def _single_mav_process(self, mav_id, ctrl, mon):
        """单架无人机的完整处理流程"""
        # 启动仿真监控
        mon.SimProcessStartThreadMonitor(mavID=mav_id)

        # 启动仿真进程
        ctrl.StartSimProcess()
        ctrl.SimProcessLoopStart()

        # 数据记录监控
        mon.DataRecordThreadMonitor(mavID=mav_id)
        ctrl.DataRecordLoop()

        # 结束流程
        ctrl.SimProcessLoopEnd()
        ctrl.EndSimProcess()
        mon.SimProcessEndThreadMonitor(mavID=mav_id)

        # 清理通信
        ctrl.EndMavComm()

# 使用示例
if __name__ == "__main__":
    batch_ctrl = BatchMavController(mav_num=3)
    batch_ctrl.batch_init()
    threads = batch_ctrl.async_start_all()

    # 等待所有线程完成
    for t in threads:
        t.join()
    print("所有无人机批量任务完成")

注意事项与避坑指南¶

InitMavEnv 与 InitMavComm 调用顺序：必须先调用 InitMavEnv 初始化环境配置，再调用 InitMavComm 建立通信连接，颠倒顺序会导致通信初始化失败或获取不到正确的 MAV 参数。
BVNum 与 BSingle 的互斥使用：BVNum 用于设置批量无人机数量，BSingle 用于标记单无人机模式，两者在同一配置中可能产生冲突，需根据实际场景选择批量模式或单机构型，避免重复调用导致环境配置异常。
监控线程的生命周期管理：AutoMavMonitor 的各监控方法（如 SimProcessStartThreadMonitor、DataRecordThreadMonitor）需在对应仿真阶段开始前调用，且需确保与 AutoMavCtrler 的流程方法配对使用，提前结束或遗漏监控会导致数据记录不完整或进程状态误判。
SimProcessLoopStart 与 SimProcessLoopEnd 必须成对调用：这两个方法标记仿真主循环的边界，若因异常退出导致 SimProcessLoopEnd 未被调用，可能造成仿真进程残留、资源未释放，建议在 try...finally 结构中确保结束方法被执行。
BEMap 与 BMap 的地图加载优先级：BEMap 用于加载环境地图，BMap 用于基础地图配置，当两者同时存在时需注意加载顺序，环境地图可能覆盖基础地图的部分配置，建议在调用 BEnv 启用环境前完成所有地图相关配置，避免运行时地图参数不一致。

更新日志¶

2026-04-08: 🐛 fix: 修正变量名拼写错误
2025-04-01: fix
2024-08-02: chore:为生成html格式API添加代码注释
2024-07-18: fix:更新API主页索引
2024-05-01: fix: 增加QGC启动命令，确保不会在仿真时错误连接飞控，HITL时占用串口、或SITL时串口与UDP冲突显示。
2023-11-09: commit by Jinhu Tu
2023-11-09: fix: 增加自动化安全评估的接口类文件

AutoMavCtrl 接口文档¶

简介¶

环境与依赖¶

核心接口说明¶

全局常量与枚举定义¶

独立常量¶

枚举定义¶

MAV_COMMON_REG¶

全局/独立函数¶

MavMonitor()¶

SimMonitor()¶

ReSetREG()¶

InitMavAutoEnv 类¶

__init__(mav, conf, map)¶

InitMAVEnv()¶

BInfo()¶

BReset()¶

BatEnvConf()¶

BSingle(Path)¶

GetPath(Frame)¶

BVNum(path, num)¶

BEnv(Path, Index, Num)¶

BEMap(path)¶

BMap()¶

AutoMavMonitor 类¶

__init__()¶

AutoMavThreadMonitor()¶

SimProcessStartThreadMonitor()¶

SimProcessEndThreadMonitor()¶

DataRecordThreadMonitor()¶

AutoMavCtrler 类¶

__init__(mav, conf)¶

InitModelConf()¶

InitMavEnv()¶

SimProcessLoopStart()¶

SimProcessLoopEnd()¶

StartSimProcess()¶

EndSimProcess()¶

DataRecordLoop()¶

DataRecord()¶

InitMavComm()¶

EndMavComm()¶

AutoMavLoopStart()¶

ShowWinLoop()¶

ShowWin()¶

AutoMavRun()¶

TRIGGERMAVCMD(ctrlseq)¶

is_alive()¶

calculate_flight_status(angular_velocity_data)¶

GetDesiredPV()¶

Deviation(desired, true)¶

CMDANA(cmd)¶

Get_TestResult(test_result)¶

进阶用法示例¶

注意事项与避坑指南¶

更新日志¶

`MAV_COMMON_REG`¶

`MavMonitor()`¶

`SimMonitor()`¶

`ReSetREG()`¶

`InitMavAutoEnv` 类¶

`init(mav, conf, map)`¶

`InitMAVEnv()`¶

`BInfo()`¶

`BReset()`¶

`BatEnvConf()`¶

`BSingle(Path)`¶

`GetPath(Frame)`¶

`BVNum(path, num)`¶

`BEnv(Path, Index, Num)`¶

`BEMap(path)`¶

`BMap()`¶

`AutoMavMonitor` 类¶

`init()`¶

`AutoMavThreadMonitor()`¶

`SimProcessStartThreadMonitor()`¶

`SimProcessEndThreadMonitor()`¶

`DataRecordThreadMonitor()`¶

`AutoMavCtrler` 类¶

`init(mav, conf)`¶

`InitModelConf()`¶

`InitMavEnv()`¶

`SimProcessLoopStart()`¶

`SimProcessLoopEnd()`¶

`StartSimProcess()`¶

`EndSimProcess()`¶

`DataRecordLoop()`¶

`DataRecord()`¶

`InitMavComm()`¶

`EndMavComm()`¶

`AutoMavLoopStart()`¶

`ShowWinLoop()`¶

`ShowWin()`¶

`AutoMavRun()`¶

`TRIGGERMAVCMD(ctrlseq)`¶

`is_alive()`¶

`calculate_flight_status(angular_velocity_data)`¶

`GetDesiredPV()`¶

`Deviation(desired, true)`¶

`CMDANA(cmd)`¶

`Get_TestResult(test_result)`¶