适用于产品: 幻尔科技树莓派系列（LanderPi / MentorPi / TurboPi / PuppyPi / ROSOrin Pro 树莓派版 等）
涉及模块: USB 枚举 / 集线器 / udev 设备别名 / ROS2 驱动节点
核心标签: 通用 树莓派 usb #图传相机 #激光雷达 #语音盒
一句话顺序：先用 lsusb 确认设备在不在总线上，再用 lsusb -t 看速率和驱动，再用 dmesg 看是一条链掉还是一串掉；一串掉查共同上游，一条掉查那根线和那个口，最后才看 /dev 别名和 ROS 节点。顺序颠倒会浪费大量时间。
一、准备
（1）连上树莓派设备，进入 VNC 远程桌面。
（2）在桌面上打开终端，后续命令都在这个终端里敲。
二、第 1 层 枚举层：设备到底在不在总线上
lsusb
看设备有没有出现在列表里。这一步只回答"在不在"，不回答"好不好"。
树莓派机型的 USB 口位有固定分工（Pi5）：bus 1 是 USB 2.0 黑口，bus 3 是 USB 3.0 蓝口。相机、雷达、语音盒分别挂在哪个口，出厂是有要求的，换口会连带别名失效。
三、第 2 层 链路层：挂在哪个口、什么速率、被谁占着
lsusb -t
看三件事：
（1）设备挂在哪一条总线的哪一个端口（例如 1-2.1 表示 bus 1 的第 2 口下第 1 个子口）。
（2）速率是不是 480M 或 5000M。速率掉到 12M 说明协商降级，通常是线材或接触问题。
四、第 3 层 时间线：掉的是哪一条链（这一步信息量最大）
sudo dmesg -T | grep -iE 'usb|xhci|disconnect|over-current|error -7' | tail -80
看下面这几种信息，对照含义：
| 日志关键字 | 含义 | 排查方向 |
|---|---|---|
| new device number 反复递增 | 在反复重枚举，一会儿好一会儿坏 | 线材、接触、供电 |
| Cannot enable. Maybe the cable is bad? | 使能失败 | 接触、线材、供电 |
| over-current | 电流超限 | 供电，优先换电源或去掉外设 |
| USB disconnect 加父路径 | 掉了具体某条链 | 顺父路径查那一条 |
| error -71 | 物理层（协议/握手） | 线、口、上电时序 |
| error -110 | 传输超时 | 供电、线材、固件卡死 |
| error -32 | 收尾动作，单独出现不定论 | 需要结合上下文 |
| 干净的 disconnect 加干净重枚举 | 设备自己掉电或复位 | 供电波动、固件复位 |
判断口径：
（1）一次掉一个设备，查那根线和那个口。
（2）几个设备一起掉，说明共同上游有问题，比如集线器。优先排查集线器接口松动、集线器供电、通信线。
想在拔插的那一刻看到日志，必须加 --line-buffered，否则 grep 会缓存，等你看到时现场已经过去了：
sudo dmesg -Tw | grep --line-buffered -iE 'usb|3251'
五、第 4 层 命名层：/dev 别名还在不在
ls -l /dev/lidar /dev/ldlidar /dev/rrc /dev/ring_mic
ls -l /dev/serial/by-id
设备在总线上、别名却没了，基本就是插错口了。
原因在于 udev 规则分两种写法：
| 写法 | 例子 | 换 USB 口的结果 |
|---|---|---|
| 按口位绑定 | 雷达 / 语音盒的规则锁死某个端口号（如 3-1:1.0） | 换口就失配，别名不生成 |
| 按设备名通配 | 控制板的规则用 ttyACM 通配 | 换口照样生成，别名不丢 |
所以同一台机器上，控制板的 /dev/rrc 换口后还在，而雷达和语音盒的别名换口后消失，这不是巧合。
修复时用 VID:PID 匹配，不要写口位后缀。临时应急可以先手工补一个软链接，重启后失效。
六、第 5 层 应用层：程序有没有在跑
pgrep -af aurora930
fuser -v /dev/lidar
ros2 node list
能打开但没数据，通常是两种情况：被第二个进程抢了串口，或驱动节点根本没起来。
fuser 只做查看，不要顺手加 kill。当场杀掉正在占用串口的进程，会连带把上层 ROS 链路一起打断，先记录 PID，再决定怎么处理。
七、拔插实验：一次只改一个变量
一次只改一个变量，否则判不出是谁的问题。
| 步骤 | 只改什么 | 观察什么 |
|---|---|---|
| 1 | 原样不动 | 测存活时长，记下来作为基线 |
| 2 | 只换线，口不动 | 再测存活时长；同时看 lsusb -t 速率有没有从 480M 变成 5000M |
| 3 | 只换口，换到蓝色 USB 3.0 口，线用新的 | 再测存活时长 |
| 4 | 换到已知正常的设备（U 盘、鼠标） | 确认那个口本身好不好 |
每一次都要边操作边看日志，用带 --line-buffered 的那条命令。