15. 常见问题 FAQ

适用产品：Odin1
配套软件：ROS Driver、MindCloud Studio
版本：v0.1.0 · 2026.05

录制bag包规范：ros2录制bag包之前，请使用QoS进行录包，可以尽可能的减少丢包几率。使用方法如下：

ros2 bag record /odin1/cloud_raw /odin1/imu /odin1/image/compressed --qos-profile-overrides-path rosbag2_qos.yaml

rosbag2_qos.yaml文件获取

一、硬件与供电

❓ Q1.1 标配适配器规格是什么？为什么强烈要求按规格供电？

回答：

  • 标配：建议使用 12V / 2A 适配器。
  • 风险点：输入电压超过 26V 会直接烧毁内部 DC 芯片，26.8V 即烧毁。
  • 建议：客户使用电源前，请提供电源型号 / 输出范围 / 尖峰电压参数确认；切勿使用非官方电源线。拿到的电源线如果有裸线，请在使用前将裸露的地方用绝缘胶带包起来后使用。

❓ Q1.2 设备红灯不亮 / 无法上电怎么办？

回答：

  • 常见原因：电源正负极是否反接；航插头接触不良；反复插拔后表现为间歇性失败。
  • 现场操作：
    1. 万用表检查电源是否符合 DC 12V 2A（12~24V 以内）；
    2. 拔下航插重新插紧到位、确认锁紧，左右轻微晃动观察红灯是否亮起；
    3. 问题排查：万用表调至【导通/降压】档位，黑色笔接 GND，红色笔先后接触 SYNC 和 GPIO（wiki 中有定义说明）引脚，观察万用表读数：
      • 正常情况：SYNC 引脚降压在 0.9V 左右，GPIO 引脚降压在 1.3V 左右；
      • 异常情况：低于 0.6V 或者不显示压降证明芯片内部烧坏，请联系售后。

❓ Q1.3 Odin1 连接到电脑后运行驱动没有数据

回答：

  • 请检查设备是否供电正常，正常供电红灯常亮；
  • 输入 lsusb 查看设备是否被识别，设备 id：2207:0019；
  • 检查 /etc/udev/rules.d/99-odin1.rules 文件是否存在，如果不存在请手动创建，存在则检查文件内容是否正确；
  • 重启 udev 服务：sudo udevadm control --reload-rules && sudo udevadm trigger；
  • 检查驱动中的 Log 信息是否出现版本过低的提示字样，如果有请更新固件，更新方法见 固件升级。
  • 如果之前可以正常使用，使用过程中提示start listening usb event, further connection should be handleed by hotplug_callback，一般这种情况是脚本启动驱动，后台仍存在节点在运行，需要将后台节点杀掉后重新插拔USB，重新启动驱动。杀进程时务必使用 SIGINT / SIGTERM 让驱动走清理流程释放 USB，详见 Q2.7，否则下一次启动会出现 LIBUSB_ERROR_BUSY。

❓ Q1.4 线材与航插选型？

回答：

  • 我司提供原生 USB 3.0 数据线、防水航插供电线。
  • 目前没有提供 90 度弯头航插头。
  • 极端紧凑安装可选定制方案：① 取消防水，电源线背板直出 + 密封胶；② 定制弯头 / 长度（联系商务沟通）。

二、USB 与连接稳定性

❓ Q2.1 USB 频繁报 heartBeat timeout / waiting for device connecting / 需要掉电重启？

回答： 建议排查顺序：

  1. USB 集线器负载：避免 Odin 与多台高带宽设备共享同一 USB 2.0 hub。建议 Odin1 独占总线，或在系统启动时最后上电 Odin，让其握手更稳定；
  2. 驱动版本：升级到最新 ROS Driver（v0.10.5 及以上）；
  3. 重定位地图配置：确认地图文件路径正确，且地图与算法版本匹配，即使用最新版的驱动采集地图或使用最新版的 MindCloud 处理地图；
  4. 主机算力：弱算力平台（如部分边缘计算盒）CPU 长期满载会导致心跳漏帧，建议预留资源。

❓ Q2.2 心跳超时后 USB 从 3.2 协商降到 2.0 / 2.1？

回答： 典型成因：

  1. 单台 LiDAR 硬件异常（换线无效、换设备恢复 → 通常是该设备硬件故障，需返修）；
  2. 主机 USB 控制器降速兼容（部分平台启用了 USB 兼容模式）。

处置：先在另一台主机上交叉验证；若另一台主机无问题，可能是当前使用开发板问题。

❓ Q2.3 升级固件报 LIBUSB_ERROR_NO_MEM / 传输到 90%+ 失败？

回答：

  1. 升级时单独接到 PC 进行，不要挂在机器人主机上；
  2. 升级期间避免 host 总线上其他高带宽设备占用，可通过 lsusb 检查；
  3. 偶发情况下重试 1–2 次可通过。

❓ Q2.4 lsusb 看不到设备 / 红灯亮但无任何枚举？

回答： 大多为底层供电或硬件问题（与非官方电源线相关案例较多），请按 Q1.2 排查电源；如本地手段无法恢复，按售后流程寄回。

❓ Q2.5 系统中存在多个 OpenCV / libusb 版本时驱动启动失败？

回答：

  • 现象：报错 [host sdk sample-2] process has died [pid 6487, exit code -11 ......]；单独关闭 sendrgb 可正常启动；
  • OpenCV：ROS1 同时存在 4.2 / 4.5 时部分系统会冲突。建议按 README 强制安装单一版本；或者使用 docker 进行环境隔离；
  • libusb：可临时通过调整 LD_LIBRARY_PATH 优先加载系统兼容版本规避。

❓ Q2.6 Odin1 和 RTK 一起使用时，RTK 无法固定？

回答：

  • USB 3.0 在工作时会产生宽频带电磁辐射，其中包含 GNSS L1 频段（1575.42 MHz）附近的噪声；
  • 建议降级为 USB 2.0 或者使用屏蔽更好的连接线。

❓ Q2.7 启动驱动报 failed to claim interface 0: LIBUSB_ERROR_BUSY / 提示 further connection should be handled by hotplug_callback？

回答： 这是上一次启动残留的驱动节点仍占着 USB 接口导致的，常见于用脚本反复启动驱动、或上一次用 kill -9 强杀过进程。

1. 根因：必须用 SIGINT，不能用 kill -9

驱动主进程 host_sdk_sample 只对 SIGINT(2) 和 SIGTERM(15) 注册了清理回调（close device、释放 libusb interface、DeInit lidar）：

// host_sdk_sample.cpp
static void signal_handler(int signum) {
    if (signum == SIGINT || signum == SIGTERM) {
        // Close device  → 释放 USB interface
        // Deinitializing lidar system
    }
}
signal(SIGINT, signal_handler);
signal(SIGTERM, signal_handler);
  • kill -9 PID（SIGKILL）不能被捕获，进程被强杀，USB interface 没释放 → 下次启动 LIBUSB_ERROR_BUSY；
  • kill -2 PID（SIGINT）等价于命令行 Ctrl+C，会走清理流程，USB 正常释放；
  • kill -15 PID（SIGTERM）效果一样。

2. 手动清理命令 

# 按进程名发 SIGINT（推荐，不用查 PID）
pkill -SIGINT -f host_sdk_sample

# 等价写法
pkill -2 -f host_sdk_sample
killall -SIGINT host_sdk_sample

-f 是匹配整条命令行，host_sdk_sample 是 launch 文件里启动的主可执行文件，是真正持有 USB 句柄的那个节点。

3. 推荐写进启动脚本的清理片段

在 ros2 launch ... 之前插入：

#!/bin/bash

# === 启动前先优雅清理上一次残留的节点（关键：先 SIGINT 让它释放 USB） ===
cleanup_old() {
    local procs=(
        host_sdk_sample
        pcd2depth_ros2_node
        cloud_reprojection_ros2_node
        image_overlay_node
    )

    # 第 1 步：发 SIGINT（=Ctrl+C），触发 signal_handler 释放 USB
    for p in "${procs[@]}"; do
        pkill -SIGINT -f "$p" 2>/dev/null
    done

    # 第 2 步：最多等 5 秒让它自己清理退出
    for i in {1..10}; do
        if ! pgrep -f host_sdk_sample >/dev/null; then
            break
        fi
        sleep 0.5
    done

    # 第 3 步：兜底——如果还赖着不走，再 SIGTERM；最后才 SIGKILL
    if pgrep -f host_sdk_sample >/dev/null; then
        echo "进程未在 5s 内退出，发送 SIGTERM..."
        for p in "${procs[@]}"; do pkill -SIGTERM -f "$p" 2>/dev/null; done
        sleep 2
    fi
    if pgrep -f host_sdk_sample >/dev/null; then
        echo "仍未退出，强杀 SIGKILL（USB 可能仍占用，需要拔插）"
        for p in "${procs[@]}"; do pkill -SIGKILL -f "$p" 2>/dev/null; done
    fi
}

cleanup_old

# === 然后再正常启动 ===
source /opt/ros/humble/setup.bash
source ~/odin_ws/install/setup.bash
ros2 launch odin_ros_driver odin1_ros2.launch.py

要点：

  1. 先 SIGINT → 等待 → 再 SIGKILL，顺序不能颠倒；
  2. 必须 sleep 几秒，因为 close device、DeInit 不是瞬间完成的；
  3. host_sdk_sample 是最重要的那个，其他几个跟 launch 一起起的节点顺手清理掉，避免节点名冲突；
  4. 不要一上来就 pkill -9，否则必然留下 LIBUSB_ERROR_BUSY 的坑。

4. 兜底：USB 已被强杀进程占住的恢复方法 

# 方法 A：直接重置 USB 设备（不用拔线）
sudo usbreset 2207:0019
# 或：sudo usbreset /dev/bus/usb/<bus>/<device>

# 方法 B：物理重新插拔 Odin1 USB 线

按上述脚本改造后，failed to claim interface 0: LIBUSB_ERROR_BUSY 基本不会再出现。

三、ROS Driver 报错

❓ Q3.1 ROS Driver 无法获取标定参数

回答： 表现：

  • config 文件夹中没有生成 calib.yaml 文件；
  • cloud_slam 点云呈现黑色，且 odometry 很容易发散。

解决方案：联系留形售后支持，获取参数重新写入工具。若之前正常运行，则可以在之前的驱动中找到标定文件进行复用。若无记录保存，可联系留形售后支持协助查询出场记录。

❓ Q3.2 怎么查看当前固件和驱动的版本？

回答： 运行驱动，在驱动运行终端中可以看到固件与驱动版本的打印信息。

❓ Q3.3 重定位模式下启动驱动报错 file start fail. transfer relocalizaiton map fail. please retry. / 开流崩溃 / 进程内存被打满？

回答：

  • 典型现象：终端持续打印 file start fail. transfer relocalizaiton map fail. please retry.，重试无效甚至导致 driver 进程内存被打满。
  • 根因：旧版 Driver 在重定位模式下，开流过程中触发 deinit，已知 deinit 之后再开流会爆内存。下列两种情况会触发 deinit：
    1. 地图文件路径错误（最常见）—— 加载路径不存在 / 没有读权限 / 不是合法 odin1 地图；
    2. 地图上传 odin1 连续 3 次失败 —— 通常发生在 USB 链路不稳或主机算力被占满时。
  • 解决方案：
    1. 升级到最新 ROS Driver（v0.11.0），固件版本升级到 0.12.0；
    2. 检查启动参数中的地图绝对路径，确保文件可读、与算法版本匹配；
    3. 如果链路上传仍然失败，请按 Q2.1 排查 USB 集线器 / 自配线材 / 主机算力，并确认升级期间无其他高带宽设备占用同一总线。

❓ Q3.4 算法是否有重置功能，怎么使用？

回答： 使用 Driver 版本高于 0.10.0，建议使用 0.10.5 驱动版本 + 0.11.9 固件版本：

cd $ROS_WORKSPACE/src/odin_ros_driver
./set_param.sh algo_reset 1

同时配套：IMU 平滑发送（最高 400 Hz）、PTP 平滑、双图叠加可视化、修复重投影不准确。

❓ Q3.5 驱动报错 the queue is full？

回答：

  • 原因：SDK 内部队列发布速度 < 入队速度，导致积压溢出。常见于本地资源被抢占或网络带宽不足。
  • 解决方法：
    1. 给 Odin1 分配独立的数据传输链路，避免共享网络；
    2. 通过 ROS_DOMAIN_ID 做通信域隔离，减少无关广播；
    3. 确保 pub/sub 的 QoS 一致（reliable / sensor_data / best_effort 不匹配会阻塞）；
    4. 关闭不必要的话题（如 sendrgb: 0、sendcloudrender: 0）；
    5. 优先订阅小数据量话题，如用 /odin1/image/compressed 替代 /odin1/image。

四、时间同步与延迟

❓ Q4.1 Odin 时间比 host 时间”靠后”是 bug 吗？

回答： 早期版本存在该问题，已通过 PTP 平滑 + Driver 时间戳改造在 0.11.0 系列修复。请升级到最新固件 + Driver 后重新配置。

❓ Q4.2 IMU / RGB / 点云通道间相对延迟是多少？

回答： 已发布资料覆盖 RGB 延迟与 IMU 延迟统计；dTOF 延迟数据将在后续版本补齐。如需第一手白盒数据请联系技术支持。

❓ Q4.3 cloud_raw 与 image 时间戳存在 20–30 ms gap？

回答： 已定位为 IMU 回调路径上的发布阻塞与 high_odo 处理阻塞，新版 Driver 通过异步化拆分回调修复。请升级到最新 Driver。

❓ Q4.4 TF 时间戳与点云时间戳偏差大 / 高速场景 TF 不跟车？

回答： 适合启用高频 TF（HIGHFREQ）模式发布，建议同时关闭 config 中不必要的数据通信而非仅关闭 publish，可显著降低 odometry_highfreq 的时间戳跳变。

❓ Q4.5 点云的 header.stamp 代表一帧的起始时刻还是结束时刻？

回答： dtof 点云分成 32 组逐一曝光（类似卷帘快门），第一点位于第一组曝光，因此 header.stamp 与第一组曝光开始时刻一致，代表整帧的起始时刻。

❓ Q4.6 点云 offset_time 的生成依据：dtof_subframe_odr 是速率还是微秒间隔？

回答： dtof_subframe_odr（odr = output data rate）是每组（subframe）的输出频率（速率），不是微秒间隔。SDK 头文件中”微秒间隔”的描述有误，已安排修改，请以示例代码（按速率使用）为准。

❓ Q4.7 第一块点 offset_time = 0 是真同时刻，还是未填充？

回答： 是真时刻。第一点位于第一组曝光，其时间戳与整帧数据 header.stamp 一致，因此 offset_time = 0 表示真实的同步起点，并非未填充。

❓ Q4.8 图像 header.stamp 对应曝光中点还是开始？相机是全局快门还是卷帘快门？

回答：

  • 图像时间戳：对应曝光中点；
  • 相机快门类型：全局快门（Global Shutter）。

五、点云质量

❓ Q5.1 0.4m 近距离点云畸变？

回答： 当前 0.4m 内已出现明显畸变，建议避障近距离用 cloud_raw，建图与定位用 cloud_slam。安装时若机器有近距遮挡（如保险杠 / 防撞圈），建议把传感器适度前倾或避让，防止反射干扰。

❓ Q5.2 点云看起来有噪点，怎么办？

回答： FOV 边缘 110° 以上区域容易出现噪点，安装时尽量让目标处于 FOV 中央偏向位置。

❓ Q5.3 cloud_raw 与 cloud_slam 有什么区别？为什么 cloud_raw 看起来”分层”？

回答：

  • cloud_raw：未矫正历史位姿的原始点云，时延最低，用于近处避障 / 实时感知；
  • cloud_slam：经位姿矫正后的点云，用于建图、定位，无分层现象；
  • “分层”是 Odin1 不回放矫正历史点云的设计本身，不是 bug；建议按用途使用对应话题。

❓ Q5.4 RGB 颜色异常（偏暗 / 偏紫）？

回答：

  • 偏紫：固件层 ISP 配置异常，请联系售后刷新固件即可恢复；
  • 暗光偏暗：对环境补光，后续硬件版本将改善高增益场景。

六、重定位与地图

❓ Q6.1 用 Q9000 建图给 Odin1 重定位很难定位？

回答：

  • 现象：Q9000 扫描的地图相对 Odin1 自建地图更不容易重定位成功。
  • 排查方向：
    1. 使用最新版本的 MindCloud 处理和导出 Q9000 的地图文件；
    2. Q9000 手持扫描时正面镜头角度和高度对齐 Odin1 实际安装角度。
  • 建议方案：使用 custom_init_pos 功能，给定初始位姿，可提高重定位效率。

❓ Q6.2 静态重定位 / 设备不动时无法定位？

回答：

  • 算法机制：算法需要累积 10 次重定位检测后才输出，特征不明显的场景原地不动场景较难凑齐；
  • 建议：开机后让设备做小幅度运动（步行 / 转身 / 缓慢旋转）以触发检测；针对”上电不在平地、原地旋转风险高”的场景（如机器狗），静态重定位建议搭配init_pose使用。

❓ Q6.3 竖装雷达重定位困难？

回答： 升级最新固件与驱动即可。

❓ Q6.4 地图保存失败 / 失败率较高？

回答： 已知优化项已在最新固件 + Driver 落地，建议升级后重测；如仍失败，请录制保存阶段完整日志反馈。

❓ Q6.5 地图导入 / 导出与 MindCloud Studio？

回答：

  • 重定位地图导入 MindCloud Studio：1.0.3 版本 MindCloud 已经可以正常使用；
  • MindCloud Studio 导出编辑后的地图：目前不支持，研发已立项；
  • Q9000 数据导入云平台 → 导出 Odin 重定位地图：已实现。

❓ Q6.6 MindCloud 授权 / 涉密地图不上云？

回答：

  • 授权机制不需要联网，可在内网通过离线授权方式完成；
  • MindCloud 授权后可离线使用，无需上网。

七、极端场景定位（机载 / 隧道 / 暗光）

❓ Q7.1 暗光 + 飞行震动 + 低纹理（白墙立面）场景？

回答：

  1. 现场加装补光（建议白光 / 发散光源）；
  2. 安装尽量减少震动（橡胶减震）。

❓ Q7.2 隧道场景：odom 模式悬停打滑、SLAM 模式沿线退化？

回答：

  • odom 模式：当前 odom 模式下不输出”位置变化”信息，飞控不能纠偏，弱纹理隧道易漂；
  • SLAM 模式：长直退化场景需要充足特征支撑。

建议：

  1. 优化结构设计，确认 Odin1 可视范围内没有扫到机翼、机身、机架等固定障碍物；
  2. 提供至少 5°~10° 的横滚 / 俯仰小幅扰动，避免完全单调直行；
  3. 若测试仍有问题，建议提前联系技术支持做 bag 复盘，建议客户录制 /odin1/cloud_raw & /odin1/imu & /odin1/image/compressed 成一个 bag 包，另提供重定位 bin 地图和标定参数 calib.yaml 文件到 FAE。

❓ Q7.3 算法重置（algo_reset）什么时候用？

回答： 用于碰撞、剧烈位姿跳变后主动让 SLAM 重新初始化。0.10.5+ Driver 已提供 algo_reset 接口与 demo，可由客户在异常事件触发时调用。

调用方式：另起终端，进入 $ros_workspace/src/odin_ros_driver/ 目录，执行：

./set_param.sh algo_reset 1

八、抗冲击与工作温度

❓ Q8.1 抗冲击数据

回答：

测试场景 数值
铁锤直接砸 ≈ 32 G（超日常 10 倍）
流星锤甩 合角速度 ≈ 17.49 rad/s（≈ 2.78 圈/秒）
机器狗跳跃（第三下） ≈ 16.8 G

注：超过陀螺仪量程时会输出最大量程并短暂失能，宣传抗冲击时不要与极限振动场景混用。

❓ Q8.2 工作温度 / 存储温度？

回答：

项 范围
工作温度 -20 °C ~ 55 °C
存储温度 -20 °C ~ 60 °C
  • 主要发热源：dTOF 与 SOC。
  • 影响因素：
    1. 环境温度（建议 ≤ 50 °C）；
    2. dTOF 帧率（10 Hz vs 14.5 Hz，后者发热更高）；
    3. 场景复杂度（特征越多 SOC 计算量越大）。

九、帧率模式与 FOV

❓ Q9.1 高速运动场景效果差？

回答： Odin1 提供 14.5 Hz 隐藏模式，高速场景下开启效果更好。

❓ Q9.2 修改 Odin1 FOV？

回答： 在 Driver 启动配置中可指定 FOV，需配合算法 dynamic 文件中的 init_pose_search_radius、init_pose_max_rot_deg 等参数。完整文档将在 0.12.0 版本配套发布。

十、多机同场使用

❓ Q10.1 同一场地能放多少台 Odin？会互相干扰吗？

回答：

  • Odin1 dTOF 采用编码 / 时分等机制，多台同场干扰较低，已在赛事场景试验；
  • 具体最大并发数受空间密度与遮挡关系影响，建议批量部署前做现场试装；如需技术联调，联系技术支持。

❓ Q10.2 与机械式 LiDAR 相比的差异化？

回答：

  • 黑漆 / 低反射率材料：机械式 LiDAR（如部分 mid 系列、机械旋转激光）容易扫不出，Odin（dTOF）可正常成像；
  • 结构紧凑：无机械旋转，抗振动能力更好（参见第八章）。

十一、系统兼容

❓ Q11.1 Odin1 支持的系统有哪些？

回答： Odin1 支持 x86 架构和 ARM 架构 Ubuntu 20.04 ROS1/ROS2、Ubuntu 22.04 ROS2 等 Linux 系统。

十二、售后服务

❓ Q12.1 返修政策与维修周期？

回答：

  • 返修政策：
    • 适配器规格内损坏（参见 Q1.1）：常规返修流程；
    • 软件 / 配置类问题：原则上远程协助 + 升级固件 / Driver 即可解决，不需要回寄。
  • 维修周期：正常维修周期为 4~5 个工作日，以售后回执为准；复杂硬件问题（如 USB 协商降级 / lsusb 不识别）需要工厂级排查。
  • 备用机机制：批量项目可申请备用机；具体规则联系商务。

十三、标准录包命令

❓ Q13.1 Odin1 录包命令？

回答：

# ros1
rosbag record /odin/image/compressed /odin/imu /odin/cloud_raw /odin/odometry

# ros2
ros2 bag record /odin/image/compressed /odin/imu /odin/cloud_raw /odin/odometry

注 1：需同时提供标定文件 calib.yaml，重定位模式需提供地图文件；
注 2：可根据问题现象，录制问题相关的话题。

附录 A：Odin1 关键版本对照

组件 版本 关键变更
固件 0.11.0 2026-03 多机能力对齐、algo_reset 接口、mask 传输接口
固件 0.11.3 2026-04 修复心跳超时模组需重启的问题、动态初始化、照片盲区设置
固件 0.11.4 2026-04 升级时偶现 LIBUSB_NO_MEM，重试 1–2 次可过
固件 0.11.5+ 2026-05+ 默认开启 confidence 滤波
ROS Driver 0.10.0 2026-04 IMU 平滑 400 Hz、PTP 平滑、双图叠加、algo_reset demo
ROS Driver v1.0.0+ 2026-04 多 Odin1 支持、热插拔修复、重定位地图下发稳定性（强烈推荐）

如本手册未涵盖您的问题，请联系技术支持并提供：① 设备 SN；② 固件 / Driver 版本；③ 完整启动日志；④ 复现 bag（建议 30 秒以上）。我们将按工单优先级响应。

中文 | EN
This site uses Just the Docs, a documentation theme for Jekyll.