SwarmCore 快速入门教程：从零跑通第一个单机演示
适用对象：第一次接触 SwarmCore 的用户 / 客户评估人员 完成本教程约需 30~60 分钟（含环境安装） 最终效果：一架仿真无人机自动完成 起飞 → 向前飞 → 顺时针画 2m 正方形 → 回到原点 → 降落，并可在 Web 地面站实时观看
1. SwarmCore 是什么
SwarmCore 是一套面向科研与教学的低成本无人机集群验证平台，软件栈完全基于业界主流开源生态：
| 层次 | 组件 | 作用 |
|---|---|---|
| 飞控固件 | PX4 v1.15 | 飞行控制、状态估计（EKF）、安全保护 |
| 仿真器 | Gazebo Garden | 物理仿真（动力学、传感器） |
| 通信桥 | Micro-XRCE-DDS | 飞控 ↔ ROS 2 之间的数据桥 |
| 中间件 | ROS 2 Humble | 话题通信、功能包生态 |
| 地面站 | 自研 Web 地面站 | 浏览器查看状态、下发指令、电子围栏、数据记录 |
对开发者最友好的一点：仿真里写的控制代码，和真机完全通用——因为两边走的是同一套 PX4 Offboard 接口。
2. 环境要求与安装
系统要求、一键安装与发行版注意事项见 发行版总览与安装。安装完成后目录为 0c00_ws，本文后续命令均基于该路径。
3. 一分钟跑通演示
需要两个终端：
# 终端 1：启动单机仿真（第 2 个参数 1=无头，0=带 Gazebo 界面）
~/0c00_ws/swarm_ws/src/bringup/scripts/start_swarm_sim.sh 1 1
# 终端 2：加载环境，运行演示程序（ENU 坐标版，推荐新手）
source /opt/ros/humble/setup.bash
source ~/0c00_ws/swarm_ws/install/setup.bash
python3 ~/0c00_ws/swarm_ws/src/bringup/scripts/demo_square_enu.py
终端会依次打印：
等待飞控数据…（请先启动仿真）
地面实测高度 1.32 m，目标高度 2.82 m
预发设定点，然后请求 Offboard 模式 + 解锁…
>>> 起飞到 1.5m
>>> 向前飞（北）
>>> 右转，向东
>>> 右转，向南
>>> 右转，向西，回到原点
>>> 降落
已降落并上锁，演示完成 ✔
整个过程约 20 秒。想同时看 3D 画面，启动 Web 地面站后用浏览器打开 http://<主机IP>:8080：
~/0c00_ws/swarm_ws/src/ground_station/scripts/start_ground_station.sh
提示：页面如有异常请先 Ctrl+F5 强制刷新（浏览器缓存是新手最常见的问题来源）。
演示的起飞高度与正方形边长可通过参数调整（默认 1.5m / 2m）：
python3 ~/0c00_ws/swarm_ws/src/bringup/scripts/demo_square_enu.py --ros-args -p takeoff_alt:=2.0 -p side:=3.0
演示结束后如需清理环境：
~/0c00_ws/swarm_ws/src/bringup/scripts/stop_swarm_sim.sh # 停止仿真
~/0c00_ws/swarm_ws/src/ground_station/scripts/stop_ground_station.sh # 停止地面站
4. 演示程序做了什么（逐段讲解）
演示脚本位于 swarm_ws/src/bringup/scripts/demo_square_enu.py，全文约 150 行，纯线性结构。它是学习 PX4 Offboard 控制的最佳入口。
4.1 整体流程
等飞控数据 → 预发设定点 → 请求 Offboard+解锁 → 逐航点飞行 → 降落上锁
4.2 关键概念 1：Offboard 模式与设定点流
PX4 的 Offboard 模式允许外部计算机（这里是我们脚本）直接给飞控发位置设定点。两条铁律：
- 必须先连续发一段设定点，飞控才允许切入 Offboard——所以脚本先预发 1 秒再请求切模式；
- 设定点必须持续发送（≥2Hz），一旦断流，飞控判定"Offboard 失联"自动降落——这也是脚本被 Ctrl+C 后飞机不会掉下来的原因。
4.3 关键概念 2：坐标系（NED 与 ENU）
| NED（PX4 飞控内部） | ENU（ROS 惯例，REP-103） | |
|---|---|---|
| x | 北 | 东 |
| y | 东 | 北 |
| z | 下（负值=向上） | 上 |
| 航向 0° | 北，顺时针为正 | 东，逆时针为正 |
demo_square_enu.py 里你看到的所有坐标都是 ENU，只在两个函数里做转换，这也是理解坐标系的全部内容：
def enu_to_ned(x, y, z): # 位置：直接换轴
return y, x, -z
def yaw_enu_to_ned(yaw): # 航向：差 90° 且方向相反
return math.pi / 2 - yaw
仓库里另有 demo_square.py（NED 版），逻辑完全相同，可对照阅读。
4.4 关键概念 3：高度基准
EKF 的高度原点在仿真/室内环境下可能有偏差。因此脚本不用写死的绝对高度，而是：
h_target = node.pos[2] + TAKEOFF_ALT # 目标高度 = 起飞前实测高度 + 想爬的高度
这样无论飞控的高度零点偏到哪，飞机都严格爬升 1.5m。
4.5 关键概念 4：QoS 与命令目标
- 发给飞控的话题（
/uav_1/fmu/in/*）必须用默认 QoS（reliable），否则指令被静默丢弃；订阅飞控话题（fmu/out/*）用best_effort。 VehicleCommand.target_system必须等于该机的MAV_SYS_ID（单机仿真固定为 1），否则命令被忽略。
4.6 航线设计
| 航段 | ENU 目标点 | 说明 |
|---|---|---|
| 起飞 | (0, 0) | 爬升至 1.5m |
| 边 1 | (0, 2) | 向前（北）2m |
| 边 2 | (2, 2) | 右转，向东 2m |
| 边 3 | (2, 0) | 右转，向南 2m |
| 边 4 | (0, 0) | 右转，向西 2m，回到原点 |
每段把机头对准航段方向（atan2 计算），到达判定为水平与垂直误差同时小于 0.3m。
5. Web 地面站使用指南
本节是速览，完整功能说明（指点飞行、围栏、话题记录等）见 Web 地面站使用手册。
启动：~/0c00_ws/swarm_ws/src/ground_station/scripts/start_ground_station.sh，浏览器打开 http://<主机IP>:8080。
- 状态卡片：每机的解锁状态、飞行模式、电量、电压/电流、位置、速度；3 秒无数据自动变灰。
- 控制按钮：每架卡片下有 解锁/起飞/返航/降落/上锁；顶栏有全局按钮和起飞高度输入框（默认 1.5m）。起飞 = 自动先解锁再起飞，单击即可。
- 3D 地图：四旋翼标记（桨叶解锁旋转/上锁停转）、机名标签、历史轨迹；左键旋转、右键平移、滚轮缩放。
- 坐标系切换（顶栏）：
GPS 共享（各机经纬度换算共享坐标，适合 GPS/仿真）与本机/UWB（各机本地坐标即全局坐标，适合 UWB 定位的真机）。 - 电子围栏：青色全息圆柱（默认 R10m × H6m），越界变红告警，并按顶栏所选动作（关闭/悬停/降落/返航）自动处置；飞控侧另有
GF_*参数强制兜底。 - "记录"标签页：勾选话题后用 rosbag 只录所选内容，bag 存于
swarm_ws/logs/bags/。
6. 常用参数与环境变量速查
| 参数 | 位置 | 默认 | 说明 |
|---|---|---|---|
| 起飞高度 | Web 顶栏输入框 | 1.5 m | 起飞命令的目标高度（相对起飞点） |
GF_ACT | 启动脚本环境变量 | 3（返航） | 飞控围栏动作：0=无 1=警告 2=悬停 3=返航 5=降落 |
RTL_ALT | 启动脚本环境变量 | 0 | 返航爬升高度 RTL_RETURN_ALT，0=按当前高度返航不爬升 |
HGT_REF | 启动脚本环境变量 | 1（GPS） | EKF 高度参考 EKF2_HGT_REF |
示例：GF_ACT=2 RTL_ALT=10 ~/0c00_ws/swarm_ws/src/bringup/scripts/start_swarm_sim.sh 1 1
7. 常见问题（FAQ）
Q1：页面显示"等待无人机数据"或 rosbridge 已连接但没飞机？ 先 Ctrl+F5 强刷页面。rosbridge 重启过的话，新版页面会在重连后自动恢复订阅，等 2 秒即可。
Q2：点"起飞"没反应？ PX4 的起飞命令只切换模式，未解锁时不执行——本地面站的起飞按钮已内置"先解锁后起飞"，若仍无反应，检查卡片上是否有位置数据（解锁前需要位置估计就绪）。
Q3：地面站里飞机高度显示和 Gazebo 不一致 / 悬停时读数一直在漂？ 正常现象，不是地面站 Bug。仿真 EKF 各实例的海拔有 ±0.5~1m 散布（GPS 仿真噪声特性），悬停时位置/高度读数缓慢漂移也源于定位精度与传感器噪声；真机的漂移幅度取决于定位源质量（动捕/RTK > UWB > 光流 > GPS）。地面站显示的高度是"相对各机起飞点"的语义，以卡片读数为准。
Q4：脚本发命令飞机完全不理？
十有八九是 QoS 或 target_system 问题，参见 4.5 节。
Q5：日志把磁盘写满了？ 历史版本曾因 PX4 控制台刷屏产生几十 GB 日志，已修复；当前仿真日志只保留最近 5 次，rosbag 请在"记录"页勾选所需话题。
Q6：局域网内别的电脑打不开地面站？
确认用 http://<主机IP>:8080。当前版本页面与 WebSocket 共用 8080 单端口，只需放行这一个端口。
8. 从仿真到真机
仿真代码可直接用于真机（同一套 Offboard 接口），但请注意：
- 定位：室外用 GPS/RTK，室内必须接入 UWB 或动捕（经
vision_position_estimate喂给 EKF），并把地面站坐标系切到"本机/UWB"； - 安全：真机务必配置飞控侧电子围栏（
GF_*）、返航高度（RTL_RETURN_ALT，按场地障碍物设置并告知飞手）、遥控器随时可接管； - 通信：多机 WiFi 环境需调整 DDS 发现机制，图像等大数据不要裸传；
- 流程：建议 HITL（硬件在环）→ 单机外场 → 多机逐步验证。
9. 目录与脚本速查
0c00_ws/
├── install.sh # 一键安装
├── PX4-Autopilot/ # PX4 飞控源码（v1.15.4）
├── Micro-XRCE-DDS-Agent/ # DDS 桥源码
└── swarm_ws/src/
├── bringup/scripts/
│ ├── start_swarm_sim.sh # 仿真启动 [机数] [0=GUI/1=无头]
│ ├── stop_swarm_sim.sh # 仿真停止
│ ├── demo_square.py # 单机演示（NED 版）
│ ├── demo_square_enu.py # 单机演示（ENU 版，推荐）
│ └── swarm_takeoff.py # 三机集群起飞基线（也可 ros2 run bringup swarm_takeoff.py）
├── swarm_msgs/ # 自定义消息（TargetMap / TaskAssignment）
└── ground_station/
├── scripts/ # 地面站启停、web 服务、话题记录
└── web/ # 地面站前端（Three.js）
10. 下一步
跑通单机演示后，继续学习 集群控制框架（swarm_api）——QoS、坐标转换、设定点流这些样板代码全部封装好，用十几行代码控制 N 架无人机同时起飞、编队、降落。
本文档对应 SwarmCore 仿真发行版，安装与发行版注意事项见 发行版总览与安装，如有更新以仓库 README 为准。