做无人机集群快两年了前后给实验室搭过三套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与ReadTheDocsCrazySwarm的官方文档主要分布在两处。一处是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.54Crazyflie用的电池接口是特殊定义的不同容量的电池重量和放电能力差异会影响整体飞行表现选电池时最好同步核对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上对锚节点布局、校准过程和定位质量有完整说明选择这条路线的朋友建议先读完整套部署文档再开始。从选型资料的角度我整理过一个对比表方案精度成本实时性适合场景主要资料位置VICON亚毫米极高高高精度的集群算法/飞行实验官网 Crazyswarm外部位姿配置文档OptiTrack毫米级高高大多数室内集群编队Motive软件文档 VRPN协议说明Loco UWB约10cm低较高入门学习、预算有限Bitcraze Wiki Loco系列页面不考虑极端精度需求时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编写的依赖编译的时候就会报出一堆找不到包的错误。这里给出一张我实际验证过的版本组合表Crazyswarm版本系统版本ROS版本Python依赖备注一代 crazyswarmUbuntu 20.04ROS1 NoeticPython 3.8教程最多兼容性好一代 crazyswarmUbuntu 18.04ROS1 MelodicPython 3.6较老不建议新环境二代 crazyswarm2Ubuntu 22.04ROS2 HumblePython 3.10新起点功能和实时性更好我自己实践下来如果实验室有一堆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这套框架并不难跑通难点一直被资料散落各处 版本快速变化两个因素放大。把这份地图理清楚之后后面每一篇笔记我都会沿着具体主题展开实操细节包括动捕标定流程、第一架飞机起飞、多机编队配置和常见故障实录。也建议你动手之前先把本篇文章提到的仓库和文档页收藏好搭建过程中随时回来对照比临时去搜索引擎里捞帖子靠谱得多。