Livox ROS Driver 2: one driver across ROS 1 and ROS 2, and five lidar models

What the driver is and the warning attached to it

Livox ROS Driver 2 is the second-generation driver package used to connect lidar products produced by Livox, applicable to ROS with Noetic recommended, and to ROS2 with Foxy or Humble recommended. The note that comes with it is the first thing to read: as a debugging tool, Livox ROS Driver is not recommended for mass production but limited to test scenarios, and you should optimise the code based on the original source to meet your various needs. That is a statement about the intended role of the package rather than a defect report. The driver is a reference implementation of how to talk to the hardware, and a starting point you are expected to fork and tune. Anyone evaluating it for a production robot should read that note and stop there, because the upstream expectation is that you will change the code.

The OS and ROS matrix, one Ubuntu per distribution

The preparation section maps operating systems to ROS distributions explicitly. Ubuntu 18.04 goes with ROS Melodic, Ubuntu 20.04 with ROS Noetic and ROS2 Foxy, Ubuntu 22.04 with ROS2 Humble, and Ubuntu 24.04 with ROS 2 Jazzy. Each distribution has its own installation instructions linked. A Desktop-Full installation is recommended rather than a minimal one, which is a reasonable ask for a driver that pulls in visualisation and tooling. For ROS2 the build tool is colcon, with its own installation guide. So the practical first step for anyone trying this is to identify which row of the matrix they are on, because the answer determines the build script argument later, and a mismatch here produces a build failure rather than a subtle problem.

Cloning into src, then SDK2, then the build script argument

The build sequence is three steps and the order is enforced. First, clone the driver.

git clone https://github.com/Livox-SDK/livox_ros_driver2.git ws_livox/src/livox_ros_driver2

The note attached to that command is the detail that catches people: be sure to clone the source code in a [work_space]/src/ folder as shown above, otherwise compilation errors will occur due to the compilation tool restriction. Colcon and catkin both require that layout. Second, build and install the Livox-SDK2, following the guidance in the Livox-SDK2 README, since the driver links against that library. Third, build the driver itself, and the build script takes an argument naming the target distribution.

source /opt/ros/noetic/setup.sh
./build.sh ROS1

source /opt/ros/humble/setup.sh
./build.sh humble

So the arguments are ROS1 for ROS1, and the distribution name for ROS2: ROS2 for Foxy, humble for Humble, jazzy for Jazzy. The pattern is that the argument selects the ROS generation and the version together.

Running it: two launch systems, one package name

The run step differs between the two generations in how you source the environment and how you launch. For ROS you source the devel setup script and use roslaunch with the package name livox_ros_driver2 and a launch file. For ROS2 you source the install setup script and use ros2 launch with the same package name.

source ../../devel/setup.sh
roslaunch livox_ros_driver2 [launch file]

source ../../install/setup.sh
ros2 launch livox_ros_driver2 [launch file]

The launch file name is the last variable part. The launch_ROS1 folder holds several launch samples for ROS and launch_ROS2 holds the ROS2 equivalents, and the two named examples are the rviz ones, which connect to a HAP lidar, publish pointcloud2 data and autoload rviz. For ROS that is rviz_HAP.launch, and for ROS2 the equivalent is a Python launch file, rviz_HAP_launch.py. The naming difference, a .launch file against a .launch.py file, is small but it is the kind of thing that sends you looking in the wrong directory.

Twelve launch files for five sensors and two output formats

The launch file table is the clearest description of what the driver supports, because it enumerates the combinations. There are rviz and msg variants for each device, where the rviz variant publishes pointcloud2 format data and autoloads rviz, and the msg variant publishes the Livox customised pointcloud data. The devices are HAP, MID360, MID360s, MID360l and AVIA2, plus two mixed variants, rviz_mixed.launch and msg_mixed.launch, which connect to a HAP and a MID360 device together. The mixed files are the interesting ones for a vehicle with more than one sensor, since they avoid running two separate driver instances that would fight over the same topic.

Three parameters that decide what your consumers see

All internal parameters live in the launch file, and the documentation describes three of them in detail while warning that the others should not be changed unless fully understood. publish_freq sets the point cloud publish frequency as a floating point value, with recommended values of 5.0, 10.0, 20.0 and 50.0, and a maximum of 100.0 Hz; the default is 10.0. multi_topic decides whether every lidar device publishes to the same topic or each device gets its own, with 0 for shared and 1 for separate, defaulting to 0. xfer_format chooses the point cloud format: 0 for the Livox pointcloud2 PointXYZRTLT format, 1 for the Livox customised pointcloud format, and 2 for the standard pointcloud2 PCL PointXYZI format, which the documentation says is for ROS only, with the default being 0.

The point cloud fields and what they carry

The documentation spells out the field layout of the Livox pointcloud2 format, which tells you what a consumer of the topic actually receives.

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
float64 timestamp

The fields beyond position are the ones worth understanding. Intensity is reflectivity on a scale of 0 to 255, not a radiometric measurement, so it is usable for filtering and for visualisation shading rather than for any physical inference. The tag field carries a Livox tag, and the line field is the laser number within the lidar, which matters for sensors that interleave returns from multiple lasers into one stream. The timestamp is a 64-bit float rather than an integer, which is the right call for a driver that has to represent sub-microsecond timing across a scan.

The repository layout

The top-level listing shows a package built for two ROS generations at once. There are two package manifests, package_ROS1.xml and package_ROS2.xml, two launch directories, launch_ROS1 and launch_ROS2, and separate msg directories, so the message definitions are versioned alongside the package format. The source lives in src, the build is driven by CMakeLists.txt with a cmake directory and a build.sh that takes the target argument. There is a config directory, a 3rdparty directory for vendored dependencies, a CHANGELOG.md and a LICENSE.txt. The licence field on the repository carries a custom classification that GitHub cannot label, so the LICENSE.txt file is the document that governs, which matters for a driver that vendors third-party code in a 3rdparty directory.

Editorial conclusion

Use Livox ROS Driver 2 when you are bringing a Livox sensor onto a ROS or ROS2 workspace and want the device's launch configuration and point cloud format chosen for you rather than assembled by hand. Do not put it on a robot that ships, because the project itself states it is not recommended for mass production and that you should optimise the code based on the original source for your needs. Verify first that your sensor and your ROS distribution are on the compatibility list, since the driver targets Ubuntu 18.04 through 24.04 across Melodic, Noetic, Foxy, Humble and Jazzy, that you install the Livox-SDK2 library first because the build depends on it, and that you clone into a src folder inside your workspace, since anything else produces compilation errors.

Frequently asked questions

Official sources

1. Issues
2. Livox-SDK/livox_ros_driver2 on GitHub
3. README
4. Releases