适用于产品: TonyPi、MasterPi、TurboPi、SpiderPi、LanderPi、JetHexa、JetMax、GoGoPi 等机器人产品
涉及模块: 主板 / 扩展板 / 电机 / 舵机 / 雷达 / 摄像头 / 线缆 / Linux / ROS2 / 网络
核心标签: 通用 #机器人运维 ros2 故障排查 导航
一、本文解决什么问题
机器人现场故障通常不是单一软件问题，而是电源、硬件连接、Linux 系统、ROS 节点、传感器、运动控制和用户操作共同组成的链路问题。
本文用于：
- 机器人日常维护、用户问题排查和现场故障处理；
- 快速收集问题信息，减少反复追问；
- 排查 ROS2 小车“设置导航点后不移动”；
- 判断问题属于配置/软件、环境/接线还是硬件故障；
- 明确什么时候可以现场恢复，什么时候需要升级工程师或返修。
铁律：任何涉及电机、轮组、舵机和底盘的测试，都要先清空周围人员和障碍物，必要时抬起驱动轮或断开执行器电源。不要在未知状态下连续发送速度指令。
二、如何向工程师描述问题
1. 遵循“何物、何时、何地、如何复现”
至少一次性提供以下信息：
- 何物： 产品型号、主板型号、系统版本、ROS 发行版、镜像/代码版本；
- 何时： 第一次使用就有，还是之前正常后突然出现；
- 何地： 家庭、实验室、展厅；Wi-Fi/路由器/网络限制；
- 如何复现： 从开机到故障的完整操作顺序；
- 表现： 完全不动、短暂移动后停止、路径规划失败、没有速度指令，还是底盘有速度指令但电机不转；
- 证据： 视频、截图、终端报错、LED 状态、日志、设备照片；
- 已尝试： 是否重启、换线、换 USB 口、换电池、重新烧录或修改配置。
2. 三种时间线场景
情景一：第一次使用就出现问题
例：第一次启动导航程序，机器人从未正常工作。
优先检查：
- 电源、电池、充电器和开关；
- 主板是否正常启动，LED 是否异常；
- Wi-Fi/网口、SSH、HDMI 是否可用；
- 扩展板、驱动板、电机、雷达和摄像头线缆；
- 镜像、SD 卡、主板固件和产品版本是否匹配。
如果主板无法启动、没有 Wi-Fi、LED 异常或 HDMI 报错，镜像、SD 卡、电源和主板启动链优先级较高。
如果主板可正常启动并能 SSH，不要直接判定“软件坏了”或“硬件坏了”，应先沿着控制链路：配置 → ROS 节点 → 串口/总线 → 扩展板 → 电机/舵机逐层检查。
情景二：之前正常，某天首次启动后出现问题
例：
产品：LanderPi 三合一 ROS2 智能车
主板：Raspberry Pi 5 16GB
购买时间：2026-07-06
问题日期：2026-08-06
复现步骤：第一次启动导航程序，设置导航点后小车不移动
之前状态：此前使用正常
近期变更：是否换过 USB 口、电池、网络、代码、镜像或配置
优先回忆最近变化：换线、换 USB 口、更新系统、修改参数、重新建图、换电池、路由器变化、运输碰撞。
这类问题先做变更对比和日志采集，不要一开始就重刷镜像。
情景三：一直不正常，只是最近才发现
例：之前只测试摄像头，第一次使用导航才发现底盘不动。
处理重点：
- 先确认此前到底测试过哪些功能，避免把“未验证”误认为“曾经正常”；
- 用最小功能测试区分：主板启动、网络、传感器、底盘手动控制、导航；
- 记录每一步的结果，建立问题首次出现的准确边界。
同一句“导航小车不动”，可能对应四种完全不同的问题：没有导航节点、没有导航速度指令、有速度指令但底盘不执行、底盘执行但被安全逻辑立即停止。
三、排查前的准备
1. 硬件准备
- 已知正常的电源、充电器、电池、USB 线、网线和 HDMI 线；
- 备用 SD 卡或可恢复镜像；
- 螺丝刀、扎带、标签纸和拍照设备；
- 需要测量时使用万用表，禁止短接或带电插拔；
- 记录机器人、主板、扩展板和电池的序列号。
2. 软件准备
- SSH/VNC 工具和同一局域网连接；
- 对应产品教程、镜像、源码和 ROS2 环境；
- 记录系统时间、产品版本、镜像日期和 Git commit；
- 准备只读巡检命令，先采集再重启；
- 日志中脱敏 Wi-Fi 密码、Token、API Key 和用户隐私数据。
3. 维护前检查单
外观： 外壳、轮组、支架、线缆和接口无松动、挤压、破损。
电源： 电池电量正常、无鼓包/异味/异常发热，充电器匹配。
系统： 能启动、能联网、磁盘空间充足、系统时间正确。
功能： 摄像头、雷达、底盘手动控制、语音和 App 按需验证。
记录： 设备 ID、版本、检查人、时间、结果和遗留问题。
四、“导航小车不动”排查流程
1. 先判断“不动”的具体含义
| 现象 | 重点方向 |
|---|---|
| 设置导航点后没有路径 | 地图、定位、TF、Nav2 生命周期、目标点 |
有路径但没有 /cmd_vel |
控制器、规划器、障碍物层、目标状态 |
有 /cmd_vel 但车不动 |
底盘驱动、串口/总线、扩展板、电机、电池、急停 |
| 车短暂移动后停止 | 障碍物检测、TF/里程计超时、控制器失败、限速/安全策略 |
| 手动控制也不动 | 电源、底盘、驱动板、线缆或机械故障 |
| 手动控制正常，导航不动 | Nav2、定位、地图、TF、QoS 或命令仲裁 |
2. 安全与电源
（1）清空运动区域： 取消当前导航目标，确认人员和障碍物远离轮组。
（2）检查急停和电源： 确认急停未触发、电池电量和电压状态正常。
（3）做手动最小测试： 在低速、短时、可急停条件下确认底盘是否能响应。
不要为了确认底盘是否正常而长时间发送
cmd_vel。未知故障时优先抬起驱动轮或断开电机供电。
3. 主板、驱动板和设备枚举
hostname
uname -a
df -h
ip addr
lsusb
ls /dev/ttyUSB* /dev/ttyACM* 2>/dev/null
dmesg -T | tail -n 120
检查：
- 主板是否稳定运行，是否存在反复重启或欠压日志；
- USB/串口设备是否被枚举；
- 更换 USB 口后设备名是否变化；
- ROS 参数中的设备路径是否与实际路径一致；
- 扩展板、电机驱动板和主板之间的线缆是否插紧、方向正确。
4. ROS2 节点与话题
ros2 node list
ros2 topic list
ros2 topic info /cmd_vel -v
ros2 topic echo /cmd_vel --once
ros2 topic hz /odom
ros2 topic hz /scan
ros2 topic echo /tf --once
ros2 action list
ros2 action info /navigate_to_pose
ros2 topic echo /diagnostics --once
判断逻辑：
- 没有导航节点：检查 launch、环境变量、依赖和启动日志；
- 节点存在但没有
/cmd_vel：检查导航目标、定位、地图、TF、规划器和障碍物层； /cmd_vel有数据但底盘不动：检查底盘驱动节点、串口、扩展板、电机和急停；/odom或/tf不更新：检查编码器、底盘驱动、时间戳和坐标系；/scan无数据：检查雷达供电、USB 枚举、串口软链接、驱动和 QoS；- 多个节点同时发布
/cmd_vel：检查 teleop、Nav2、速度平滑器和命令仲裁。
验证不能只看 topic 是否存在，还要看是否有数据、频率是否稳定、时间戳是否更新、
frame_id是否正确，以及下游节点是否真的订阅。
5. Nav2 与定位链路
依次确认：
- 地图服务是否加载；
- 定位节点是否正常，机器人位姿是否更新；
map -> odom -> base_linkTF 是否连续；- Nav2 生命周期节点是否处于 active；
- 目标点是否在可通行区域；
- costmap 是否把机器人或目标点判定为障碍；
- planner/controller 是否产生路径和速度；
- 是否被恢复行为、超时或安全策略取消。
/cmd_vel没有数据，再查 controller 和障碍物层。
6. 底盘与机械链路
当 /cmd_vel 正常而车仍不动时：
- 检查底盘驱动节点日志和串口权限；
- 检查扩展板是否供电、是否被系统识别；
- 检查电机驱动板指示灯和线缆；
- 检查轮子是否卡住、减速箱是否异常；
- 用已知正常电机/线缆/扩展板做 A/B 对比；
- 需要拆装或测量时先断电，并记录更换前后的结果。
五、临时恢复与升级判断
可以现场处理
- USB 设备号或软链接异常；
- ROS 环境未加载、参数路径错误；
- 单个服务崩溃且日志明确；
- 网络、账号或 App 配置问题；
- 线缆松动、急停触发、设备未上电；
- 有明确回滚路径的配置错误。
需要升级工程师/返修
- 电池鼓包、异味、异常发热；
- 主板反复重启、欠压或烧毁痕迹；
- 已更换已知正常线缆/接口/电源后仍无法枚举；
- 电机、舵机、驱动板持续异常；
- 故障具有随机性且无法稳定复现；
- 需要修改底层固件、驱动、设备树或硬件设计。
升级时一次性提供：产品和主板型号、设备 ID、购买时间、问题时间、完整复现步骤、版本、日志、照片/视频、已尝试动作和当前安全状态。
六、标准问题报告模板
【产品】
型号：
主板/内存：
系统/ROS2版本：
设备ID：
【时间线】
购买/首次使用时间：
最后一次正常时间：
首次发现异常时间：
之前是否正常：是/否/未验证
【问题现象】
期望结果：
实际结果：
是否必现：
影响范围：
【复现步骤】
1.
2.
3.
【环境与变更】
网络环境：
是否换过线/USB口/电池：
是否更新代码、镜像或配置：
【证据】
终端报错：
日志：
LED状态：
照片/视频：
相关topic和频率：
【已尝试】
重启：
换线/换口：
换电池/备用设备：
恢复镜像：
【当前状态】
是否存在安全风险：
是否可以继续使用：
需要支持团队做什么：
七、维护完成后的闭环
（1）按原始复现步骤重新验证。
（2）记录修复前后版本、配置和日志。
（3）确认底盘、传感器、导航和 App 的关键功能。
（4）把一次性解决方案转成 checklist、教程或故障码。
（5）向用户说明恢复结果、限制条件和后续联系人。
“能启动”不等于“功能正常”。恢复后至少确认电源、网络、主板、传感器、运动控制、导航和异常恢复。
八、图示导航
1. 日常维护故障闭环
先保证安全，再采集证据；恢复后必须按原始步骤回归，并把结论沉淀为文档或检查项。
2. 按时间线快速分流
“第一次就异常”“之前正常后异常”“一直未验证”对应的检查优先级不同，不要混用处理方案。
3. ROS2 导航不动排障树
最关键的分叉是：手动控制能不能动。手动也不能动，优先查底盘和硬件；手动能动，再查 Nav2、定位、TF 和 /cmd_vel。
4. ROS2 控制与反馈链路
排查时沿着“导航目标 → Nav2 → /cmd_vel → 安全/仲裁 → 底盘驱动 → 扩展板/电机”，再通过 odom、TF 和诊断信息反向确认执行结果。
如果以上步骤无法定位，请不要只回复“还是不行”。请按“产品信息 + 时间线 + 复现步骤 + 证据 + 已尝试动作”提交问题，便于快速分流。