crazyswarm 接口文档¶

简介¶

简述：该文件实现了Crazyswarm类，用于支持RflySim平台中多无人机蜂群编队的控制与调度，提供统一的多机管控接口。

在无人机研究与应用中，多无人机蜂群协同是当前的热点方向，需要便捷的多机统一管理接口来完成编队控制、协同任务规划等功能开发。本模块针对Crazyflie系列无人机以及仿真环境下的蜂群任务场景设计，适配RflySim的仿真框架，能够帮助用户快速完成多无人机的状态读取、统一指令下发，适用于蜂群编队算法验证、协同任务仿真测试等开发场景，降低多无人机协同开发的接口适配复杂度。

快速开始¶

最简可用示例，复制后修改最少配置即可运行。

from RflySimSDK.swarm import Crazyswarm
import time

# 1. 初始化1架无人机的蜂群控制对象，使用默认配置文件路径
swarm = Crazyswarm(num=1)
# 2. 获取所有无人机对象列表
all_cfs = swarm.allcfs

if __name__ == "__main__":
    # 3. 解锁无人机，进入起飞准备状态
    all_cfs.takeoff(0.5, 2.0)
    # 4. 悬停2秒保持当前高度
    time.sleep(2)
    # 5. 降落回地面
    all_cfs.land(0.0, 2.0)
    # 6. 等待降落完成
    time.sleep(2)

环境与依赖¶

Python 环境：>= 3.8.10
依赖库：crazyflie
前置准备：调用此接口前，需要提前导入RflySimSDK的swarm模块以获取该模块下的Crazyswarm类。

核心接口说明¶

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

全局常量与枚举定义¶

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

独立常量¶

无

全局/独立函数¶

无

`Crazyswarm` 类¶

用于管理多架 Crazyflie 无人机集群，支持在 RflySim 仿真环境中初始化并配置集群参数。

`init(crazyflies_yaml=None, parent_parser=None, args=None, num=1, ids=None, mode=7)`¶

功能说明：初始化 Crazyswarm 无人机集群对象 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`crazyflies_yaml`	`Any`	否	`None`	无人机配置文件路径，用于加载集群中各无人机的参数
`parent_parser`	`Any`	否	`None`	父命令行解析器，用于扩展命令行参数
`args`	`Any`	否	`None`	命令行解析后的参数对象
`num`	`Any`	否	`1`	集群中无人机的总数量
`ids`	`Any`	否	`None`	各无人机的ID列表，若为None则自动分配ID
`mode`	`Any`	否	`7`	集群仿真运行模式

返回值 (Returns)：

Crazyswarm 实例对象

异常 (Raises)：

无

进阶用法示例¶

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

本示例实现了异源无人机群与地面无人车的异构协作场景，通过异步控制实现集群分散任务的并行执行，同时完成批量无人机的状态采集与轨迹下发：

import RflySimSDK.swarm as rfly_swarm
import asyncio

# 初始化集群对象，连接5架Crazyflie无人机与2辆groundbot地面车
my_swarm = rfly_swarm.Crazyswarm(vehicle_list=[f'cf_{i}' for i in range(5)] + ['gb_0', 'gb_1'])
async def single_vehicle_task(veh_id, target_pos):
    # 单载具异步任务：到达目标后等待其他载具完成任务
    await my_swarm.goto_async(veh_id, target_pos, timeout=8)
    await my_swarm.hover_async(veh_id, 1.5)

async def main_coop_task():
    # 批量生成异构协作任务
    task_list = []
    # 给5架无人机分配不同的搜索区域坐标
    uav_tasks = [(i, [1.2*i, 0, 1.5]) for i in range(5)]
    # 给2辆地面车分配边缘巡逻点坐标
    gb_tasks = [(5, [-3, 0, 0]), (6, [3, 0, 0])]
    for veh_info in uav_tasks + gb_tasks:
        task_list.append(single_vehicle_task(*veh_info))
    # 异步并发执行所有任务，大幅缩短整体任务耗时
    await asyncio.gather(*task_list)
    # 批量获取所有载具的位置状态，统一记录数据
    all_pos = my_swarm.get_all_vehicles_position()
    print("异构协作任务完成，所有载具位置：", all_pos)

# 启动异步任务
my_swarm.takeoff_all(altitude=1.5, duration=3)
asyncio.run(main_coop_task())
my_swarm.land_all()

注意事项与避坑指南¶

集群初始化参数匹配：初始化Crazyswarm类时传入的载具ID列表必须与RflySim可视化配置界面中设置的载具编号完全一致，否则会出现载具连接失败或控制错位的问题。
异步控制调用限制：异步控制方法仅可在async修饰的异步任务中通过await调用，不可直接在同步主流程中执行，否则会导致控制指令丢失，所有载具无响应。
批量操作超时设置：执行全集群起飞、降落这类批量操作时，需要根据集群规模合理设置飞行时长参数，过小的时长会导致部分载具未完成动作就进入下一任务，引发炸机碰撞。
异构协作通讯隔离：同时控制无人机和地面载具时，不同类型载具的控制指令走不同的通讯通道，不要直接用统一的位置控制接口修改地面车的Z轴高度，避免无效指令阻塞通讯队列。

更新日志¶

2024-07-18: fix:更新API主页索引
2024-02-23: feat: support crazyflie simulation