crazyflie 接口文档¶

简介¶

简述：实现RflySim仿真环境中单机与集群蜂群无人机的基础对象管理与控制接口，支持时间调度、单无人机状态管理和全集群指令广播。

该模块是RflySim平台针对Crazyflie蜂群无人机仿真开发的底层核心接口模块，适配集群无人机仿真任务的开发需求，既可以通过Crazyflie类单独管理单架蜂群无人机的状态与控制，也可以通过CrazyflieServer类实现对整集群无人机的统一指令广播与对象管理，TimeHelper类还提供了集群仿真所需的统一时间管理能力，保障多机调度的时序一致性。

该模块适用于蜂群无人机协同任务开发、多机编队控制算法验证、集群路径规划仿真等场景，是上层蜂群任务应用开发的基础对象支撑模块。

快速开始¶

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

from RflySimSDK.swarm import Crazyflie
import time

# 1. 初始化单架无人机，ID=0，初始位置停在地面原点处
drone = Crazyflie(
    id=0,
    initialPosition=[0, 0, 0.01], # 初始位置，z设置小高度避免碰撞地面
    tf=None, # 不使用自定义坐标系变换，默认世界系
    mode=None # 使用默认控制模式
)

# 2. 设置无人机所属组，加入第0组，对应bit 0置1
drone.setGroupMask(0b00000001)

# 3. 进入主循环运行，维持无人机状态更新
drone.loop()

# 此处可添加自定义任务逻辑，比如起飞、航点飞行
time.sleep(3) # 示例：保持3秒后退出

环境与依赖¶

Python 环境：>= 3.8.10
依赖库：ctrl、numpy、threading、time
前置准备：调用此接口前，必须先完成RflySimSDK的导入并正确配置集群仿真环境。

核心接口说明¶

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

全局常量与枚举定义¶

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

独立常量¶

无

全局/独立函数¶

无

`TimeHelper` 类¶

包含所有与时间相关的功能，该类主要用于支持真实硬件和可变速率仿真使用同一套脚本，在真实硬件上使用ROS时间函数，仿真模式不依赖ROS，无需脚本关心当前运行环境。类属性包含空实现的可视化器对象，符合仿真脚本使用的可视化API规范。

`init()`¶

功能说明：初始化TimeHelper类实例 参数列表 (Args)：无参数 返回值 (Returns)：

TimeHelper 实例对象

异常 (Raises)：无

`time()`¶

功能说明：获取当前时间，单位为秒 参数列表 (Args)：无参数 返回值 (Returns)：

float: 当前时间，单位为秒

异常 (Raises)：无

示例：

from RflySimSDK.swarm.crazyflie import TimeHelper
time_helper = TimeHelper()
current_t = time_helper.time()

`sleep(duration)`¶

功能说明：休眠指定时长，单位为秒 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`duration`	`float`	是	-	需要休眠的时长，单位为秒

返回值 (Returns)：

无

异常 (Raises)：无

示例：

from RflySimSDK.swarm.crazyflie import TimeHelper
time_helper = TimeHelper()
# 休眠2秒
time_helper.sleep(2)

`sleepForRate(rateHz)`¶

功能说明：在循环中调用该方法时，可让循环以指定的频率运行，通过休眠补足间隔时间 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`rateHz`	`float`	是	-	目标循环频率，单位为赫兹

返回值 (Returns)：

无

异常 (Raises)：无

`isShutdown()`¶

功能说明：判断脚本是否应该中止（例如收到Ctrl+C中断信号） 参数列表 (Args)：无参数 返回值 (Returns)：

bool: 如果脚本应该中止返回True，否则返回False

异常 (Raises)：无

`Crazyflie` 类¶

代表单个Crazyflie无人机的对象，本模块的大部分功能都封装在该类中。

`init(id, initialPosition, tf, mode)`¶

功能说明：初始化单个Crazyflie无人机对象。 参数列表 (Args)：

参数名	类型	说明
id	int	无人机的整数ID，范围为[0, 255]，对应无人机通信地址的最后一字节
initialPosition	iterable of float	无人机的初始位置，格式为[x, y, z]，通常初始放置在实验区域地面，z值为0.0
tf	tf.TransformListener	ROS变换监听器，用于查询无人机当前状态
mode	None	无人机工作模式参数

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

`loop()`¶

功能说明：无额外功能说明 参数列表 (Args)：无参数 返回值 (Returns)：无返回值 异常 (Raises)：无

`setGroupMask(groupMask)`¶

功能说明：设置当前无人机的组掩码比特。分组的作用是可以仅对所有无人机的子集触发动作（例如执行预先上传的轨迹），而只需要发送一个无线数据包，这对于实现紧密同步的编队动作非常重要。最多支持8个分组，每个分组对应groupMask字节中的一个比特。当在CrazyflieServer对象调用带groupMask参数的广播命令时，命令只会影响那些自身groupMask和命令groupMask按位与结果非零的无人机。groupMask为0的命令会应用到所有无人机，无论其分组关系。部分单无人机（非广播）命令也支持groupMask，但该场景下使用没有特殊作用。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
groupMask	int	是	无	8位整数，表示当前无人机在最多8个可能分组中的成员状态

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

`enableCollisionAvoidance(others, ellipsoidRadii)`¶

功能说明：开启无人机机载避障功能。开启后，无人机使用缓冲 Voronoi 单元法（Buffered Voronoi Cells method）实现与其他 Crazyflie 无人机的避撞，所有计算都在机载完成。该避撞方法考虑了下洗效应：旋翼产生的高速气流让从另一无人机下方通过的安全距离远大于从侧方通过的安全距离，因此将碰撞检测边界设置为椭球形。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
others	List[Crazyflie]	是	无	其他Crazyflie对象的列表。在仿真中，仅会和列表中的无人机进行避撞检测；在真实硬件中该列表会被忽略，会和同一无线信道下的所有其他Crazyflie进行避撞检测
ellipsoidRadii	array-like of float[3]	是	无	碰撞体积椭球的半径，单位为米，三个元素分别对应三个坐标轴方向的半径

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

`disableCollisionAvoidance()`¶

功能说明：关闭机载避撞功能。 参数列表 (Args)：无参数 返回值 (Returns)：无返回值 异常 (Raises)：无

`takeoff(targetHeight, duration, groupMask=0)`¶

功能说明：执行起飞动作：垂直上升至目标高度，之后无限悬停。该命令为异步命令，会立即返回。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
targetHeight	float	是	无	悬停目标高度的z坐标，单位为米
duration	float	是	无	到达目标高度所需的时间，单位为秒
groupMask	int	否	0	组掩码比特，参见`setGroupMask()`方法说明

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

`land(targetHeight, duration, groupMask=0)`¶

功能说明：执行降落动作：垂直下降至目标高度，降落完成后用户必须切断电机动力。该命令为异步命令，会立即返回。通常目标高度应设置为高于初始位置几厘米，避免动捕坐标原点不准时控制器尝试穿入地面。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
targetHeight	float	是	无	降落目标高度的z坐标，单位为米
duration	float	是	无	到达目标高度所需的时间，单位为秒
groupMask	int	否	0	组掩码比特，参见`setGroupMask()`方法说明

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

`stop(groupMask=0)`¶

功能说明：在低级命令模式下切断电机动力。该方法适用于非紧急场景，例如降落之后还需要后续起飞的场景；后续的低级或高级命令会重新启动电机。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
groupMask	int	否	0	组掩码比特，参见`setGroupMask()`方法说明

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

`goTo(goal, yaw, duration, relative=False, groupMask=0)`¶

功能说明：平滑移动到目标位置，之后无限悬停。该命令为异步命令，会立即返回。该方法通过满足初始位置/速度/加速度、目标位置零速度零加速度、边界加加速度为零的7次多项式规划平滑轨迹，如果当前处于悬停状态，规划的轨迹为直线；如果当前速度非零，规划轨迹为平滑曲线。⚠️ 注意：如果频繁调用goTo或使用过短的时长（远小于1秒）可能引发系统不稳定，这种场景建议使用cmdPosition()代替。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
goal	iterable of 3 floats	是	无	目标位置，单位为米
yaw	float	是	无	目标偏航角（航向），单位为弧度
duration	float	是	无	到达目标位置所需的时间，单位为秒
relative	bool	否	False	如果为True，则目标位置会被解释为相对于当前位置的偏移；否则目标位置为全局参考系下的绝对坐标
groupMask	int	否	0	组掩码比特，参见`setGroupMask()`方法说明

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

`uploadTrajectory(trajectoryId, pieceOffset, trajectory)`¶

功能说明：上传分段多项式轨迹，供后续执行使用。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
trajectoryId	int	是	无	该轨迹的ID编号，支持同时上传多条轨迹
pieceOffset	int	是	无	分段偏移量
trajectory	pycrazyswarm.uav_trajectory.Trajectory	是	无	轨迹对象

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

`startTrajectory(trajectoryId, timescale=1.0, reverse=False, relative=True, groupMask=0)`¶

功能说明：开始执行预先上传的轨迹。该命令为异步命令，会立即返回。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
trajectoryId	int	是	无	上传轨迹时使用的ID编号
timescale	float	否	1.0	轨迹时长缩放系数，例如timescale=2.0会让轨迹执行时间变为标称时长的两倍
reverse	bool	否	False	如果为True，则从时间上反向执行轨迹
relative	bool	否	True	如果为True（默认），轨迹的起点会被偏移到当前设定点位置，这是通常期望的行为
groupMask	int	否	0	组掩码比特，参见`setGroupMask()`方法说明

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

`notifySetpointsStop(remainValidMillisecs=100, groupMask=0)`¶

功能说明：通知无人机，流式低级设定点数据包即将停止发送。cmdVelocityWorld、cmdFullState等都属于流式设定点命令，出于安全考虑，这类命令默认会抢占机载高级命令（如goTo）。被抢占后，Crazyflie只有在长时间未收到低级设定点后才会切回机载高级命令或其他机载规划逻辑。该命令可以将等待时间缩短为用户指定的值，应当在发送完最后一个低级设定点后、发送高级命令前调用，常见的使用场景是使用流式设定点后执行降落命令。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
remainValidMillisecs	int	否	100	最后一个流式设定点在切回机载行为前仍需要保持的毫秒数，如果一个无线控制多台无人机可以设置更大的值
groupMask	int	否	0	组掩码比特，参见`setGroupMask()`方法说明

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

`position()`¶

功能说明：返回动捕系统最新的真实位置测量值。如果自启动以来已经收到过至少一次位置测量，会直接返回最新测量值；如果还没有收到过任何位置测量，该方法会阻塞直到收到第一个位置测量后返回。 参数列表 (Args)：无参数 返回值 (Returns)：np.array[3]，当前位置，单位为米 异常 (Raises)：无

`getParam(name)`¶

功能说明：返回机载指定名称参数的当前值。参数是控制固件行为的命名基础类型值，参数会在系统启动时通过无线电读取并缓存；启动时也可通过ROS启动文件设置参数值，后续setParam()调用会更新缓存值；如果参数因为其他原因改变，缓存可能过期，但这种情况并不常见。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
name	str	是	无	参数名称

返回值 (Returns)：Any，参数的值 异常 (Raises)：无

`setParam(name, value)`¶

功能说明：修改指定参数的值。参数系统的整体说明参见getParam()方法文档。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
name	str	是	无	参数名称
value	Any	是	无	参数新的值

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

`setParams(params)`¶

功能说明：一次性修改多个参数的值。参数系统的整体说明参见getParam()方法文档。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
params	Dict[str, Any]	是	无	参数名和参数值构成的字典

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

`cmdFullState(pos, vel, acc, yaw, omega)`¶

功能说明：发送流式全状态控制器设定点命令。全状态设定点非常适合需要加速度和角速度前馈输入才能获得良好跟踪性能的高机动动作，全状态设定点可以从任何至少三阶可微的轨迹参数化中获取（例如分段多项式）。发送任何类型的流式设定点都会强制从高级命令模式切换为低级命令模式，当前不支持切回，因此发送流式设定点后无法再使用land()或goTo()等方法。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
pos	array-like of float[3]	是	无	位置，单位：米
vel	array-like of float[3]	是	无	速度，单位：米/秒
acc	array-like of float[3]	是	无	加速度，单位：米/秒²
yaw	float	是	无	偏航角，单位：弧度
omega	array-like of float[3]	是	无	机体坐标系下的角速度，单位：弧度/秒

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

`cmdVelocityWorld(vel, yawRate)`¶

功能说明：发送世界坐标系下的流式速度控制器设定点命令。在该模式下，上位机指定期望速度向量和偏航速率，机上控制器会尝试跟踪该速度。需要注意：默认的Mellinger控制器未对该模式调参，需要将启动配置中firmwareParams.stabilizer.controller修改为1来切换PID控制器。发送任何类型的流式设定点都会强制从高级命令模式切换为低级命令模式，当前不支持切回，因此发送流式设定点后无法再使用land()或goTo()等方法。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
vel	array-like of float[3]	是	无	速度，单位：米/秒
yawRate	float	是	无	偏航角速度，单位：度/秒

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

`cmdStop()`¶

功能说明：中断所有高级命令，停止电机并切断动力。适用于非紧急场景，例如降落之后后续仍需要重新起飞的情况，后续发送新的低级别或高级别命令会重新启动电机，效果等效于高级模式下的stop()方法。 参数列表 (Args)：无参数 返回值 (Returns)：无返回值 异常 (Raises)：无

`cmdVel(roll, pitch, yawrate, thrust)`¶

功能说明：发送"简易模式"手动控制输入的流式命令。该命令使用绝对滚转、俯仰角，偏航速率和推力作为输入，通常适合新手休闲飞行，区别于控制滚转俯仰速率的特技模式。该模式会限制可用动作，例如无法完成翻转，因为控制器需要摇杆输入旋转360度。需要注意：该命令中的角度和角速度单位为度，而cmdFullState中使用弧度作为单位。更多流式设定点命令说明可参考cmdFullState()文档。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
roll	float	是	无	滚转角，单位：度，正值表示向右滚转
pitch	float	是	无	俯仰角，单位：度，正值表示向前/向下俯仰
yawrate	float	是	无	偏航角速度，单位：度/秒，正值表示逆时针旋转
thrust	float	是	无	推力大小，范围为[0, 2^16)的无意义单位，最大值对应最大推力

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

`cmdPosition(pos, yaw=0)`¶

功能说明：发送绝对位置和偏航设定点的流式命令。适用于高级规划器已经计算出期望位置，其余控制交给机上控制器的慢速动作。作为流式设定点，该方法需要每秒发送多次（保守最小为10Hz），如果应用中生成目标位置较慢，且目标位置间隔较远，更适合使用goTo()方法。更多流式设定点命令说明可参考cmdFullState()文档。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
pos	array-like of float[3]	是	无	位置，单位：米
yaw	float	否	0	偏航角，单位：弧度

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

`setLEDColor(r, g, b)`¶

功能说明：设置LED环甲板的颜色。该方法方便在飞行过程中多次修改LED颜色用作状态指示，使用前提是需要将参数ring/effect设置为7（纯色模式）才会生效，默认模式下LED环颜色用于指示无线连接质量。该方法是阻塞命令，对于大规模集群或高频修改颜色可能会导致稳定性问题。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
r	float	是	无	红色分量，范围[0, 1]
g	float	是	无	绿色分量，范围[0, 1]
b	float	是	无	蓝色分量，范围[0, 1]

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

`readmsg()`¶

功能说明：读取无人机反馈信息 参数列表 (Args)：无参数 返回值 (Returns)：无返回值 异常 (Raises)：无

`getMotionPos()`¶

功能说明：获取无人机当前位置 参数列表 (Args)：无参数 返回值 (Returns)：长度为3的列表，依次为x/y/z方向位置，单位：米 异常 (Raises)：无

`getMotionVel()`¶

功能说明：获取无人机当前速度 参数列表 (Args)：无参数 返回值 (Returns)：长度为3的列表，依次为x/y/z方向速度，单位：米/秒 异常 (Raises)：无

`getMotionAcc()`¶

功能说明：获取无人机当前加速度 参数列表 (Args)：无参数 返回值 (Returns)：长度为3的列表，依次为x/y/z方向加速度，单位：米/秒² 异常 (Raises)：无

`Translation` 类¶

该类用于坐标平移变换，是无人机群坐标变换工具类，通常用于调整无人机群的整体位置偏移。

`init()`¶

功能说明：初始化 Translation 类实例 参数列表 (Args)：无 返回值 (Returns)：

Translation 实例对象

异常 (Raises)：无

`Transform` 类¶

坐标变换工具类，用于无人机集群场景下的空间坐标转换操作。

`init()`¶

功能说明：初始化 Transform 类实例 参数列表 (Args)：无

返回值 (Returns)：

Transform 实例对象

异常 (Raises)：无

`Msgg` 类¶

此类未提供功能描述文档，暂不明确具体用途与使用场景。

`init()`¶

功能说明：初始化 Msgg 类实例 参数列表 (Args)：无参数 返回值 (Returns)：

Msgg 实例对象

异常 (Raises)：无

`CrazyflieServer` 类¶

用于向集群内所有无人机同时广播控制命令，同时作为单个 Crazyflie 实例的容器，支持多无人机集群的同步控制。

属性：

crazyfliesById (Dict[int, Crazyflie]): 通过无人机ID（无线地址最后一个字节）索引对应的 Crazyflie 对象。

`init(crazyflies_yaml="../launch/crazyflies.yaml", num="1", ids=None, mode="7")`¶

功能说明：初始化服务器，会等待所有ROS服务就绪后再返回。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`crazyflies_yaml`	`str`	否	`../launch/crazyflies.yaml`	如果以`.yaml`结尾，则作为路径从文件加载配置；否则作为YAML字符串直接解析
`num`		否	`"1"`	需要连接的无人机数量
`ids`		否	`None`	指定无人机ID列表，若为None则使用默认编号
`mode`		否	`7`	仿真模式参数

返回值 (Returns)：

CrazyflieServer 实例对象

异常 (Raises)：

无

`init_poses()`¶

功能说明：初始化无人机位置 参数列表 (Args)：无参数 返回值 (Returns)：

无

异常 (Raises)：

无

`emergency()`¶

功能说明：执行紧急停止，切断电机动力，且会忽略后续所有控制命令。当控制脚本存在错误，继续执行可能导致无人机损坏时，可调用该方法保障安全；紧急停止后只能通过物理硬重置或nRF51重启命令恢复固件。 参数列表 (Args)：无参数 返回值 (Returns)：

无

异常 (Raises)：

无

`takeoff(targetHeight, duration, groupMask=0)`¶

功能说明：广播同步起飞命令，所有匹配组掩码的无人机同时直线上升到目标高度后悬停，异步命令，调用后立即返回，用于多无人机同步起飞。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`targetHeight`	`float`	是	-	起飞后悬停的z坐标高度，单位：米
`duration`	`float`	是	-	到达目标高度所需的时间，单位：秒
`groupMask`	`int`	否	`0`	组掩码位，仅匹配掩码的无人机会执行该命令

返回值 (Returns)：

无

异常 (Raises)：

无

`land(targetHeight, duration, groupMask=0)`¶

功能说明：广播同步降落命令，所有匹配组掩码的无人机同时直线下降到目标高度，异步命令，调用后立即返回，用于多无人机同步降落；降落完成后需要手动切断动力。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`targetHeight`	`float`	是	-	降落目标的z坐标高度，单位：米；通常设置为比初始位置高几厘米，避免原点误差导致无人机穿模地面
`duration`	`float`	是	-	到达目标高度所需的时间，单位：秒
`groupMask`	`int`	否	`0`	组掩码位，仅匹配掩码的无人机会执行该命令

返回值 (Returns)：

无

异常 (Raises)：

无

`goTo(goal, yaw, duration, groupMask=0)`¶

功能说明：广播同步移动命令，所有匹配组掩码的无人机同时平滑移动到目标位置后悬停，异步命令，调用后立即返回，用于多无人机同步运动；仅支持相对坐标偏移，保证集群运动不碰撞。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`goal`	`iterable of 3 floats`	是	-	目标位置偏移，格式为(x, y, z)，单位：米
`yaw`	`float`	是	-	目标偏航角（航向），单位：弧度
`duration`	`float`	是	-	到达目标位置所需的时间，单位：秒
`groupMask`	`int`	否	`0`	组掩码位，仅匹配掩码的无人机会执行该命令

返回值 (Returns)：

无

异常 (Raises)：

无

`startTrajectory(trajectoryId, timescale=1.0, reverse=False, relative=True, groupMask=0)`¶

功能说明：广播启动预上传轨迹命令，所有匹配组掩码的无人机同时开始执行已上传的轨迹，异步命令，调用后立即返回。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`trajectoryId`	`int`	是	-	轨迹ID，由上传轨迹时 `Crazyflie.uploadTrajectory()` 指定
`timescale`	`float`	否	`1.0`	轨迹时长缩放因子，例如值为2.0时，轨迹执行时间变为标称时长的2倍
`reverse`	`bool`	否	`False`	如果为True，反向执行轨迹
`relative`	`bool`	否	`True`	如果为True，轨迹起点偏移到当前设定点位置
`groupMask`	`int`	否	`0`	组掩码位，仅匹配掩码的无人机会执行该命令

返回值 (Returns)：

无

异常 (Raises)：

无

`setParam(name, value)`¶

功能说明：广播批量设置无人机参数，详细说明见 Crazyflie.setParam()。 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`name`		是	-	参数名称
`value`		是	-	参数值

返回值 (Returns)：

无

异常 (Raises)：

无

`readmsg()`¶

功能说明：读取消息 参数列表 (Args)：无参数 返回值 (Returns)：

无

异常 (Raises)：

无

`singleGetpos(id)`¶

功能说明：获取单个无人机的位置 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`id`		是	-	目标无人机ID

返回值 (Returns)：

无

异常 (Raises)：

无

`Getpos(id)`¶

功能说明：该实现不适用于此类 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`id`		是	-	目标无人机ID

返回值 (Returns)：

无

异常 (Raises)：

无

`Getvel(id)`¶

功能说明：该实现不适用于此类 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`id`		是	-	目标无人机ID

返回值 (Returns)：

无

异常 (Raises)：

无

`Getacc(id)`¶

功能说明：该实现不适用于此类 参数列表 (Args)：

参数名	类型	是否必填	默认值	说明
`id`		是	-	目标无人机ID

返回值 (Returns)：

无

异常 (Raises)：

无

示例：

from RflySimSDK.swarm import CrazyflieServer

# 初始化3架无人机集群服务器
cf_server = CrazyflieServer(num=3)

# 同步起飞到0.8米高度，耗时2秒
cf_server.takeoff(targetHeight=0.8, duration=2.0)

# 所有无人机向前移动1米，耗时3秒，偏航保持0弧度
cf_server.goTo(goal=(1.0, 0, 0), yaw=0, duration=3.0)

# 同步降落回0.1米高度，耗时2秒
cf_server.land(targetHeight=0.1, duration=2.0)

进阶用法示例¶

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

import RflySimSDK.swarm.crazyflie as cf_sdk
from RflySimSDK.swarm.crazyflie import TimeHelper, Crazyflie, CrazyflieServer

# 初始化集群服务器与无人机对象
cf_server = CrazyflieServer()
cf_list = [Crazyflie(i) for i in range(5) for _ in range(5)]
time_helper = TimeHelper()

# 批量初始化起飞，启用碰撞避免，分组执行异构任务
cf_server.init_poses([(0, 1, 0) for i in range(5])
for idx, cf in enumerate(cf_list):
    if idx < 3:
        cf.setGroupMask(0b01)
        cf.enableCollisionAvoidance()
    else:
        cf.setGroupMask(0b10)
        cf.disableCollisionAvoidance()
cf_server.takeoff(height=0.8, duration=2)
time_helper.sleep(2)

# 上传并启动异构轨迹，异步协作飞行
for cf in cf_list:
    if cf.group_mask == 0b01:
        traj = [[0.5 * x/20, 0, 0.8, 0.5] for x in range(20)]
    else:
        traj = [[0, 0.5 * x/20, 0.8, 0.5] for x in range(20)]
    cf.uploadTrajectory(traj_id=1, traj=traj)
    cf.startTrajectory(traj_id=1, timescale=1, reversed=False, relative=False)

# 按固定频率循环获取位置，监控集群状态
while not time_helper.isShutdown():
    all_pos = cf_server.Getpos()
    for idx, pos in enumerate(all_pos):
        print(f"无人机{idx}当前位置：", pos)
    if not time_helper.sleepForRate(10):
        break

# 任务完成后批量降落
cf_server.land(height=0, duration=2)
time_helper.sleep(3)

注意事项与避坑指南¶

分组掩码生效范围：setGroupMask方法仅对单个Crazyflie对象生效，若需要批量修改多架无人机的分组属性，需要遍历所有目标无人机对象逐一调用该方法，仅调用CrazyflieServer端的批量方法不会自动同步分组设置。
碰撞避免开关切换：切换碰撞避免功能后需要等待至少1个控制周期才能生效，若在调用enableCollisionAvoidance或disableCollisionAvoidance后立刻执行移动指令，可能会出现开关未生效的情况，建议搭配TimeHelper.sleep预留足够的等待时间。
轨迹上传参数要求：调用uploadTrajectory上传轨迹时，每个轨迹点需要同时包含位置信息和时间间隔两个部分，若仅传入位置数组会导致轨迹解析失败，必须保证每段轨迹的点序列格式与接口要求一致。
固定频率循环控制：使用sleepForRate维持固定控制频率时，若单次循环的处理时间超过设定频率对应的周期，函数会自动跳过本次休眠来维持频率，不要在循环内加入耗时过长的自定义计算或打印操作，避免整体控制周期会出现明显偏差。
紧急状态处理：飞行过程中若出现位置异常或失控情况，需要立刻调用CrazyflieServer.emergency终止所有无人机的动力输出，不要直接终止进程可能会导致仿真进程异常卡顿。

更新日志¶

2024-12-10: fix:更新API页面
2024-12-10: fix:更新集群控制接口注释
2024-07-18: fix:更新API主页索引
2024-02-23: feat: support crazyflie simulation

crazyflie 接口文档¶

简介¶

快速开始¶

环境与依赖¶

核心接口说明¶

全局常量与枚举定义¶

独立常量¶

全局/独立函数¶

TimeHelper 类¶

__init__()¶

time()¶

sleep(duration)¶

sleepForRate(rateHz)¶

isShutdown()¶

Crazyflie 类¶

__init__(id, initialPosition, tf, mode)¶

loop()¶

setGroupMask(groupMask)¶

enableCollisionAvoidance(others, ellipsoidRadii)¶

disableCollisionAvoidance()¶

takeoff(targetHeight, duration, groupMask=0)¶

land(targetHeight, duration, groupMask=0)¶

stop(groupMask=0)¶

goTo(goal, yaw, duration, relative=False, groupMask=0)¶

uploadTrajectory(trajectoryId, pieceOffset, trajectory)¶

startTrajectory(trajectoryId, timescale=1.0, reverse=False, relative=True, groupMask=0)¶

notifySetpointsStop(remainValidMillisecs=100, groupMask=0)¶

position()¶

getParam(name)¶

setParam(name, value)¶

setParams(params)¶

cmdFullState(pos, vel, acc, yaw, omega)¶

cmdVelocityWorld(vel, yawRate)¶

cmdStop()¶

cmdVel(roll, pitch, yawrate, thrust)¶

cmdPosition(pos, yaw=0)¶

setLEDColor(r, g, b)¶

readmsg()¶

getMotionPos()¶

getMotionVel()¶

getMotionAcc()¶

Translation 类¶

__init__()¶

Transform 类¶

__init__()¶

Msgg 类¶

__init__()¶

CrazyflieServer 类¶

__init__(crazyflies_yaml="../launch/crazyflies.yaml", num="1", ids=None, mode="7")¶

init_poses()¶

emergency()¶

takeoff(targetHeight, duration, groupMask=0)¶

land(targetHeight, duration, groupMask=0)¶

goTo(goal, yaw, duration, groupMask=0)¶

startTrajectory(trajectoryId, timescale=1.0, reverse=False, relative=True, groupMask=0)¶

setParam(name, value)¶

readmsg()¶

singleGetpos(id)¶

Getpos(id)¶

Getvel(id)¶

Getacc(id)¶

进阶用法示例¶

注意事项与避坑指南¶

更新日志¶

`TimeHelper` 类¶

`init()`¶

`time()`¶

`sleep(duration)`¶

`sleepForRate(rateHz)`¶

`isShutdown()`¶

`Crazyflie` 类¶

`init(id, initialPosition, tf, mode)`¶

`loop()`¶

`setGroupMask(groupMask)`¶

`enableCollisionAvoidance(others, ellipsoidRadii)`¶

`disableCollisionAvoidance()`¶

`takeoff(targetHeight, duration, groupMask=0)`¶

`land(targetHeight, duration, groupMask=0)`¶

`stop(groupMask=0)`¶

`goTo(goal, yaw, duration, relative=False, groupMask=0)`¶

`uploadTrajectory(trajectoryId, pieceOffset, trajectory)`¶

`startTrajectory(trajectoryId, timescale=1.0, reverse=False, relative=True, groupMask=0)`¶

`notifySetpointsStop(remainValidMillisecs=100, groupMask=0)`¶

`position()`¶

`getParam(name)`¶

`setParam(name, value)`¶

`setParams(params)`¶

`cmdFullState(pos, vel, acc, yaw, omega)`¶

`cmdVelocityWorld(vel, yawRate)`¶

`cmdStop()`¶

`cmdVel(roll, pitch, yawrate, thrust)`¶

`cmdPosition(pos, yaw=0)`¶

`setLEDColor(r, g, b)`¶

`readmsg()`¶

`getMotionPos()`¶

`getMotionVel()`¶

`getMotionAcc()`¶

`Translation` 类¶

`init()`¶

`Transform` 类¶

`init()`¶

`Msgg` 类¶

`init()`¶

`CrazyflieServer` 类¶

`init(crazyflies_yaml="../launch/crazyflies.yaml", num="1", ids=None, mode="7")`¶

`init_poses()`¶

`emergency()`¶

`takeoff(targetHeight, duration, groupMask=0)`¶

`land(targetHeight, duration, groupMask=0)`¶

`goTo(goal, yaw, duration, groupMask=0)`¶

`startTrajectory(trajectoryId, timescale=1.0, reverse=False, relative=True, groupMask=0)`¶

`setParam(name, value)`¶

`readmsg()`¶

`singleGetpos(id)`¶

`Getpos(id)`¶

`Getvel(id)`¶

`Getacc(id)`¶