做无人机集群快两年了，前后给实验室搭过三套CrazySwarm环境，从让第一架Crazyflie顺利起飞，到最终让几十架小飞机在室内完成协同编队、轨迹避障，每一步都没少吃文档混乱的亏。今天这篇是系列笔记的第一篇，先把搭建CrazySwarm无人机集群过程中所有值得看的资料，按代码仓库、论文、官方文档、硬件手册、调试工具和中文社区资源等几个维度系统索引一遍。如果你正准备入坑无人机集群实验，这份清单能帮你省下不少踩坑时间。

CrazySwarm本身不是某款飞机，而是一套面向微型无人机集群的算法开发与实验框架，由南加州大学、加州大学伯克利分校相关团队主导维护，底层飞行平台用的是Bitcraze公司的Crazyflie系列微型四旋翼。它解决的核心问题非常直接：研究者不必从零手写底层无线协议、遥控通道和姿态解算，只要准备一个室内定位环境，就能在普通Linux主机上用Python或ROS节点同时指挥几十架几十克重的微型无人机飞行，做编队、一致性、避障、航迹规划等实验。这套框架特别适合高校实验室、算法团队、机器人竞赛选手，以及想快速验证无人机集群算法的深度硬件爱好者。

但CrazySwarm的配套资料分布得极散：核心代码在GitHub上横跨多个仓库，协议和硬件原理挤在Bitcraze Wiki的各个角落，系统级说明放在ReadTheDocs，算法细节散落在几篇顶会论文里，版本更新还非常频繁。第一次接触的人跟着各种教程折腾半天，最后卡在版本不匹配、驱动装不上、动捕标定不准这类问题上。所以我决定在第一篇就把资料地图画清楚，后面再逐步展开具体搭建步骤。

1. 参考资料索引之前，先看懂CrazySwarm的分层体系

1.1 CrazySwarm在解决什么问题

说直白一点，CrazySwarm解决的是"想研究多机协同，但不想被困在底层工程"的尴尬问题。如果你自己买散件组装几十架四轴，光是把每一架的PID整定、通信链路、电池管理调通，就得耗掉一个学期；就算调通了，算法实验还会被硬件问题反复打断，编队飞到一半某架飞机掉线，你根本分不清是算法出的错还是通信出了故障。

CrazySwarm把这种负担大幅降低：飞机是统一规格的微型整机，固件层面已经内置姿态控制、状态估计和速度环位置环；PC端提供了一套和飞机数量无关的高层通信机制，你可以像调用普通API一样给任意一架飞机下发位置设定点；再加上一个外部位姿系统，整个集群在空间里的位置都能被实时定位。这样一来，研究者的精力就能集中在真正想做的集群算法上，而不是每次实验都从底层开始查。

它有两代实现：一代基于ROS1，用Python脚本+C++节点混合编写，代码先有历史包袱之后，二代的Crazyswarm2用C++重写并转向ROS2，实时性和扩展性都更好。两代解决的核心问题相同，但接口、性能和维护状态不同，这直接影响你该优先看哪些资料。

1.2 三层系统架构与资料地图的对应关系

我实际搭建时习惯把整套系统拆成执行、通信、算法三层来看。

执行层在每架Crazyflie上，包括STM32主控、IMU、气压计、电机和扩展传感器，运行的是Crazyflie固件代码。这一层的资料基本都在Bitcraze Wiki和crazyflie-firmware仓库里，你遇到"飞机自己飞不稳"、"姿态解算漂移"这类问题，就得回这一层查。

通信层在主机和飞机之间，包括USB连接的Crazyradio PA无线加密狗、nRF24L01的2.4GHz协议、以及crazyswarm底层封装的通信驱动。这个环节的资料分散在Bitcraze协议文档、仓库源码和通信调试工具说明里，最常见的症状是"飞机掉线"、"控制指令延迟"。

算法层运行在主机上，包括轨迹规划、编队生成、避障策略、安全保护机制这些逻辑。对应的资料是crazyswarm主仓库里的Python与C++代码、相关论文，以及ROS话题和rviz可视化配置。

清楚这个分层之后，找资料就有章法了：写算法报错去主仓库的Issue区搜，飞机姿态异常去固件仓库和Wiki查，通信掉包去看Crazyradio PA的官方文档。一旦你开始盲目地全盘搜索，反而最容易浪费时间。

1.3 为什么索引先于实操

这个系列的第一篇我坚持写资料索引，原因很简单：CrazySwarm的资料体系存在较强的版本时效性。你搜到一个2020年的教程，里面的Ubuntu版本、ROS版本、固件版本和现在是完全不同的，照着跑大概率失败。与其让你在无数教程里用真实错误去试错，不如我先把哪些资料是权威的、哪些内容会随版本变化、哪些坑我踩过的前置信息一次说清。

另外，资料索引还能降低"劝退率"。很多新同学第一天接触CrazySwarm，看到官方Wiki一长串页面和几十个仓库，第一反应是不知道从哪里下手。索引的本质是给你一条经过验证的主线：先读什么、后读什么、什么阶段不需要碰什么。它能让你在第一天就进入"能跑通的路上"，而不是在资料海里漂泊。

2. 官方第一手资料：代码仓库、核心论文与文档入口

2.1 四个必须吃透的代码仓库

第一个仓库是USC-ACTLab/crazyswarm，一代ROS1实现的主仓库。它里面既有ros_ws工作空间，也有Python与C++混合的算法代码，还有一批典型的demo脚本，比如单机起飞降落、多机编队、圆形轨迹跟踪。你平时和CrazySwarm打交道最多的就是这个仓库，它包含launch启动文件、YAML配置文件以及很多工具函数，几乎所有集群行为都能从这里找到原型。

第二个仓库是whoenig/crazyswarm2，也就是二代C++/ROS2实现。它在API设计上与一代有区别，但核心概念继承过来：通过RCLCPP节点订阅传入的位姿、发布期望设定点、转发给底层通信驱动。如果你从零起步且没有历史ROS1代码包袱，我建议你直接基于这个仓库开始，因为当前更活跃的维护和更新都在这个方向上。

第三个仓库是Bitcraze的crazyflie-firmware，即飞机端固件源码。默认情况下官方demo不需要动它，用出厂固件就行。但如果你想调整飞行控制参数、加装传感器并读取数据，或者给飞机做特定行为定制，就必须自己编译固件。仓库里包含了Bootloader、FreeRTOS任务结构以及各类传感器驱动，是所有硬件行为的最底层真面目。

第四个仓库是Bitcraze的crazyflie-lib-python，它提供了PC和飞机之间直接通信的Python库。Crazyswarm底层的通信驱动就是基于这个库封装的，理解里面的Command和Logging API，对排查"指令没发出去""状态没回传"会很有帮助。

2.2 系统论文与算法延伸论文怎么读

系统级的必读论文是发表在ICRA 2020的《CrazySwarm: A Large Nano-Quadcopter Swarm》。这篇论文把整个系统的软件架构、硬件选型、通信协议、实验流程讲得非常完整，包括如何用动捕系统提供外部位姿、如何与多架Crazyflie进行低延迟通信、如何生成并执行编队轨迹。它是整个框架的"系统设计说明书"，建议把原文下载下来，对照代码一条条过。

读这篇论文时不要只读摘要和数据图，重点抓三个点：消息传递方式、设定点生成频率、算法与硬件的对接边界。论文里有一个数据流图，基本就是CrazySwarm运行时所有关键信息的走向，把这个图画在自己笔记里，后面看代码会轻松很多。

算法延伸论文方面，我比较推荐去跟踪多无人机航迹生成与避障方向，尤其是基于凸优化或混合整数规划做时空轨迹规划的方法。这类论文会告诉你，一批目标点是如何被转成每架飞机不带碰撞的安全轨迹的，而这些算法在crazyswarm仓库中都有对应或近似的demo实现。看算法论文时不必死磕每个数学证明，需要抓住的是它为何选这种规划方式、约束怎么建模、最终如何离散成飞行控制能用的设定点。

2.3 官方文档的两种形态：Wiki与ReadTheDocs

CrazySwarm的官方文档主要分布在两处。一处是ReadTheDocs上的Crazyswarm说明文档，它负责讲解如何安装环境、如何编译、如何启动demo、常见FAQ，以及ROS话题和参数列表，是软件侧的一手教程。另一处是Bitcraze Wiki，它覆盖了Crazyflie有关的所有硬件知识，包括每个扩展模块的引脚定义、通信协议、电池规范、固件编译指南，以及Crazyradio PA的详细使用说明。

我自己的使用习惯是：遇到"怎么在我的机器上跑起来"这类问题，先翻ReadTheDocs的安装和快速入门；遇到"这个板子为什么这么接""这个寄存器是什么含义"这类硬件问题，去Bitcraze Wiki的对应产品页，把原理图和引脚表存好。

另外别忘了GitHub Issue区。它虽然不是正式文档，但却记录了维护者和使用者大量的真实调试过程。很多你搜索后无解的错误，可能就是某个Issue中讨论过的问题。学会用"错误关键字 + repos:crazyswarm"这样的搜索方式，能在Issue里快速定位讨论帖。

3. 硬件侧资料：Crazyflie选型、定位系统与无线链路

3.1 Crazyflie本体与扩展模块的规格资料

CrazySwarm的飞行平台几乎都是Crazyflie 2.x系列，最常见的是Crazyflie 2.1。整机由一块集成主控板、四个空心杯电机、保护罩和机架组成，重量很轻，一块250mAh左右的1S锂聚合物电池能飞大约七到十分钟，具体取决于是否加装扩展模块和飞行强度。主控芯片是STM32F405，负责姿态估计和位置控制，另外还有一颗协处理器专跑2.4GHz无线协议栈。

Bitcraze Wiki上有这套硬件最完整的资料：芯片手册链接、引脚图、扩展接口定义、固件烧录说明和维修拆解指南。如果你买的飞机是散件需要自己组装，Wiki上的装配教程一定要看；就算买整机，我也建议把引脚图和扩展接口文档存一份到本地，因为后面很多传感器调试都会用到。还有一个容易被忽略的点：电池不是标准的XH2.54？Crazyflie用的电池接口是特殊定义的，不同容量的电池重量和放电能力差异会影响整体飞行表现，选电池时最好同步核对Wiki上的电池推荐列表。

扩展模块方面，最常用的有Loco Positioning Deck，用来做UWB定位；Flow Deck v2，用来做光流测速和高度估计；还有无线充电模块、测距模块等。每个Deck在Wiki上都有专门的资料页，里面包含驱动文档、固件配置和校准方式。你接入任何新Deck之前，先到Wiki把对应页面的资料看完。

3.2 三种定位方案的资料与选型对比

集群实验的基础条件是每架飞机有准确的外部位姿。主流方案有三种：

VICON和OptiTrack都属于光学动捕系统，通过多个红外相机捕捉贴在飞机上的反光球，解算出六自由度位姿。VICON精度通常能达到亚毫米级别，但整套系统价格很高，需要专门的场地和标定流程；OptiTrack精度也非常高，在实验室里更常见。它们通过VRPN协议与主机通信，Crazyswarm通过订阅VRPN话题来获得位姿数据。官方文档里对动捕的坐标系配置有专门说明，务必仔细看，否则会出现起飞后方向冲突的问题。

第三种是Bitcraze官方的Loco Positioning System，基于UWB技术。多个室内锚节点和飞机上的Loco Deck相互测距，解算出飞机位置，精度大致在10厘米量级。它的好处是便宜、布设灵活、不依赖光学，适合没有动捕资金的团队；缺点是精度相对有限，高动态编队时会显得吃力。Wiki上对锚节点布局、校准过程和定位质量有完整说明，选择这条路线的朋友建议先读完整套部署文档再开始。

从选型资料的角度，我整理过一个对比表：

不考虑极端精度需求时，UWB方案足够帮你迈出第一步，但如果你的研究方向是密集编队或近距离避障，动捕系统几乎绕不开。

3.3 Crazyradio PA的通信原理与调试资料

主机与飞机之间依托Crazyradio PA这个USB无线加密狗完成通信，它本质上是一个利用nRF24L01芯片的2.4GHz收发器。它和飞机通过Bitcraze自定义的数据包协议通信，支持一对多的轮询机制，也就是一个加密狗可以轮询并调度多架飞机。

官方Wiki上的Crazyradio PA页面有数据手册和协议说明，讲清楚了数据包结构、ACK机制、信道设置和固件升级方法。要特别注意的是，当飞机数量增加时，单个加密狗的带宽会成为瓶颈，可能出现控制指令延迟或掉线。常见对策是增加第二个Crazyradio PA，将飞机分组到不同信道，或者降低控制频率。这些参数怎么调，官方文档和仓库源码中都有注释，但最终的组合没有标准答案，需要根据你的场地和飞机数量实测。

我自己遇到过的通信类故障，大多数不是硬件坏了，而是信道干扰或频率设置不对。比如实验室内有大量Wi-Fi和蓝牙设备，它们同样工作在2.4GHz频段，互相干扰很正常。这时候通过手动切换信道、错开BLE广播频段，问题经常就解决了。这些调试方法和技巧在Bitcraze的Wiki和社区论坛里都有讨论，值得去搜。

4. 软件侧资料：ROS环境、固件工具链与调试可视化

4.1 环境选型与版本对应关系表

软件环境是很多新同学的第一道大坎。一代crazyswarm基于ROS1，常见搭配是Ubuntu 18.04 + ROS Melodic，或者Ubuntu 20.04 + ROS Noetic；二代crazyswarm2基于ROS2，更推荐Ubuntu 22.04 + ROS2 Humble。版本不能随便混搭，比如你在Noetic上装了原本为Melodic编写的依赖，编译的时候就会报出一堆找不到包的错误。

这里给出一张我实际验证过的版本组合表：

我自己实践下来，如果实验室有一堆ROS1历史代码，留在Noetic也完全够用；如果想从零搭建一套长期维护的环境，直接学ROS2并上crazyswarm2是更划算的选择。无论选哪一代，Python依赖都建议放进虚拟环境或conda环境里管理，不要直接混进系统Python。早期我把依赖装进系统环境后，系统一升级，依赖冲突导致整个环境崩溃，只能重装系统，这种教训不值得再踩。

4.2 固件编译烧录与应急回退

固件编译在初始阶段可以放在后面，但迟早会用到。Bitcraze固件使用Makefile加ARM交叉编译器构建，在Linux下克隆仓库、安装工具链后，按Wiki上的步骤执行编译即可生成烧录文件。烧录方式有USB直连和无线OTA两种，无线烧录更省事，但前提是飞机能和主机正常通信。

我在修改固件时立了一个规矩：动手之前先备份当前固件版本和编译产物。这看起来麻烦，却能在关键时刻救你。有次我调了一个传感器滤波参数，上机后发现解算出来的姿态剧烈抖动，当时如果没有保留旧固件，就只能靠猜来排查；因为能一键回退到稳定版本，才快速确定问题出在我的参数而不是硬件损坏。另外，不同固件版本对外的无线协议可能有差异，升级固件后如果crazyswarm报通信异常，先查固件与crazyswarm仓库的版本兼容说明，别急着怀疑硬件。

编译报错是新手最容易卡住的地方。常见的错误包括工具链版本不对、依赖库缺失、Python路径没配好。应对的思路很简单：把报错信息复制到Issue区搜索，通常都能找到别人处理过的方案。

4.3 cfclient、rviz与飞行日志的使用要点

调试工具里，我每天都会用到cfclient、rviz和飞行日志这三个东西。

cfclient是Bitcraze官方桌面客户端，适合单机场景。它可以连接一架飞机，查看IMU原始数据、电机转速、电量、遥控器输入，也能手动推杆起飞和降落。当你怀疑"这架飞机是不是自身状态异常"的时候，cfclient就是第一个排障工具。

rviz是ROS生态的通用可视化工具，crazyswarm会把每架飞机的真实位置、期望位置、规划轨迹发送到rviz话题上。开启rviz后，你能直观看到几十架飞机在地图上飞行的过程，这是判断"算法算出来对不对"的关键。如果你发现rviz里轨迹规划正常、但真实飞机偏离轨迹，那问题大概率出在通信或飞控参数；如果rviz里轨迹本身就是乱的，那就回到算法层排查。

飞行日志方面，Crazyflie支持在飞行中记录IMU、姿态、控制量等高频数据，之后通过cfclient或命令行导出。我的习惯是每次实验都自动存一份日志，并命名带上时间戳和实验编号。很多故障是偶发的，比如飞着飞着突然掉高度，如果没有日志，你根本不知道掉高度之前哪个传感器数值已经异常；有日志后，来回放几次对比正常时段，基本能定位到是气压计干扰、通信卡顿还是电机响应变慢。

5. 中文社区资源、阅读路线与避坑筛选

5.1 中文资料哪些值得看、怎么筛选

中文社区关于CrazySwarm的内容集中在技术博客、问答平台和视频平台。以我看过的量而言，最有参考价值的是两类：一类是"环境安装和排错日志"，博主会写清楚自己的Ubuntu、ROS、Python版本，以及每一步报错怎么解决，这类内容很容易直接复用；另一类是"demo运行记录"，作者会记录跑通某个编队demo的完整操作，读完能让你在动手之前就对整体流程有概念。

但中文内容质量参差不齐，有的只是翻译了老版本官方文档，有的从别人博客搬过来连版本号都没更新。我筛选的原则很简单：看发布时间是否离当前环境版本近，看文中是否说明了依赖的具体版本，看作者有没有贴出真正的报错和解决方案。一条"我只改了这些配置就运行成功"的帖子，参考价值远高于"默认安装一切正常"的帖子，因为它说明写的人真实验过。

还在视频平台搜到过一些很短的飞行演示片段，这些看起来赏心悦目，但教学价值有限。真正能带你走完安装流程的长视频非常少，所以我建议中文视频资源只看思路，不要当完整教程。

5.2 从零到编队：我建议的阅读路线

我总结过一套从零起步的阅读路线，分成三个阶段。

第一阶段是"跑通demo"：只读官方README和快速开始文档，不看太多原理，先把环境装好，让一架飞机成功起飞并降落。这里的目标是建立信心和手感，让整条链路先通起来。第二阶段是"理解链路"：读那篇系统论文，对照官方demo里的Python脚本，理清从"你写下目标点坐标"到"飞机真的飞过去"之间经过的所有节点和话题。第三阶段是"改造算法"：根据你的研究方向去改轨迹生成、编队逻辑或安全策略，这时候再深入读固件源码、协议文档和相关领域论文。

这个阅读顺序我验证过多次，效果稳定。最怕的是新人一开始扑到协议文档里，读完还不知道飞机怎么起飞。先跑通再深究，效率最高，也更能维持兴趣。

5.3 新手查资料最常踩的三个坑

第一是版本错位。你搜到的教程可能是三年前的ROS Melodic版，而你装的是ROS2 Humble，命令和依赖都变了，照抄必挂。解决方案是看任何教程前，先确认对方的系统版本和软件版本，遇到不对劲的地方先猜"是不是版本不一样"。

第二是照搬参数。官方文档给的默认值是通用值，不一定适合你的场地、飞机数量和定位系统。比如通信频率设太高会导致丢包，设太低会有明显延迟；某个避障代码里的安全距离在动捕精度高时能跑，换到UWB定位下可能频繁误报。所有参数都应该在你的环境中实测后调整。

第三是只抄结论，不提过程。有些帖子最后只给出一句"把文件改成这样就好了"，但不说明为什么。这种结论往往在特定条件下才成立，你不理解背后的因果，换一台机器或换一个版本就失效。所以看资料时要多问一句"为什么这样改"，把原理弄懂，才能真的把别人的经验迁移到自己的场景里。

资料索引部分到这里基本梳理完整了。我自己最大的感受是：CrazySwarm这套框架并不难跑通，难点一直被"资料散落各处 + 版本快速变化"两个因素放大。把这份地图理清楚之后，后面每一篇笔记我都会沿着具体主题展开实操细节，包括动捕标定流程、第一架飞机起飞、多机编队配置和常见故障实录。也建议你动手之前先把本篇文章提到的仓库和文档页收藏好，搭建过程中随时回来对照，比临时去搜索引擎里捞帖子靠谱得多。