mmr/Livox-SDK
Archived
1
0
Fork 0
Code Issues 105 Pull Requests 11 Actions Packages Projects Releases 9 Wiki Activity

feat:add new doc

Livox-SDK
2020-10-26 20:15:29 +08:00
parent a0af686859
commit acd0297d38
4 changed files with 1 additions and 575 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Timestamp-Synchronization.md
-232
@@ -1,232 +0,0 @@
**Livox LiDAR Timestamp Synchronization**
| **Document Release History** | | |
| ------------------------------ | ----------- | ------------------------------------ |
| **Date** | **Release** | **Change Description** |
| 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** |
| ----------- | ------------------------------------------------ |
| Livox LiDAR | 1. PTP v2<br>2. GPS<br>3. Pulse Per Second (PPS) |
| Livox Hub | 1. PTP v2<br>2. GPS |
## 1.1 Application Scenarios
### PTP v2:
In the absence of GPS and PPS signals, PTP v2 can be used to synchronize time between Livox LiDAR/Hub and other devices. This method requires minimal external hardware environment and only requires a master clock supporting device in the whole network.
### PPS:
Livox LiDAR supports PPS time synchronization. PPS signal usually comes from GPS receiver. PPS signal generated by other devices such as MCU is also suitable.
### GPS:
Livox Hub supports GPS time synchronization, which is recommended when integrating multiple LiDAR units via Livox Hub. Livox Hub needs the PPS and the time signal in GPRMC format from GPS receiver.
# 2 Usage
## 2.1 PTP v2
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.
### 2.1.1 Connection
Connect Livox LiDAR/Hub normally without additional wiring.
### 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).
### 2.1.3 Accuracy
Hundreds of nanoseconds
## 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.
Here is the pseudocode to achieve this synchronization:
```c
// GPS Time Synchronization
static uint64_t LiDAR_time_last;
static uint64_t LiDAR_time_real;
// 1. Read total second of the UTC time, Unit is second.
uint32_t gps_time_s = get_gps_utc_second();
// 2. Read LiDAR point time, Unit is nanosecond.
uint64_t LiDAR_time = get_LiDAR_pack_time();
// 3. Update real time.
if (LiDAR_time < LiDAR_time_last)
{
//LiDAR time jump indicates the generation of GPS pulse.
LiDAR_time_real = gps_time_s*(1e9) + LiDAR_time%(1000000000);
}
else
{
LiDAR_time_real += LiDAR_time - LiDAR_time_last;
}
//Update history
LiDAR_time_last = LiDAR_time;
```
### 2.3.1 Connection
**Mid:**
![](images/gps_ttl_mid.png)
**Horizon:**
![](images/gps_ttl_horizon.png)
### 2.3.2 Attention
- If the data output by the GPS module is 485 level, TTL to 485 module is not needed.
### 2.3.3 Accuracy
1 microsecond
# 3 Appendix
## 3.1 Set Up PTP Master Clock
Address: [https://github.com/ptpd/ptpd](https://github.com/ptpd/ptpd)
Download, compile and install:
```bash
git clone https://github.com/ptpd/ptpd.git
autoreconf -vi
./configure
make
make install
```
Modify the configuration file client-e2e-socket.conf in the test folder according to your needs. You can use the following configuration:
Add a network interface name, such as eth0:
```
; Network interface to use (required)
ptpengine:interface = eth0
```
Set the master clock function and set the parameters to masteronly:
```
; Options: none slaveonly masteronly masterslave
ptpengine:preset = masteronly
```
Set clock_class to a value lower than 128:
```
; Clock class - announced in master state. Always 255 for slave-only mode.
; Minimum, maximum and default values are controlled by presets.
; If set to 13 (application specific time source), announced
; time scale is always set to ARB. This setting controls the
; states a PTP port can be in. If below 128, port will only
; be in MASTER or PASSIVE states (master only). If above 127,
; port will be in MASTER or SLAVE states.
ptpengine:clock_class = 126
```
Then run the following command:
```bash
ptpd2 -c test/client-e2e-socket.conf
```
When a sync packet appears on the network, it indicates that the master clock of ptpd is successfully turned on.
livox device time synchronization manual.md
-342
@@ -1,342 +0,0 @@
**Livox device time synchronization**([livox设备时间同步说明中文文档](./livox设备时间同步说明.md))
[TOC]
# 1 Time synchronization instructions
Livox devices support 3 time synchronization methods:
PTP: IEEE 1588v2.0 PTP network protocol synchronization;
GPS: Pulse per second + GPRMC time data, forming a GPS time synchronization method;
PPS: Pulse synchronization per second, requires the upper application program to obtain the time information of each pulse through other channels (such as uart) and correct the point cloud time. At present, only LiDAR supports this synchronization method, and because the usage is relatively complicated, it is not recommended for users to use this method for LiDAR time synchronization.
Synchronization methods supported by different devices:
| Devices | Supported synchronization method |
| ----------- | ------------------------------------------- |
| Livox LiDAR | 1. PTP v2<br>2. GPS<br>3. PPS(not recommanded) |
| Livox Hub | 1. PTP v2<br>2. GPS |
## 1.1 Synchronization principle
### 1.1.1 PTP time synchronization principle
The synchronization process uses the Delay request-response mechanism (two steps) of IEEE 1588v2.0 PTP. The Livox device acts as the slave and synchronizes the PTP time with the master clock device.
![](./images_timesync/ptp_1588.png)
The master and slave clocks obtain the t1, t2, t3, and t4 time through the interaction of Sync, Follow_Up, Delay_Req, Delay_Resp these data packets, and the transmission path delay and the offset of the two clocks are calculated as follows:
Transmission path delay: Delay = [(t4 – t1) – (t3 – t2)]/2
Time offset: Offset = (t2 - t1) - Delay = [(t2 – t1) + (t3 – t4)]/2
### 1.1.2 GPS time synchronization principle
The PPS port of the GPS clock source sends a hardware pulse (PPS signal) once per second, and then the data port sends the time information corresponding to the rising edge of this pulse (GPRMC format) once.
After the Livox device receives the rising edge of the PPS signal and parses the correct time information from the GPRMC data, it will set the point cloud time as the GPS time, and keep this time reference for continuous accumulation to achieve time synchronization with the GPS device.
- Livox Hub can directly receive RS485 level GPRMC signal;
- Livox LiDAR cannot directly receive GPRMC signals, it needs to connect the GPRMC data port to the PC, and then send it to the radar through the SDK protocol;
![](./images_timesync/gps_sync.png)
The timing requirements of PPS signal and GPRMC signal:
| Time | Description | Effective Range | Recommended Value |
| ---- | --------------------------------------- | ---------------- | -------------- |
| t0 | Interval between rising edges of adjacent twice second pulse | 900 ms ~ 1100 ms | 1000 ms |
| t1 | High level time of each second pulse | 5 ms ~ 900 ms | 10 ms ~ 200 ms |
| t2 | GGPRMC transmission time (baud rate: 9600bps） | ≈ 70 ms | 70 ms |
| t3 | The delay of GPRMC data transmission relative to the rising edge of the pulse | 0 ms ~ 900 ms | 0 ms ~ 430 ms |
## 1.2 Application scenario
**PTP:**
In the absence of GPS and PPS hardware signals, PTP v2 can be used for time synchronization between Livox LiDAR/Hub and other devices. This method requires minimal external hardware support, and only requires a master clock device in the entire network.
**GPS:**
This synchronization method can be used when Livox Hub is connected to multiple LiDARs. Livox Hub needs to be connected to the PPS signal of the GPS receiver and the time signal in GPRMC format. At this time, the LiDAR point cloud time will be automatically corrected to the GPS time.
Livox LiDAR can also use GPS synchronization, but it needs to connect the GPRMC signal to the PC, and then send the time data to the LiDAR through the SDK protocol.
# 2 Instructions of use
## 2.1 PTP
When Livox LiDAR or Hub is connected to a network with a ptp master clock, the device will automatically synchronize its time to the master clock.
### 2.1.1 Configuration and use
**Step one: Check whether the master clock in the network is normal**
For the method of configuring the master clock on the PC, please refer to the appendix [Configuring the PTP master clock](#Appendix);
If there are datas of Sync and Follow_Up in the network, it means that the PTP master clock source is working normally:
![](./images_timesync/wireshark_ptp.png)
**Step 2: Connect Livox LiDAR/Hub**
Livox LiDAR/Hub can be connected normally through the network cable, no additional wiring is required.
**Step 3: How to check the device is using PTP 1588 synchronization**
1、By checking the timestamp_type data in the point cloud data packet header, the point cloud data protocol: https://github.com/Livox-SDK/Livox-SDK/wiki/Livox-SDK-Communication-Protocol
If timestamp_type is 1, it means that the device is performing PTP time synchronization:
| timestamp_type | data_type | timestamp type |
| -------------- | --------- | ---------- |
| 1 | uint64_t | Nanosecond(ns) |
2、Or check the Settings option in the Livox Viewer host computer, the Sync State in the figure below indicates that the Hub is using ptp 1588 synchronization.
![](./images_timesync/viewer_ptp.png)
### 2.1.2 Precautions
- PTP synchronization has the highest priority. When PTP, PPS or GPS are available at the same time, PTP network synchronization will be selected priority;
- Does not support network environments with multiple master clocks;
- Hundred nanoseconds accuracy;
## 2.2 GPS
In order to be compatible with LiDAR hardware from other manufacturers, Livox devices also support GPS time synchronization.
Since Livox has different types of hardware (LiDAR/Hub), when using GPS synchronization, the hardware interfaces can be divided into 3 categories:
1. Use Livox Hub;
2. LiDAR connected with Livox Converter 1.0 (such as Mid-40, Mid-100);
3. LiDAR connected with Livox Converter 2.0 (such as Tele-15, Horizon);
The following will introduce how to use these three interfaces to synchronize GPS time.
### 2.2.1 Configuration and use
#### 2.2.1.1 Livox Hub
##### Hardware connection
If the GPS module's time signal and PPS signal are both RS485 level, directly connect the line to the GPS time synchronization port (GPS sync port) of Hub.
If the time signal of the GPS module and the PPS signal are both TTL level, the following level conversion is required before the signal can be connected to the GPS time synchronization port of Hub (GPS sync port).
![](images/gps_ttl_hub.png)
Remarks：
When the Hub uses GPS synchronization, there is no need to configure the SDK software.
#### 2.2.1.2 Livox Converter 1.0
Currently, the default devices using Livox Converter 1.0 include:
1. Mid-40
2. Mid-100
##### Hardware connection
Connect the GPS module's time signal (GPRMC) to the PC through the TTL-to-usb module, and connect the PPS signal to the Sync Port of the LiDAR adapter box.
![](images/gps_ttl_mid.png)
If the PPS output by the GPS module is an RS485 level signal, the TTL to 485 module can be omitted in the above figure.
##### Software configuration
Since the PC needs to receive the GPRMC data and then send it to LiDAR through the SDK protocol, the product firmware version has the following requirements:
- Mid firmware version: >= **v03.07.0000**
- SDK version >= **v2.1.0**
**When using ROS driver**
1. Connect the hardware correctly according to the above introduction;
2. Check the port name of the usb module connected to the PC, such as `/dev/ttyUSB0`，add to the "device_name" of the "timesync_config" 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 then configure "enable_timesync" to 'true'，the baud rate "baudrate_index" can be set to specific value referring to https://github.com/Livox-SDK/livox_ros_driver ;
```
"timesync_config": {
"enable_timesync": true,
"device_name": "/dev/ttyUSB0",
"comm_device_type": 0,
"baudrate_index": 2,
"parity_index": 0
```
3. Run launch file；
**When using SDK only**
The following link is a program for receiving and analyzing GPRMC data and sending it to LiDAR through the SDK protocol:
[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.1.3 Livox Converter 2.0
Currently, the standard equipments using Livox Converter 2.0 in the box include:
1. Horizon
2. Tele-15
##### Hardware connection
Connect the GPS module's time signal (GPRMC) to the PC through the TTL-to-usb module, and connect the PPS signal to the Sync Port of the LiDAR adapter box.
![](images/gps_ttl_horizon.png)
##### Software configuration
Since the PC needs to receive the GPRMC data and then send it to LiDAR through the SDK protocol, the product firmware version has the following requirements:
- Horizon firmware version: >= **v06.06.0000**
- Tele-15 firmware version: >= **v07.09.0000**
- SDK version >= **v2.1.0**
**When using ROS driver**
1. Connect the hardware correctly according to the above introductions;
2. Check the port name of the usb module connected to the PC, such as `/dev/ttyUSB0`, add to the "device_name" of "timesync_config" 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 then set "enable_timesync" to 'true'，baud rate "baudrate_index" can be set to specific value referring to https://github.com/Livox-SDK/livox_ros_driver ;
```
"timesync_config": {
"enable_timesync": true,
"device_name": "/dev/ttyUSB0",
"comm_device_type": 0,
"baudrate_index": 2,
"parity_index": 0
```
3. Run launch file；
**Using SDK only**
The following link is a program for receiving and analyzing GPRMC data and sending it to LiDAR through the SDK protocol:
[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 Status check
1. By viewing the timestamp_type data in the point cloud data packet header, the point cloud data protocol: https://github.com/Livox-SDK/Livox-SDK/wiki/Livox-SDK-Communication-Protocol
If timestamp_type is 3, it means that the device is in GPS time synchronization:
| timestamp_type | data_type | time type |
| -------------- | -------------- | ----------- |
| 3 | UTC（8 Bytes） | UTC time format |
UTC time format:
![](./images_timesync/utc_time.png)
2. Or in the Livox Viewer host computer, check the Settings option, the Sync State in the figure below indicates that the Hub is using GPS synchronization.
![](./images_timesync/viewer_gps.png)
### 2.2.3 Precautions
- Normally, the GPS module can output the PPS signal and time signal normally after receiving the GPS signal. When in use, you need to ensure that the GPS signal is stable;
- Currently the time signal only supports the two formats: GPRMC and GNRMC;
- 1 us level accuracy
## 2.3 PPS
**Due to the complexity of this usage, users are not recommended to use this synchronization method**
Every time Livox LiDAR receives the rising edge of the PPS signal, it will set the point cloud time at the current moment to 0, and then restart timing until the next PPS pulse arrives. We can use this feature to realize the synchronization of the PPS pulse to the LiDAR time.
The following is the pseudo code to implement this process:
```c
// PPS Time Synchronization
static uint64_t lidar_time_last;
static uint64_t lidar_time_real;
// 1. Read the PPS rising edge time, Unit is nanosecond.
uint64_t pps_time_ns = get_pps_rising_nsecond();
// 2. Read LiDAR point time, Unit is nanosecond.
uint64_t lidar_time = get_lidar_pack_time();
// 3. Update real time.
if (lidar_time < lidar_time_last)
{
//LiDAR time jump indicates the generation of PPS rising edge.
lidar_time_real = pps_time_ns + lidar_time%(1000000000);
}
else
{
lidar_time_real += lidar_time - lidar_time_last;
}
//Update history
lidar_time_last = lidar_time;
```
Remarks:
Users need to obtain the time information of the rising edge of the PPS through other methods, corresponding to the get_pps_rising_nsecond() interface in the above code.
# Appendix
## Configure PTP master clock
Address: [http://linuxptp.sourceforge.net](http://linuxptp.sourceforge.net)
Download, compile and install:
```bash
git clone http://git.code.sf.net/p/linuxptp/code linuxptp
cd linuxptp
make
sudo make install
```
If you want ptp4l to work normally, you need the system's Linux kernel version 3.0 or later. Use the following command to check whether the network card supports the software/hardware timestamp function (for example: query the status of the network card'eth0').
```bash
ethtool -T eth0
```
In the example below, it shows that the eth0 network card supports hardware time stamping.
![](./images_timesync/support.png)
In the example below, the wlan0 network card does not support hardware and software timestamps, linuxptp/ptp4l cannot work normally.
![](./images_timesync/not_support.png)
Run the following command to enable the master clock function of ptp4l:
```bash
sudo ptp4l -i eth0 -l 6 -m
```
If the `Sync Message` data appears in the network, it means that the master clock function of the ptp4l program is operating normally:
![](./images_timesync/wireshark_ptp.png)
You can also use the following command to make sure that PTP hardware clock is synchronized to system clock:
For more details of the usage, please refer to the [phc2sys link](http://manpages.ubuntu.com/manpages/cosmic/man8/phc2sys.8.html)
```bash
sudo phc2sys -c eth0 -s CLOCK_REALTIME -O 0
```
After completing the above steps, the LiDAR time and the PC system time can be synchronized through ptp4l.
livox设备时间同步说明.md → livox-device-time-synchronization-manual-cn.md
livox-device-time-synchronization-manual.md
+1 -1
@@ -1,6 +1,6 @@
**Livox device time synchronization**([livox设备时间同步说明中文文档](https://github.com/Livox-SDK/Livox-SDK/wiki/livox设备时间同步说明))
**Livox device time synchronization**([livox设备时间同步说明中文文档](https://github.com/Livox-SDK/Livox-SDK/wiki/livox-device-time-synchronization-manual-cn))