跳到主要内容

SwarmCore Web 地面站使用手册

🎮 不想部署也能先体验：地面站在线演示 —— 浏览器内置 3 架模拟无人机，可实际操作起飞、指点飞行、返航、话题记录与回放。演示数据为模拟生成，完整功能（真实飞控、CSV 导出、真机协同）请按本文档部署到自己的系统。

适用对象：SwarmCore 平台用户（仿真与真机通用） 前置条件：已完成 发行版安装，并能跑通 快速入门 的单机演示 对应版本：2026-07-27 及以后的发行版 一句话：浏览器打开就能用的集群无人机地面站，无需安装任何客户端

目录​

  1. 启动与连接
  2. 界面总览
  3. 状态卡片
  4. 控制按钮（解锁/起飞/返航/降落/上锁）
  5. 指点飞行
  6. 电子围栏
  7. 坐标系模式
  8. 话题记录与数据分析
  9. 3D 视图操作
  10. 注意事项汇总（必读）
  11. 常见问题

1. 启动与连接​

地面站由三个后台进程组成（一键脚本全部拉起）：

~/0c00_ws/swarm_ws/src/ground_station/scripts/start_ground_station.sh
# 停止: stop_ground_station.sh
进程作用
rosbridge (9090)ROS ↔ 浏览器的 WebSocket 桥
web_server (8080)网页服务 + /ws 中转（单端口设计，避开某些网络对 9090 的拦截）
web_control_node控制后端：按钮指令的可靠执行（基于 swarm_api 框架）
recorder_node话题记录后端（"记录"标签页）

启动后浏览器访问：

http://localhost:8080          # 本机
http://<地面站IP>:8080         # 局域网内其他电脑/平板

左上角连接灯变绿（"rosbridge 已连接"）即可使用。

注意：地面站只是"遥控器"，飞机数据来自仿真或真机。 先启动仿真（start_swarm_sim.sh 3 1，见 快速入门）或接入真机，页面才会有飞机出现。

2. 界面总览​

SwarmCore 地面站界面总览：左侧状态卡片、右侧 3D 视图与围栏圆柱、顶栏全局控制

三机仿真操作实录（约 80 秒）：一键全部起飞 → 爬升至设定高度 → 指点飞行实时规划轨迹 → 多机轨迹实时回传 → 一键全部降落、落地自动上锁：

  • 左侧：状态卡片（每架一张）+ "记录" / "数据"标签页
  • 右侧：3D 视图（左键旋转、滚轮缩放、右键平移）
  • 顶栏：全局控制、坐标系、围栏动作、起飞高度

3. 状态卡片​

每架飞机一张卡片，实时显示：

  • 飞行模式：PX4 当前导航状态（Offboard / AUTO_RTL / AUTO_LAND 等）
  • 电量与电压电流：百分比 + 颜色条（绿>50%，黄>25%，红≤25%）
  • 位置 N/E/高：北向/东向/高度（米）
  • 速度 水平/垂直：m/s

点卡片可以选中飞机（蓝色高亮边框）——选中状态用于指点飞行。

卡片变灰 = 该飞机超过 3 秒没有数据（掉线/仿真已停）。

关于位置/高度读数漂移：官方在线体验版中飞机位置纹丝不动，那是理想演示环境；在自己部署的仿真或真机中，悬停时位置/高度读数缓慢漂移是正常现象——来源于定位精度限制与传感器噪声（仿真 GPS 噪声、光流/UWB 精度、风扰等），并非地面站显示问题。真机的漂移幅度取决于定位源质量（动捕/RTK > UWB > 光流 > GPS）。

4. 控制按钮​

4.1 单机按钮（每张卡片上）​

按钮行为
解锁电机电机解锁（不起飞），命令重发直到确认
起飞完整 Offboard 起飞流程，升到"起飞高度"输入框指定的高度（默认 1.5m）
返航PX4 执行返航并自动降落上锁
降落原地降落，触地自动上锁
上锁电机锁桨。地面正常上锁；空中 PX4 会拒绝普通上锁，5 秒后自动升级为强制停桨（kill），飞机会坠落（有二次确认框）

4.2 全局按钮（顶栏）​

"全部起飞/全部返航/全部降落/全部上锁"对所有在线飞机同时执行，有确认框。

4.3 可靠性设计（了解即可）​

按钮不是"发了就不管"：指令发给后端 web_control_node，由 swarm_api 框架重发命令直到飞控确认，右下角会弹出"执行中…/成功 ✔/失败原因"。

注意事项：

  • 按钮在执行期间会置灰，等结果出来再点下一次，不要狂点；
  • 同一架飞机上一个动作没执行完，新动作会被拒绝（提示"请稍候"），这是保护机制；
  • 提示"后端无响应"说明 web_control_node 没在跑——重新执行 start_ground_station.sh；
  • 起飞高度逐次生效：改输入框只影响下一次起飞，不影响已在空中的飞机。

5. 指点飞行​

类似 RViz 的"点击目的地"：让选中的飞机飞向你点击的位置。

使用步骤：

  1. 飞机先起飞（指点飞行只在空中有效）；
  2. 点击顶栏【指点飞行】按钮（按钮发亮 = 已开启，鼠标变十字）；
  3. 点击左侧卡片选中目标飞机（默认选中第一架上线的）；
  4. 在 3D 视图的地面网格上单击目标位置——出现一个金色圆锥标记，飞机开始飞往该点，到达后标记消失并提示"成功 ✔"。

指点飞行实拍：金色圆锥为目标标记，右下角显示&quot;uav_1 指点飞行 执行中&quot;

规则与注意事项：

  • 目标高度 = 飞机当前高度（等高水平飞行，不改变高度）；
  • 围栏外的点会被拒绝并提示，不会发出指令；
  • 拖动旋转视角（位移超过 5 像素）不会误触发，放心调整视角；
  • 再次点击【指点飞行】关闭，恢复普通视角操作；
  • GPS 共享/本机 UWB 两种坐标系模式下都可以使用，页面会自动做坐标换算；
  • 指点飞行走的是 PX4 Offboard 位置模式，路径是直线——真机使用时确认路径上没有障碍物，框架没有避障。

6. 电子围栏​

页面中的青色圆柱 = 虚拟围栏（半径 10m × 高 6m，圆心 = uav_1 的起始位置），仅作演示与告警。

  • 飞机越界时机身变红，顶栏弹出红色告警条；
  • "围栏动作"下拉选择越界后自动执行：关闭 / 悬停 / 降落 / 返航（默认返航），15 秒内不重复触发；
  • 真正的安全兜底在飞控：PX4 侧写入了 GF_MAX_HOR_DIST=10、GF_MAX_VER_DIST=6，网页关了飞控围栏依然生效。

围栏动作下拉选项：关闭 / 悬停 / 降落 / 返航（默认返航），旁边是起飞高度输入框

注意事项：

  • 网页围栏是演示层，真机实验请以飞控围栏参数为准（布场后按 SOP 核对 GF_* 参数）；
  • 修改围栏尺寸目前需要改启动脚本参数/页面常量，不在页面上提供。

7. 坐标系模式​

顶栏"坐标系"下拉（选择后自动记住）：

模式含义适用
GPS 共享用经纬度把各机换算到共享平面（原点 = uav_1 的 EKF 原点）仿真、GPS 真机
本机/UWB各机本地坐标直接当全局坐标用UWB 定位的真机（UWB 各机天然同原点）

注意：仿真中每架飞机的本地坐标系原点在各自出生点，"本机/UWB" 模式下多机会重叠显示——仿真请用 GPS 共享模式。

8. 话题记录与数据分析​

"记录"标签页用于把飞行数据录成 rosbag（科研数据闭环）——飞完之后可以完整回溯每一次实验；"数据"标签页则把 bag 的查看、回放、导出全部收进网页，不用碰命令行。

记录标签页：按机勾选话题、预设按钮、实验备注、开始/停止、历史 bag 列表与目录占用

8.1 录制​

  1. 勾选要录的话题——话题列表是动态枚举的（页面上线时自动获取 ROS 图中全部有发布者的话题，按命名空间分组，10 秒自动刷新；以后视觉等新话题上线，点【刷新话题】即可出现，包括 IMU 原始数据 sensor_combined、机体系里程计 vehicle_odometry 等）；
  2. 预设按钮可快速选择：评估标准集（状态+位置+电量）/ 全选 / 清空；勾选结果自动记住，刷新页面不丢；
  3. 可选：填写实验备注（会写入 bag 目录的 metadata.json，建议养成习惯）；
  4. 点【开始记录】，状态区显示红色"● 录制中"和实时大小；
  5. 点【停止】结束。

标注 ⚠大流量 的话题（图像、点云类）会显著增加磁盘占用，按需短录。

8.2 历史记录​

下方列出最近的 bag（名称/大小），可单个删除（有确认框，删除不可恢复）。底部显示 bags 目录总占用，超过 20GB 会提醒清理——rosbag 不加选择地全录会迅速撑爆磁盘，这就是只录勾选话题的原因。

注意事项：

  • bag 存于 ~/0c00_ws/swarm_ws/logs/bags/；
  • 录制的飞机掉线不会中断录制，停止时才写盘收尾，不要直接 kill 进程（用页面【停止】按钮）；
  • 记录页话题列表为空说明仿真/真机没启动或 rosapi 未就绪，先启动再点【刷新话题】。

8.3 录制的数据如何回看（db3 格式）​

rosbag2 默认把数据存成 SQLite（.db3）+ metadata.yaml，不能双击直接打开。四种回看方式，由浅到深：

方式一：快速查看概要

source /opt/ros/humble/setup.bash
ros2 bag info ~/0c00_ws/swarm_ws/logs/bags/bag_20260727_120000
# 显示时长、消息总数、各话题的类型与条数

方式二：回放进 ROS（在地面站里"情景重现"）

source /opt/ros/humble/setup.bash && source ~/0c00_ws/swarm_ws/install/setup.bash
ros2 bag play ~/0c00_ws/swarm_ws/logs/bags/bag_20260727_120000
# 可选: --rate 0.5 半速慢放   --loop 循环播放

回放时打开 Web 地面站，飞机会按录制的轨迹重新飞行一遍，适合做实验复盘和演示。 注意：回放前先停掉仿真/真机，否则真实数据和回放数据混在同一批话题里。

方式三：画图分析（推荐，论文图表主力）：PlotJuggler

sudo apt install ros-humble-plotjuggler
ros2 run plotjuggler plotjuggler

启动后把 bag 目录整个拖进窗口，左侧勾选字段即可画曲线（位置、速度、加速度 ax/ay/az、电量随时间变化），支持多机对比、XY 轨迹图、导出 CSV。做集群误差分析优先用它。

方式四：Python 脚本批处理（自定义指标/导出 CSV）

平台装了 rosbag2_py，可以直接读消息。把下面存为 bag2csv.py，执行 python3 bag2csv.py <bag目录> > out.csv（先 source 两个 setup.bash）：

#!/usr/bin/env python3
"""把 bag 里的 vehicle_local_position（含加速度）导出成 CSV"""
import csv, sys
from rosbag2_py import SequentialReader, StorageOptions, ConverterOptions
from rclpy.serialization import deserialize_message
from px4_msgs.msg import VehicleLocalPosition

reader = SequentialReader()
reader.open(StorageOptions(uri=sys.argv[1], storage_id="sqlite3"),
            ConverterOptions("", ""))
w = csv.writer(sys.stdout)
w.writerow(["t_ns", "x", "y", "z", "vx", "vy", "vz", "ax", "ay", "az"])
while reader.has_next():
    topic, data, t = reader.read_next()
    if topic.endswith("vehicle_local_position"):
        m = deserialize_message(data, VehicleLocalPosition)
        w.writerow([t, m.x, m.y, m.z, m.vx, m.vy, m.vz, m.ax, m.ay, m.az])

换成其他消息类型（VehicleStatus、BatteryStatus…）只需改 import 和字段。

另外两个补充：

  • 每个 bag 目录里还有我们写入的 metadata.json（实验备注、话题列表、大小），cat 即可查看；
  • rosbag 是 ROS 侧数据，PX4 飞控侧的黑匣子 .ulg 是另一套，ulog 用 Flight Review 在线分析。查"飞控为什么这样决策"看 ulog，查"算法/集群表现"看 rosbag。

8.4 数据分析与回放（"数据"标签页）​

侧栏第三个标签页，把 bag 的查看、回放、导出、删除全部收进网页，不用碰命令行：

数据分析与回放标签页：左侧 bag 卡片列表（时长/条数/大小/操作按钮），右侧内置曲线面板展示 vehicle_local_position 的各数值字段时序曲线

  • bag 卡片：每个 bag 显示名称、时长、消息条数、大小、实验备注（来自 metadata.yaml 和 metadata.json）；
  • 查看数据（内置图表）：卡片上选话题、点【查看数据】，3D 视图左下角弹出曲线面板——该话题的所有数值字段（位置、速度、加速度、电压…）以时序曲线展示，勾选字段自由组合，关闭点 ✕。图表库已内嵌（uPlot），离线可用，不需要 PlotJuggler 也不用导出；
  • 回放：点【回放】= 后台执行 ros2 bag play，地面站 3D 视图"情景重现"。回放前请确认仿真/真机已停止（有确认框提醒），否则真假数据混在同一批话题里。再点【停止回放】结束；
  • 导出 CSV：点【导出 CSV】后台把 bag 里所有话题转成 CSV（每话题一个文件，全字段成列，消息类型不限——以后的视觉消息也自动支持），完成后卡片里出现【⬇ 下载 CSV】链接，下载 zip 包；
  • 删除：有确认框，不可恢复。

9. 3D 视图操作​

操作效果
左键拖拽旋转视角
右键拖拽平移
滚轮缩放（3~100m）
点击飞机卡片选中该飞机（指点飞行目标）
  • 网格间距 1m；北 = -Z 方向；坐标轴为 ROS 右手系（X 东 / Y 北 / Z 上）；
  • 飞机模型会显示真实姿态（滚转/俯仰/偏航），解锁后桨叶旋转、上锁停转；
  • 轨迹线保留最近一段（切换坐标系模式会自动清空轨迹，避免跨坐标系连线）。

下图为指点飞行与返航的三维轨迹实录——侧视视角可以清楚看到爬升、指点飞行与返航降落的垂直段：

无人机三维轨迹（侧视）：红色轨迹线记录指点飞行与返航过程，含爬升与降落的垂直段

俯视视角下轨迹与围栏圆柱的相对位置一目了然：

无人机三维轨迹（俯视）：指点飞行与返航轨迹在围栏圆柱内的投影

10. 注意事项汇总（必读）​

  1. 先启动仿真/真机，再开地面站；页面开着重启仿真不影响，数据会自动恢复。
  2. 改动页面后必须 Ctrl+F5 强制刷新——浏览器会缓存旧页面，功能和文档对不上时先想这一条。
  3. 按钮看右下角提示，失败要读原因（解锁超时多半是 preflight 没过：EKF 未收敛/没定位）。
  4. 真机飞行时遥控器始终在手，页面只是辅助——PX4 遥控器接管优先级最高。
  5. 真机实验前必须先在仿真中跑过同样流程（平台强制流程）。
  6. 指点飞行无避障，真机使用确认路径安全。
  7. 上锁电机按钮有确认框是有原因的：在空中点击 = 强制停桨 = 炸机，它本质上是紧急情况下的最后手段，不是常规降落方式——常规降落请用【降落】或【返航】。
  8. bags 和仿真日志都会持续占磁盘，定期清理（logs/ 目录，仿真日志自动保留最近 5 次，bag 需手动删）。

11. 常见问题​

Q1：页面打开一直"连接 rosbridge..."？ 地面站没启动或 8080 被占。执行 start_ground_station.sh；还不行看 tail /tmp/gs_http.log /tmp/rosbridge.log。

Q2：连接正常但"等待无人机数据…"？ 仿真/真机没启动。先 start_swarm_sim.sh 3 1，等 30~40 秒。

Q3：按钮提示"后端无响应"？ web_control_node 没运行。重新执行 start_ground_station.sh（缺哪个起哪个，不会重复启动）。

Q4：起飞失败，提示"进入 Offboard/解锁超时"？ 仿真刚启动 EKF 没收敛，等 15~20 秒再点；真机检查定位源。虚拟机用户检查 CPU 是否 ≥4 核（性能不足时 EKF 永远无法收敛）。

Q5：指点飞行点了没反应？ 依次检查：指点飞行开关是否打开（按钮发亮）、是否先选了飞机（卡片高亮）、飞机是否已起飞、目标点是否在围栏内。

Q6：飞机在 3D 图里位置不对/叠在一起？ 坐标系模式不对：仿真用"GPS 共享"，UWB 真机用"本机/UWB"。

Q7：为什么浏览器标签页上没有图标 / 页面没 logo？ 旧缓存，Ctrl+F5。

Q8：页面能同时几个人开吗？ 可以，rosbridge 支持多客户端，但操作建议只由一个人执行，避免多人同时给同一架飞机下指令（后端会拒绝并发，但容易引起误会）。

Q9：飞机明明在悬停，位置/高度读数却一直在漂，是地面站 Bug 吗？ 不是。在线体验版是理想演示环境所以看不到漂移；自己部署的仿真或真机中，定位精度限制与传感器噪声会让读数缓慢漂移（仿真 GPS 噪声下高度漂 ±0.5~1m 都常见）。想减小漂移：真机升级定位源（动捕/RTK/UWB）、保持传感器校准；仿真属预期行为，不影响功能验证。

文档版本：v1.1（2026-07-27），对应发行版 commit 023fddcd 及以后。功能变更时同步更新。