常见问题排查

本页按“动捕系统”和“无人机飞行”分类汇总教程中的常见问题及建议检查顺序。遇到飞行相关异常时，应先保证人员和设备安全，再根据终端中最早出现的报错逐项检查。

动捕系统

软件无法启动或授权失败

依次检查：

1. 软件加密狗是否已经插入电脑；
2. Windows 是否正确识别加密狗；
3. License 文件是否来自设备管理员或 NOKOV 客服；
4. License 是否与当前软件版本匹配；
5. 软件是否提示授权过期或设备数量不匹配。

仍无法解决时，记录错误提示截图并联系设备管理员或 NOKOV 客服。

软件无法识别摄像头

常见原因是电脑与摄像头不在同一网络。

请检查：

• 摄像头和交换机是否供电；
• 网线是否插在正确端口；
• 电脑 IP 是否为 10.1.1.198；
• 子网掩码是否为 255.255.255.0；
• 是否存在冲突的网络连接；
• 防火墙是否阻止软件通信；
• 能否通过 ping 命令访问摄像头。

参见：配置动捕系统网络

摄像头全部显示在原点

如果是首次启动且尚未完成 T 型杆标定，这通常属于正常现象。完成标定并计算摄像头位置后，摄像头应显示在计算得到的实际位置。

2D 视图中出现白色圆点

在没有标定杆时出现的白色小圆点通常来自反光物体或外部红外干扰。示例图中所示这种小点其实可以忽略，但是如果出现比较大的白点则建议：

• 拉上窗帘；
• 移除镜面、玻璃和反光金属；
• 遮挡无法移除的反光区域；
• 检查周围房间或设备的红外光源；
• 清理完成后重新进行环境遮蔽。

参见：检查摄像头

T 标定覆盖率不足

可能原因包括：

• 挥杆范围只集中在场地中心；
• 高处、低处或边缘区域未覆盖；
• 标记点被手或身体遮挡；
• T 型杆参数与实物不一致；
• 场地中存在较强反光干扰。

建议重新清理反光点并覆盖更多拍摄区域。

T 标定偏差值过大

原始文档建议偏差值保持在 1.1 及以下。如果结果高于建议范围，可按以下顺序重新检查：

1. 标定杆参数是否正确；
2. 摄像头是否牢固、标定过程中是否发生移动；
3. 场地中是否存在未处理的反光点；
4. 挥杆是否覆盖全部摄像头和场地区域；
5. 是否有人或物体在标定过程中进入场地。

然后重新执行环境遮蔽和 T 型杆标定。

L 标定无法建立原点

通常是软件没有同时识别 L 型杆的四个标记点。

请检查：

• 四个标记点是否完整；
• 是否有人或物体遮挡；
• L 型杆是否处于全部摄像头可见区域；
• 标定框架参数是否与实物一致；
• L 型杆是否稳定摆放。

刚体创建后方向不正确

请暂停后续飞行实验，并重新检查：

• 无人机是否沿 X 轴正方向摆放；
• 选择的四个点是否全部属于同一架无人机；
• 骨骼朝向是否设置为 X；
• 刚体坐标轴是否与场地坐标轴正确对应；
• X、Y 平移值是否按照流程归零；
• 刚体名称是否与代码配置一致。

不要带着错误坐标直接起飞

动捕位置、朝向或刚体命名存在问题时，应先在软件和控制程序中完成核对，不要直接进入无人机飞行测试。

位姿存在但起飞异常（动捕软件问题）

如果无人机已经离地，应先立即降落或执行现场规定的急停。无人机落地上锁后，首先检查动捕软件的问题，若下述问题未发生则参考位姿存在但起飞异常（其他原因）。

首先点击软件界面左上角的“数据广播”按钮，位置如下图所示：

如果软件当前界面中对应位置没有该按钮，点击左上角“视图”按钮后点击“数据广播”按钮即可。

数据广播界面中可以详细设置 VRPN 流中的部分参数。首先，将“启用 VRPN”右侧的滑块由“开启”切换为“关闭”（此时软件界面右下角的 VRPN 左侧勾选框会自动取消勾选），此时下方所有参数均可自由更改。

接下来需要注意的是动捕系统传输 VRPN 数据时使用的单位必须与上位机保持一致。默认情况下上位机使用的单位是“米”，但动捕软件第一次使用时可能默认传输单位为“毫米”，如果上述情况发生，需要将单位切换为“米”并重新启用 VRPN。

无人机飞行

问题排查原则

遇到问题时，建议先记录“在哪台电脑、哪个终端、执行了什么命令、最早出现了什么报错”，再按本页对应栏目排查。不要只截取终端最后一行，因为最后显示的错误可能只是前面某个步骤失败后的连锁结果。

排查时先判断问题属于哪一层：

现象	优先检查
Compose 启动时提示没有镜像	Docker 镜像名称和标签
容器启动后立即退出	容器日志和 Compose 配置
地面站或 RViz 窗口不出现	DISPLAY、X11 授权和套接字挂载
ros2、包或 launch 文件找不到	ROS 2 与工作空间环境是否已加载
没有无人机位姿话题	Windows VRPN、网络、刚体名称和客户端
有 VRPN 话题但 FCU 收不到	话题名称、消息类型和 remap
位姿正常但飞行姿态异常	坐标轴、机头方向、刚体识别和设备编号
点击解锁后没有反应或只有三声报警音	无人机重新上电后的高度初始化
RViz 面板不存在或飞控打不开	自定义面板包、串口设备号和启动终端报错

排查期间禁止起飞

只要位姿、飞控、控制面板或降落手段中任意一项尚未确认正常，就不要解锁或起飞。已经起飞后出现异常时，应先安全降落或执行现场急停，再继续运行诊断命令。

Docker 镜像或容器问题

找不到镜像

现象：

pull access denied
No such image: aiswarmlab_control:ros2_cmdvel_bridge_v2

检查：

docker images | grep aiswarmlab_control

处理：重新执行 docker load -i ...，并确认镜像标签与 Compose 文件一致。

容器没有运行

在 Ubuntu 宿主机执行：

docker ps -a --filter name=aiswarmlab_vrpn
docker logs aiswarmlab_vrpn

如果已有同名但停止的容器，不要盲目重复创建。先确认它是否为本项目当前版本，再决定使用 docker start aiswarmlab_vrpn 还是由维护人员处理旧容器。

地面站或 RViz 无法显示

常见报错：

could not connect to display
Could not load the Qt platform plugin "xcb"

在宿主机检查：

echo "$DISPLAY"
xhost +local:docker

在容器中检查：

echo "$DISPLAY"
ls -la /tmp/.X11-unix

如果仍有问题，可在宿主机桌面终端尝试项目已有记录中的授权方式：

xhost +SI:localuser:$(id -un)

地面站图标显示为乱码时，镜像可能缺少彩色 Emoji 字体。仓库已有记录的依赖为：

sudo apt install fonts-noto-color-emoji

安装系统依赖会修改容器环境，应由镜像维护人员统一处理。

编译或包缺失

colcon build 失败

先确认 ROS 2 环境：

source /opt/ros/humble/setup.bash
which ros2
which colcon

成功时，which ros2 和 which colcon 都应输出可执行文件路径。然后进入主工作空间重新构建，并显示较完整的实时输出：

cd /home/linuxbrew/swarmlab_simulator_ws
colcon build --event-handlers console_direct+

应查看终端中最先出现的 Failed 包和它前面的具体错误；后续 Aborted 包往往只是依赖该包失败后的结果。一次只处理最早的根因，修改后再重新构建。

编译时机

不要在无人机仍处于解锁或飞行状态时重新编译工作空间，也不要在多个终端中同时对同一个工作空间执行 colcon build。

找不到 ROS 2 包或 launch 文件

每个新打开的容器终端都需要重新加载基础 ROS 2 环境和项目安装空间：

source /opt/ros/humble/setup.bash
source /home/linuxbrew/swarmlab_simulator_ws/install/setup.bash
ros2 pkg list | grep fcu_core

每个新终端都需要重新 source，一个终端中的环境不会自动传递给另一个终端。

检查关键包：

ros2 pkg prefix fcu_core
ros2 pkg prefix rviz2_custom_panel

成功判据：命令能输出对应包的安装路径。如果基础 ROS 2 环境已加载，但仍找不到项目包，通常表示主工作空间没有成功编译、编译后没有加载 install/setup.bash，或当前终端加载了错误的工作空间。

VRPN 没有无人机话题

先判断网络还是 ROS 2 客户端问题

在容器中依次执行：

ping -c 3 10.1.1.198
ros2 node list | grep vrpn
ros2 topic list | grep vrpn
ros2 topic list | grep uav

各命令的含义如下：

检查	正常表现	异常时优先处理
ros2 node list | grep vrpn	能看到 VRPN 客户端节点	检查终端 C 的 launch 是否成功启动
ros2 topic list | grep vrpn	能看到带 VRPN 前缀的 tracker 话题	检查 Windows VRPN 服务、端口及刚体名称
ros2 topic list | grep uav	能看到目标无人机位姿话题	检查刚体命名以及话题转发/remap

同时在 Windows 动捕主机检查：

• VRPN 数据发送服务已经真正启动，而不只是打开了动捕软件；
• Windows 主机 IP 仍为 10.1.1.198；
• VRPN 使用的端口为 3883；
• Windows 防火墙允许该通信；
• 目标刚体处于可见和持续跟踪状态；
• 刚体名称与无人机编号一致，例如无人机 1 使用 uav_1；
• 刚体名称没有空格、连字符或其他不适合 ROS 2 名称的字符。

网络正常但没有 VRPN 节点时，应回到终端 C 查看 vrpn_client_ros 启动时最先出现的错误。存在节点但没有 tracker 话题时，应优先检查 Windows 发送端和刚体识别状态。

有 VRPN 话题，但 FCU 收不到位姿

比较目标话题和带 VRPN 前缀的话题：

ros2 topic list | grep '/uav_1/pose'
ros2 topic list | grep '/vrpn_client_node/uav_1/pose'

如果只有 /vrpn_client_node/uav_1/pose，请按动捕与 VRPN 定位中的方法转发或修改 remap。

位姿存在但起飞异常（其他原因）

如果无人机已经离地，应先立即降落或执行现场规定的急停。无人机落地上锁后，再检查：

• 动捕刚体坐标系是否与无人机机头方向一致；
• 平移无人机时，x/y/z 的方向和单位是否符合现场坐标定义；
• 静止时数据是否稳定，移动和旋转时是否连续，有无冻结、突跳或 NaN；
• 刚体标记点是否牢固，是否存在反光点串扰或刚体误识别；
• 无人机编号、动捕刚体名称和 /uav_<编号>/pose 是否一一对应；
• 是否存在多个节点同时发布同一个位姿话题；
• 算法环境、设备 ID 和场地边界是否与本次真实设备一致。

ros2 topic echo /uav_1/pose
ros2 topic info /uav_1/pose -v

点击解锁后无人机无法解锁

将无人机关机重启后，托举至离地面 1m（或以上）高度，等待一段时间直至飞机播放出提示音效再将其平稳放回地面。此时在控制台即可正常解锁无人机。

RViz 面板、串口与设备号

RViz 中没有自定义控制面板

先在启动 RViz 的容器终端加载环境并检查包：

source /opt/ros/humble/setup.bash
source /home/linuxbrew/swarmlab_simulator_ws/install/setup.bash
ros2 pkg prefix rviz2_custom_panel

如果命令能输出安装路径，说明包可以被 ROS 2 发现。随后在 RViz 中通过以下菜单添加：

Panels -> Add New Panel -> rviz2_custom_panel/Rviz2Panel

串口权限或设备号错误

ls -l /dev/ttyACM*
ls -l /dev/ttyUSB*

当前容器通过 Compose 挂载了 /dev 并启用了 privileged: true。如果 launch 配置写的是 /dev/ttyACM0，但实际设备是 /dev/ttyACM1，仍然需要修改配置，单纯增加权限无法解决设备号不一致。

C30D 底板小车

WiFi 模块 AT 配置

发送 AT 没有任何返回

检查：

• 串口号是否正确；
• 串口是否被其他软件占用；
• TX/RX 是否交叉；
• GND 是否连接；
• 模块是否供电；
• 当前波特率是 115200 还是 921600；
• 是否启用了 CRLF；
• 模块是否已经自动进入透传。

如果模块处于透传，关闭 CRLF 后发送 +++，等待约 500 ms，再启用 CRLF 发送 AT。

手动创建 UDP Client 的时候（或手动进入临时透传的时候）接收到 ERROR

如下图所示：

通常是 Socket 数量不对，或者类型不对。首先用以下命令查询当前的所有连接：

AT+SOCKET?

可能会返回类似：

1,2,3,192.168.1.43,8888,-1,-1
2,2,3,192.168.1.43,8888,-1,-1
5,2,3,192.168.1.43,8888,-1,-1
OK

上述每一行开头的数字就是 ConID。下一步需要把所有连接都删除，例如：

AT+SOCKETDEL=1
AT+SOCKETDEL=2
AT+SOCKETDEL=5

具体删除哪些，需要以 AT+SOCKET? 实际查询到的结果为准。官方指令格式就是：

AT+SOCKETDEL=<ConID>

多余连接全部删除后，重新输入创建 Socket 指令（或进入临时透传指令）即可。

1.2 串口接收区乱码

最常见原因是波特率不匹配：

• 恢复出厂或首次配置：尝试 115200 8N1；
• 已执行 AT+UARTCFG=921600,8,1,0 并重启：使用 921600 8N1；
• 切换参数后必须关闭并重新打开串口。

还应检查电源是否稳定、GND 是否可靠，以及 USB-TTL 是否支持 921600。

1.3 +++ 无法退出透传

确认：

• 只发送三个 ASCII 加号；
• 关闭 CRLF；
• 没有空格；
• 没有使用 HEX 字符串文本 2B2B2B；
• 发送前后保留约 500 ms 静默；
• 当前确实已经进入 AT+SOCKETTT 或自动透传。

1.4 模块无法连接 WiFi

检查：

• SSID 和密码大小写；
• 指令中的双引号是否完整；
• WiFi 是否为模块支持的频段，常见模块只支持 2.4 GHz；
• 路由器是否限制新设备；
• DHCP 地址池是否可用；
• 模块供电是否在连接 WiFi 时掉压。

1.5 AT+SOCKET 返回错误

检查命令格式：

AT+SOCKET=2,192.168.2.128,8888

• 2 为 UDP Client；
• IP 不加双引号；
• 端口为纯数字；
• 模块必须先取得 WiFi IP；
• 地面站目标 IP 必须与实际网卡地址一致。

1.6 重启后没有自动透传

检查是否执行并收到 OK：

AT+WAUTOCONN=1
AT+SOCKETAUTOTT=2,<GROUND_IP>,8888

还要确认模块重启后可以自动取得 IP。如果地面站 IP 已变化，需要退出透传后重新配置目标地址。

1.7 tcpdump 完全没有 UDP 数据

按顺序检查：

1. WiFi 模块是否在线；
2. 自动透传目标是否正确；
3. C30D 是否向 UART5 发送数据；
4. PC12/TX 是否接到模块 RX；
5. 两端是否同为 921600 8N1；
6. 地面站网卡是否与模块互通；
7. 防火墙和 AP 隔离；
8. 抓包是否使用了 -i any。

1.8 有 UDP 包但没有 ROS2 话题

执行：

sudo tcpdump -ni any -XX -c 10 udp port 8888
ros2 topic echo /vehicle_info
ros2 topic hz /robot_2/velocity

可能原因：

• vehicles.yaml 源 IP 填错；
• UDP 数据长度不是 24 字节；
• 波特率不匹配导致串口数据损坏；
• 帧头、帧尾或 XOR 校验错误；
• protocol 不是 stm32_wheeltec；
• 修改配置后没有重新构建或重启；
• 当前终端 source 了错误工作空间。

1.9 车辆出现错误的 robot_N 编号

通常是未知 IP 被 auto_register 自动分配。用抓包确认源 IP，在 vehicles.yaml 中添加静态配置，并保证 mapped_id 唯一。

1.10 UDP 8888 端口被占用

错误可能类似：

Address already in use

检查：

ss -lunp | grep ':8888'
ps -ef | grep '[b]ridge_node'

关闭旧桥接，只保留一个实例。特别注意不要同时运行命令行桥接和 UI 桥接。

1.11 ROS2 状态正常但小车不动

上行状态正常说明 PC12/TX 到 WiFi RX 大概率可用，但下行还需单独检查：

• /robot_2/cmd_vel 是否有桥接订阅者；
• 地面站是否向小车发出 UDP 包；
• WiFi 模块是否支持双向 UDP 透传；
• WiFi TX 是否连接 C30D PD2/RX；
• C30D 是否收到有效 11 字节控制帧；
• 小车是否处于允许 ROS 控制的固件模式；
• 是否有安全状态、电压保护或其他模式阻止电机输出。

1.12 ackermann_msgs 缺失

错误：

ModuleNotFoundError: No module named 'ackermann_msgs'

处理：

sudo apt install ros-humble-ackermann-msgs
source /opt/ros/humble/setup.bash
cd "$WS"
colcon build --packages-select wheelswarm_bridge --symlink-install
source install/setup.bash

不要执行 pip install ackermann_msgs。

1.13 地面站按钮报槽函数参数错误

如果出现：

_on_generate_environment() takes exactly 1 positional argument (2 given)

这是 UI 信号槽参数或 Cython 模块版本问题，不是 C30D、WiFi 或 UDP 通信问题。应在与当前 .so 对应的源码中让槽函数接收可选参数，或用 lambda 忽略 clicked(bool) 传入的布尔值，并用相同 Python 版本重新编译。

1.14 C30D 串口设备异常

C30D 2.0 之后的板载 CH9102 串口芯片提供 RTS 复位点。如果连接电脑有提示音但不出现串口设备，可能是串口芯片配置异常。该操作只针对板载 USB 串口芯片，不是 WiFi 模块常规配置步骤；应依据 C30D 原厂复位说明，在断电和明确目标芯片后操作，避免误短接其他引脚。

2. AT 指令速查表

除 +++ 外，下列指令均使用 ASCII 文本并启用 CRLF。

指令	用途	预期结果/注意事项
AT	测试命令模式通信	返回 OK
AT+WMODE=1,1	设置 STA 模式并保存	返回 OK
AT+WJAP="<SSID>","<PASSWORD>"	连接 WiFi	等待 WIFI_CONNECT、WIFI_GOT_IP、OK
AT+WAUTOCONN=1	开启上电自动重连	返回 OK
AT+UARTCFG=921600,8,1,0	设置模块串口为 921600 8N1	返回 OK 后重启并切换串口助手波特率
AT+SOCKET=2,<GROUND_IP>,8888	手动创建 UDP Client	IP 不加引号
AT+SOCKETTT	手动进入临时透传	进入后普通 AT 不再解析
+++	退出透传	关闭 CRLF，不加空格，前后等待约 500 ms
AT+SOCKETAUTOTT=2,<GROUND_IP>,8888	固化上电自动 UDP 透传	2 为 UDP Client
AT+SOCKETAUTOTT=0	取消自动透传	返回 OK
AT+RST	重启模块	按当前保存参数重新启动
AT+RESTORE	恢复出厂	清空配置，通常恢复为 115200

2.1 可直接执行的配置清单

先以 115200 8N1 打开串口，并启用 CRLF：

AT
AT+WMODE=1,1
AT+WJAP="<WIFI_SSID>","<WIFI_PASSWORD>"
AT+WAUTOCONN=1
AT+UARTCFG=921600,8,1,0
AT+RST

将串口助手切换到 921600 8N1，关闭并重新打开串口：

AT
AT+SOCKET=2,<GROUND_IP>,8888
AT+SOCKETTT

完成临时测试后，关闭 CRLF 发送：

+++

等待约 500 ms，重新启用 CRLF：

AT
AT+SOCKETAUTOTT=2,<GROUND_IP>,8888
AT+RST

3. 最终验收清单

3.1 硬件与串口

• [ ] 已确认 C30D 版本和雷达串口位置；
• [ ] PC12/TX 接 WiFi RX；
• [ ] PD2/RX 接 WiFi TX；
• [ ] GND 共地；
• [ ] 模块供电电压正确且稳定；
• [ ] USB-TTL 已拆除，没有双重供电或双 TX 冲突；
• [ ] C30D UART5 和 WiFi 模块均为 921600 8N1。

3.2 WiFi 与 UDP

• [ ] 模块上电后自动连接正确 WiFi；
• [ ] 模块取得预期 IP；
• [ ] 地面站 IP 与 SOCKETAUTOTT 中目标 IP 一致；
• [ ] UDP 目标端口为 8888；
• [ ] tcpdump 持续收到来自小车源 IP 的 UDP 包；
• [ ] 状态包通常为 24 字节；
• [ ] 控制时可以看到地面站发回小车的 UDP 包。

3.3 ROS2 桥接

• [ ] vehicles.yaml 中填写的是小车源 IP；
• [ ] mapped_id 与预期 ROS2 车辆编号一致且唯一；
• [ ] protocol 为 stm32_wheeltec；
• [ ] 只有一个桥接实例监听 UDP 8888；
• [ ] /vehicle_info 可以看到车辆；
• [ ] /robot_2/velocity 持续发布；
• [ ] IMU 和电池话题正常；
• [ ] EKF/动捕配置完成时 /robot_2/odom、/robot_2/pose 正常。

3.4 控制与地面站

• [ ] /robot_2/cmd_vel 有 bridge_node 订阅；
• [ ] 已在架空车轮或开阔场地完成低速测试；
• [ ] 零速度停止命令有效；
• [ ] 地面站选择了 wheelswarm 平台；
• [ ] 真实车辆列表显示正确编号和在线状态；
• [ ] 命令行桥接与 UI 桥接没有同时运行；
• [ ] 小车断电重启后可自动联网、自动透传并恢复 ROS2 在线状态。

4. 最小化现场启动流程

4.1 上电前

1. 启动路由器/热点
2. 地面站连接 WiFi
3. 检查地面站 IP
4. 检查 UDP 8888 未被旧进程占用
5. 给小车上电

4.2 终端 1：启动桥接

export WS=/home/linuxbrew/swarmlab_simulator_ws
source /opt/ros/humble/setup.bash
source "$WS/install/setup.bash"
ss -lunp | grep ':8888'
ros2 launch wheelswarm_bridge bridge.launch.py

4.3 终端 2：检查状态

export WS=/home/linuxbrew/swarmlab_simulator_ws
source /opt/ros/humble/setup.bash
source "$WS/install/setup.bash"
ros2 node list | grep -E 'bridge|ekf'
ros2 topic echo /vehicle_info
ros2 topic hz /robot_2/velocity

4.4 终端 3：低速测试

export WS=/home/linuxbrew/swarmlab_simulator_ws
source /opt/ros/humble/setup.bash
source "$WS/install/setup.bash"
ros2 topic pub --rate 10 \
  /robot_2/cmd_vel geometry_msgs/msg/Twist \
  "{linear: {x: 0.1, y: 0.0, z: 0.0}, angular: {z: 0.0}}"

验证完命令行通信后，如需由地面站 UI 管理桥接，应先停止终端 1 中的桥接，确认 UDP 8888 已释放，再从 UI 启动 wheelswarm_bridge。

完成最终验收后，可返回 C30D 底板小车前言复核完整流程，或按照本页的最小化现场启动流程使用小车。