feat:add livo ros driver application documents

Home.md

@@ -1,4 +1,5 @@
-# Getting Started
+
+## Getting Started
 
 [Livox MID40/100 Downloads](https://www.livoxtech.com/mid-40-and-mid-100/downloads)
 
@@ -6,18 +7,25 @@
 - Livox MID-40/100 Point Cloud Characteristics
 - Livox MID-40 Point Cloud Data
 
-# Install Livox-SDK
+## Install Livox-SDK
 
 - [Install Livox SDK in Linux 32-bit system and Mac](https://github.com/Livox-SDK/Livox-SDK/wiki/The-installation-of-Livox-SDK-on-Linux-32-bit-system-and-Mac)
 
-# Development Guide
+## Development Guide
 
 - [Time synchronization of Livox LiDARs](https://github.com/Livox-SDK/Livox-SDK/wiki/Timestamp-Synchronization)
 - [Livox SDK Communication Protocol](https://github.com/Livox-SDK/Livox-SDK/wiki/Livox-SDK-Communication-Protocol)
 
-# Livox Viewer
+## Livox Viewer
 
 - [Color Coding Strategy](https://github.com/Livox-SDK/Livox-SDK/wiki/Livox-Viewer#1-color-coding-strategy)
 
-# Quick Links
+## livox_ros_driver application
-> * [LivoxTech Official website](https://www.livoxtech.com/)
+
+- [How to use lvx file in ros](https://github.com/Livox-SDK/Livox-SDK/wiki/how_to_use_lvx_file_in_ros)
+- [Set publish frequency](https://github.com/Livox-SDK/Livox-SDK/wiki/set_publish_frequency)
+- [外参标定与点云显示](https://github.com/Livox-SDK/Livox-SDK/wiki/calibrate_extrinsic_and_display_in_ros_cn)
+
+## Quick Links
+
+- [LivoxTech Official website](https://www.livoxtech.com/)

Livox-SDK-Communication-Protocol.md

@@ -556,10 +556,11 @@ request
 |      |gw_addr | 11             | uint8_t[4] |IPV4 gateway<br> IP gateway is valid when ‘ip_mode’ is 0x01(Static IP)<br> Example: AA.BB.CC.DD<br> gw_addr[0]: AA<br> gw_addr[1]: BB<br> gw_addr[2]: CC<br> gw_addr[3]: DD<br><br>**Supported devices:** <br>Horizon/06.04.0000+ <br>Tele-15/07.03.0000+ |
 
 IP Address Information:
+
 | Device Type/Firmware version                    | IP Address Information                                       |
 | ----------------------------------------------- | ------------------------------------------------------------ |
 | Livox Hub<br/>Mid-40<br/>                       | IPV4 Address<br/> IP address is valid when ‘ip_mode’ is 0x01(Static IP) <br/>ip_addr[0]: 192<br/> ip_addr[1]: 168<br/> ip_addr[2]: 1<br/> ip_addr[3]: Range is as follows<br/> Last bit of broadcast code:<br/> 1: 11 ~ 80<br/> 2: 81 ~ 150<br/> 3: 151 ~ 220 |
-| Horizon/06.04.0000+ <br>Tele-15/07.03.0000+<br> | IPV4 Address<br/> IP address is valid when ‘ip_mode’ is 0x01(Static IP) <br/>ip_addr[0]: 1~126 && 127~223<br/> ip_addr[1]: 0~255<br/> ip_addr[2]: 0~255<br/> ip_addr[3]: 0~255 |
+| Horizon/06.04.0000+ <br>Tele-15/07.03.0000+ <br> | IPV4 Address<br/> IP address is valid when ‘ip_mode’ is 0x01(Static IP) <br/>ip_addr[0]:1 ~ 126 && 127 ~ 223<br/> ip_addr[1]: 0 ~ 255<br/> ip_addr[2]: 0 ~ 255<br/> ip_addr[3]: 0 ~ 255 |
 
 response
 
@@ -818,7 +819,7 @@ request
 | ---- | ------- | ------------- | --------- | ------------------------------------------------------------ |
 | data | cmd_set | 0             | uint8_t   | LiDAR Command: 0x01                                          |
 |      | cmd_id  | 1             | uint8_t   | Command ID: 0x0A                                             |
-|      | year   | 2             | uint8_t   | UTC Year:<br>0 is 2000 year <br>255 is 2555 year |
+|      | year   | 2             | uint8_t   | UTC Year:<br>0 is 2000 year <br>255 is 2255 year |
 |      | month  | 3             | uint8_t   | UTC Month: Range is 1-12 |
 |      | day    | 4             | uint8_t   | UTC Day: Range is 1-31 |
 |      | hour   | 5             | uint8_t   | UTC Hour: Range is 0-23|

Timestamp-Synchronization.md

@@ -2,19 +2,23 @@
 
 **Livox LiDAR Timestamp Synchronization**
 
-| **Document   Release History** |             |                        |
+| **Document   Release History** |             |                                      |
-| ------------------------------ | ----------- | ---------------------- |
+| ------------------------------ | ----------- | ------------------------------------ |
-| **Date**                       | **Release** | **Change Description** |
+| **Date**                       | **Release** | **Change Description**               |
-| 2019/6/19                      | v1.0.0      | Initial release        |
+| 2019/6/19                      | v1.0.0      | Initial release                      |
-|                                |             |                        |
+| 2020/2/13                      | v1.1.0      | LiDAR add GPS synchronization method |
+|                                |             |                                      |
+
+[TOC]
+
 
 
 # 1 Summary
 
-| **Device**  | **Supported   Time Synchronization Method** |
+| **Device**  | **Supported Time Synchronization Method**        |
-| ----------- | ------------------------------------------- |
+| ----------- | ------------------------------------------------ |
-| Livox LiDAR | 1. PTP v2<br>2. Pulse Per Second (PPS)      |
+| Livox LiDAR | 1. PTP v2<br>2. GPS<br>3. Pulse Per Second (PPS) |
-| Livox Hub   | 1. PTP v2<br>2. GPS                         |
+| Livox Hub   | 1. PTP v2<br>2. GPS                              |
 
 ## 1.1 Application Scenarios
 
@@ -36,19 +40,98 @@ Livox Hub supports GPS time synchronization, which is recommended when integrati
 
 When Livox LiDAR or Livox Hub is connected to a network with master clock, the clock of  each LiDAR point cloud is automatically synchronized to the master clock. When PTP, PPS or GPS are available at the same time, PTP network synchronization is preferred.
 
-### Connection:
+### 2.1.1 Connection
 
 Connect Livox LiDAR/Hub normally without additional wiring. 
 
-### Attention:
+### 2.1.2 Attention
 
 Network environments with multiple master clocks are not supported. For the construction of master clock, please refer to Appendix [3.1 Set Up PTP Master Clock](#3.1).
 
-### Accuracy:
+### 2.1.3 Accuracy
 
 Hundreds of nanoseconds
 
-## 2.2 PPS
+## 2.2 GPS
+
+### 2.2.1 Livox Hub
+
+#### 2.2.1.1 Connection
+
+Connect the PPS signal and time stamp signal from GPS module to the Livox Hub's GPS sync port.
+
+![](images/gps_ttl_hub.png)
+
+Remarks: 
+
+- If the data output by the GPS module is 485 level, TTL to 485 module is not needed.
+
+#### 2.2.1.2 Configuration
+
+Do not require any software configuration when using Livox Hub for GPS time synchronization.
+
+### 2.2.2 Mid40/100
+
+#### 2.2.2.1 Connection
+
+Connect the PPS signal from GPS module to the sync port of Mid40/100 converter, and connect the time stamp signal to PC through the TTL to USB module.
+
+![](images/gps_ttl_mid.png)
+
+Remarks: If the data output by the GPS module is 485 level, the TTL to 485 module is not needed.
+
+#### 2.2.2.2 Configuration
+
+Mid firmware version: >= v03.07.0000, SDK version >= v2.0.0
+
+**Use ROS driver**
+
+- Connect the hardware according to the above block diagram;
+- View the name of the port receiving "Time signal"(GPRMC/GNRMC) in PC system, such as `/dev/ttyUSB0`, configure "device_name" to this name in the file [livox_lidar_config.json](https://github.com/Livox-SDK/livox_ros_driver/blob/master/livox_ros_driver/config/livox_lidar_config.json), and set "enable_timesync" to `true`;
+- Run the launch file;
+
+**Use only SDK**
+
+The link below is an example showing how to synchronize using only SDK:
+
+[https://github.com/Livox-SDK/Livox-SDK/tree/master/sample_cc/lidar_utc_sync](https://github.com/Livox-SDK/Livox-SDK/tree/master/sample_cc/lidar_utc_sync)
+
+### 2.2.3 Horizon
+
+#### 2.2.3.1 Connection
+
+Connect the PPS signal from GPS module to the sync port of Livox converter 2.0, and connect the time stamp signal to PC through TTL to USB module.
+
+![](images/gps_ttl_horizon.png)
+
+#### 2.2.3.2 Configuration
+
+Horizon firmware version: >= v06.06.0000, SDK version >= v2.0.0
+
+**Use ROS driver**
+
+- Connect the hardware according to the above block diagram;
+- View the name of the port receiving "Time signal"(GPRMC/GNRMC) in PC system, such as `/dev/ttyUSB0`, configure "device_name" to this name in the file [livox_lidar_config.json](https://github.com/Livox-SDK/livox_ros_driver/blob/master/livox_ros_driver/config/livox_lidar_config.json), and set "enable_timesync" to `true`;
+- Run the launch file;
+
+**Use only SDK**
+
+The link below is an example showing how to synchronize using only SDK:
+
+[https://github.com/Livox-SDK/Livox-SDK/tree/master/sample_cc/lidar_utc_sync](https://github.com/Livox-SDK/Livox-SDK/tree/master/sample_cc/lidar_utc_sync)
+
+### 2.2.4 Attention
+
+- Generally, when there is GPS satellite signal, the GPS module will have PPS signal and time signal output. In normal use, make sure the GPS satellite signal is stable.
+- Make sure that the output of "Time signal" is standard GPRMC/GNRMC message.
+
+### 2.2.5 Accuracy
+
+1 microsecond
+
+## 2.3 PPS
+
+**Because the LiDAR has supported GPS synchronization, the PPS method is not recommended.**
 
 Every time the LiDAR receives the rising edge of a pulse, the timestamp of point cloud will be reset to 0, and then the time will increase until the rising edge of the next pulse is received. We can use this feature to update the timestamp in each point cloud packet to the external GPS time.
 
@@ -77,43 +160,21 @@ else
 LiDAR_time_last = LiDAR_time;
 ```
 
-### Connection:
+### 2.3.1 Connection
 
-GPS uses 485 level:
+**Mid:**
 
-![](images/gps_485.png)
+![](images/gps_ttl_mid.png)
 
-GPS uses TTL level:
+**Horizon:**
 
-![](images/gps_ttl.png)
+![](images/gps_ttl_horizon.png)
 
-### Attention:
+### 2.3.2 Attention
 
-When the GPS signal is weak or missing, the GPS module will not be able to generate TTL pulses. When this happens, it cannot correct the timestamp of point cloud.
+- If the data output by the GPS module is 485 level, TTL to 485 module is not needed.
 
-### Accuracy:
+### 2.3.3 Accuracy
-
-1 microsecond
-
-## 2.3 GPS
-
-Connect the PPS signal and timestamp signal from GPS receiver to the Livox Hub's synchronization interface.
-
-### Connection:
-
-GPS uses 485 level:
-
-![](images/gps_485_1.png)
-
-GPS uses TTL level:
-
-![](images/gps_ttl_1.png)
-
-### Attention:
-
-Make sure that the "Time signal" in the above figure is GPRMC message.
-
-### Accuracy:
 
 1 microsecond
 

calibrate_extrinsic_and_display_in_ros_cn.md

@@ -0,0 +1,47 @@
+# 外参标定与点云显示
+
+览沃 ROS 驱动程序支持补偿 LiDAR 外参，在补偿外参之前必须标定好 LiDAR 外参。
+
+## 1. 使用 Livox Viewer 标定外参
+
+### 外参标定
+
+使用 Livox Viewer 标定外参的方法如下图 ：
+
+![Calibrate_extrinsic](image_ros/calibrate_extrinsic_01.png)
+
+设置与写入雷达外参数值
+
+![Calibrate_extrinsic](image_ros/calibrate_extrinsic_02.png)
+
+***注意事项 :***
+
+（1）在空旷环境下，准备标定物（标定板、标定支架……）；
+
+（2）寻找雷达之间的共同 FOV 方向的同一目标物；
+
+（3）通过旋转一定角度，平移一定距离，使得目标物重叠；
+
+（4）完成外参标定；
+
+（5）如果没有共同 FOV ，则只能根据每个雷达之间的空间关系进行外参调整；
+
+## 2. Git clone livox_ros_driver
+
+`git clone https://github.com/Livox-SDK/livox_ros_driver.git ws_livox/src`
+
+## 3. 在Livox Ros Driver 中修改 config 配置表
+
+进入以下文件路径： "../ws_livox/src/livox_ros_driver/config"，打开 livox_lidar_config.json 文件，如果只有一台设备，则只根据以下步骤修改对应的信息，如果有多台Livox雷达设备，则在 lidar_config 增加雷达的配置信息，再打开 Rviz 点云显示界面即可正常显示；
+
+![Calibrate_extrinsic](image_ros/calibrate_extrinsic_03.png)
+
+## 4. 打开Rviz显示点云效果
+
+在 "../ws_livox" 文件路径下打开终端，执行以下语句连接当前局域网设备：
+
+`roslaunch livox_ros_driver livox_lidar_rviz.launch`
+
+![Calibrate_extrinsic](image_ros/calibrate_extrinsic_04.png)
+
+![Calibrate_extrinsic](image_ros/calibrate_extrinsic_05.png)

how_to_use_lvx_file_in_ros.md

@@ -0,0 +1,67 @@
+# How to use lvx file in ros
+
+lvx is a point cloud storage format customized by livox; if you want to use lvx file in ros, you need to convert it to rosbag file.
+
+## 1. Save lvx data file
+
+### 1.1 Use livox viewer to store lvx files
+
+The operation steps are as follows :
+
+- Open device manager;
+- Connect device;
+- Play point cloud;
+- Record and save lvx data file;
+
+![Save lvx data by viewer](image_ros/save_lvx_data_by_viewer.png)
+
+### 1.2 Use Livox-SDK to store lvx files
+
+#### 1.2.1 Git clone Livox-SDK
+
+`git clone https://github.com/Livox-SDK/Livox-SDK.git`
+
+#### 1.2.2 Connect Lidar device and save the lvx file
+
+- Open the terminal window under this file path: ../Livox_SDK/build/sample/lidar_lvx_file
+- Execute the follow command:  ./lidar_lvx_sample
+- Connect specify device: -c “Lidar SN”
+- Set the duration of recorded point cloud data: -t 10 (10 second)
+
+![Save lvx data by Livox-SDK 1](image_ros/save_lvx_data_by_SDK_01.png)
+
+![Save lvx data by Livox-SDK 2](image_ros/save_lvx_data_by_SDK_02.png)
+
+![Save lvx data by Livox-SDK 3](image_ros/save_lvx_data_by_SDK_03.png)
+
+## 2. Convert Lvx data file（v1.0/v1.1）to rosbag file（Only supports Ubuntu System)
+
+### 2.1 Git clone livox_ros_driver
+
+`git clone https://github.com/Livox-SDK/livox_ros_driver.git ws_livox/src`
+
+### 2.2 Set publish frequency
+
+If you need to convert rosbag data with the frequency to 10Hz, please set the ‘publish_freq’ parameter to 10.0 in "../ws_livox/src/livox_ros_driver/launch/lvx_to_rosbag.launch file". Similarly, you can set other frequencies.
+
+![Set frequency](image_ros/set_freq.png)
+
+### 2.3 Open a terminal window under this path
+
+`../ws_livox`
+
+### 2.4 Convert lvx point cloud data file (v1.0/v1.1) to rosbag file
+
+livox_ros_driver supports the conversion of lvx pointcloud data files to rosbag files. Use the command as follows :
+
+`roslaunch livox_ros_driver lvx_to_rosbag.launch lvx_file_path:="/home/livox/test.lvx"`
+
+After replacing "/home/livox/test.lvx" in the above command with the local lvx data file path, you can simply run it; if the conversion is successful, a rosbag format file with the same name will be generated under the above path.
+
+![Convert lvx file](image_ros/lvx_to_rosbag_01.png)
+
+![Convert lvx file](image_ros/lvx_to_rosbag_02.png)
+
+### 2.5 Playing the Rosbag data
+
+![Play rosbag file](image_ros/play_rosbag_file_01.png)

set_publish_frequency.md

@@ -0,0 +1,34 @@
+
+# Set publish frequency
+
+## 2.1 Git clone livox_ros_driver
+
+`git clone https://github.com/Livox-SDK/livox_ros_driver.git ws_livox/src`
+
+## 2.2 Set publish frequency
+
+Take the conversion of lvx files to rosbag files as an example :
+
+If you need to convert rosbag data with the frequency to 10Hz, please set the ‘publish_freq’ parameter to 10.0 in "../ws_livox/src/livox_ros_driver/launch/lvx_to_rosbag.launch file". Similarly, you can set other frequencies.
+
+![Set frequency](image_ros/set_freq.png)
+
+## 2.3 Open a terminal window under this path
+
+`../ws_livox`
+
+## 2.4 Convert lvx point cloud data file (v1.0/v1.1) to rosbag file
+
+livox_ros_driver supports the conversion of lvx pointcloud data files to rosbag files. Use the command as follows :
+
+`roslaunch livox_ros_driver lvx_to_rosbag.launch lvx_file_path:="/home/livox/test.lvx"`
+
+After replacing "/home/livox/test.lvx" in the above command with the local lvx data file path, you can simply run it; if the conversion is successful, a rosbag format file with the same name will be generated under the above path.
+
+![Convert lvx file](image_ros/lvx_to_rosbag_01.png)
+
+![Convert lvx file](image_ros/lvx_to_rosbag_02.png)
+
+## 2.5 Playing the Rosbag data
+
+![Play rosbag file](image_ros/play_rosbag_file_01.png)