这几年做无人机相关项目的人越来越多但真正能跑通“集群”的并不多。我最近扎进crazyswarm这个开源项目里从论文、源码到实机一步步趟过来最大的感受是资料真的不少散得也真的厉害。GitHub、ReadTheDocs、Bitcraze论坛、IEEE论文各管一段中间还有大量版本断层和过时教程。于是决定把这个过程记成一个系列笔记第一篇就先把资料索引整理清楚避免后来者像我一样满世界找文件。crazyswarm是由USC南加州大学ACT Lab开源的微型无人机集群系统核心概念是用大量Crazyflie小四旋翼执行集中式的集群飞行任务室内靠光学动捕系统做厘米级定位。它的代码虽然已经发布了好几年但至今仍然是复现无人机集群实验绕不开的参考方案。这篇笔记适合几类人正在做集群编队、轨迹规划方向的研究生准备在实验室搭建室内集群平台的工程师以及单纯想了解“集群系统到底由哪几块组成”的入门爱好者。今天这篇先把“地基”打好把该看的资料、该收藏的页面、该有心理预期的版本问题全部列出来。1. 先搞清楚crazyswarm是一个什么系统1.1 它解决的并不是“让无人机起飞”的问题很多新手听到“无人机集群”第一反应是打开地面站画个航线再让飞机排着队飞过去。这个理解放在消费级无人机上没问题但crazyswarm面对的完全是另一套逻辑。它要解决的是从底层飞行控制、到多机通信、再到上层路径规划和编队控制的一整条链路问题而不是简单说“起飞”两个字。整个系统可以拆成四层来看飞控层每台Crazyflie上运行的固件负责姿态解算、电机混控、传感器融合这是单机稳定的基础通信层Crazyradio PA数传电台基于增强型 ShockBurst 协议做广播通信一台地面端可以同时管辖上百台Crazyflie这也是“集群”在通信层面的支撑规划层跑在地面站ROS里的上层逻辑负责轨迹生成、编队控制、碰撞避免、任务分配集群表现出来的“智能”基本都在这层定位层动捕系统通过VRPN协议把每台飞机的高精度位置发给ROS再由ROS时钟统一同步后下发给飞机。理解这个分层结构很重要因为后续看的所有资料几乎都是在往这四个方向延伸。GitHub仓库里的doc目录和ReadTheDocs文档站的“System Overview”章节是官方为数不多把这个架构讲明白的地方我建议放在所有资料的第一位来看不要一上来就盯着安装命令敲。1.2 为什么选Crazyflie而不是自组四轴做集群实验不选大飞机是有现实原因的。自组一架能室内飞行的四轴机架、电调、飞控、避障传感器加起来成本往小了说也要上千元而且室内测试一旦失控几公斤的东西撞到人或者设备麻烦非常大。Crazyflie的单机价格只是零头更重要的是它几乎没有“危险的上限”——整机只有几十克桨叶外面还有保护罩就算多台飞机撞在一起大概率也就是掉几个桨叶。另一个关键原因是Crazyflie从硬件到固件完全开源。板载的STM32F4主控、NRF51蓝牙管理、IMU传感器选型、参考设计文件Bitcraze全部公开了固件用的是FreeRTOS加模块化驱动二次开发的门槛比消费级飞控低很多。而且crazyswarm项目本身就是基于Bitcraze生态开发的协议栈、固件版本、上位机接口都是验证过的用Crazyflie等于站在了官方铺好的路上。1.3 定位方案为什么离不开动捕系统集群实验里的定位精度直接决定了上层算法能不能跑得起来。编队飞行时两架飞机的距离常常只有几十厘米GPS在室内根本不可用UWB方案虽然能做相对定位但受多径效应影响精度和刷新率都达不到tight formation的要求。光学动捕系统比如OptiTrack、Vicon通过多台红外相机对标记点的三维重建能提供亚毫米级、刷新率100Hz以上的位置输出这才是crazyswarm敢把几十台飞机塞进一个三维空间里的底气。在资料层面你需要知道的是crazyswarm的定位数据流是“动捕软件如Motive通过VRPN协议发布刚体数据 → 地面站上的VRPN客户端接收 → 转换成ROS topic → 控制节点消费”。这个链路在官方文档里讲得比较清楚动手前务必先把这个数据流跑通否则后续一切基于位置的实验都会莫名其妙地失败。2. 官方资源四件套GitHub、文档站、Bitcraze Wiki、固件仓2.1 GitHub主仓库USC-ACTLab/crazyswarm这是整个项目的神经中枢里面包含了ROS工作空间的顶层结构ros_ws/src下有控制节点、通信节点、规划节点、launch文件和脚本。README里写了安装步骤和硬件要求但内容偏精炼很多细节散布在源码注释里。仓库自带的doc目录值得逐页读一遍里面有架构说明、通信机制、文件结构介绍这些内容在别的地方很难找到如此集中的梳理。另外要留意的是分支和commit。crazyswarm的主分支一直有更新但部分功能依赖特定的Crazyflie固件版本你在clone后应该把当前commit的时间和固件commit对应起来否则非常容易出现“上位机代码和飞控固件版本不匹配”这种隐蔽问题。2.2 ReadTheDocs文档站crazyswarm.readthedocs.io相比GitHub的READMEReadTheDocs要系统得多。它把安装指南、教程、节点API、ROS话题接口、常用命令都重新组织了。尤其推荐两个模块Installation从装ROS到编译crazyswarm再到烧录固件的完整命令清单Tutorials包括校准地面站、室内实飞、仿真环境切换等操作级别的指导。文档站还有一个优势它按版本做了文档快照当你切换到某个旧分支时能查到对应的文档版本。这一点在实践中太救命了因为很多网上教程引用的API在老版本里根本不存在。2.3 Bitcraze官方硬件资料Crazyflie的硬件信息、Crazyradio PA的使用细节、固件烧录工具、Debug Adapter的接线方式全部在Bitcraze的官方文档和Wiki里。虽然crazyswarm是一个上层项目但你在安装过程中一定会和这些底层硬件打交道比如用cfloader烧写固件、用crazyflie-clients-python里的客户端连接飞机看状态、用cfclient检查传感器的实时数据。资料集中在bitcraze.io/documentation/repository/下的各仓库文档Bitcraze GitHub组织下的crazyflie-firmware和crazyflie-clients-python。在crazyswarm的语境里这些资料的作用是“底座”你不能等到飞机飞不稳了才回去翻硬件手册而是应该在搭建之前就对这些内容有基本概念。3. 硬件资料与装备清单按这份索引采购不出偏差3.1 集群硬件采购清单经常有人在群里问“我想组20台飞机需要买什么”答案其实比想象中简单。我整理了一份可以直接抄作业的清单组件推荐型号单台必须说明飞控板Crazyflie 2.1是核心控制板板载IMU、STM32F405、NRF51机架官方碳纤机架或3D打印机架是新手先用官方件公差最稳电机桨官方DC电机套装是正反桨各半官方动力套装最省心电池1S 250mAh LiPo是每台至少配2块交替充电保证出勤率充电板官方并行充电板否集群必备一次充6块省大量时间数传Crazyradio PA是一个地面端可管辖上百台强烈建议备第二个定位动捕系统VRPN桥接是实验室已有则跳过无动捕先做仿真通信普通WiFi路由器推荐用于地面站多电脑之间及VRPN数据分发保护桨叶保护罩套装强烈建议室内集群飞行的“安全带”采购时有一点要特别提醒Crazyflie 2.0和2.1在传感器和部分电气特性上有差异固件选择也不同买之前查一下Bitcraze官方“Supported Hardware”页面并和你想用的crazyswarm版本对齐。很多人栽在这个细节上飞机到了刷固件刷不进去最后发现是硬件版本太老官方固件早就不再支持了。3.2 机械模型文件与3D打印件如果你所在的实验室有3D打印机可以通过官方CAD资源打印备件。Bitcraze在GitHub上公开了机架、螺旋桨保护罩、电池仓等3D模型文件社区里也有很多改进版本比如加高了起落架的版本、兼容第三方摄像头支架的版本、方便绑定位标记点的版本。我的建议是第一套全用官方模型确认能正常飞行之后再去尝试社区魔改件。你不需要在搭建初期就引入“公差不对、装不上、飞起来震动大”这些额外变量。3.3 通信链路资料很多人忽略的“隐形瓶颈”crazyswarm的通信设计是它区别于普通多机系统的核心。Crazyradio PA虽然是单地面端控制多机但它并不是像WiFi那样每台飞机一个信道而是通过广播和时分机制来复用一个2.4GHz物理信道。官方Wiki的Crazyradio PA页面、crazyswarm源码里src/crazyswarm/scripts/下的通信相关脚本、以及launch目录里的radio参数构成了通信链路的三份核心资料。实操中常见的问题包括地面站天线位置不对导致部分飞机丢包、相邻实验场地之间工作在同一个信道形成干扰、发射功率设置过高反而造成接收器饱和。这些经验GitHub Issues里都有真实案例排查起来既花时间又容易上头建议提前养成“先从通信链路找原因”的思维习惯。4. 软件环境文档版本匹配是新手第一大坑4.1 系统版本和ROS版本怎么选版本这件事情我在调研阶段发现它其实是很多新手半天装不上的根本原因不是操作问题是版本压根没对齐。根据官方文档和维护者的回复目前主流可用组合是Ubuntu 18.04 ROS Melodic官方文档默认平台资料最多踩坑样本最丰富Ubuntu 20.04 ROS Noetic有社区成员验证过可用但需要自行处理部分依赖改动新手不建议作为首选Windows / macOS / ROS 2现阶段不要在这些平台上花时间crazyswarm主体代码仍是ROS 1ROS 2支持并不完整。所以我的建议非常直接找一台干净的Ubuntu 18.04机器虚拟机也行装ROS Melodic desktop-full然后严格按照ReadTheDocs的安装步骤走。虚拟机跑仿真没有性能问题但如果后面要接VRPN实时数据最好把地面站放在物理机上减少虚拟化层带来的USB和网络延迟。4.2 依赖库清单与编译顺序crazyswarm编译依赖并不复杂但缺一个库报错就会让人非常困惑。按官方安装文档整理主要依赖包括ROS Melodic桌面完整版自带Gazebo 9catkin_tools或catkin_makelibeigen3-dev矩阵运算库找不到头文件基本就是它geographiclib全球坐标转换工具yaml-cpp读取launch和配置文件libzip-dev固件烧录和日志工具需要编译顺序上我踩过坑不要一上来就直接catkin_make整个工作空间更不要在一个已经source了其他ROS工作空间的终端里去编译。正确做法是先.bashrc里只source ROS自带的setup然后进入ros_ws目录逐包编译看到每个包都成功后再整体构建。crazyswarm源码里的CMakeLists.txt对库版本很敏感漏装或者版本不对错误信息会把方向引到“缺某个头文件”然后你开始怀疑人生其实是依赖库版本的问题。4.3 仿真环境资料不买硬件也能跑通全链路仿真和实机共享同一套ROS节点框架区别只在于定位源实机从VRPN拿动捕数据仿真把Gazebo里模型的位姿模拟成VRPN话题输出。这一设计的好处是你可以在没有任何硬件的情况下把上层算法完全跑通等实机环境具备了再无缝切换。仿真相关资料集中在USC-ACTLab/crazyswarm_gazebo仓库包含无人机模型、控制器插件、仿真启动文件官方提供的仿真地图和launch文件用于构造不同形状的障碍物环境Gazebo官方教程中关于gazebo_ros_pkgs的部分。一个常见的坑是launch文件里topic名字不匹配仿真环境的定位话题叫/vrpn_client_node/...还是/gazebo/...直接决定了控制节点能不能收到位置。如果仿真里飞机不动排除姿势之外先检查rostopic list看定位话题是否真的在发布。5. 论文与算法资料导向源码的一条检索路线5.1 奠基论文是理解系统的第一块拼图crazyswarm不是纯粹的工程堆砌它的设计有一篇系统论文作为支撑Crazyswarm: A Large Nano-Quadcopter SwarmICRA 2017。这篇论文把硬件选型、通信方案、控制架构、系统评估一次讲透是整个项目最重要的文字资料。读它的时候不要只看摘要重点看系统架构图和实验部分你会对“集群系统在工程上到底难在哪里”有直观认识。还可以在Google Scholar里找到所有引用这篇论文的文章顺藤摸瓜就能看到后续几年的扩展工作更鲁棒的编队控制、更高效的轨迹规划、多机器人任务分配等。这条引文链比任何一篇综述都更适合你快速了解这个领域的演变。5.2 按研究方向找算法资料crazyswarm里已经实现了多种算法模块如果你的目标是做研究建议按方向找资料编队控制先看虚拟结构和领航者法的综述再看crazyswarm demo里编队行为的实现理解集中式规划是怎么下发到各个体上的避障与轨迹规划从速度障碍法RVO/ORCA入手github上很多实现都标注了和crazyswarm集成的思路crazyswarm源码里也有基于优化和采样的轨迹生成模块官方demo中就有在障碍物中间穿梭的实例集群安全与一致性参考多智能体一致性理论结合crazyswarm的时间同步机制理解“同一个期望轨迹为什么有的飞机做得好有的飞机误差大”。5.3 源码地图论文到代码之间的一条路论文和代码从来不是一一对应的所以要学会从源码反推算法。crazyswarm的话题接口注释里会提到论文名或算法名再结合GitHub上的commit历史基本能把模块对应起来。比如做编队的关注formation_controller做上层任务规划的看trajectory相关脚本做底层控制的去翻crazyflie_ros里的crazyflie_driver。每找一个模块都先读对应launch文件里挂了哪些参数再读节点代码效率和“一行行读整个src目录”完全不是一个量级。6. 社区经验与常见问题官方文档没有写透的部分6.1 Bitcraze论坛和GitHub Issues在中文搜索引擎里搜crazyswarm能看到的资料非常有限真正高质量的答案几乎都在Bitcraze论坛的crazyswarm版块和GitHub Issues里。这里记录了用户遇到的各种真实问题比如“某台飞机随机关联丢失”“VRPN话题时断时续”“编队飞行时某些飞机高度发散”以及官方维护者给出的排查方向。在这些地方搜关键词比在技术群里等人回答高效太多。GitHub Issues尤其适合用来查看版本兼容问题。搜索ROS Noetic、firmware、VRPN等关键词你能看到哪些问题已经解决、哪些是已知限制。我每一次升级依赖或更换硬件前都会先去Issues里扫一遍这个习惯帮我避开了至少两次严重的环境灾难。6.2 视频演示带来的直观感受crazyswarm在ICRA上的官方demo视频和USC ACT Lab发布的YouTube演示虽然是旧视频但仍然很有价值。看视频能给建立“集群规模”和“行为形态”的直觉比如20台、50台、100台飞机在视觉上完全是三个量级视频里的队形变换方式也和论文里的算法思路对应。如果访问不了国外视频平台B站上也有搬运版但建议把论文当作言语参考不要把视频里的技术点当作唯一真相。6.3 中文资料怎么筛选中文世界里的crazyswarm资料大多是官方安装步骤的翻译少部分包含个人排错经验。我看过的几篇质量还不错的搭建笔记都明确标注了所用commit和ROS版本这种笔记才值得参考。那些完全不提版本、只贴一堆成功截图的教程十有八九是环境快照照做反而容易出问题。作为你阅读这条索引时的原则任何中文教程都当成“线索”而不是“标准”最终优先级排序永远是官方文档 源码 论坛 中文博客。7. 索引怎么用按目标选路线而不是按顺序通读7.1 只跑仿真最省事的路线如果你手里没有硬件、没有动捕只是想先把crazyswarm跑起来感受一下集群控制按这个顺序走读ICRA 2017论文了解架构 → 看ReadTheDocs安装页 → clone主仓库和gazebo仓库 → 编译整个工作空间 → 跑官方仿真demo。这套流程不需要额外采购任何硬件一台普通配置的电脑就够了预计耗时一到两天。仿真里能验证的东西比想象中多轨迹跟踪、编队、避障策略都能做很多算法结论在仿真里就能初步验证。7.2 实飞一套小型集群的路线有仿真基础之后想上真机按这个节奏安排资料买齐第3章的硬件清单 → 阅读Bitcraze固件烧录文档并给飞机刷入匹配固件 → 配置动捕系统和VRPN → 用官方客户端连接单台飞机做校准 → 跑通单机手动起飞 → 两台飞机联调通信 → 再逐步扩大到5到10台。每一步对应的资料都以官方文档为主遇到通信类问题优先去Bitcraze论坛搜crazyswarm和radio关键词会比看任何教程都有针对性。7.3 做算法研究应该重点啃什么如果你的目标是发论文或者做深入的算法研究那么时间应该花在论文和源码精读上而不是反复折腾环境第5章的论文引文链整体读一遍 → 按自己的方向把源码模块拆开读 → 在仿真里对比不同参数的效果 → 去Issues和论坛里找你关注方向和实机表现相关的讨论。研究的重心是“改算法”而不是“搭环境”所以别在一遍遍重装系统上消耗太多精力。下面用一个简短的对照表把三条路线汇总一下目标核心资料硬件投入预计周期跑通仿真论文、ReadTheDocs、gazebo仓库无1~2天实飞集群硬件清单、Bitcraze Wiki、论坛案例中高1周以上算法研究论文引文链、源码模块、Issues可选持续迭代我把这套资料索引梳理出来之后最大的感受是crazyswarm的门槛并不在代码本身而在信息的分散程度。官方文档、论文、固件手册、论坛讨论就像四块拼图缺一块都拼不出完整画面。网上能搜到的中文资料又往往只覆盖了其中一个角导致很多人卡在第一步很久。后面这个系列我打算接着写编译过程的完整流程、仿真环境的实际踩坑记录、实机联调时的通信问题排查每一篇都会拿着具体的commit、具体的错误信息来讲尽量把那些官方文档里“默认你会”的部分补上。第一篇索引先到这里大家照着这份清单去收集资料下一步再动手的时候会轻松很多。