This driver package provides core functionality for point cloud SLAM applications and targets specific use cases. It is intended exclusively for technical professionals conducting secondary development. End users must perform scenario-specific optimization and custom development to align with operational requirements in practical deployment environments.

1. Version

Current Version: v0.5.1

2. Preparation

2.1 OS Requirement

● Ubuntu 18.04 for ROS Melodic;

● Ubuntu 20.04 for ROS Noetic and ROS2 Foxy;

● Ubuntu 22.04 for ROS2 Humble;

2.2 Dependencies

● Opencv >= 4.5.0(recommand 4.5.5/4.8.0. Make sure only one version of opencv is installed)

● yaml-cpp

● thread

● OpenSSL

● Eigen3

2.3 Dependencies Install

2.3.1 System

sudo apt update
sudo apt-get install build-essential cmake git libgtk2.0-dev pkg-config libavcodec-dev libavformat-dev libswscale-dev

2.3.2 yaml-cpp

sudo apt update
sudo apt install -y libyaml-cpp-dev

2.3.3 libusb

sudo apt update
sudo apt install -y libusb-1.0-0-dev

2.3.4 opencv

sudo apt update
sudo apt-get install libopencv-dev

2.3.4 ROS install

For ROS Melodic installation, please refer to: ROS Melodic installation instructions

For ROS Noetic installation, please refer to: ROS Noetic installation instructions

For ROS2 Foxy installation, please refer to: ROS Foxy installation instructions

For ROS2 Humble installation, please refer to: ROS Humble installation instructions

3. Preparation

3.1 Create Udev rules

sudo vim /etc/udev/rules.d/99-odin-usb.rules

Add the following content to the 99-odin-usb.rules file

SUBSYSTEM=="usb", ATTR{idVendor}=="2207", ATTR{idProduct}=="0019", MODE="0666", GROUP="plugdev"

Reload rules and reinsert devices

sudo udevadm control --reload
sudo udevadm trigger

3.2 OS Requirement

git clone https://github.com/manifoldsdk/odin_ros_driver.git catkin_ws/src/odin_ros_driver

Note: Please clone the source code into the "[ros_workspace]/src/" folder, otherwise compilation errors will occur.

3.3 make

3.3.1 ROS1 (Noetic for example):

source /opt/ros/noetic/setup.bash
./script/build_ros.sh

3.3.2 ROS2 (Foxy for example):

source /opt/ros/foxy/setup.bash
./script/build_ros2.sh

3.4 run:

3.4.1 ROS1 (Noetic for example):

source [ros_workspace]/devel/setup.bash
roslaunch odin_ros_driver [launch file]

● odin_ros_driver: package name;

● launch file: launch file;

● ros_workspace: User's ROS environment workspace;

roslaunch odin_ros_driver odin1_ros1.launch

3.4.2 ROS2 (Foxy for example):

source [ros2_workspace]/install/setup.bash
ros2 launch odin_ros_driver [launch file]

● odin_ros_driver: package name;

● launch file: launch file;

● ros2_workspace: User's ROS2 environment workspace;

ROS2 Demo Launch Instructions:

ros2 launch odin_ros_driver odin1_ros2.launch.py

4. File structure and data format

4.1 File structure

Odin_ROS_Driver/                // ROS1/ROS2 driver package
    3rdparty/                   // Third-party libraries
    src/
        host_sdk_sample.cpp     // Example source code
        yaml_parser.cpp         // Source code for reading yaml parameters
        rawCloudRender.cpp      // Source code for RenderCloud
        depth_image_ros_node.cpp //depth_image_ros_node
        depth_image_ros2_node.cpp //depth_image_ros2_node
        pcd2depth_ros.cpp       //Source code for pcd2depth_ros
        pcd2depth_ros2.cpp      //Source code for pcd2depth_ros2
        pointcloud_depth_converter.cpp //Source code for pointcloud_depth_converter
    lib/
        liblydHostApi_amd.a     // Static library for AMD platform
        liblydHostApi_arm.a     // Static library for ARM platform
    include/
        host_sdk_sample.h       // Example header file
        lidar_api_type.h        // API data structure header file
        lidar_api.h             // API function declarations
        yaml_parser.h           // Parameter file reading header file
        rawCloudRender.h        // API about RenderCloud
        data_logger.h           // LOG about save_data
        depth_image_ros_node.hpp // depth_image_ros_node
        depth_image_ros2_node.hpp // depth_image_ros2_node
        pointcloud_depth_converter.hpp // pointcloud_depth_convert
    config/
        control_command.yaml    // Control parameter file for driver
        calib.yaml              //Machine calibration yaml
    launch_ROS1/
        odin1_ros1.launch       // ROS1 launch file
    launch_ROS2/
        odin1_ros2.launch.py    // ROS2 launch file
    script/
        build_ros1.sh           // Installation script for ROS1
        build_ros2.sh           // Installation script for ROS2
    recorddata/                 // holds recorded data that can import into MindCloud
    log/                        // holds log files
    README.md                   // Usage instructions
    CMakeLists.txt              // CMake build file
    License                     // License file

4.2 File structure

Launch File Name	Description
odin1_ros1.launch	Launch file for ROS1 - Odin1 Basic Operations Demo
odin1_ros2.launch.py	Launch file for ROS2 - Odin1 Basic Operations Demo

4.3 ROS topics

Internal parameters of the Odin ROS driver are defined in config/control_command.yaml. Below are descriptions of the commonly used parameters:

Topic	control_command.yaml	Detailed Description
odin1/imu	sendimu	Imu Topic
odin1/image	sendrgb	RGB Camera Topic, decoded from jpeg data from device
odin1/image_undistort	sendrgbundistort	undistorted RGB Camera Topic, processed with calib.yaml from device
odin1/image/compressed	sendrgbcompressed	RGB Camera compressed Topic, original jpeg data from device
odin1/cloud_raw	senddtof	Raw_Cloud Topic
odin1/cloud_render	sendcloudrender	Render_Cloud Topic, processed with raw point cloud, rgb image, and calib.yaml from device
odin1/cloud_slam	sendcloudslam	Slam_PointCloud Topic
odin1/odometry	sendodom	Odom Topic
odin1/odometry_high	sendodom	high frequency Odom Topic
odin1/depth_img_competetion	senddepth	Dense depth image Topic, demo, high computing power required
odin1/depth_img_competetion_cloud	senddepth	Dense Depth_Cloud Topic, demo, high computing power required

4.4 Data format

The raw point cloud (cloud_raw) has the following fields:

float32 x             // X axis, in meters
float32 y             // Y axis, in meters
float32 z             // Z axis, in meters
uint8  intensity      // Reflectivity, range 0–255
uint16 confidence     // Point confidence, range 0–65535
float32 offset_time   // Time offset relative to the base timestamp

To work with this custom format in PCL, first define the point type:

/*** LS ***/
namespace ls_ros {
    struct EIGEN_ALIGN16 Point {
        float x;
        float y;
        float z;
        uint8_t intensity;
        uint16_t confidence;
        float offset_time;
        EIGEN_MAKE_ALIGNED_OPERATOR_NEW
    };
}  // namespace ls_ros

POINT_CLOUD_REGISTER_POINT_STRUCT(ls_ros::Point,
      (float, x, x)
      (float, y, y)
      (float, z, z)
      (uint8_t, intensity, intensity)
      (uint16_t, confidence, confidence)
      (float offset_time , offset_time)
)

Then, you can easily convert a ROS sensor_msgs::PointCloud2 message into a PCL point cloud:

pcl::PointCloud<ls_ros::Point> ls_cloud;
pcl::fromROSMsg(*msg, ls_cloud);

4.5 Other functionalities

control_command.yaml	Detailed Description
recorddata	Record data in specific format that can be imported into MindCloud(TM) for post-processing. Please be aware that this will consume a lot of storage space. Testing shows 9.5G for 10mins of data.
devstatuslog	Device status logging, currently save device status (soc temperature, cpu usage, ram usage, dtof sensor temp .etc) and data tx & rx rate to devstatus.csv under log folder. A new file will be created every time the driver is started.

5. FAQ

5.1 Segmentation fault upon re-launching host SDK

Error Message
No device connected after 60 seconds

Solution

Please power on Odin module again # Disconnect and reconnect odin power
Reinitialize Odin SDK # Execute SDK after device reboot

5.2 Library binding failure during compilation

Error Message
ld: cannot find -llydHostApi or symbol lookup errors

Resolution

Clean previous build artifacts

ROS1

rm -rf devel/ build/

ROS2

rm -rf devel/ install/ log/

Re-run script installation

5.3 Docker GUI passthrough failure

Error Message
Unable to open X display or No protocol specified

Resolution

xhost + #This command enables graphical passthrough to Docker containers

5.4 ROS driver exit with get version failed error

Error Message

<ERROR><api.cpp:lidar_get_version:672>: get device version fail.
get version failed.

Resolution

Device firmware version is too low, please update to latest version.

5.5 RVIZ has not responded for a long time

Error Message
Rviz does not respond, and after a while the terminal prints Device disconnected, waiting for reconnection...

Resolution

Please power on Odin module again

5.6 Device not responding

Error Message
Missed ok response from device,probably wrong interaction procedure.

Resolution

Please adopt the solution mentioned in 5.1

5.7 Device has no external calibration file

Error Message
ERROR：Missing camera node 'cam_0'

Resolution

Please plug and unplug the USB again

5.8 ROS Driver report device disconnected immediately after stream started

Error Message

Device ready and streams activated
Device detaching...
Wating for device reconnection...
Device disconnected, waiting for reconnection...

Reason

Mostly common on ros2 environment and connected to complex network environment, such as office wifi & ethernet. ROS2 default to broadcast, and complex network environment will cause ros2 publish to block, leading to device disconnection.

Resolution

If cross-device communication is not required, please restrict ros2 to localhost only with:

export ROS_LOCALHOST_ONLY=1

If cross-device communication is required, please simplify the network environment as much as possible. Mini local network with only required devices is recommended.

6. Contact Information

To help diagnose the issue, please provide the following details to our FAE engineer:

Current firmware version

[device_version_capture]: ros_driver_version: [Version Number]

Photos of power adapter and converter cable in use.
Does the issue happen occasionally or consistently?
Provide images of the problem scenario.
Did the troubleshooting methods in Section V resolve the issue?
Expected timeline for issue resolution.

README.md Unescape Escape

Odin_ROS_Driver Readme

Odin_ROS_Driver

Important Notice:

1. Version

2. Preparation

2.1 OS Requirement

2.2 Dependencies

2.3 Dependencies Install

2.3.1 System

2.3.2 yaml-cpp

2.3.3 libusb

2.3.4 opencv

2.3.4 ROS install

3. Preparation

3.1 Create Udev rules

3.2 OS Requirement

3.3 make

3.3.1 ROS1 (Noetic for example):

3.3.2 ROS2 (Foxy for example):

3.4 run:

3.4.1 ROS1 (Noetic for example):

3.4.2 ROS2 (Foxy for example):

4. File structure and data format

4.1 File structure

4.2 File structure

4.3 ROS topics

4.4 Data format

4.5 Other functionalities

5. FAQ

5.1 Segmentation fault upon re-launching host SDK

5.2 Library binding failure during compilation

5.3 Docker GUI passthrough failure

5.4 ROS driver exit with get version failed error

5.5 RVIZ has not responded for a long time

5.6 Device not responding

5.7 Device has no external calibration file

5.8 ROS Driver report device disconnected immediately after stream started

6. Contact Information​​

README.md

6. Contact Information