FAST-LIO2 Quick Start

1 Prerequisites

Before you start, prepare:

• An Ubuntu + ROS environment: ROS 1 (Melodic or Noetic recommended) or ROS 2 (Humble).
• The HesaiLidar_SDK_2.0, HesaiLidar_ROS_2.0, and FAST_LIO_Hesai repositories.
• For a live LiDAR connection, the LiDAR, host NIC, and driver configuration on the same subnet.

2 Quick start

After building the driver and FAST-LIO2, choose a model and input:

# Live LiDAR: start the driver, FAST-LIO2, and RViz
./tools/run_fastlio.sh jt128 live

# Existing rosbag: start FAST-LIO2 and play the bag
./tools/run_fastlio.sh jt32 bag /data/jt32.bag

# PCAP: convert to rosbag, start FAST-LIO2, and play it
./tools/run_fastlio.sh jt128 pcap /data/JT128/input.pcap

Run the commands from the root of FAST_LIO_Hesai. main is ROS 1 and ROS2 is ROS 2. The script finds workspaces, selects the IMU unit for bag/PCAP input, and cleans up its processes automatically.

2.1 Save a PCD map

# Save to a timestamped file under ~/slam_ws/src/slam_maps/
./tools/run_fastlio.sh jt128 live --save-map

# Choose the output file
./tools/run_fastlio.sh jt128 bag /data/jt128.bag \
  --save-map ~/slam_ws/src/slam_maps/customer_site.pcd

Map buffering is enabled only with --save-map. All models and both ROS versions save under ~/slam_ws/src/slam_maps/ by default.

2.2 Useful options

# Check all resolved paths without starting ROS or changing files
./tools/run_fastlio.sh jt128 live --dry-run

# Workspaces in non-standard locations
./tools/run_fastlio.sh jt128 live \
  --fastlio-ws ~/my_fastlio_ws \
  --driver-ws ~/my_hesai_driver_ws

Other options, including --no-rviz and --play-rate, are listed by ./tools/run_fastlio.sh --help.

JT32 driver availability

FAST-LIO2 already contains the JT32 algorithm configuration, but JT32 uses UDP 1.12. The current public Hesai ROS driver cannot parse this packet format. JT32 live and PCAP modes require the validated compatible driver. An existing rosbag containing /lidar_points and /lidar_imu can still be used.

3 First-time setup

Choose one ROS version. The workspace names below are examples.

3.1 Common SDK

The ROS driver contains the SDK as a submodule, but building the SDK separately is useful for checking the dependency and using SDK tools.

sudo apt update
sudo apt install -y libpcl-dev libpcap-dev libyaml-cpp-dev openssl

mkdir -p ~/hesai_sdk_ws/src
cd ~/hesai_sdk_ws/src
git clone --recurse-submodules https://github.com/HesaiTechnology/HesaiLidar_SDK_2.0.git
cd HesaiLidar_SDK_2.0
mkdir -p build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

3.2 Supported environments

ROS	Branch	Typical system	Build command
ROS 1	main	Ubuntu 20.04 + Noetic	catkin_make
ROS 2	ROS2	Ubuntu 22.04 + Humble	colcon build

3.3 ROS 1 (main)

sudo apt install -y ros-noetic-pcl-ros libeigen3-dev libpcl-dev libboost-all-dev

mkdir -p ~/hesai_ros_ws/src ~/fast_lio_ws/src
cd ~/hesai_ros_ws/src
git clone --recurse-submodules https://github.com/HesaiTechnology/HesaiLidar_ROS_2.0.git
cd ~/fast_lio_ws/src
git clone -b main https://github.com/HesaiTechnology-Spatial-Perception/FAST_LIO_Hesai.git
cd FAST_LIO_Hesai
git submodule update --init --recursive

source /opt/ros/noetic/setup.bash
cd ~/hesai_ros_ws
catkin_make -DCMAKE_BUILD_TYPE=Release
source devel/setup.bash

cd ~/fast_lio_ws
catkin_make -DCMAKE_BUILD_TYPE=Release
source devel/setup.bash

For ROS Melodic, replace noetic with melodic in the package and setup commands.

3.4 ROS 2 (ROS2)

sudo apt install -y ros-humble-pcl-ros ros-humble-pcl-conversions \
  ros-humble-tf2-ros libeigen3-dev libpcl-dev libboost-all-dev

mkdir -p ~/hesai_ros2_ws/src ~/fast_lio_ros2_ws/src
cd ~/hesai_ros2_ws/src
git clone --recurse-submodules https://github.com/HesaiTechnology/HesaiLidar_ROS_2.0.git
cd ~/fast_lio_ros2_ws/src
git clone -b ROS2 https://github.com/HesaiTechnology-Spatial-Perception/FAST_LIO_Hesai.git
cd FAST_LIO_Hesai
git submodule update --init --recursive

source /opt/ros/humble/setup.bash
cd ~/hesai_ros2_ws
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
source install/local_setup.bash

cd ~/fast_lio_ros2_ws
colcon build --packages-select fast_lio --cmake-args -DCMAKE_BUILD_TYPE=Release
source install/setup.bash

The Hesai driver must publish:

Data	Topic	Message
Point cloud	/lidar_points	sensor_msgs/PointCloud2
IMU	/lidar_imu	sensor_msgs/Imu

Point clouds require x, y, z, intensity, ring, and a monotonic per-point timestamp.

Pass --driver-ws or --fastlio-ws if the script cannot find a workspace. In RViz, use camera_init as the fixed frame and display /cloud_registered and /path.

4 Configuration and checks

The first argument selects config/jt16.yaml, jt32.yaml, or jt128.yaml. Normally only these settings need attention:

• Keep common.imu_gyr_unit: "auto". Driver 2.0.10/2.0.11 publishes SI values (m/s², rad/s), while 2.0.12 publishes SDK-scale values (g, deg/s). FAST-LIO2 detects the pair from startup acceleration and retains those startup IMU samples so bag synchronization initializes normally.
• preprocess.timestamp_unit: 0=s, 1=ms, 2=µs, 3=ns.
• mapping.extrinsic_T and mapping.extrinsic_R: LiDAR-to-IMU extrinsics.
• pcd_save.leaf_size: optional voxel size for reducing save memory.

Validate a configuration without starting ROS:

# ROS 1
python3 tools/check_config.py --config config/jt128.yaml --model jt128 --ros 1

# ROS 2
python3 tools/check_config.py --config config/jt128.yaml --model jt128 --ros 2

Validate live or replayed input:

# ROS 1
rosrun fast_lio check_input.py --model jt128

# ROS 2
ros2 run fast_lio check_input.py --model jt128

5 FAQ

5.1 Workspace not found or no output

Pass the built workspace explicitly when auto-discovery fails:

./tools/run_fastlio.sh jt128 live \
  --fastlio-ws ~/fast_lio_ws \
  --driver-ws ~/hesai_ros_ws

If the process starts without output, confirm /lidar_points and /lidar_imu exist, then run check_input.py before changing algorithm parameters.

5.2 The trajectory diverges or the map has ghosting

Check, in this order:

1. Run check_input.py and fix timestamp, frame-drop, or time-sync failures.
2. Keep imu_gyr_unit: "auto" unless a custom driver is known to require a manual override.
3. Verify the selected model and scan_line.
4. Calibrate extrinsic_T and extrinsic_R.
5. Confirm the LiDAR and IMU are mechanically rigid.

5.3 PCAP or JT32 cannot start

Pass only the missing value to the lower-level converter:

bash tools/pcap_to_rosbag/pcap_to_rosbag_ros1.sh /data/JT128/input.pcap \
  --correction /data/JT128/correction.csv

Use the ROS 2 converter on the ROS2 branch and add --dry-run to inspect paths. JT32 UDP 1.12 is not supported by the public driver; use the compatible driver or an existing bag containing point cloud and IMU topics.

5.4 The PCD map was not saved

Start with --save-map and let FAST-LIO2 receive points before stopping it. The script prints the target path. It defaults to ~/slam_ws/src/slam_maps/. Ensure that directory is writable. For manual launches, enable pcd_save.pcd_save_en and call:

# ROS 1
rosservice call /map_save "{}"

# ROS 2
ros2 service call /map_save std_srvs/srv/Trigger "{}"

For long runs, set pcd_save.leaf_size to 0.1 or 0.2 to reduce memory. /cloud_registered shows the current frame, not the full accumulated map; inspect the saved PCD with:

python3 tools/check_map.py --pcd ~/slam_ws/src/slam_maps/your_map.pcd