FAST-LIO2 快速启动

1 前置条件

开始前请准备：

• 已准备 Ubuntu + ROS 环境：ROS 1（推荐 Melodic 或 Noetic）或 ROS 2（Humble）。
• HesaiLidar_SDK_2.0、HesaiLidar_ROS_2.0 和 FAST_LIO_Hesai 源码。
• 连接实机时，雷达、主机网卡和驱动配置位于同一子网。

2 快速启动

编译驱动和 FAST-LIO2 后，选择型号和输入即可：

# 连接实机：启动驱动、FAST-LIO2 和 RViz
./tools/run_fastlio.sh jt128 live

# 使用已有 rosbag：启动 FAST-LIO2 并回放
./tools/run_fastlio.sh jt32 bag /data/jt32.bag

# 使用 PCAP：转换为 rosbag、启动 FAST-LIO2 并回放
./tools/run_fastlio.sh jt128 pcap /data/JT128/input.pcap

请在 FAST_LIO_Hesai 根目录执行命令。main 是 ROS 1，ROS2 是 ROS 2。 脚本会自动查找工作空间、为 bag/PCAP 选择 IMU 单位，并在退出时清理子进程。

2.1 保存 PCD 地图

# 自动保存到 ~/slam_ws/src/slam_maps/ 下的带时间文件
./tools/run_fastlio.sh jt128 live --save-map

# 指定输出文件
./tools/run_fastlio.sh jt128 bag /data/jt128.bag \
  --save-map ~/slam_ws/src/slam_maps/customer_site.pcd

只有使用 --save-map 时才开启地图缓存。所有型号和 ROS 版本默认保存到 ~/slam_ws/src/slam_maps/。

2.2 常用选项

# 只检查自动解析结果，不启动 ROS，也不修改文件
./tools/run_fastlio.sh jt128 live --dry-run

# 工作空间不在常用位置
./tools/run_fastlio.sh jt128 live \
  --fastlio-ws ~/my_fastlio_ws \
  --driver-ws ~/my_hesai_driver_ws

--no-rviz、--play-rate 等选项见 ./tools/run_fastlio.sh --help。

JT32 驱动可用性

FAST-LIO2 已包含 JT32 算法配置，但 JT32 使用 UDP 1.12。当前公开 Hesai ROS 驱动无法解析该报文格式，因此 JT32 实机和 PCAP 模式需要经过验证的兼容驱动。 已经包含 /lidar_points 和 /lidar_imu 的 rosbag 仍可直接使用。

3 首次安装

选择一个 ROS 版本。以下工作空间名称仅为示例。

3.1 公共 SDK

ROS 驱动通过子模块包含 SDK，但单独编译 SDK 便于确认依赖和使用 SDK 工具。

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 支持环境

ROS	分支	常用系统	编译命令
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

如果使用 ROS Melodic，请将安装包名和环境路径中的 noetic 替换为 melodic。

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

Hesai 驱动必须发布：

数据	Topic	消息类型
点云	/lidar_points	sensor_msgs/PointCloud2
IMU	/lidar_imu	sensor_msgs/Imu

点云必须包含 x、y、z、intensity、ring 和单调递增的逐点 timestamp。

如果脚本找不到工作空间，请传入 --driver-ws 或 --fastlio-ws。RViz 的 Fixed Frame 使用 camera_init，显示 /cloud_registered 和 /path。

4 配置与检查

第一个参数会选择 config/jt16.yaml、jt32.yaml 或 jt128.yaml。通常只需 关注以下参数：

• 建议保持 common.imu_gyr_unit: "auto"。驱动 2.0.10/2.0.11 发布 SI 单位（m/s²、rad/s），2.0.12 发布 SDK 原始单位（g、deg/s）； FAST-LIO2 会根据启动阶段的加速度自动识别，并保留检测阶段的 IMU 数据， 确保 bag 回放可以正常完成同步初始化。
• preprocess.timestamp_unit：0=秒、1=毫秒、2=微秒、3=纳秒。
• mapping.extrinsic_T 和 mapping.extrinsic_R：LiDAR 到 IMU 的外参。
• pcd_save.leaf_size：可选体素尺寸，用于降低保存内存。

不启动 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

检查实机或回放数据：

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

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

5 常见问题

5.1 找不到工作空间或启动后没有输出

自动查找失败时，显式传入已编译的工作空间：

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

启动后没有输出时，确认 /lidar_points 和 /lidar_imu 存在，然后运行 check_input.py；不要先修改算法参数。

5.2 轨迹发散或地图重影

按以下顺序检查：

1. 运行 check_input.py，先解决时间戳、丢帧和时间同步问题。
2. 保持 imu_gyr_unit: "auto"，除非自定义驱动明确需要手动覆盖。
3. 确认型号选择和 scan_line 正确。
4. 标定 extrinsic_T 和 extrinsic_R。
5. 确认 LiDAR 和 IMU 机械连接牢固。

5.3 PCAP 或 JT32 无法启动

只向底层转换器补充缺少的参数：

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

ROS2 分支使用 ROS 2 转换器；增加 --dry-run 可查看解析路径。公开驱动目前 不支持 JT32 UDP 1.12，请使用兼容驱动，或使用已有点云和 IMU 的 bag。

5.4 PCD 地图没有保存

启动时增加 --save-map，并在停止前确保 FAST-LIO2 已收到点云。脚本会打印目标路径， 默认目录为 ~/slam_ws/src/slam_maps/，请确认该目录可写。手动启动时需开启 pcd_save.pcd_save_en，然后调用：

# ROS 1
rosservice call /map_save "{}"

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

长时间运行时，将 pcd_save.leaf_size 设置为 0.1 或 0.2 以降低内存。 /cloud_registered 只显示当前配准帧；完整累计地图请保存 PCD 后检查：

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