排障与 FAQ

常见现象速查

现象	原因	处理
`open()` 返回 `Timeout`	网络/端口不通	`ping <ip>` + `nc -z <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 <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 需要注意什么？ 同一实例的方法不可并发调用，须调用方自行加锁。不同实例互不影响。