真机控制

适用对象：需要在真实"雀"无人机上运行 SwarmCore 的用户强制前置：先在仿真中跑通同样流程（平台铁律，没有例外）；真机飞行时遥控器始终在手对应版本：2026-10-07 参数基线（二次冻结）

真机与仿真使用完全同一套 swarm_api 与命名空间规则（/uav_<N>/fmu/*），控制代码零改动——区别只在链路层和定位源。本文讲清这两层。

1. 硬件与链路拓扑

雀（每架）                          地面站电脑
┌───────────────────┐
│ MicoAir H743 飞控  │  TELEM2 (ttyS1, 921600)
│  + LinkTrack UWB   │──────────┐
│    tag（定位）     │          ▼
│  + 光流/激光测距   │     通信模块（串口→以太网）
└───────────────────┘     （端口2，UDP Server，921600 8N1）
                                │ UDP :8888（模块 IP 192.168.10.10x）
                                ▼
                    udp_serial_bridge.py（UDP↔PTY /tmp/ttyUAV_N，
                     带 ~KNOCK 看门狗，防 通信模块 锁对端死锁）
                                ▼
                    MicroXRCEAgent serial --dev /tmp/ttyUAV_N
                                ▼
                    ROS 2 话题 /uav_N/fmu/*（与仿真同构）

要点：

XRCE-DDS 走 UART 是 serial 帧，Agent 必须用 serial 模式，不能用仿真的 udp4。
MAVLink（QGC / fc_configurator，目标端口 14550）与 DDS 各走一个独立的通信模块通道/串口，互不干扰；但同一时刻只能一个客户端占用 MAVLink 通道——用 fc_configurator 前先关 QGC。
每架机的链路（bridge + Agent）是独立进程，多机互不影响。

2. 定位架构（室内纯 UWB，无磁罗盘）

LinkTrack UWB tag ──串口──► linktrack 驱动（飞控内）
                              CRC → 坐标变换(LT_TF_ROT/LT_TF_YAW) → 方差下限
                              → LT_MAX_STEP 毛刺拒绝 + hold-publish（拒帧重发
                                最后有效位置、方差×4，VO 流永不中断）
                              → 中值滤波 → 一阶低通
                                        ▼
                    vehicle_visual_odometry ──► EKF2 外部视觉融合

水平位置：UWB 经 EV 融合（EKF2_EV_CTRL=1，只融位置不融速度——速度融合已实测证伪）。
高度：激光测距（EKF2_HGT_REF=2），行为最接近仿真里的干净气压计。
航向：罗盘禁用（EKF2_MAG_TYPE=5）+ EKF2_YAW0_INIT=1 补丁——tilt 对齐完成瞬间航向归零，上电瞬间的机头方向 = 本地系 X 轴方向，之后纯陀螺积分（慢漂，短时间飞行可接受）。

摆放纪律（每次上电必做）

机头必须对准锚点 X 轴方向再上电（当前坐标约定 LT_TF_YAW=-90：本地系/地面站地图北=锚点X、东=-锚点Y）。摆错方向位置环会发散。
改动 LT_TF_YAW 与上电方向必须成对，二者是同一约定的两面。
地面站"前"方向恒定 = 地图北（YAW0_INIT + LT_TF_YAW=-90 前提下）。

3. 启动真机

前提（一次性配置）

飞控 SD 卡有 etc/extras.txt，内容含 uxrce_dds_client start ... -n uav_N（重启后无 DDS 话题 = 这个文件缺失）。
每架机：N == MAV_SYS_ID == UXRCE_DDS_KEY（uav_2 → sysid 2 → key 2）；UXRCE_DDS_CFG 指向通信模块对应串口（v1 板 ttyS1），波特率 921600 与通信模块一致；多机时各机 UXRCE_DDS_DOM_ID 必须都为 0。
通信模块已配置（工具见第 5 节）：端口2 = UDP Server、921600 8N1。

单机

~/0c00_ws/swarm_ws/src/bringup/scripts/start_real_uav.sh [N=1] [模块IP=192.168.10.100] [端口=8888]

多机

~/0c00_ws/swarm_ws/src/bringup/scripts/start_real_swarm_uav.sh        # 启动机队表全部
~/0c00_ws/swarm_ws/src/bringup/scripts/start_real_swarm_uav.sh 1 3    # 只起 1、3 号机

机队表在脚本顶部 UAV_LIST（编号：模块IP：UDP端口），加机改数组。每机独立 bridge+Agent，日志在 bridge_uav$N.log / agent_uav$N.log；单机失败不影响其余机，退出码反映是否有失败机。

验证链路

ros2 topic list | grep uav_1                     # 有话题 = 链路通
ros2 topic hz /uav_1/fmu/out/vehicle_local_position

4. 控制真机

链路起来后，与仿真完全相同的代码：

from swarm_api import Drone
d = Drone("uav_1")
d.takeoff(1.0)
d.goto(0, 2, 1.0)
d.land()
d.shutdown()

推荐先跑基线 demo 验证：demo_takeoff_hover_land.py → demo_square_goto.py → demo_circle_smooth.py 0.3（真机演示推荐，平滑模式压 UWB 噪声抖动）。

真机参数基线（2026-10-07 二次冻结，勿自行改动）

参数	值	说明
`EKF2_EV_CTRL`	1	只融 UWB 水平位置（加速度融合 bit 已证伪：动态污染）
`EKF2_EVP_NOISE`	0.4	EV 位置噪声；调低（紧融合）构成 ~200ms 延迟反馈，悬停失稳
`EKF2_EV_DELAY`	80	EV 延迟补偿 (ms)；改 200 无收益
`EKF2_HGT_REF`	2	激光测距定高
`EKF2_MAG_TYPE`	5	罗盘禁用（室内无磁方案）
`EKF2_YAW0_INIT`	1	上电航向归零补丁（需自编译固件，见 5.3）
`LT_COV_POS`	0.20	UWB 位置方差下限 (m²)
`LT_COV_VEL`	0.04	UWB 速度方差（EV_CTRL=1 下不融合，惰性）
`LT_MAX_STEP`	0.1	跳帧抑制门限 (m)，EMI 毛刺拒绝
`LT_LPF_TAU`	0.15	低通时间常数 (s)
`LT_MEDIAN_WIN`	3	中值滤波窗口
`LT_TF_ROT` / `LT_TF_YAW`	0 / -90	坐标约定：北=锚点X、东=-锚点Y
`MPC_THR_HOVER`	0.75	加重后实测悬停油门（参数上限 0.8）

已知物理地板：运动中 EKF 估计相对 UWB 真值弯曲 mean ~~0.06~~0.08m（瞬时 0.2~0.5m），目视轨迹毛边属正常，不是控制 bug；三个调参方向（速度融合/紧融合/延迟补偿）已实测证伪，封盘。再提升只有硬件路径（锚点布置优化 / VIO）。

5. 工具链

5.1 fc_configurator（飞控配置器）

python3 ~/0c00_ws/tools/fc_configurator/server.py   # http://localhost:8082

功能：参数全量拉取/搜索/导入导出、EKF2 定位参数设置页（中文注释）、五种校准、电机测试、.px4 固件烧录（仅 USB）、SD 卡文件管理。真机走网络连接：host=通信模块 IP、port=14550（先关 QGC，UDP Server 锁对端互抢）。

5.2 comm_module_config（通信模块配置工具）

python3 ~/0c00_ws/tools/comm_module_config/server.py   # http://localhost:8081

搜索/读/写/恢复出厂通信模块 + 配置导入导出。替代 Windows 版 NetModuleConfig。多网卡机器需在页面选择正确网卡。

5.3 真机固件编译

export PATH=~/0c00_ws/tools/toolchain/gcc-arm-none-eabi-9-2020-q2-update/bin:$PATH
make -C ~/0c00_ws/PX4-Autopilot micoair_h743_default
# 产物: PX4-Autopilot/build/micoair_h743_default/micoair_h743_default.px4
# 烧录: QGC 自定义固件，或 fc_configurator（USB）

改 LinkTrack 驱动或 EKF2_YAW0_INIT 补丁后必须重编烧录才生效。注意板型：雀是 H743 v1 板（TELEM2=ttyS1），v2 是 ttyS3，以真机 ver all 为准。

6. SOP 与安全

仿真先行：任何代码/参数改动先在仿真跑通同流程（demo PASS），再上真机。
上电前：机头对准锚点 X 方向；确认场地净高与围栏参数（GF_*）。
飞行中：遥控器始终在手——PX4 遥控器接管优先级最高，这是最后防线。
数据：联调/实验建议录 bag（至少 vehicle_local_position、vehicle_visual_odometry、vehicle_status），保留原始 bag 与实验备注。
变更纪律：真机参数基线已冻结，改动前先读 docs/MAINTENANCE.md 2026-10-07 条目（三个方向已证伪，不要重试）。

能力边界（未验证 = 不要承诺）

✅ 已验证：单机 DDS 链路、takeoff/goto/正方形/画圆（trajectory/smooth 均 PASS）、无磁航向方案、连续多趟 0 断流 0 EKF 重启 0 位置瞬移。
❌ 未验证：真机多机编队（链路各机已通、仿真已验证，真机未编队飞行）、VIO（待立项）。

7. 常见问题

Q1：重启后 ros2 topic list 没有飞机话题？ SD 卡缺 etc/extras.txt（uxrce_dds_client 自启）。用 fc_configurator 的文件管理（/fs/microsd/etc/）写入。

Q2：链路起了但某机话题不可见？ 检查 UXRCE_DDS_DOM_ID 必须为 0；UXRCE_DDS_KEY 与命名空间尾数一致。

Q3：fc_configurator 连不上真机？ 先关 QGC——通信模块 UDP Server 锁定对端，MAVLink 通道同时只服务一个客户端。

Q4：起飞后打转 / 飞走？ 上电时没对准锚点 X 方向（航向错 → 位置环正反馈）。断电重摆再上电。

Q5：.ulg 里 vehicle_visual_odometry 只有 33Hz？ 是 logger 降频（SDLOG_PROFILE=129），实际链路 100Hz；需全速率设 SDLOG_PROFILE=131。

Q6：电量/电流显示异常？ 已知待查项（2026-08-27 记录），不影响飞行控制。

8. 相关文档

单机仿真与控制 —— 真机前必先跑通的仿真流程
swarm_api 使用 —— 控制代码写法（仿真/真机通用）
AGENTS.md —— 真机参数基线与坑清单的权威记录
docs/MAINTENANCE.md —— 真机栈演进与证伪记录

本文档采用 CC BY-NC 4.0 许可。

1. 硬件与链路拓扑​

2. 定位架构（室内纯 UWB，无磁罗盘）​

摆放纪律（每次上电必做）​

3. 启动真机​

前提（一次性配置）​

单机​

多机​

验证链路​

4. 控制真机​

真机参数基线（2026-10-07 二次冻结，勿自行改动）​

5. 工具链​

5.1 fc_configurator（飞控配置器）​

5.2 comm_module_config（通信模块 配置工具）​

5.3 真机固件编译​

6. SOP 与安全​

能力边界（未验证 = 不要承诺）​

7. 常见问题​

8. 相关文档​