常见问题 (FAQ)

使用前先看

问：遇到问题应该先怎么判断？

答：

先做这几步

先判断问题发生在哪一层：网络与页面、Web 控制、底盘、摄像头、ROS 2、供电或二次开发。
如果涉及运动，先停止机器人，再继续排查。
只保留一个控制入口，例如 Web、Notebook、ROS 2 或自定义脚本，不要同时控制底盘。
按现象回到对应教程：Web 与 JupyterLab 见入门教程，视觉见上位机教程，JSON 与底盘见下位机教程，ROS 2 见 ROS 2 教程。

需要提供的信息

当前网络模式、OLED 显示内容和访问地址。
使用的是 Web、JupyterLab、ROS 2 还是自定义脚本。
终端报错、页面截图或短视频。

问：机器人正在运动，怎么先停止？

答：

先停止机器人，再继续排查。

Web 控制时，先点击页面停止 / 暂停按钮。
ROS 2 Navigation 时，先在 RViz Navigation 2 面板点击 Cancel 或 Pause。

ROS 2 终端可发送一次零速度：

ros2 topic pub --once /cmd_vel geometry_msgs/msg/Twist "{linear: {x: 0.0}, angular: {z: 0.0}}"

如果仍在运动，立即断电。

不要继续的情况

停止按钮无效；
底盘持续运动；
自动功能或脚本仍在发送控制指令。

这类情况不要继续点击其它方向按钮，先断电检查。

网络与页面访问

问：Web 控制端打不开怎么办？

答：

先做这几步

确认机器人已上电，Jetson Orin 启动完成。
查看 OLED 显示的 IP。AP 模式通常访问：
```
http://192.168.50.5:5000
```
STA 或网线模式以 OLED 显示的实际 IP 为准：
```
http://<OLED显示IP>:5000
```
确认电脑、平板或手机与机器人在同一网络。
换用 Chrome 浏览器，关闭代理或清除缓存后重试。

仍不行再检查

如果可通过 JupyterLab Terminal 或 SSH 登录 Jetson，查看 Web 主程序日志：

tail -n 80 ~/ugv.log

需要提供的信息

OLED 屏幕照片。
浏览器访问地址和错误截图。
当前网络模式：AP / STA / 网线 / USB。

问：JupyterLab 打不开怎么办？

答：

先做这几步

先确认 Web 控制端是否能打开。
在浏览器访问 OLED 显示的 IP，并使用端口 8888：
```
http://<OLED显示IP>:8888
```
确认访问设备与机器人在同一网络。
如果 Web 能打开但 JupyterLab 打不开，重启机器人后等待 Jetson 启动完成再访问。

仍不行再检查

通过 SSH 或 Web 终端查看 JupyterLab 相关服务状态，以当前镜像中的服务名称为准。

需要提供的信息

Web 是否能打开。
JupyterLab 访问地址。
浏览器报错截图。

问：机器人连不上 WiFi 怎么办？

答：

先做这几步

检查 WiFi 名称和密码，避免中文标点、空格或大小写错误。
确认路由器没有开启客户端隔离、MAC 过滤或访客网络限制。
让机器人靠近路由器，再重新配置。
查看 OLED 是否显示路由器分配的 IP。

仍不行再检查

通过网线或 USB SSH 登录 Jetson，检查当前网络连接状态；具体配置流程见入门教程。

不要继续的情况

不确定当前连接的是 AP 模式还是 STA 模式；
OLED 未显示有效 IP；
修改过网络服务或 AccessPopup 后无法恢复。

问：Web 页面能打开，但按钮无响应怎么办？

答：

先做这几步

刷新页面，确认页面没有断开连接或长时间卡住。
先测试低风险按钮，例如灯光、OLED、语音提示或状态刷新。
如果只有底盘、云台或视觉按钮无响应，分别进入对应 FAQ 排查。
如果刚运行过 Notebook、ROS 2 或自定义脚本，先关闭可能占用串口或摄像头的程序。

仍不行再检查

查看 ~/ugv.log 最近日志，检查是否有 Python 报错、串口占用、摄像头占用或依赖缺失。

需要提供的信息

哪些按钮无响应，哪些按钮正常。
Web 页面截图。
~/ugv.log 最近日志。

Web 控制与云台

问：Web 页面里怎么控制云台？

答：

先做这几步

先确认 Web 页面能打开，视频画面能显示。
在云台控制区域使用方向按钮或页面当前提供的云台控件。
如果页面提供 WASD、拖拽圆圈、方块面板、AHEAD / Center 等入口，以当前页面显示为准。
第一次测试只做短按，不要长时间按住方向键。

仍不行再检查

如果所有云台入口都无反应，转到“云台不动怎么办？”继续排查。

问：云台不动怎么办？

答：

先做这几步

停止其它正在控制云台的程序。
刷新 Web 页面后短按云台方向按钮。
检查云台线缆、舵机供电和机械结构是否卡住。
如果底盘和灯光正常，但云台无反应，记录页面操作和日志。

不要继续的情况

云台有异响、发热或明显卡住；
云台碰到外壳、线缆或桌面；
连续点击后仍无反应。

这类情况先断电检查机械结构。

问：云台方向和按钮方向不一致怎么办？

答：

先做这几步

确认当前观察方向，是从机器人前方看，还是从摄像头画面看。
短按上、下、左、右，记录每个按钮对应的实际动作。
如果只是理解方向不同，以摄像头画面和页面说明为准。
如果方向完全反了，停止测试并记录当前页面、按钮和动作视频。

仍不行再检查

检查是否修改过 Web 页面、云台控制参数或下位机相关配置。

问：云台回中失败或卡住怎么办？

答：

先做这几步

不要继续点击 AHEAD、Center 或方向按钮。
检查云台是否被线缆、外壳或外设挡住。
断电后手动检查云台转动范围，不要用力掰动舵机。
重新上电后只短按回中按钮一次，观察是否恢复。

需要提供的信息

卡住时的云台角度和照片。
是否加装过摄像头、线缆或外设。
是否修改过云台相关代码或参数。

问：功能按钮很多，哪些可以先安全测试？

答：

先做这几步

先测试只读或低风险功能，例如状态显示、拍照、灯光、OLED 或语音提示。
再测试云台短动作。
最后测试底盘短时低速动作。
巡线、追踪、自动识别反应、自动导航等功能，先阅读对应教程并确认停止方式。

不要继续的情况

不知道按钮会控制哪个硬件；
没有准备停止方式；
场地狭窄、有线缆、人或障碍物。

底盘与下位机控制

问：底盘不动怎么办？

答：

先做这几步

检查电池电量、电源开关和底盘是否放在地面。
检查轮子是否被线缆、异物或外壳卡住。
先在 Web 页面点击停止，再短按低速前进或后退。
如果使用 ROS 2，确认底盘 bringup 正在运行，且没有其它程序占用串口。
如果使用 JSON，先确认命令格式和停止命令。

仍不行再检查

区分是所有硬件无反应，还是只有底盘无反应。只有底盘无反应时，优先检查底盘供电、串口占用和下位机通信。

需要提供的信息

当前控制方式：Web / JSON / ROS 2 / 自定义脚本。
底盘是完全不动，还是单侧轮子不动。
操作视频或终端命令截图。

问：底盘运动后停不下来怎么办？

答：

先做这几步

Web 控制时，先点击停止按钮。
JSON 控制时，发送停止指令，以当前教程中的底盘停止命令为准。

ROS 2 控制时，发送一次零速度：

ros2 topic pub --once /cmd_vel geometry_msgs/msg/Twist "{linear: {x: 0.0}, angular: {z: 0.0}}"

如果仍在运动，立即断电。

不要继续的情况

自动脚本、巡线、追踪或 Navigation 仍在运行；
停止后又继续移动；
不清楚哪个程序在发控制指令。

先停止相关终端或直接断电，再排查。

问：底盘方向反了怎么办？

答：

先做这几步

明确机器人车头方向和摄像头朝向。
分别测试前进、后退、左转、右转，记录实际动作。
如果 Web、JSON、ROS 2 三种入口方向都异常，检查底盘装配、线序或底层配置是否被修改。
如果只有某一个入口异常，优先检查该入口的按钮映射或命令参数。

不要继续的情况

方向不确定时不要测试高速动作；
不要通过增大速度掩盖方向错误。

问：底盘抖动、跑偏或单侧异常怎么办？

答：

先做这几步

换到平整、干燥地面低速测试。
检查轮子、轮胎、底盘结构和线缆是否干涉。
观察是否只有一侧轮子不动、抖动或发热。
停止高负载任务，确认电压是否过低。

不要继续的情况

单侧轮子持续发热、异响或卡住；
底盘明显跑偏且无法停止；
轮子或结构件松动。

这类情况先断电检查机械结构。

JSON 指令发出后车轮不动怎么办？

问：JSON 指令发出后车轮不动怎么办？

答：

先做这几步

确认命令输入位置正确，是 Web 命令输入框或下位机教程中的串口调用入口。
JSON 内使用英文半角符号，不要混入中文标点。
先发送停止或低风险指令，再测试短时低速运动。
如果速度太小没有明显运动，可按下位机教程中的说明小幅调整，不要同时调大速度和时间。
检查 Web、Notebook、ROS 2 是否同时占用底盘串口。

不要继续的情况

轮子卡住、异响或发热；
不知道停止命令是否有效；
串口被多个程序占用。

摄像头、拍照、录像与视觉识别

问：摄像头无画面怎么办？

答：

先做这几步

检查摄像头线缆和 USB 连接。
关闭其它正在读取摄像头的 Web、Notebook、ROS 2 或视觉脚本。
刷新 Web 页面，确认浏览器没有阻止视频加载。
如果在 Notebook 中测试，先按上位机教程中的摄像头资源释放流程处理。

需要提供的信息

Web 页面截图。
当前是否运行 Notebook、ROS 2 或自定义视觉脚本。
摄像头连接方式和设备编号。

问：图像延迟高怎么办？

答：

先做这几步

关闭不需要的 DNN、MediaPipe、录像、ROS 2、浏览器多标签页等高负载任务。
检查网络质量，优先使用同一局域网或有线连接。
降低画面分辨率或关闭不需要的识别叠加。
如果正在录像，先停止录像后对比延迟。

仍不行再检查

查看 Jetson 负载、网络延迟和浏览器性能。长时间高负载还会影响续航和温度。

问：拍照或录像后找不到文件怎么办？

答：

先做这几步

先确认 Web 页面中摄像头画面正常。
拍照后查看页面的图片列表或 Photo Gallery。
录像后先点击停止录像，再查看视频列表或 Video Files。
如果列表不刷新，刷新页面后再查看。

仍不行再检查

通过 JupyterLab 或 SSH 查看项目中的图片、视频保存目录；具体路径以当前镜像和页面显示为准。

需要提供的信息

点击的是拍照还是录像。
页面是否提示保存。
文件列表截图。

问：视觉识别没有结果怎么办？

答：

先做这几步

先确认摄像头画面正常。
确认目标完整出现在画面中，距离不要过远或过近。
检查光照、反光、遮挡和背景干扰。
如果是按钮触发的识别功能，先查看上位机教程中对应示例。

仍不行再检查

Simple Detection、Advance CV、手势、颜色等入口可能依赖不同模型或参数。按钮名称以当前页面显示为准，不要把一个示例的参数套到其它示例。

问：颜色识别不准怎么办？

答：

先做这几步

使用当前场景重新采集颜色阈值。
避开反光、阴影、复杂背景和目标边缘。
查看 Mask 或识别结果图，确认目标主体是主要识别区域。
光照变化后重新采集参数。

仍不行再检查

颜色识别受光照和相机白平衡影响明显。如果目标颜色接近背景，先更换背景或目标材料。

问：OpenCV、DNN 或 MediaPipe 示例运行失败怎么办？

答：

先做这几步

确认是在 Jetson 主机 / JupyterLab 环境中运行，而不是 ROS 2 Docker 终端。
确认摄像头没有被 Web 或其它 Notebook 占用。
先运行上位机教程中的基础摄像头示例，再运行 DNN 或 MediaPipe 示例。
如果提示缺少依赖，不要直接升级整套系统包，先查看当前教程中的依赖说明。

需要提供的信息

完整 Python 报错。
当前运行入口：Notebook / 终端 / Web。
是否修改过 OpenCV、NumPy 或 MediaPipe。

问：自动识别、巡线、追踪能不能直接打开？

答：

先做这几步

先确认摄像头画面、目标识别和停止方式。
再确认底盘低速运动和停止按钮有效。
将 UGV 放在空旷地面，远离人、线缆和桌脚。
第一次只做短时间低速测试。

不要继续的情况

摄像头没有画面；
识别结果抖动明显；
底盘停止方式未验证；
场地狭窄或有动态障碍物。

ROS 2、SLAM、Navigation

问：ROS 2 topic 没有输出怎么办？

答：

先做这几步

确认当前终端是 ROS 2 Docker 终端。

加载 ROS 2 环境：

cd /home/ws/ugv_ws
source /opt/ros/humble/setup.bash
source install/setup.bash

查看节点和 topic：
```
ros2 node list
ros2 topic list
```
确认对应 launch 仍在运行。

仍不行再检查

如果涉及底盘、雷达或相机，检查是否有其它程序占用硬件资源。ROS 2 详细流程见 ROS 2 教程。

问：RViz 没有显示模型、TF 或 LaserScan 怎么办？

答：

先做这几步

确认 bringup、雷达或 Navigation launch 没有退出。
在 RViz 中检查 Fixed Frame 是否和当前流程一致。
查看 /tf、/tf_static、/scan 是否存在。
如果只有 LaserScan 不显示，转到“雷达无数据怎么办？”。

仍不行再检查

查看启动终端是否有 TF、frame、message filter 或 process died 相关报错。

问：雷达无数据怎么办？

答：

先做这几步

确认雷达供电和连接正常。
确认没有重复启动多个占用雷达或底盘资源的 launch。

在 ROS 2 终端检查：

ros2 topic list | grep scan
timeout 8 ros2 topic hz /scan

查看雷达启动终端是否有设备连接或通信报错。

不要继续的情况

/scan 没有稳定输出时，不要继续 SLAM、Navigation 或自动探索。

问：SLAM 无法建图怎么办？

答：

先做这几步

确认 /scan、/odom 和 TF 正常。
启动 Gmapping 或 Cartographer 后，先等待地图初始化。
低速小幅转向，再短距离移动，不要快速原地旋转。
保存地图前检查地图是否有重影、断墙、错位或大片未知区域。

不要继续的情况

地图质量明显异常时，即使 map.pgm 和 map.yaml 能保存，也不要直接进入 Navigation。

问：Navigation 定位不准、乱撞或目标到不了怎么办？

答：

先不要继续点 Nav2 Goal。

确认 Navigation 实际加载的是当前地图：
```
ros2 param get /map_server yaml_filename
```

检查地图文件是否为当前场地保存的地图：

ls -lh src/ugv_main/ugv_nav/maps/map.pgm \
       src/ugv_main/ugv_nav/maps/map.yaml

在 RViz 中重新设置 2D Pose Estimate。
观察 LaserScan 是否与地图墙体或障碍边缘大致对齐。
观察 AMCL 粒子是否集中在机器人真实位置附近。

如果机器人周围被 costmap 大面积覆盖，先确认清理服务存在，再清理 costmap：

ros2 service list | grep clear
ros2 service call /global_costmap/clear_entirely_global_costmap nav2_msgs/srv/ClearEntireCostmap {}
ros2 service call /local_costmap/clear_entirely_local_costmap nav2_msgs/srv/ClearEntireCostmap {}

不要继续的情况

LaserScan 与地图明显错开；
AMCL 粒子很分散；
地图有重影、断墙、错位；
机器人附近或目标点被 costmap 高风险区域覆盖；
启动终端出现 process has died、multiple access、KeyError。

这种状态下不要继续测试保存导航点或自动探索。

问：保存导航点后回不到目标点怎么办？

答：

先做这几步

先用 RViz 手动 Nav2 Goal 测试极近距离目标。
如果手动目标都到不了，不要继续测试保存点。
确认 /robot_pose 有输出，save_map_point 能保存当前位姿。
确认 pub_nav_point 发布后 /goal_pose 有输出，且 frame_id 为 map。

仍不行再检查

save_map_point / pub_nav_point 只是保存和发布目标。真正路径规划、避障和底盘运动仍由 Navigation 完成。如果地图、AMCL、TF 或 costmap 不正常，即使 /goal_pose 正确，UGV 也可能无法到达目标。

Gazebo 仿真

问：为什么镜像文件 SHA256 与文档不一致？

答：

现象

对 UGV-Gazebo-Humble-Classic-Verified-2026-07-10.tar 执行 Get-FileHash -Algorithm SHA256 后，结果与教程中的校验值不一致，或文件大小不是 6934579200 字节。

原因

下载未完成、文件被重复下载或保存过程中损坏，都会导致文件大小或 SHA256 改变。

检查步骤

在 Windows PowerShell 中确认当前文件路径，再执行：

Get-Item $ImagePath | Select-Object FullName, Length
Get-FileHash $ImagePath -Algorithm SHA256

处理方法

不要继续导入该文件。重新确认下载已完成，并重新获取镜像文件后再次校验。

观察点

Length 为 6934579200；
SHA256 为 168C57F2FB4EA1FD870F47797B212571410D66DBB5B240004E0836CD57D2F454。

问：为什么 `wsl --import` 提示发行版名称已存在？

答：

现象

执行 wsl --import UGV-Gazebo-Humble ... 时，PowerShell 提示该发行版名称已经存在。

原因

电脑中已经存在名为 UGV-Gazebo-Humble 的 WSL2 发行版。

检查步骤

wsl --list --verbose

处理方法

保留现有发行版时，为新导入实例选择不同的名称和安装目录。需要重新导入同名发行版时，先确认现有实例中的文件和任务已经不再需要，再按 Windows 的 WSL2 管理流程处理。

观察点

wsl --list --verbose 中发行版名称不重复；
导入完成后目标发行版的 VERSION 为 2。

问：为什么 Windows Terminal 中没有 `UGV-Gazebo-Humble`？

答：

现象

镜像已导入，但 Windows Terminal 标签页旁的下拉菜单中没有 UGV-Gazebo-Humble。

原因

Windows Terminal 尚未刷新发行版列表，或者没有自动生成该发行版的配置文件。

检查步骤

wsl --list --verbose
wsl -d UGV-Gazebo-Humble -u ag

处理方法

关闭并重新打开 Windows Terminal。仍未显示时，在 Windows Terminal 的“设置”中创建空配置文件，将命令行设置为 wsl.exe -d UGV-Gazebo-Humble -u ag。

观察点

PowerShell 可以进入 UGV-Gazebo-Humble；
Windows Terminal 下拉菜单中可以打开对应终端。

问：为什么打开导入的发行版后进入了 `root`？

答：

现象

执行 whoami 后输出 root，并且 ~ 不对应 /home/ag。

原因

导入的 WSL2 发行版默认登录用户未设置为镜像内置账户。

检查步骤

whoami
echo "$HOME"

处理方法

从 Windows PowerShell 或 Windows Terminal 使用 wsl -d UGV-Gazebo-Humble -u ag 进入镜像。ag 是当前镜像的内置 Linux 用户，与 Windows 登录账户名称无关。

观察点

whoami 输出 ag；
echo "$HOME" 输出 /home/ag；
~/ws/ugv_ws 可以访问。

问：为什么找不到 `/home/ag/ws/ugv_ws`？

答：

现象

终端中不存在 /home/ag/ws/ugv_ws，或者 test -d ~/ws/ugv_ws 没有输出预期结果。

原因

当前终端可能未以镜像内置用户 ag 进入，或者导入的文件不是教程指定的预配置镜像。

检查步骤

whoami
echo "$HOME"
test -d /home/ag/ws/ugv_ws && echo "ugv_ws exists"

处理方法

退出当前终端后，使用 wsl -d UGV-Gazebo-Humble -u ag 重新进入。仍缺少工作空间时，重新核对镜像文件名和 SHA256；不要在当前教程主线中手动创建替代工作空间。

观察点

当前账户为 ag；
/home/ag/ws/ugv_ws 存在；
显示 ugv_ws exists。

问：为什么 `ros2 pkg prefix ugv_gazebo` 提示找不到功能包？

答：

现象

在新的 UGV-Gazebo-Humble 终端中执行 ros2 pkg prefix ugv_gazebo 时提示找不到功能包。

原因

每个新终端都需要加载 ROS 2 Humble 和镜像中工作空间的 install/setup.bash。

检查步骤

whoami
echo "$ROS_DISTRO"
ls -l ~/ws/ugv_ws/install/setup.bash

处理方法

source /opt/ros/humble/setup.bash
source ~/ws/ugv_ws/install/setup.bash
ros2 pkg prefix ugv_gazebo

观察点

whoami 输出 ag；
echo "$ROS_DISTRO" 输出 humble；
ros2 pkg prefix ugv_gazebo 输出 /home/ag/ws/ugv_ws/install/ugv_gazebo。

问：为什么导入后不能移动 `$InstallPath`？

答：

现象

导入完成后，需要调整 $InstallPath 对应的目录位置，或尝试通过文件管理器移动该目录。

原因

$InstallPath 保存 WSL2 发行版的虚拟磁盘和运行数据。直接移动、重命名或删除该目录会使 WSL2 无法按原位置访问发行版。

检查步骤

wsl --list --verbose

确认 UGV-Gazebo-Humble 已经导入并且当前目录是其运行数据目录。

处理方法

导入前确定安装目录。导入完成后保持该目录不变；需要调整存储位置时，先备份当前发行版数据，再按 Windows 的 WSL2 迁移流程重新导入。

观察点

wsl --list --verbose 可以显示 UGV-Gazebo-Humble；
wsl -d UGV-Gazebo-Humble -u ag 可以正常进入终端。

问：图形环境脚本缺失或损坏怎么办？

答：

现象

执行 source use_vcxsrv_gazebo.sh 时提示文件不存在或脚本语法错误。

检查

在 UGV-Gazebo-Humble 终端执行：

cd ~/ws/ugv_ws
ls -l use_vcxsrv_gazebo.sh
bash -n use_vcxsrv_gazebo.sh

正常结果

文件存在，且 bash -n 没有输出。

原因

导入的不是教程提供的预配置镜像、工作空间文件被删除或修改、使用了其它 WSL2 发行版，或者镜像下载或导入不完整。

处理

备份当前发行版中的个人文件。
在 Windows PowerShell 中核对镜像 SHA256。
重新导入经过校验的预配置镜像。

正确 SHA256：

168C57F2FB4EA1FD870F47797B212571410D66DBB5B240004E0836CD57D2F454

问：Gazebo 报 `gazebo_ros` not found 怎么办？

答：

现象

启动 ugv_gazebo 时提示 Package 'gazebo_ros' not found，或者系统找不到 gazebo、gzserver、gzclient。

原因

当前终端未加载镜像中的 ROS 2 Humble 与工作空间环境，或者导入的不是教程指定的预配置镜像。只有 ros_gz 或新版 Gazebo 的环境不能直接运行当前 Gazebo Classic launch。

检查步骤

source /opt/ros/humble/setup.bash

ros2 pkg prefix gazebo_ros
ros2 pkg prefix gazebo_plugins
which gazebo
which gzserver
which gzclient
gazebo --version

处理方法

先使用 wsl -d UGV-Gazebo-Humble -u ag 进入镜像，再加载 ROS 2 和工作空间环境。仍找不到功能包时，检查镜像文件名和 SHA256，并重新导入已验证的镜像；不要在当前教程主线中另行安装 Gazebo 组件。

观察点

gazebo --version 显示 Gazebo 11；
ros2 pkg prefix gazebo_ros 和 ros2 pkg prefix gazebo_plugins 能输出安装路径；
ros2 launch ugv_gazebo bringup.launch.py 不再提示功能包缺失。

问：为什么启动 Gazebo 后 `gzclient` 出现 `exit code -6`？

答：

现象

gzserver 已启动，但 Gazebo 窗口没有显示，启动日志中出现 gzclient 退出或 exit code -6。

原因

Windows 重启后 XLaunch 不会自动恢复。VcXsrv 未运行、DISPLAY 为空或当前终端未加载 VcXsrv 环境时，WSL2 中的 gzclient 无法连接 Windows X Server。

检查步骤

检查 Windows 任务栏通知区域是否显示 VcXsrv 图标。

在 UGV-Gazebo-Humble 终端中执行：

echo "$DISPLAY"
ps -ef | grep gzserver | grep -v grep

处理方法

重新启动 XLaunch，选择“Multiple windows”和“Start no client”，勾选“Disable access control”，并在 Additional parameters 中填写 -nowgl。随后重新加载 use_vcxsrv_gazebo.sh，再启动 Gazebo。

观察点

Windows 任务栏通知区域显示 VcXsrv 图标；
DISPLAY 输出非空；
Gazebo 窗口可以显示；
gzclient 不再以 exit code -6 退出。

问：为什么 Gazebo 窗口失去响应，但 ROS 2 话题仍在更新？

答：

现象

长时间建图或导航后，Gazebo 窗口无法交互，但 /clock、/scan 等 ROS 2 话题仍在更新。

原因

WSL2 + VcXsrv 环境中的 gzclient 图形进程可能失去响应，而负责物理仿真的 gzserver 仍在运行。Gazebo GUI 状态不能单独用于判断仿真后端是否停止。

检查步骤

timeout 5 ros2 topic hz /clock
timeout 5 ros2 topic hz /scan
ps -ef | grep -E "gzserver|gzclient" | grep -v grep

处理方法

先停止自动探索、导航和控制节点，再结束无响应的 gzclient。长时间测试可保留 gzserver，并使用 RViz 观察模型、LaserScan、地图和路径。

观察点

/clock 和 /scan 的状态可独立确认；
重新启动图形客户端后 Gazebo 窗口恢复；
后端停止时，/clock 不再更新。

问：为什么 `spawn_entity.py` 一直等待 `/spawn_entity`？

答：

现象

启动日志停留在等待 /spawn_entity，UGV Rover 模型没有出现在 Gazebo 场景中。

原因

/spawn_entity 由 Gazebo ROS Factory 插件提供。gzserver 未运行，或者启动 world 时没有加载 libgazebo_ros_init.so 和 libgazebo_ros_factory.so，都会导致该服务不可用。

检查步骤

ps -ef | grep gzserver | grep -v grep
ros2 service list | grep spawn_entity
ros2 pkg prefix gazebo_ros

处理方法

停止当前启动流程后，重新使用 ros2 launch ugv_gazebo bringup.launch.py。该入口会按当前 ugv_world.world 配置启动 Gazebo ROS 插件并生成模型，不要根据其它机器人教程猜测 world 文件名或手工组合插件命令。

观察点

/spawn_entity 出现在服务列表中；
spawn_entity.py 不再持续等待；
UGV Rover 模型出现在 Gazebo 场景中。

问：为什么 House 场景提示缺少装饰模型？

答：

现象

Gazebo 加载 House 场景时提示 first_2015_trash_can 的 mesh 或模型资源缺失。

原因

first_2015_trash_can 属于场景装饰资源，不是 UGV Rover、激光雷达、TF、里程计或导航链路的组成部分。

检查步骤

ros2 topic list | grep -E "clock|scan|odom|tf"
timeout 5 ros2 topic hz /scan

同时确认 UGV Rover 模型已经生成，并能接收 /cmd_vel。

处理方法

主流程数据正常时，可继续控制、建图和导航测试。需要完整场景外观时，再补充缺失的 Gazebo 模型资源和模型搜索路径。

观察点

UGV Rover 模型正常显示；
/clock、/scan、/odom 和 TF 正常更新；
单个装饰模型缺失不影响控制和算法流程。

问：为什么 RViz 提示 Selector 或 Docking 插件不可用？

答：

现象

打开 view_nav_3d.rviz 后，RViz 提示 Selector、Docking 或其它插件类无法加载。

原因

该 RViz 配置引用的插件可能不在当前 ROS 2 Humble 环境中，或者插件类名称与当前版本不兼容。该现象不表示整个 ROS 2 或 Gazebo 环境需要重新安装。

检查步骤

查看启动命令实际加载的 RViz 配置文件。
检查 RViz 左侧 Displays 中标记为 Error 的项目。
确认 RobotModel、TF、LaserScan、Map 和 Path 等基础显示是否正常。

处理方法

导航测试可改用 ROS 2 Humble 的 nav2_default_view.rviz，或从当前 RViz 配置中移除不受支持的显示插件。不要同时启动多个 RViz 实例读取不同导航配置。

观察点

RViz 不再提示对应插件类缺失；
RobotModel、TF、LaserScan、地图和路径能够显示；
Nav2 面板可以接收和取消目标。

问：为什么 EMCL 定位时地图和代价地图反复重置？

答：

现象

EMCL 与 TEB 或 DWA 组合运行时持续出现 RESET，RViz 中的地图、机器人位姿或代价地图抖动、跳变或反复重置。

原因

当前版本的 EMCL 仿真组合在已测环境中没有形成稳定定位状态，因此不作为推荐定位主线。

检查步骤

ros2 node list | grep -E "emcl|amcl|map_server|controller_server"
ros2 topic info /map
ros2 topic info /tf

确认没有同时启动 AMCL、EMCL 或其它定位来源。

处理方法

停止 EMCL 组合，改用已验证的 AMCL + Nav2，或者单独使用 RTAB-Map Localization + 纯 Nav2。EMCL 仅保留为实验性组合。

观察点

定位来源只保留一个；
地图和代价地图不再反复重置；
机器人位姿和 LaserScan 显示稳定。

问：为什么 RTAB-Map Localization 与 AMCL 同时运行后定位异常？

答：

现象

同时启动 RTAB-Map Localization 与包含 AMCL 或 map_server 的导航入口后，地图、TF、机器人位姿或代价地图出现跳变。

原因

多个定位源或多个地图发布节点同时工作时，可能重复发布 /map 或 map 到 odom 的 TF。原有组合入口也可能同时引入 AMCL、map_server 和 RTAB-Map Localization。

检查步骤

ros2 node list
ros2 topic info /map
ros2 topic info /tf

检查是否同时存在 amcl、多个 map_server 或多个 RTAB-Map 定位节点。

处理方法

停止所有定位和 Nav2 节点。需要 RTAB-Map 定位时，单独启动 rtabmap_localization_launch.py，且不同时启动 AMCL 或 map server。本教程中的该流程仅验证已有数据库定位，不发送导航目标。

观察点

/map 和定位 TF 的发布来源符合当前组合；
RViz 中的机器人位姿不再跳变；
RTAB-Map 定位数据持续更新。

问：为什么 PowerShell 中无法执行 `ros2` 命令？

答：

现象

在 Windows PowerShell 中输入 ros2 后，系统提示无法识别该命令。

原因

ROS 2 Humble 位于导入的 UGV-Gazebo-Humble WSL2 发行版中，Windows PowerShell 不会直接加载 Linux 中的 ROS 2 环境。

检查步骤

在 Windows PowerShell 中执行：

wsl --list --verbose

确认目标发行版存在且 VERSION 为 2。

处理方法

先进入镜像发行版：

wsl -d UGV-Gazebo-Humble -u ag

再在 UGV-Gazebo-Humble 终端加载 ROS 2 和工作空间环境后执行 ros2 命令。

观察点

终端提示符进入 Linux 环境；
echo "$ROS_DISTRO" 输出 humble；
ros2 --help 可以显示命令列表。

问：为什么配套手柄接收器未出现在 usbipd list 中？

答：

现象

Windows PowerShell 执行 usbipd list 后，未找到 UGV 配套 2.4G 手柄的 USB 接收器。

原因

接收器未被 Windows 识别，或者 PowerShell 尚未加载 usbipd-win 命令。

检查

确认接收器已插入，手柄已开机；更换 USB 接口后重新执行 usbipd list，并重新打开 PowerShell。

处理

确认 usbipd-win 已安装：

usbipd list

仍未出现时，重新插拔接收器并检查 Windows 是否识别该 USB 设备。

观察点

usbipd list 中出现 VID:PID 为 045e:028e 的接收器及其当前 BUSID。

问：为什么 PowerShell 执行 BUSID 占位符报错？

答：

现象

PowerShell 显示 RedirectionNotSupported，或提示“< 运算符是为将来使用而保留的”。

原因

将文档中的 <BUSID> 原样复制到 PowerShell 后，尖括号会被解析为特殊符号。

处理

执行：

usbipd list
$BusId = "4-1"

将示例 4-1 替换为当前实际编号，后续命令使用 $BusId。

观察点

PowerShell 能正常执行使用 $BusId 的 usbipd 命令。

问：为什么 usbipd bind 提示权限不足？

答：

现象

执行 usbipd bind --force --busid $BusId 时提示权限不足。

原因

共享 USB 接收器需要管理员权限。

检查

确认当前 PowerShell 窗口标题包含“管理员”。

处理

以管理员身份打开 Windows PowerShell 后重新执行：

usbipd list
$BusId = "4-1"
usbipd bind --force --busid $BusId

观察点

命令完成后，usbipd list 中的接收器显示 Shared (forced)。attach 通常可在普通 PowerShell 中执行。

问：为什么 attach 提示设备未共享？

答：

现象

执行 usbipd attach --wsl --busid $BusId 时提示接收器未共享。

原因

该接收器尚未完成 bind，或使用了已变化的 BUSID。

检查

在 Windows PowerShell 中执行 usbipd list，确认当前 BUSID。

处理

在管理员 Windows PowerShell 中执行：

usbipd list
$BusId = "4-1"
usbipd bind --force --busid $BusId

将示例 4-1 替换为当前实际编号。完成强制绑定后重启 Windows，再重新查询当前 BUSID 并执行 attach。

观察点

接收器成功连接到 WSL2，usbipd list 显示 Attached。

问：为什么 attach 提示 Device busy (exported)？

答：

现象

Device busy (exported)
The device appears to be used by Windows
Failed to attach device

原因

UGV 配套接收器被 Windows HID 驱动占用，普通 bind 不能完成共享。

处理

在管理员 Windows PowerShell 中执行：

usbipd list
$BusId = "4-1"
usbipd bind --force --busid $BusId

将示例 4-1 替换为当前实际编号。出现 A reboot may be required before the changes take effect. 后，重启 Windows；重启后重新查询 BUSID，再执行 attach。

观察点

重启后，usbipd list 中的接收器显示 Shared (forced)，attach 成功后显示 Attached。

问：为什么配套手柄无法连接到 WSL2？

答：

现象

执行 attach 后，UGV-Gazebo-Humble 中未出现配套 USB 接收器或输入设备。

原因

WSL2 发行版未运行、接收器未正确 attach，或接收器仍被 Windows 中的其它程序占用。

检查

保持 UGV-Gazebo-Humble 终端打开，在 Windows PowerShell 中执行 usbipd list，确认接收器状态为 Attached；再在 WSL2 中执行：

lsusb

处理

重新执行：

usbipd list
$BusId = "4-1"
usbipd attach --wsl --busid $BusId

将示例 4-1 替换为当前实际编号。若 attach 提示设备被 Windows 占用，执行强制绑定并重启 Windows。

观察点

lsusb 显示 045e:028e Microsoft Corp. Xbox360 Controller，/joy 随手柄输入更新。

问：为什么重新插入接收器后 BUSID 变化？

答：

现象

重新插入接收器或重启 Windows 后，之前记录的 BUSID 无法用于 attach。

原因

BUSID 由当前 USB 连接位置决定，接收器插入不同接口或 Windows 重启后可能变化。本次实测中，编号由 3-1 变为 4-1，该变化仅作示例。

检查

执行：

usbipd list

处理

使用当前输出中的 BUSID 设置 $BusId 后执行 attach，不重复使用旧编号。接收器仍显示 Shared (forced) 时，不需要再次执行强制绑定。

观察点

当前 BUSID 对应的接收器可成功 attach 到 WSL2。

问：为什么 /joy 没有数据？

答：

现象

ros2 topic echo /joy 没有输出，或操作配套手柄时数据不变化。

原因

接收器未 attach、手柄未与接收器连接，或手柄控制 launch 未正常运行。

检查

确认 usbipd list 显示 Attached，lsusb 显示 045e:028e Microsoft Corp. Xbox360 Controller，再执行：

ros2 topic info /joy

处理

重新启动：

ros2 launch ugv_tools teleop_twist_joy.launch.py

不要同时运行多个手柄驱动节点。

观察点

操作配套手柄时，/joy 中的轴值或按键值变化。不同 WSL2 内核和输入驱动环境中，/dev/input/js* 的显示可能不同，不作为最终判断依据。

问：为什么 /joy 有数据但 UGV Rover 不运动？

答：

现象

/joy 有更新，但 Gazebo 中的 UGV Rover 不运动。

原因

控制节点未发布 /cmd_vel、Gazebo 未运行，或键盘控制节点与手柄控制节点同时运行。

检查

执行：

ros2 topic info /cmd_vel
ros2 topic echo /cmd_vel

处理

确认 Gazebo 保持运行，停止键盘控制节点，再检查产品配套手柄的摇杆和使能键映射。

观察点

操作运动摇杆时，/cmd_vel 数值变化，UGV Rover 能够运动。

问：为什么 Windows 无法使用已连接到 WSL2 的接收器？

答：

现象

接收器 attach 到 WSL2 后，Windows 无法同时使用该设备。

原因

USB 接收器在同一时间只能由 Windows 或 WSL2 其中一方使用。

检查

在 Windows PowerShell 中执行 usbipd list，确认接收器当前连接状态。

处理

执行：

usbipd list
$BusId = "4-1"
usbipd detach --busid $BusId

将示例 4-1 替换为当前 usbipd list 显示的实际编号。

观察点

接收器从 WSL2 释放后，Windows 可以重新使用该设备。

问：为什么自动探索持续旋转、重复规划或找不到前沿？

答：

现象

explore_lite 启动后，UGV Rover 持续旋转、反复规划同一区域，或者没有生成新的探索目标。

原因

自动探索依赖连续的地图、稳定定位、正确 TF 和可用代价地图。地图前沿不足、机器人附近被高代价区域覆盖或 Navigation 状态异常时，探索节点无法持续生成可执行目标。

检查步骤

ros2 topic list | grep -E "map|scan|odom|tf"
ros2 node list | grep -E "explore|planner_server|controller_server|bt_navigator"

在 RViz 中检查地图是否继续扩展、LaserScan 是否对齐，以及机器人周围是否被代价地图覆盖。

处理方法

先在探索终端按 Ctrl + C，再取消当前 Nav2 目标。恢复地图、定位、TF 和代价地图状态后重新启动探索，不要在状态异常时持续等待机器人自行恢复。

观察点

地图和定位状态稳定；
explore_lite 可以生成新的前沿目标；
Nav2 生成路径后，UGV Rover 不再持续原地旋转。

问：为什么按 `Ctrl + C` 后仍有 Gazebo 进程？

答：

现象

Gazebo launch 终端已经退出，但 gzserver、gzclient 或 spawn_entity.py 仍留在进程列表中，下一次启动可能出现重复进程。

原因

图形客户端失去响应、launch 终止过程中子进程没有及时退出，或者其它终端独立启动了 Gazebo 相关进程。

检查步骤

ps -ef | grep -E "gzserver|gzclient|spawn_entity" | grep -v grep

处理方法

先确认列表中的确是当前仿真残留进程，再分别执行：

pkill -f gzclient
pkill -f gzserver
pkill -f spawn_entity.py

不要使用 killall python。以上命令不是每次启动前的固定步骤。

观察点

再次检查时不再显示对应进程；
重新启动 Gazebo 后没有重复服务器或重复模型；
/clock 只由当前 Gazebo 实例发布。

电源、电量与重启

问：Web 页面电压显示异常是什么意思？

答：

先做这几步

确认机器人供电正常，电池连接可靠。
刷新 Web 页面，观察电压是否持续异常。
停止底盘、视觉、ROS 2、录像等高负载任务后再观察。
如果电压跳变明显，先停止运动测试。
如果 Web 主程序已停止，可通过 ROS 2 /voltage 或自定义只读脚本读取电压，不要同时启动多个会占用串口的程序。

需要提供的信息

Web 电压截图。
当前是否在运动、录像、运行 ROS 2 或视觉任务。
是否出现重启或断电。

问：为什么 UGV 使用过程中会突然关机？

答：

先做这几步

检查电池电量和供电线连接。
停止高负载任务，例如长时间底盘运动、视觉识别、录像、ROS 2 建图或导航。
检查底盘是否有机械阻力，轮子是否卡住。
充电后再进行低速短时测试。

不要继续的情况

反复关机；
电池或供电线发热；
底盘运动时伴随异响或明显卡滞。

二次开发与恢复

问：修改配置后 Web 异常怎么办？

答：

先做这几步

停止继续修改，记录改过的文件和时间。
如果有备份，先恢复备份文件。
查看 Web 日志：
```
tail -n 80 ~/ugv.log
```
如果修改了 app.py、config.yaml 或模板文件，先回退到上一个可用版本。

需要提供的信息

修改的文件。
修改前后 diff 或截图。
~/ugv.log 最近日志。

问：Notebook 运行后一直卡住怎么办？

答：

先做这几步

停止当前 Notebook cell。
如果正在读取摄像头或串口，确认没有其它程序同时占用。
重启 Notebook kernel，再只运行前几格初始化代码。
运动类 cell 先保持 dry-run，不直接控制底盘。

不要继续的情况

Notebook 正在持续发送运动指令；
摄像头窗口或循环无法退出；
不知道当前 cell 控制了哪个硬件。

问：自定义脚本或自启动导致异常怎么办？

答：

先做这几步

先禁用自启动，再重启机器人观察是否恢复。
检查脚本日志、systemd 状态或 crontab 配置。
确认脚本是否占用摄像头、串口或持续发送运动指令。
恢复修改前备份，或回退到上一版脚本。
如果 Python 示例提示缺少依赖，先确认运行环境，不要直接执行整机 apt upgrade；自定义项目优先用虚拟环境和 requirements.txt 记录依赖。

不要继续的情况

开机后自动运动；
脚本反复重启；
日志持续报错但仍在控制硬件。

部署自定义任务前，先按二次开发中的验收模板记录停止方式和回退方法。

需要提供的信息

完整报错和运行入口。
修改过的脚本、自启动配置或依赖。
Python 版本，以及是否修改过 OpenCV、NumPy、MediaPipe 或 ROS 2 环境。

文档反馈

使用前先看​

网络与页面访问​

Web 控制与云台​

底盘与下位机控制​

JSON 指令发出后车轮不动怎么办？​

摄像头、拍照、录像与视觉识别​

ROS 2、SLAM、Navigation​

Gazebo 仿真​

电源、电量与重启​

二次开发与恢复​

使用前先看

网络与页面访问

Web 控制与云台

底盘与下位机控制

JSON 指令发出后车轮不动怎么办？

摄像头、拍照、录像与视觉识别

ROS 2、SLAM、Navigation

Gazebo 仿真

电源、电量与重启

二次开发与恢复