Crazyswarm Interface Documentation¶

Introduction¶

Overview: This file implements the Crazyswarm class to support multi-UAV swarm formation control and scheduling within the RflySim platform, providing a unified interface for managing multiple drones.

In UAV research and application, cooperative swarm operations are a current hotspot, requiring convenient unified management interfaces to facilitate development of formation control, coordinated mission planning, and other functionalities. This module is designed for Crazyflie-series UAVs and swarm mission scenarios in simulation environments, compatible with the RflySim simulation framework. It enables users to quickly perform state reading and unified command issuance for multiple UAVs, making it suitable for development scenarios such as swarm formation algorithm validation and cooperative mission simulation testing—significantly reducing the complexity of interface adaptation in multi-UAV cooperative development.

Quick Start¶

Minimal working example; copy and modify minimal configuration to run.

from RflySimSDK.swarm import Crazyswarm
import time

# 1. Initialize swarm control object for 1 UAV using default config file path
swarm = Crazyswarm(num=1)
# 2. Get list of all UAV objects
all_cfs = swarm.allcfs

if __name__ == "__main__":
    # 3. Unlock UAVs and enter takeoff-ready state
    all_cfs.takeoff(0.5, 2.0)
    # 4. Hover for 2 seconds at current altitude
    time.sleep(2)
    # 5. Land back to ground
    all_cfs.land(0.0, 2.0)
    # 6. Wait for landing to complete
    time.sleep(2)

Environment and Dependencies¶

Python Environment: >= 3.8.10
Dependencies: crazyflie
Prerequisites: Before calling this interface, import the swarm module from RflySimSDK to access the Crazyswarm class within this module.

Core Interface Description¶

The module crazyswarm.py includes configuration variables, helper functions, and core business classes.

Global Constants and Enumerations¶

This section lists all globally accessible constants and enumerations defined in the module.

Standalone Constants¶

None

Global/Standalone Functions¶

None

`Crazyswarm` Class¶

Manages a cluster of Crazyflie UAVs, supporting initialization and configuration of cluster parameters within the RflySim simulation environment.

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

Functionality: Initializes the Crazyswarm UAV cluster object.
Parameters (Args):

Parameter Name	Type	Required	Default	Description
`crazyflies_yaml`	`Any`	No	`None`	Path to the UAV configuration file, used to load parameters for each UAV in the cluster
`parent_parser`	`Any`	No	`None`	Parent command-line argument parser, used to extend command-line arguments
`args`	`Any`	No	`None`	Parsed command-line argument object
`num`	`Any`	No	`1`	Total number of UAVs in the cluster
`ids`	`Any`	No	`None`	List of UAV IDs; if `None`, IDs are auto-assigned
`mode`	`Any`	No	`7`	Cluster simulation execution mode

Returns:

Instance of Crazyswarm

Raises:

None

Advanced Usage Examples¶

Demonstrates complex composite scenarios (e.g., heterogeneous collaboration, asynchronous control, batch operations)

This example implements a heterogeneous collaboration scenario involving heterogeneous UAVs and ground robots (groundbots), achieving parallel execution of distributed swarm tasks via asynchronous control, while simultaneously collecting batch UAV states and下发ing trajectories:

```python import RflySimSDK.swarm as rfly_swarm import asyncio

Initialize swarm object connecting 5 Crazyflie UAVs and 2 groundbots¶

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): # Single-vehicle asynchronous task: reach target, then wait for others to complete 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(): # Batch generate heterogeneous cooperative tasks task_list = [] # Assign different search area coordinates to 5 UAVs uav_tasks = [(i, [1.2i, 0, 1.5]) for i in range(5)] # Assign edge patrol points to 2 groundbots 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)) # Asynchronously execute all tasks in parallel, significantly reducing total task duration await asyncio.gather(*task_list) # Batch retrieve position states of all vehicles for unified data logging all_pos = my_swarm.get_all_vehicles_position() print("Heterogeneous cooperative task completed; all vehicle positions:", all_pos)

Start asynchronous tasks¶

my_swarm.takeoff_all(altitude=1.5, duration=3) asyncio.run(main_coop_task()) my_swarm.land_all()

Notes and Pitfall Avoidance Guide¶

Cluster Initialization Parameter Matching: The vehicle ID list passed when initializing the Crazyswarm class must exactly match the vehicle numbers configured in the RflySim visualization interface; otherwise, vehicle connection failures or control misalignment issues may occur.
Asynchronous Control Invocation Limitation: Asynchronous control methods can only be invoked via await within an async-decorated asynchronous task; direct execution within a synchronous main flow will result in lost control commands and all vehicles becoming unresponsive.
Batch Operation Timeout Configuration: When performing batch operations such as collective takeoff or landing, flight duration parameters must be set appropriately based on cluster size; insufficient duration may cause some vehicles to proceed to the next task before completing their action, potentially leading to crashes or collisions.
Heterogeneous Collaboration Communication Isolation: When simultaneously controlling drones and ground vehicles, control commands for different vehicle types traverse distinct communication channels; avoid directly modifying the Z-axis height of ground vehicles via a unified position control interface, as this may cause invalid commands to block the communication queue.

Changelog¶

2024-07-18: fix: Update API homepage index
2024-02-23: feat: Support Crazyflie simulation