Livox ROS Driver 2 README.md中文翻译及解析

Livox ROS Driver 2

Livox ROS Driver 2 是用于连接 Livox 生产的激光雷达产品的第二代驱动程序包，适用于 ROS（推荐 Noetic）和 ROS2（推荐 Foxy 或 Humble）。

注意：

Livox ROS Driver 作为调试工具，不推荐用于量产，仅限于测试场景。您应根据原始源代码优化代码以满足各种需求。

1. 准备工作

1.1 操作系统要求

• Ubuntu 18.04 – 用于 ROS Melodic;
• Ubuntu 20.04 – 用于 ROS Noetic 和 ROS2 Foxy;
• Ubuntu 22.04 – 用于 ROS2 Humble;

提示：

Colcon 是 ROS2 中使用的构建工具。 如何安装 colcon: Colcon 安装说明

1.2 安装 ROS & ROS2

ROS Melodic 安装请参考： ROS Melodic 安装说明

ROS Noetic 安装请参考： ROS Noetic 安装说明

ROS2 Foxy 安装请参考： ROS Foxy 安装说明

ROS2 Humble 安装请参考： ROS Humble 安装说明

推荐安装 Desktop-Full 版本。

2. 构建 & 运行 Livox ROS Driver 2

2.1 克隆 Livox ROS Driver 2 源代码：

cd <ros_ws>/src
git clone https://github.com/Livox-SDK/livox_ros_driver2.git ws_livox/src/livox_ros_driver2

注意：

请务必将源代码克隆到 [work_space]/src/ 文件夹中（如上所示），否则由于编译工具的限制会导致编译错误。

2.2 构建 & 安装 Livox-SDK2

注意：

请遵循 Livox-SDK2/README.md 中的安装指南。

2.3 构建 Livox ROS Driver 2：

对于 ROS1

cd <ros_ws>
catkin_make # 或者您可以使用 `catkin build`

对于 ROS2

cd <ros_ws>
colcon build –symlink-install

2.4 运行 Livox ROS Driver 2：

对于 ROS：

cd <ros_ws>
source ./devel/setup.sh
roslaunch livox_ros_driver2 [启动文件]

其中，

• livox_ros_driver2 : 是 Livox ROS Driver 2 的 ROS 包名；
• [启动文件] : 是您想要使用的 ROS 启动文件；launch_ROS1 文件夹中包含几个供您参考的启动示例；

一个用于 HAP 激光雷达的 rviz 启动示例如下：

roslaunch livox_ros_driver2 rviz_HAP.launch

对于 ROS2：

cd <ros_ws>
source ./install/setup.sh
ros2 launch livox_ros_driver2 [启动文件]

其中，

• [启动文件] : 是您想要使用的 ROS2 启动文件；launch_ROS2 文件夹中包含几个供您参考的启动示例。

一个用于 HAP 激光雷达的 rviz 启动示例如下：

ros2 launch livox_ros_driver2 rviz_HAP_launch.py

3. 启动文件及 livox_ros_driver2 内部参数配置说明

3.1 启动文件配置说明

ROS 的启动文件位于 ws_livox/src/livox_ros_driver2/launch_ROS1 目录，ROS2 的启动文件位于 ws_livox/src/livox_ros_driver2/launch_ROS2 目录。不同的启动文件具有不同的配置参数值，用于不同的场景：

3.2 Livox ros driver 2 内部主要参数配置说明

Livox_ros_driver2 的所有内部参数都在启动文件中配置。以下是三个常用参数的详细说明：

注意：

本表中未提及的其他参数，除非完全理解，否则不建议修改。

    Livox_ros_driver2 点云数据详细描述：

float32 x # X 轴，单位: m
float32 y # Y 轴，单位: m
float32 z # Z 轴，单位: m
float32 intensity # 反射率值，范围 0.0~255.0
uint8 tag # livox 标签
uint8 line # 激光器在雷达中的编号
float64 timestamp # 点的时间戳

注意：

帧中的点数可能不同，但每个点都提供时间戳。

std_msgs/Header header # ROS 标准消息头
uint64 timebase # 第一个点的时间基准
uint32 point_num # 点云总数
uint8 lidar_id # 激光雷达设备 ID 号
uint8[3] rsvd # 保留字段
CustomPoint[] points # 点云数据

    上述自定义数据包中的自定义点云 (CustomPoint) 格式：

uint32 offset_time # 相对于基准时间的偏移时间 (单位: ns)
float32 x # X 轴，单位: m
float32 y # Y 轴，单位: m
float32 z # Z 轴，单位: m
uint8 reflectivity # 反射率，范围 0~255
uint8 tag # livox 标签
uint8 line # 激光器在雷达中的编号

    请参考 PCL 库的 point_types.hpp 文件中的 pcl :: PointXYZI 数据结构。

4. 激光雷达配置

激光雷达的配置（如 IP、端口、数据类型等）可以通过 JSON 格式的配置文件进行设置。单个 HAP、Mid360 和混合激光雷达的配置文件位于 config 文件夹中。启动文件中的 user_config_path 参数指示该 JSON 文件的路径。

{
"lidar_summary_info" : {
"lidar_type": 8 # 协议类型索引，请勿修改此值
},
"HAP": {
"device_type" : "HAP",
"lidar_ipaddr": "",
"lidar_net_info" : {
"cmd_data_port": 56000, # 命令端口
"push_msg_port": 0,
"point_data_port": 57000,
"imu_data_port": 58000,
"log_data_port": 59000
},
"host_net_info" : {
"cmd_data_ip" : "192.168.1.5", # 主机 IP (可修改)
"cmd_data_port": 56000,
"push_msg_ip": "",
"push_msg_port": 0,
"point_data_ip": "192.168.1.5", # 主机 IP
"point_data_port": 57000,
"imu_data_ip" : "192.168.1.5", # 主机 IP
"imu_data_port": 58000,
"log_data_ip" : "",
"log_data_port": 59000
}
},
"lidar_configs" : [
{
"ip" : "192.168.1.100", # 您要配置的激光雷达 IP
"pcl_data_type" : 1,
"pattern_mode" : 0,
"blind_spot_set" : 50,
"extrinsic_parameter" : {
"roll": 0.0,
"pitch": 0.0,
"yaw": 0.0,
"x": 0,
"y": 0,
"z": 0
}
}
]
}

上 JSON 文件中的参数属性描述如下表：

激光雷达配置参数

有关 HAP 配置的更多信息，请参考： HAP 配置文件描述

{
"lidar_summary_info" : {
"lidar_type": 8 # 协议类型索引，请勿修改此值
},
"HAP": {
"lidar_net_info" : { # HAP 端口，请勿修改这些值
"cmd_data_port": 56000, # HAP 命令端口
"push_msg_port": 0,
"point_data_port": 57000,
"imu_data_port": 58000,
"log_data_port": 59000
},
"host_net_info" : {
"cmd_data_ip" : "192.168.1.5", # 主机 IP
"cmd_data_port": 56000,
"push_msg_ip": "",
"push_msg_port": 0,
"point_data_ip": "192.168.1.5", # 主机 IP
"point_data_port": 57000,
"imu_data_ip" : "192.168.1.5", # 主机 IP
"imu_data_port": 58000,
"log_data_ip" : "",
"log_data_port": 59000
}
},
"MID360": {
"lidar_net_info" : { # Mid360 端口，请勿修改这些值
"cmd_data_port": 56100, # Mid360 命令端口
"push_msg_port": 56200,
"point_data_port": 56300,
"imu_data_port": 56400,
"log_data_port": 56500
},
"host_net_info" : {
"cmd_data_ip" : "192.168.1.5", # 主机 IP
"cmd_data_port": 56101,
"push_msg_ip": "192.168.1.5", # 主机 IP
"push_msg_port": 56201,
"point_data_ip": "192.168.1.5", # 主机 IP
"point_data_port": 56301,
"imu_data_ip" : "192.168.1.5", # 主机 IP
"imu_data_port": 56401,
"log_data_ip" : "",
"log_data_port": 56501
}
},
"lidar_configs" : [
{
"ip" : "192.168.1.100", # 您要配置的 HAP IP
"pcl_data_type" : 1,
"pattern_mode" : 0,
"blind_spot_set" : 50,
"extrinsic_parameter" : {
"roll": 0.0,
"pitch": 0.0,
"yaw": 0.0,
"x": 0,
"y": 0,
"z": 0
}
},
{
"ip" : "192.168.1.12", # 您要配置的 Mid360 IP
"pcl_data_type" : 1,
"pattern_mode" : 0,
"extrinsic_parameter" : {
"roll": 0.0,
"pitch": 0.0,
"yaw": 0.0,
"x": 0,
"y": 0,
"z": 0
}
}
]
}

MID360_config1:

{
"lidar_summary_info" : {
"lidar_type": 8 # 协议类型索引，请勿修改此值
},
"MID360": {
"lidar_net_info": {
"cmd_data_port": 56100, # 命令端口
"push_msg_port": 56200,
"point_data_port": 56300,
"imu_data_port": 56400,
"log_data_port": 56500
},
"host_net_info": [
{
"lidar_ip": ["192.168.1.100"], # 激光雷达 IP
"host_ip": "192.168.1.5", # 主机 IP
"cmd_data_port": 56101,
"push_msg_port": 56201,
"point_data_port": 56301,
"imu_data_port": 56401,
"log_data_port": 56501
}
]
},
"lidar_configs": [
{
"ip": "192.168.1.100", # 您要配置的激光雷达 IP
"pcl_data_type": 1,
"pattern_mode": 0,
"extrinsic_parameter": {
"roll": 0.0,
"pitch": 0.0,
"yaw": 0.0,
"x": 0,
"y": 0,
"z": 0
}
}
]
}

MID360_config2:

{
"lidar_summary_info" : {
"lidar_type": 8 # 协议类型索引，请勿修改此值
},
"MID360": {
"lidar_net_info": {
"cmd_data_port": 56100, # 命令端口
"push_msg_port": 56200,
"point_data_port": 56300,
"imu_data_port": 56400,
"log_data_port": 56500
},
"host_net_info": [
{
"lidar_ip": ["192.168.2.100"], # 激光雷达 IP
"host_ip": "192.168.2.5", # 主机 IP
"cmd_data_port": 56101,
"push_msg_port": 56201,
"point_data_port": 56301,
"imu_data_port": 56401,
"log_data_port": 56501
}
]
},
"lidar_configs": [
{
"ip": "192.168.2.100", # 您要配置的激光雷达 IP
"pcl_data_type": 1,
"pattern_mode": 0,
"extrinsic_parameter": {
"roll": 0.0,
"pitch": 0.0,
"yaw": 0.0,
"x": 0,
"y": 0,
"z": 0
}
}
]
}

Launch1 (ROS1):

<launch>
<!–用户为 ros 配置的参数开始–>
<arg name="lvx_file_path" default="livox_test.lvx"/>
<arg name="bd_list" default="100000000000000"/>
<arg name="xfer_format" default="0"/>
<arg name="multi_topic" default="1"/>
<arg name="data_src" default="0"/>
<arg name="publish_freq" default="10.0"/>
<arg name="output_type" default="0"/>
<arg name="rviz_enable" default="true"/>
<arg name="rosbag_enable" default="false"/>
<arg name="cmdline_arg" default="$(arg bd_list)"/>
<arg name="msg_frame_id" default="livox_frame"/>
<arg name="lidar_bag" default="true"/>
<arg name="imu_bag" default="true"/>
<!–用户为 ros 配置的参数结束–>

<param name="xfer_format" value="$(arg xfer_format)"/>
<param name="multi_topic" value="$(arg multi_topic)"/>
<param name="data_src" value="$(arg data_src)"/>
<param name="publish_freq" type="double" value="$(arg publish_freq)"/>
<param name="output_data_type" value="$(arg output_type)"/>
<param name="cmdline_str" type="string" value="$(arg bd_list)"/>
<param name="cmdline_file_path" type="string" value="$(arg lvx_file_path)"/>
<param name="user_config_path" type="string" value="$(find livox_ros_driver2)/config/MID360_config1.json"/> <!– Mid360 配置文件1 –>
<param name="frame_id" type="string" value="$(arg msg_frame_id)"/>
<param name="enable_lidar_bag" type="bool" value="$(arg lidar_bag)"/>
<param name="enable_imu_bag" type="bool" value="$(arg imu_bag)"/>

<node name="livox_lidar_publisher1" pkg="livox_ros_driver2"
type="livox_ros_driver2_node" required="true"
output="screen" args="$(arg cmdline_arg)"/>

<group if="$(arg rviz_enable)">
<node name="livox_rviz" pkg="rviz" type="rviz" respawn="true"
args="-d $(find livox_ros_driver2)/config/display_point_cloud_ROS1.rviz"/>
</group>

<group if="$(arg rosbag_enable)">
<node pkg="rosbag" type="record" name="record" output="screen"
args="-a"/>
</group>

</launch>

Launch2 (ROS1):

<launch>
<!–用户为 ros 配置的参数开始–>
<arg name="lvx_file_path" default="livox_test.lvx"/>
<arg name="bd_list" default="100000000000000"/>
<arg name="xfer_format" default="0"/>
<arg name="multi_topic" default="1"/>
<arg name="data_src" default="0"/>
<arg name="publish_freq" default="10.0"/>
<arg name="output_type" default="0"/>
<arg name="rviz_enable" default="true"/>
<arg name="rosbag_enable" default="false"/>
<arg name="cmdline_arg" default="$(arg bd_list)"/>
<arg name="msg_frame_id" default="livox_frame"/>
<arg name="lidar_bag" default="true"/>
<arg name="imu_bag" default="true"/>
<!–用户为 ros 配置的参数结束–>

<param name="xfer_format" value="$(arg xfer_format)"/>
<param name="multi_topic" value="$(arg multi_topic)"/>
<param name="data_src" value="$(arg data_src)"/>
<param name="publish_freq" type="double" value="$(arg publish_freq)"/>
<param name="output_data_type" value="$(arg output_type)"/>
<param name="cmdline_str" type="string" value="$(arg bd_list)"/>
<param name="cmdline_file_path" type="string" value="$(arg lvx_file_path)"/>
<param name="user_config_path" type="string" value="$(find livox_ros_driver2)/config/MID360_config2.json"/> <!– Mid360 配置文件2 –>
<param name="frame_id" type="string" value="$(arg msg_frame_id)"/>
<param name="enable_lidar_bag" type="bool" value="$(arg lidar_bag)"/>
<param name="enable_imu_bag" type="bool" value="$(arg imu_bag)"/>

<node name="livox_lidar_publisher2" pkg="livox_ros_driver2"
type="livox_ros_driver2_node" required="true"
output="screen" args="$(arg cmdline_arg)"/>

<group if="$(arg rviz_enable)">
<node name="livox_rviz" pkg="rviz" type="rviz" respawn="true"
args="-d $(find livox_ros_driver2)/config/display_point_cloud_ROS1.rviz"/>
</group>

<group if="$(arg rosbag_enable)">
<node pkg="rosbag" type="record" name="record" output="screen"
args="-a"/>
</group>

</launch>

5. 支持的激光雷达列表

• HAP
• Mid360
• (更多类型即将推出…)

6. 常见问题解答 (FAQ)

6.1 使用 rviz_HAP.launch 启动，但在网格上没有显示点云？

请检查 RViz “Display” 面板中的 “Global Options – Fixed Frame” 字段。将该字段值设置为 livox_frame 并确保在面板中勾选了 PointCloud2 选项。

6.2 使用命令 ros2 launch livox_ros_driver2 rviz_HAP_launch.py 启动，但无法打开共享对象文件 “liblivox_sdk_shared.so”？

请将 /usr/local/lib 添加到环境变量 LD_LIBRARY_PATH 中。

• 如果只想添加到当前终端：

  export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/local/lib

• 如果想添加到当前用户（永久生效）：

  vim ~/.bashrc
  # 在文件末尾添加下面这行
  export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/local/lib
  # 保存退出后运行
  source ~/.bashrc