13. Frequently Asked Questions
❓ Which systems does Odin1 Lite support?
Answer:
| Ubuntu Version | Supported ROS Version |
|---|---|
| 20.04 | ROS1 Noetic |
| 22.04 | ROS2 Humble |
| 24.04 | ROS2 Jazzy |
x86 and ARM (Jetson) architectures are supported.
❓ The device cannot be discovered or pinged after power-on?
Answer:
- Confirm whether the device indicator is steadily on (power supply normal).
- Confirm that the PC Ethernet card IP and the device are in the same subnet:
- Device default IP:
192.168.1.251 - Recommended PC setting:
192.168.1.x/24(avoid conflicting with device.251)
- Device default IP:
- Use
ifconfigto check whether the IP is actually effective; if necessary, disable and re-enable the Ethernet card. - Check whether the firewall blocks UDP broadcast (ports 60000–60010).
- Device discovery, NIC selection and UDP ports are handled automatically by the SDK; there is no need and no way to configure
device_ipthrough launch.
❓ The camera does not have a fixed IP; how to assign an IP automatically via DHCP?
Answer: Use the script/start_dhcp.sh script provided in the repository to start the udhcpd server:
- Install udhcpd:
sudo apt install udhcpd - Modify the listening NIC, IP pool and gateway in
script/my_dhcp.confas needed. - Start DHCP:
sudo ./script/start_dhcp.sh /path/to/my_dhcp.conf - Check the lease file
/var/lib/misc/udhcpd.leasesto confirm the camera has obtained an IP.
❓ Multiple PCs connected to the same LAN interfere with each other’s topic data?
Answer:
-
ROS2: Set a different
ROS_DOMAIN_IDfor each PCecho $ROS_DOMAIN_ID # View current value (blank or 0 means shared) export ROS_DOMAIN_ID=1 # 1–99; 0 means shared -
ROS1: Restrict master to localhost only, or change port
# Recommended export ROS_LOCALHOST_ONLY=1 # Or: use another port roscore -p 11312 export ROS_MASTER_URI=http://localhost:11312
The above commands take effect only in the current terminal; add them to
~/.bashrcfor persistence.
❓ Severe mapping / relocalization drift or packet loss?
Answer:
High-rate sensor data may overflow the kernel network receive buffer, causing UDP packet loss and affecting SLAM and relocalization performance. Please enlarge the buffer and set an independent ROS_DOMAIN_ID before running the driver:
# Enlarge kernel receive buffer
sudo sysctl -w net.core.rmem_max=16777216
sudo sysctl -w net.core.rmem_default=8388608
sudo sysctl -w net.core.netdev_max_backlog=50000
# Isolate the current PC from other ROS2 hosts in the same LAN
export ROS_DOMAIN_ID=1 # 1–99; different PCs use different IDs
For persistence, write the sysctl settings to /etc/sysctl.conf (or a file under /etc/sysctl.d/), and add export ROS_DOMAIN_ID=1 to ~/.bashrc.
❓ image_width / image_height settings do not take effect in ROS1?
Answer: This issue has been fixed in v0.9.0 and later; all v3.x drivers include this fix.
❓ Should Sensor Mode be High Peak or Low Peak?
Answer:
| Mode | Recommended Scenario | Description |
|---|---|---|
| 0 / HDR | General | Automatically balances near and far |
| 1 / High Peak (long frame) | Outdoor | Good anti-strong-light performance, slightly lower near-range precision |
| 2 / Low Peak (short frame) | Indoor | Optimizes near-range and small-space noise, strongly affected by bright light |
| 3 / Adaptive | General | Adaptive switching |
For switching methods, see 7. Odin1 Lite Quick Start (Ubuntu) §7.9.
❓ Build fails with ODIN SDK not found?
Answer: This is usually because the first build did not enter the module/sdk_api submodule. Please handle it in one of the following ways:
- Use the
script/build_ros1.sh/script/build_ros2.shprovided in the driver package (the scripts will automatically build and install the SDK). - Manually initialize the SDK submodule:
git submodule update --init module/sdk_api. - If the SDK has already been pre-installed to a custom path, set the environment variable:
export ODIN_SDK_PREFIX=/path/to/install.
❓ The whole machine lags, memory fills up or even the GUI becomes unresponsive during build?
Answer: Some nodes in the driver (e.g., post_process_node) require 1.0–1.6 GB memory per translation unit; default concurrency may overwhelm small-memory platforms. build_ros1.sh / build_ros2.sh already automatically limit concurrency based on memory (about 2 GB per task), but you can also specify manually:
# Limit concurrency
ODIN_BUILD_JOBS=2 ./src/ros_driver/script/build_ros2.sh
# Or fully control with MAKEFLAGS
MAKEFLAGS="-j2 -l3" ./src/ros_driver/script/build_ros2.sh
For devices with 8 GB or less, -j1 or -j2 is recommended; if necessary, use cgroup to protect the GUI:
systemd-run --user --scope -p MemoryHigh=5G -p CPUWeight=20 \
./src/ros_driver/script/build_ros2.sh
❓ RViz reports TF transform failure and point cloud cannot be displayed?
Answer: When the device’s original TF publish frequency is low, the point cloud timestamp may fall behind the latest TF, causing tf2 to fail interpolation. Enable TF timed retransmission when starting the driver:
ros2 launch odin_ros_driver_rev1 odin1Lite.launch.py tf_publish_rate:=50
The recommended setting is 50–200 Hz; setting it to 0 disables timed retransmission and keeps the device’s original frequency.
❓ High-frequency topic packet loss when recording ROS2 rosbag?
Answer: Use the QoS override configuration provided by the driver to record in reliable mode:
ros2 bag record -a \
--qos-profile-overrides-path ~/catkin_ws/src/ros_driver/config/rosbag2_qos.yaml
ROS1 uses TCPROS; use rosbag record -a directly. For slow disk I/O, you can increase --buffsize.
❓ ros2 topic hz shows very low cloud_raw frame rate; is the driver publish frequency insufficient?
Answer: It is not necessarily low driver publish frequency. Some users reported that when viewing cloud_raw with ros2 topic hz, the printed frequency is significantly lower; this is usually caused by the measurement method of ros2 topic hz, especially after relocalization (Relocation) starts, when the algorithm sends larger point cloud data. ros2 topic hz counts based on the Python subscriber side, and for large messages such as PointCloud2 it is easily affected by deserialization and transport overhead, causing the displayed frame rate to be lower than the actual publish frame rate.
To verify the real frame rate, it is recommended to use post-recording statistics:
ros2 bag record /manifold/device0/cloud/raw \
--qos-profile-overrides-path ~/catkin_ws/src/odin_ros_driver/config/rosbag2_qos.yaml
After recording, use ros2 bag info <bag> to view Message count and Duration; the frame rate calculated by message_count / duration is more accurate.
For real-time observation, you can start the driver’s built-in
diag_subscriber_node(C++ subscriber side), which provides more accurate frame-rate statistics for large messages such asPointCloud2thanros2 topic hz.
❓ post_process_node crashes when publishing the first frame?
Answer: This is usually because multiple OpenCV versions are installed on the system, causing the OpenCV linked by the driver to be inconsistent with the ROS apt version of cv_bridge. Please rebuild cv_bridge from vision_opencv in the current workspace so that it uses the same version as the system OpenCV, then rebuild the driver:
cd ~/catkin_ws/src
git clone -b $ROS_DISTRO https://github.com/ros-perception/vision_opencv.git
cd ~/catkin_ws
colcon build --packages-select cv_bridge
source install/setup.bash
./src/ros_driver/script/build_ros2.sh
For ROS1, use catkin_make -DCATKIN_WHITELIST_PACKAGES="cv_bridge" to build cv_bridge. You can use ldd <post_process_node_path> | grep -iE 'cv_bridge|opencv_core' to confirm that only one OpenCV version is loaded.
❓ How to debug a node crash with GDB?
Answer: First build in Debug mode, then start GDB with launch-prefix:
# Debug build
./src/ros_driver/script/build_ros2.sh --cmake-args -DCMAKE_BUILD_TYPE=Debug
# Interactive GDB
ros2 launch odin_ros_driver_rev1 odin1Lite.launch.py --launch-prefix "gdb -ex run --args"
# Non-interactive (suitable for SSH / embedded)
ros2 launch odin_ros_driver_rev1 odin1Lite.launch.py \
--launch-prefix "gdb -batch -ex run -ex 'bt full' --args"
# Debug only a single node
ros2 launch odin_ros_driver_rev1 odin1Lite.launch.py \
--launch-prefix "gdb -ex run --args" --launch-prefix-filter post_process_node
After the crash, execute bt full and thread apply all bt in GDB to view the call stack. If the stack is all ??, debugging symbols are missing; rebuild in Debug mode.
❓ How to verify that hardware JPEG decoding is actually active?
Answer: The driver startup log only indicates the compile-time decoding path and cannot be used as evidence that hardware decoding is active. It is recommended to simultaneously verify that hardware interrupts are continuously increasing, that post_process_node holds the hardware decoding device node, and that CPU usage is low:
# RK3588
watch -n 1 'grep -E "jpegd|vdpu|rkvdec" /proc/interrupts'
sudo lsof /dev/mpp_service | grep post_process
# Jetson
sudo tegrastats --interval 500 | grep -E "NVJPG"
sudo lsof /dev/nvhost-nvjpg | grep post_process
❓ Hardware JPEG decoding fallback to software decoding crashes on Jetson?
Answer: On Jetson R36 / JetPack 6, when hardware decoding fails and falls back to software decoding, a free() wild pointer crash may occur due to symbol conflict between libnvjpeg.so and the libjpeg-turbo used by OpenCV. If stable software decoding is needed, please rebuild:
# ROS2 example only; for ROS1 use build_ros1.sh and add -DJPEG_PREFER_SOFTWARE_DECODER=ON
colcon build --cmake-args -DJPEG_PREFER_SOFTWARE_DECODER=ON
The default JPEG_PREFER_SOFTWARE_DECODER=OFF uses hardware decoding; enable it only when pure software decoding is needed or when encountering fallback crashes.
❓ How to upgrade firmware remotely?
Answer: Open a browser and visit http://192.168.1.251:8080 → drag the firmware package into the Update page; the system will automatically install and restart. See 8. Firmware Upgrade for details.
❓ How to export calibration files / relocalization maps / device logs?
Answer: All can be done in the HTTP Dashboard:
- Calibration file management: upload / download
camera_calib_<SN>.yaml - Map file download: export relocalization map
- System log download: package as
.tar.gz - Telemetry data recording: export CSV
← Previous Chapter:Technical Specifications | Back to Home →