The Livox ROS2 driver is a driver package based on ROS2, specifically used to connect LiDAR products produced by Livox. This is a fork of the Offical Livox ROS2 driver. Some changes are made to the original driver to make it work with our perception pipeline. If you stumbled upon this repository, you are probably looking for the original driver.

• Livox ROS2 Driver
  • 1. Install dependencies
    • 1.1 ROS2 installation
    • 1.2 install colcon
  • 2. Get and build livox_ros2_driver
  • 3. Run livox_ros2_driver
    • 3.1 Use the ROS2 launch file to load livox_ros2_driver
    • 3.2 ROS2 launch load command example
    • 3.3 ROS2 launch loads livox_ros2_driver precautions
    • 3.4 Livox LiDAR Broadcast code introduction
  • 4. Launch file and livox_ros2_driver internal parameter configuration instructions
    • 4.1 Launch file configuration instructions
    • 4.2 Livox_ros2_driver internal main parameter configuration instructions
    • 4.3 Pointcloud data specification
  • 5. Configure LiDAR parameters
  • 6. livox_ros2_driver timestamp synchronization function
    • 6.1 Hardware requirements
    • 6.2 Enable timestamp synchronization
  • 7. Support

Before running Livox ROS2 driver under ubuntu 20.04, ROS2 (galactic), colcon build tool and Livox-SDK must be installed.

For ROS2 installation, please refer to the Offical ROS2 installation guide

Somethings to note:

1. Be sure to install the ROS2 galactic version (other versions are may not be supported)
2. Follow the instructions for configuring your environment. You will need to source ROS by using the command /opt/ros/galactic/setup.bash file every time you open a new terminal.

Colcon is a tool for building and testing ROS2 packages. It is used to build the livox_ros2_driver package. For installation instructions, please refer to the offical colcon installation guide

Get livox_ros2_driver from GitHub :

cd ~
git clone https://github.com/ece191-team-b/livox_ros2_driver.git

Build livox_ros2_driver :

cd ~/livox_ros2_driver
colcon build

Source the livox_ros2_driver environment :

cd ~/livox_ros2_driver
source ./install/setup.sh

The usual format of the launch file is: ros2 launch [package_name] [launch_file_name]. Therefore, to launch the livox_ros2_driver and have it publish livox's custom pointcloud message, you can use the following command:

ros2 launch livox_ros2_driver livox_lidar_msg_launch.py

There are multiple launch files provided as an example. Primarily, there are two variants of the launch file:

1. lidar connection mode Usually the format of these launch files will be livox_lidar_{launch-type}_launch.py
2. hub connection mode Conversely, the format of these launch files will be livox_hub_{launch-type}_launch.py

We are using a livox converter and livox's custom lidar data, so we will use lidar connection mode and the msg_launch variant of the launch files. The usual launch file to use is livox_lidar_msg_launch.py.

However, if you would like to visualize the pointcloud in rviz, you can use the livox_lidar_rviz_launch.py launch file. This will launch the livox_ros2_driver and rviz.

1. The launch method of ros2 is completely different from that of ros1. The launch file of ros2 is actually a python script

2. The ros2 driver no longer supports specifying the LiDAR device to be connected under the command line, and only supports configuring the corresponding LiDAR broadcast code and other parameters in the json configuration file

3. When the connection status of the device specified in the configuration file is configured to enable connection (true), the livox_ros2_driver will only connect to the device specified in the configuration file

4. When the connection status of the devices specified in the configuration file is all configured to prohibit connection (false), livox_ros2_driver will automatically connect all the devices that are scanned

5. the json configuration file is in the ~/livox_ros2_driver/livox_ros2_driver/config directory;

Each Livox LiDAR device has a unique broadcast code. The broadcast code consists of a 14-character serial number and an additional character (1, 2, or 3), for a total of 15 characters. The above serial number is located under the QR code of the LiDAR body shell (see the figure below). The broadcast code is used to specify the LiDAR device to be connected. The detailed format is as follows :

Note: The X in the figure above corresponds to 1 in MID-100_Left/MID-40/Horizon/Tele products, 2 in MID-100_Middle, and 3 in MID-100_Right.

All launch files of livox_ros2_driver are in the ~/livox_ros2_driver/livox_ros2_driver/launch directory. Different launch files have different configuration parameter values and are used in different scenarios :

IMPORTANT The default values of the parameters might not be what is actually provided in this repo. In particular, livox_lidar_msg_launch.py and livox_lidar_rviz_launch.py have different values than the Livox default values. The default values in this repo are the values that we have found to work best for our use case.

multi_topic will be an important parameter to set if you are using more than one lidar. One thing to note is that when this parameter is set to 1, the livox will publish data to multiple topics with the format livox/lidar_{lidar_id} (lidar_id can be found on the lidar itself). When this parameter is set to 0, the livox will publish data to the topic named /livox/lidar.

You would need to modify the launch files of the nodes that subscribe to the livox data to match the topic name that the livox is publishing to.

If you are unsure of what topic name is being used. Simply do a ros2 topic list and you will see the topic name that the livox is publishing to.

All internal parameters of Livox_ros2_driver are provided in the launch files. Below are detailed descriptions of the three commonly used parameters

1. Livox pointcloud2 PointXYZRTL point cloud format, as follows :

float32 x               # X axis, unit:m
float32 y               # Y axis, unit:m
float32 z               # Z axis, unit:m
float32 intensity         # the value is reflectivity, 0.0~255.0
uint8 tag               # livox tag
uint8 line              # laser number in lidar

2. Livox customized data package format, as follows : This is the one that we will be using in the perception pipeline

Header header             # ROS standard message header
uint64 timebase           # The time of first point
uint32 point_num          # Total number of pointclouds
uint8  lidar_id           # Lidar device id number
uint8[3]  rsvd            # Reserved use
CustomPoint[] points      # Pointcloud data

    Customized Point Cloud (CustomPoint) format in the above customized data package :

uint32 offset_time      # offset time relative to the base time
float32 x               # X axis, unit:m
float32 y               # Y axis, unit:m
float32 z               # Z axis, unit:m
uint8 reflectivity      # reflectivity, 0~255
uint8 tag               # livox tag
uint8 line              # laser number in lidar

3. The standard pointcloud2 pcl::PointXYZI format in the PCL library is not currently supported. Please refer to the pcl::PointXYZI data structure in the point_types.hpp file of the PCL library.

In the ~/livox_ros2_driver/livox_ros2_driver/launch path, there are two json files, livox_hub_config.json and livox_lidar_config.json.

1. When connecting directly to LiDAR, use the livox_lidar_config.json file to configure LiDAR parameters. Examples of file contents are as follows :

{
   "lidar_config": [
      {
         "broadcast_code": "0TFDG3B006H2Z11",
         "enable_connect": true,
         "enable_fan": true,
         "return_mode": 0,
         "coordinate": 0,
         "imu_rate": 1,
         "extrinsic_parameter_source": 0
      }
   ]
}

    The parameter attributes in the above json file are described in the following table :

LiDAR configuration parameter

Note: When connecting multiple LiDAR, if you want to use the external parameter automatic compensation function, you must first use the livox viewer to calibrate the external parameters and save them to LiDAR.

1. When connecting to the Hub, use livox_hub_config.json to configure the parameters of the Hub and LiDAR. Examples of file contents are as follows :

{
   "hub_config": {
      "broadcast_code": "13UUG1R00400170",
      "enable_connect": true,
      "coordinate": 0
   },
   "lidar_config": [
      {
         "broadcast_code": "0TFDG3B006H2Z11",
         "return_mode": 0,
         "imu_rate": 1
      }
   ]
}

The main difference between the content of Hub json configuration file and the content of the LiDAR json configuration file is that the Hub configuration item "hub_config" is added, and the related configuration content of the Hub is shown in the following table :

HUB configuration parameter

    Note :

    (1) The configuration parameters enable_connect and coordinate in the Hub configuration item "hub_config" are global and control the behavior of all LiDARs. Therefore, the LiDAR related configuration in the Hub json configuration file does not include these two contents.

    (2) The Hub itself supports compensation of LiDAR external parameters, and does not require livox_ros2_driver to compensate.

Prepare a GPS device to ensure that the GPS can output UTC time information in GPRMC/GNRMC format through the serial port or USB virtual serial port, and support PPS signal output; then connect the GPS serial port to the host running livox_ros2_driver, and connect the GPS PPS signal line to LiDAR. For detailed connection instructions and more introduction to time stamp synchronization, please refer to the following links:

Timestamp synchronization

Note:

1. The time stamp synchronization function of livox_ros2_driver is based on the LidarSetUtcSyncTime interface of Livox-SDK, and only supports GPS synchronization, which is one of many synchronization methods of livox devices.
2. Be sure to set the output frequency of GPRMC/GNRMC time information of GPS to 1Hz, other frequencies are not recommended.
3. Examples of GPRMC/GNRMC format strings are as follows :

$GNRMC,143909.00,A,5107.0020216,N,11402.3294835,W,0.036,348.3,210307,0.0,E,A*31
$GNRMC,021225.00,A,3016.60101,N,12007.84214,E,0.011,,260420,,,A*67
$GPRMC,010101.130,A,3606.6834,N,12021.7778,E,0.0,238.3,010807,,,A*6C
$GPRMC,092927.000,A,2235.9058,N,11400.0518,E,0.000,74.11,151216,,D*49
$GPRMC,190430,A,4812.3038,S,07330.7690,W,3.7,3.8,090210,13.7,E,D*26

livox_ros2_driver only supports the timestamp synchronization function when connected to LiDAR. The timestamp related configuration item timesync_config is in the livox_lidar_config.json file. The detailed configuration content is shown in the table below :

Timestamp synchronization function configuration instructions

You can get support from Livox with the following methods :

• Send email to [email protected] with a clear description of your problem and your setup
• Report issue on github