排障与 FAQ
常见现象速查
| 现象 | 原因 | 处理 |
|---|---|---|
open() 返回 Timeout | 网络/端口不通 | ping <Device IP> + nc -z <Device IP> 7448 |
| 连上但所有数据 0 帧 | 设备未在录制 | 先 startRecord() 并等待进入 Recording |
| 位姿正常但点云为 0 | 重定位未运行 | 需加载先验地图并重定位成功 |
| 位姿/点云坐标"不对" | 按 Body/载体系理解了 | 数据是设备(IMU)系，载体变换自己补 |
startRecord 返回 Timeout | 命令可能已送达 | 不要重试，先 queryRecordStatus |
state 一直 Error、message 为 device not ready | 设备端服务未初始化完成 | 等待数十秒后重试 |
| 图像订阅 0 帧 | JPEG 发布未启用 | 确认设备端固件支持图像发布 |
重复订阅返回 Rejected | 该类型订阅槽已占 | 先 unsubscribeXxx 再订阅 |
liblixel_sdk.so not found | 库路径未设 | -Wl,-rpath 或 export LD_LIBRARY_PATH=<sdk>/lib/<arch> |
启动即失败，提示 GLIBC_2.xx | glibc 版本不足 | 换用匹配的交付包或升级系统 |
连接失败（Timeout）
按顺序检查：
- 网线是否连通、主机是否与设备同网段（
ping）； - 设备端口是否可达（
nc -z <Device IP> 7448）； - 设备端服务是否已启动。
若设备端调整过端口（不是默认 7448），把 Options.port / device_port 填成实际端口即可。
startRecord 返回 Ok 但状态一直不变成 Recording
设备启动录制的耗时与地图规模等因素相关，可能需要数十秒。轮询过程中状态为 Idle 或 Starting 都属正常，继续等待即可。若变成 Error，message 会指明原因（存储挂载失败、存储空间不足、相机异常、雷达数据异常、内存不足等），需要先排除故障。
注：不要因为等得久就重复调用
startRecord()。命令已经下发，重复下发不会加快启动，反而可能造成状态混乱。
startRecord 返回 Timeout
这是通信层面没收到应答，与设备启动快慢无关。命令是否送达无从判断，不要直接重试。先 queryRecordStatus() 确认命令是否已生效，再决定是否重发：
if (dev->startRecord() == xg::Error::Timeout) {
xg::RecordStatus st;
if (dev->queryRecordStatus(&st) == xg::Error::Ok && st.state != xg::RecordState::Idle) {
// 已在准备或已开始，转入正常轮询即可，勿重发
}
}
数据全为 0 帧
多数订阅要求设备已在录制且定位在跑。排查：
- 先用
record_demo确认设备能进入Recording； - 位姿有、点云无 → 重定位未运行，需加载先验地图；
- 全都没有（含位姿）→ 设备端 Publisher 未启动或端口不通。
坐标"不对"
SDK 输出的是设备（IMU）系数据，原点在设备 IMU 点。如果你按"机器人中心"或旧版 Body 系去理解，坐标就会"不对"。载体变换需要你自己补一层 TF，见核心概念。
ROS2 相关
| 现象 | 处理 |
|---|---|
ros2 topic list 无 /lixel/* | 检查 bridge 节点日志，确认已连上设备 |
| topic 有但无数据 | 设备未录制或未重定位；查看节点终端输出 |
FAQ
能同时连接多台设备吗？ 本版本一个 Device 对应一台设备，不支持同时连接多台。
回调里可以做耗时处理吗？ 不可以。回调在 SDK 内部线程触发，阻塞会拖住整个会话线程，影响所有订阅。请拷贝数据后转交自己的线程。
isLocal 字段怎么用？ 本版本它是保留字段，恒为 0，请勿使用。
getCameraCalib(0..3) 和 subscribeImage(CameraId) 编号一致吗？不一致，是两套不同映射，不要混用。
setLocInitPose 返回 Ok 就是重定位成功了吗？ 不是。Ok 只表示设备收下了先验，本版本不提供重定位成功与否的判据。
SDK 需要安装 protobuf 吗？ 不需要。protobuf 等第三方依赖已静态并入库内部。
位姿有协方差/时延吗？ 本版本对外不暴露位姿协方差与时延字段。
多线程用同一个 Device 需要注意什么？ 同一实例的方法不可并发调用，须调用方自行加锁。不同实例互不影响。