M20 Pro 辅助模式故障复盘与链路手册
1. 本次结论
本次客户反馈“重启后无法切换/使用辅助模式”，最终定位不是三台主机系统时间不同步，也不是 handler 服务本身异常，而是 103 主机上 rsdriver 发布的雷达点云使用了雷达自身时间戳：
use_lidar_clock: true
该时间戳与 yesense IMU 数据在 LIO 内部无法稳定配对，导致 lio-perception 持续丢弃点云帧，进而不输出 /LIO_ODOM 和 /CLOUD_REGISTERED_BODY。后级 height_map_nav 和 106 的 handler 因拿不到 Odom/Cloud，表现为辅助避障链路失效。
最终处理方式：
use_lidar_clock: false
修改位置：
/opt/robot/share/node_driver/config/config.yaml
该文件内两个雷达 block 均已改为 false。
备份文件：
/opt/robot/share/node_driver/config/config.yaml.bak_20260630_084928_use_lidar_clock
处理后验证结果：
103 height_map_nav:
Data freq(Hz): Cloud=10 Odom=10 IMU=200
106 handler:
Data freq(Hz): Steer=0 Odom=10 IMU=200 Cloud=10 state:1 error_code:0
说明辅助模式链路已经恢复。
2. 辅助模式完整数据链路
以下链路按《辅助避障程序介绍.pdf》和本次现场服务实际 topic 整理。
flowchart LR
subgraph Sensors["传感器与驱动层 - 103"]
Lidar["双雷达硬件<br/>RSAIRY / Hesai"]
Imu["YESENSE IMU"]
Rsdriver["rsdriver<br/>node_driver"]
Yesense["yesense_node"]
end
subgraph LIO["LIO 里程计层 - 103"]
LioPerception["lio-perception<br/>lio_ddsnode"]
end
subgraph HeightMap["高度图辅助避障层 - 103"]
HeightMapNav["height_map_nav"]
end
subgraph HandlerLayer["辅助模式决策层 - 106"]
Handler["handler"]
end
subgraph Control["运动控制层 - 103"]
Basic["basic_server"]
RL["rl_deploy"]
end
App["App / 手柄<br/>下发辅助模式"] -->|Type=1101 Command=5 Mode=2| Basic
Basic -->|set LIO Enable=1| LioPerception
Basic -->|set OOA Enable=1| Handler
Lidar --> Rsdriver
Imu --> Yesense
Rsdriver -->|/LIDAR/POINTS| LioPerception
Yesense -->|/IMU_YESENSE| LioPerception
LioPerception -->|/LIO_ODOM| HeightMapNav
LioPerception -->|/CLOUD_REGISTERED_BODY| HeightMapNav
Yesense -->|/IMU_YESENSE| HeightMapNav
HeightMapNav -->|/cloud_nav| Handler
LioPerception -->|/LIO_ODOM| Handler
Yesense -->|/IMU or /IMU_YESENSE| Handler
Basic -->|/STEER| Handler
Handler -->|避障 / 减速 / 停止命令| Basic
Basic -->|运动控制指令| RL
3. 各模块输入输出与错误含义
3.1 lio-perception
位置：103
输入：
/LIDAR/POINTS
/IMU_YESENSE
输出：
/LIO_ODOM
/LIO_ODOM_HIGH_FREQUENCY
/CLOUD_REGISTERED_BODY
/LIO_ALIGNED_POINTS
本次异常日志：
[lio] 本帧雷达无对应有效imu数据
[lio] 本帧点云为空
实际含义：
rsdriver 确实在发布 /LIDAR/POINTS，点云 width 和 data size 都不为 0；但 LIO 按时间戳做雷达/IMU 配对时无法稳定匹配，导致帧被内部丢弃，最后表现成“点云为空”。
3.2 height_map_nav
位置：103
输入：
/CLOUD_REGISTERED_BODY
/LIO_ODOM
/IMU_YESENSE
输出：
/cloud_nav
/HEIGHT_MAP_STATUS
异常时：
Data freq(Hz): Cloud=0 Odom=0 IMU=200
sensor loss!
说明 IMU 正常，但 LIO 没给它 Odom 和 Cloud。
恢复后：
Data freq(Hz): Cloud=10 Odom=10 IMU=200
3.3 handler
位置：106
输入：
/STEER
/cloud_nav
/LIO_ODOM
/IMU
输出：
避障 / 减速 / 停止命令 -> basic_server
PDF 中错误码含义：
0x02: 无点云输入
0x03: 无里程计输入
0x04: 无 IMU 输入
本次异常时：
Data freq(Hz): Steer=0 Odom=0 IMU=200 Cloud=0 state:2 error_code:3
sensor loss!
恢复后：
Data freq(Hz): Steer=0 Odom=10 IMU=200 Cloud=10 state:1 error_code:0
这说明 handler 本身不是根因，它只是下游缺少 LIO/HeightMap 数据后的表现。
4. 本次排查时间线
4.1 先排查三台主机时间
M20/M20 Pro 辅助模式涉及 103、104、106，多主机日志和 DDS 数据对时间敏感，所以先检查时间同步是正确方向。
最终状态：
103: chrony active
104: chrony active
106: chrony active
当前三台主机已对齐到同一时间源，排除“系统时间不准”作为当前主因。
4.2 排查服务状态
103 关键服务：
basic_server active
yesense active
rsdriver active
lio-perception active
height_map_nav active
106 关键服务：
handler active
服务都在运行，所以不是单纯服务没启动。
4.3 根据 PDF 链路定位到 LIO
PDF 的排查顺序是：
handler -> height_map_nav -> lio-perception -> 数据源
现场证据：
handler: Odom=0 IMU=200 Cloud=0 error_code=3
height_map_nav: Cloud=0 Odom=0 IMU=200
lio-perception: 本帧雷达无对应有效imu数据 / 本帧点云为空
因此 handler 和 height_map_nav 都是结果，真正上游异常在 lio-perception。
4.4 排查 IMU
IMU 当前已恢复：
/IMU_YESENSE: 约 200Hz
height_map_nav 和 handler 都能看到 IMU=200，所以 IMU 不是当前主因。
4.5 排查雷达点云
rsdriver 日志显示两颗雷达状态正常：
status:1
error_code:0
cld_size: 36k - 38k
DDS 也能看到 /LIDAR/POINTS：
Header time: 当前时间轴
height: 1
width: 非 0
data size: 非 0
所以雷达不是完全没数据，而是 LIO 无法正确使用这些点云。
4.6 排查重复点云源
现场同时存在：
rsdriver
hsLidar
曾临时停止 hsLidar，只保留 rsdriver，但 LIO 仍旧异常，说明根因不是单纯两个 publisher 冲突。
后续修复后再启动 hsLidar，链路仍保持：
Cloud=10 Odom=10 IMU=200
因此 hsLidar 不是本次主因。
4.7 定位到雷达时间戳策略
原始配置：
use_lidar_clock: true
这表示 rsdriver 发布点云时使用雷达自身时间戳。LIO 原始配置也按消息时间进行雷达/IMU 配对：
lidar_use_system_time: false
imu_use_system_time: false
当雷达点云时间戳与 IMU 时间戳无法稳定对应时，LIO 会认为当前雷达帧没有对应有效 IMU 数据，从而丢弃整帧。
最终把 rsdriver 的点云时间戳来源改为接收端系统时间：
use_lidar_clock: false
随后 LIO 成功初始化：
[lio] Finish init first scan!
HeightMap 和 handler 同步恢复。
5. 最终处理步骤
5.1 备份配置
sudo cp -a /opt/robot/share/node_driver/config/config.yaml \
/opt/robot/share/node_driver/config/config.yaml.bak_20260630_084928_use_lidar_clock
5.2 修改配置
文件：
/opt/robot/share/node_driver/config/config.yaml
将两个雷达 block 里的：
use_lidar_clock: true
改为：
use_lidar_clock: false
5.3 重启链路
sudo systemctl restart rsdriver
sudo systemctl restart lio-perception height_map_nav
5.4 重新进入辅助模式
App 或接口下发：
Type=1101
Command=5
Mode=2
6. 验证标准
6.1 103 验证 height_map_nav
通过：
Data freq(Hz): Cloud=10 Odom=10 IMU=200
异常：
Data freq(Hz): Cloud=0 Odom=0 IMU=200
sensor loss!
6.2 106 验证 handler
通过：
Data freq(Hz): Steer=0 Odom=10 IMU=200 Cloud=10 state:1 error_code:0
异常：
Data freq(Hz): Steer=0 Odom=0 IMU=200 Cloud=0 state:2 error_code:3
6.3 103 验证 LIO
通过：
[lio] Finish init first scan!
异常：
[lio] 本帧雷达无对应有效imu数据
[lio] 本帧点云为空
7. 重启后是否会保持
会保持。
原因：
- 修改的是持久配置文件
/opt/robot/share/node_driver/config/config.yaml。 rsdriver是enabled，重启后会读取新配置。lio-perception和height_map_nav是enabled，重启后会自动启动。hsLidar是disabled，重启后默认不会自动起来；即使手动启动过，当前验证也没有破坏链路。
当前启动状态：
rsdriver enabled / active
lio-perception enabled / active
height_map_nav enabled / active
hsLidar disabled / active only when manually started
8. 回滚方法
如需回滚：
sudo cp -a /opt/robot/share/node_driver/config/config.yaml.bak_20260630_084928_use_lidar_clock \
/opt/robot/share/node_driver/config/config.yaml
sudo systemctl restart rsdriver
sudo systemctl restart lio-perception height_map_nav
但不建议回滚，因为回滚后大概率会重新出现 LIO 点云/IMU 无法配对，辅助模式再次失效。
9. 后续同类问题排查模板
遇到“辅助模式无法使用”时，优先按下面顺序判断：
1. 三台主机时间同步
2. 103/106 服务状态
3. 106 handler 频率统计和 error_code
4. 103 height_map_nav 的 Cloud/Odom/IMU 频率
5. 103 lio-perception 是否输出 Odom/Cloud
6. /IMU_YESENSE 是否 200Hz
7. /LIDAR/POINTS 是否有 width/data size
8. rsdriver 的 use_lidar_clock 配置
关键判断：
handler error_code=3
且 height_map_nav Cloud=0 Odom=0 IMU=200
且 LIO 报“本帧雷达无对应有效imu数据”
优先检查：
/opt/robot/share/node_driver/config/config.yaml
use_lidar_clock
10. 一句话复盘
这次不是辅助模式命令没下发，也不是 handler 坏了，而是雷达点云使用雷达时钟后，LIO 无法把点云和 IMU 对上时间，导致 LIO 不输出里程计和注册点云；把 rsdriver 改为使用系统接收时间戳后，LIO、HeightMap、handler 全链路恢复，辅助模式生效。