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

feature:add timestamp sync doc

Livox-SDK
2019-07-26 16:04:19 +08:00
parent 0846fc2281
commit 0cc67d5dce
6 changed files with 251 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Livox-SDK-Communication-Protocol.md
+41 -19
@@ -1,8 +1,11 @@
**Livox SDK Communication Protocol** **Livox SDK Communication Protocol**
| **Document Release History** | | | | **Document Release History** | | |
| ---------------------------- | ----------- | --------------------------------- | | ---------------------------- | ----------- | ------------------------------------------------------------ |
| **Date** | **Release** | **Change Description** | | **Date** | **Release** | **Change Description** |
| 2019/7/08 | v1.0.6 | 1. Fix crc32 bits error <br>2. Add system status code description |
| 2019/5/17 | v1.0.5 | Fix partial description errors |
| 2019/4/18 | v1.0.4 | 1. Update motor status code (v03.05.00.00+) <br>2. Add query Hub slot power status command (v08.05.00.00+) |
| 2019/4/17 | v1.0.3 | Update Hub read LiDAR extrinsic parameters description | | 2019/4/17 | v1.0.3 | Update Hub read LiDAR extrinsic parameters description |
| 2019/3/25 | v1.0.2 | Update 3.2 Time Stamp description | | 2019/3/25 | v1.0.2 | Update 3.2 Time Stamp description |
| 2019/2/25 | v1.0.1 | Update 3.2 Time Stamp description | | 2019/2/25 | v1.0.1 | Update 3.2 Time Stamp description |
@@ -50,7 +53,7 @@ follows:
| seq_num | 5 | 2 | Frame Sequence Number | | seq_num | 5 | 2 | Frame Sequence Number |
| crc_16 | 7 | 2 | Frame Header Checksum | | crc_16 | 7 | 2 | Frame Header Checksum |
| data | 9 | n | Payload Data | | data | 9 | n | Payload Data |
| crc_32 | 9+n | 2 | Whole Frame Checksum | | crc_32 | 9+n | 4 | Whole Frame Checksum |
Command type description: Command type description:
> - **CMD (request)**: Actively send data request - need to return a corresponding ACK; > - **CMD (request)**: Actively send data request - need to return a corresponding ACK;
@@ -85,7 +88,7 @@ There are three kinds of CMD sets:
> - **Hub Command Set**: Only Livox Hub supports Hub Command Set. > - **Hub Command Set**: Only Livox Hub supports Hub Command Set.
| CMD Set | CMD ID | Function | | CMD Set | CMD ID | Function |
|--------------------------|--------|-----------------------------------------------------| | ------------------------ | ------ | --------------------------------------------------- |
| 0x00 General Command Set | 0x00 | Broadcast Message | | 0x00 General Command Set | 0x00 | Broadcast Message |
| | 0x01 | Handshake | | | 0x01 | Handshake |
| | 0x02 | Query Device Information | | | 0x02 | Query Device Information |
@@ -108,6 +111,7 @@ There are three kinds of CMD sets:
| | 0x05 | Query LiDAR Device Status | | | 0x05 | Query LiDAR Device Status |
| | 0x06 | Turn On/Off Hub Calculation of Extrinsic Parameters | | | 0x06 | Turn On/Off Hub Calculation of Extrinsic Parameters |
| | 0x07 | Turn On/Off LiDAR Rain/Fog Suppression | | | 0x07 | Turn On/Off LiDAR Rain/Fog Suppression |
| | 0x08 | Query Hub Slot Power Status |
## 2.3 SDK Connection ## 2.3 SDK Connection
@@ -251,13 +255,13 @@ LiDAR status_code consists of 32 bits, which has the following meanings:
|----------|-----------------|----------------------------------------------------------| |----------|-----------------|----------------------------------------------------------|
| Bit0:1 | temp_status | 0: Temperature in Normal State <br>1: High or Low <br>2: Extremely High or Extremely Low | | Bit0:1 | temp_status | 0: Temperature in Normal State <br>1: High or Low <br>2: Extremely High or Extremely Low |
| Bit2:3 | volt_status | Voltage Status of Internal Module<br> 0: Voltage in Normal State <br>1: High <br>2: Extremely High | | Bit2:3 | volt_status | Voltage Status of Internal Module<br> 0: Voltage in Normal State <br>1: High <br>2: Extremely High |
| Bit4:5 | motor_status | 0: Motor in Normal State <br>1: Motor in Abnormal State, Unable to Work | | Bit4:5 | motor_status | 0: Motor in Normal State <br>1: Motor in Warning State <br>2: Motor in Error State, Unable to Work |
| Bit6:7 | dirty_warn | 0: Not Dirty or Blocked <br>1: Dirty or Blocked | | Bit6:7 | dirty_warn | 0: Not Dirty or Blocked <br>1: Dirty or Blocked |
| Bit8 | firmware_status | 0: Firmware is OK <br>1: Firmware is Abnormal, Need to be Upgraded | | Bit8 | firmware_status | 0: Firmware is OK <br>1: Firmware is Abnormal, Need to be Upgraded |
| Bit9 | pps_status | 0: No PPS Signal <br>1: PPS Signal is OK | | Bit9 | pps_status | 0: No PPS Signal <br>1: PPS Signal is OK |
| Bit10 | device_status | 0: Normal <br>1: Warning for Approaching the End of Service Life | | Bit10 | device_status | 0: Normal <br>1: Warning for Approaching the End of Service Life |
| Bit11:29 | RSVD | | | Bit11:29 | RSVD | |
| Bit30:31 | system_status | 0: Normal <br>1: Warning <br>Any of the following situations will trigger warning:<br> Temperature becomes High or Low;<br> Voltage becomes High;<br> Optical system is Dirty or Blocked; <br>2: Error<br> Causes the LiDAR to Shut Down and Enter the Error State<br> Any of the following situations will trigger error:<br> Temperature becomes Extremely High or Extremely Low;<br> Voltage becomes Extremely High;<br> Motor is Abnormal;<br> Firmware is Abnormal; | | Bit30:31 | system_status | 0: Normal <br>1: Warning <br>Any of the following situations will trigger warning: <br> 1.1 'temp_status' is 1;<br> 1.2 'volt_status' is 1;<br> 1.3 'motor_status' is 1;<br> 1.4 'dirty_warn' is 1;<br> 1.5 'device_status' is 1;<br>2: Error <br>Causes the LiDAR to Shut Down and Enter the Error State. <br>Any of the following situations will trigger error: <br> 2.1 'temp_status' is 2;<br> 2.2 'volt_status' is 2;<br> 2.3 'motor_status' is 2;<br> 2.4 'firmware_status' is 1; |
### 3.4.2 Hub Status Code ### 3.4.2 Hub Status Code
@@ -271,7 +275,7 @@ Hub Status Code consists of 32 bits, which has the following meanings:
| Bit5 | LiDAR_link_status | 0: LiDAR Connection is Normal <br>1: LiDAR Connection is Abnormal | | Bit5 | LiDAR_link_status | 0: LiDAR Connection is Normal <br>1: LiDAR Connection is Abnormal |
| Bit6 | firmware_status | 0: LiDAR Firmware is OK <br>1: LiDAR Firmware is Abnormal, Need to be Upgraded | | Bit6 | firmware_status | 0: LiDAR Firmware is OK <br>1: LiDAR Firmware is Abnormal, Need to be Upgraded |
| Bit7:29 | RSVD | | | Bit7:29 | RSVD | |
| Bit30:31 | system_status | 0: Normal <br>1: Warning <br>Any of the following situations will trigger warning:<br> Temperature becomes High or Low; <br>2: Error<br> Any of the following situations will trigger error: <br>Temperature becomes Extremely High or Extremely Low; <br>LiDAR State is Abnormal; <br>Firmware is Abnormal; | | Bit30:31 | system_status | 0: Normal <br>1: Warning <br>Any of the following situations will trigger warning:<br> 1.1 'temp_status' is 1;<br>2: Error <br>Any of the following situations will trigger error: <br> 2.1 'temp_status' is 2;<br> 2.2 'LiDAR_status' is 1;<br> 2.3 'firmware_status' is 1; |
# 4 Control Command Detail # 4 Control Command Detail
## 4.1 General CMD Set ## 4.1 General CMD Set
@@ -345,7 +349,7 @@ response
| | cmd_id | 1 | uint8_t | Command ID: 0x03 | | | cmd_id | 1 | uint8_t | Command ID: 0x03 |
| | ret_code | 2 | uint8_t | Return Code: <br>0x00: Success <br>0x01: Fail | | | ret_code | 2 | uint8_t | Return Code: <br>0x00: Success <br>0x01: Fail |
| | work_state | 3 | uint8_t | LiDAR State: <br>0x00: Initializing <br>0x01: Normal <br>0x02: Power-Saving <br>0x03: Standby <br>0x04: Error <br>Hub State: <br>0x00: Initializing <br>0x01: Normal <br>0x04: Error | | | work_state | 3 | uint8_t | LiDAR State: <br>0x00: Initializing <br>0x01: Normal <br>0x02: Power-Saving <br>0x03: Standby <br>0x04: Error <br>Hub State: <br>0x00: Initializing <br>0x01: Normal <br>0x04: Error |
| | feature_msg | 4 | uint8_t | LiDAR Feature Message:<br> Bit0: Rain/Fog Suppression Switch <br>0x00: Turn Off 0x01: Turn On <br>Bit1 ~ Bit7: Reserved <br>**Hub is Reserved** | | | feature_msg | 4 | uint8_t | LiDAR Feature Message:<br> Bit0: Rain/Fog Suppression Switch <br>0x00: Turn Off <br>0x01: Turn On <br>Bit1 ~ Bit7: Reserved <br>**Hub is Reserved** |
| | ack_msg | 5 | uint32_t | ACK Message:<br> Related to ‘work_state’:<br> work_state is 0x00: Initialization Progress <br>work_state is other: Status Code | | | ack_msg | 5 | uint32_t | ACK Message:<br> Related to ‘work_state’:<br> work_state is 0x00: Initialization Progress <br>work_state is other: Status Code |
### 0x04 Start/Stop Sampling ### 0x04 Start/Stop Sampling
@@ -353,10 +357,10 @@ response
request request
| CMD | Name | Offset (byte) | Data Type | Description | | CMD | Name | Offset (byte) | Data Type | Description |
|------|-------------|---------------|-----------|------------------------------------------| | ---- | ----------- | ------------- | --------- | -------------------------------------------- |
| data | cmd_set | 0 | uint8_t | General Command: 0x00 | | data | cmd_set | 0 | uint8_t | General Command: 0x00 |
| | cmd_id | 1 | uint8_t | Command ID: 0x04 | | | cmd_id | 1 | uint8_t | Command ID: 0x04 |
| | sample_ctrl | 2 | uint8_t | 0x00: Start Sampling <br>0x01: Stop Sampling | | | sample_ctrl | 2 | uint8_t | 0x00: Stop Sampling <br>0x01: Start Sampling |
response response
@@ -459,7 +463,7 @@ response
request request
| CMD | Name | Offset (byte) | Data Type | Description | | CMD | Name | Offset (byte) | Data Type | Description |
|------|------------|---------------|-----------|---------------------| | ---- | ---------- | ------------- | --------- | ------------------------------------------------------------ |
| data | cmd_set | 0 | uint8_t | LiDAR Command: 0x01 | | data | cmd_set | 0 | uint8_t | LiDAR Command: 0x01 |
| | cmd_id | 1 | uint8_t | Command ID: 0x00 | | | cmd_id | 1 | uint8_t | Command ID: 0x00 |
| | LiDAR_mode | 2 | uint8_t | LiDAR Mode:<br>User can configure as follow:<br>0x01: Normal Mode <br>0x02: Power-Saving Mode <br>0x03: Standby Mode | | | LiDAR_mode | 2 | uint8_t | LiDAR Mode:<br>User can configure as follow:<br>0x01: Normal Mode <br>0x02: Power-Saving Mode <br>0x03: Standby Mode |
@@ -520,7 +524,7 @@ response
request request
| CMD | Name | Offset (byte) | Data Type | Description | | CMD | Name | Offset (byte) | Data Type | Description |
|------|---------|---------------|-----------|----------------------------------------------------------------| | ---- | ------- | ------------- | --------- | ------------------------------------------------------------ |
| data | cmd_set | 0 | uint8_t | LiDAR Command: 0x01 | | data | cmd_set | 0 | uint8_t | LiDAR Command: 0x01 |
| | cmd_id | 1 | uint8_t | Command ID: 0x03 | | | cmd_id | 1 | uint8_t | Command ID: 0x03 |
| | state | 2 | uint8_t | Turn On/Off Rain/Fog Suppression:<br>0x00: Turn Off <br>0x01: Turn On | | | state | 2 | uint8_t | Turn On/Off Rain/Fog Suppression:<br>0x00: Turn Off <br>0x01: Turn On |
@@ -555,7 +559,7 @@ response
In ‘info_list’, each LiDAR device information has the following format: In ‘info_list’, each LiDAR device information has the following format:
| Field | Offset (byte) | Data Type | Description | | Field | Offset (byte) | Data Type | Description |
|----------------|---------------|-------------|-----------------------------------------------------| | -------------- | ------------- | ----------- | ------------------------------------------------------------ |
| broadcast_code | 0 | uint8_t[16] | LiDAR Broadcast Code | | broadcast_code | 0 | uint8_t[16] | LiDAR Broadcast Code |
| dev_type | 16 | uint8_t | Device Type:<br> 1: Mid-40 <br>2: Tele-15 <br>3: Horizon | | dev_type | 16 | uint8_t | Device Type:<br> 1: Mid-40 <br>2: Tele-15 <br>3: Horizon |
| version | 17 | uint8_t[4] | LiDAR Firmware Version <br>Example: AA.BB.CC.DD <br>version[0] = AA <br>version[1] = BB <br>version[2] = CC <br>version[3] = DD | | version | 17 | uint8_t[4] | LiDAR Firmware Version <br>Example: AA.BB.CC.DD <br>version[0] = AA <br>version[1] = BB <br>version[2] = CC <br>version[3] = DD |
@@ -576,7 +580,7 @@ request
In ‘config_list’, each LiDAR mode configuration has the following format: In ‘config_list’, each LiDAR mode configuration has the following format:
| Field | Offset (byte) | Data Type | Description | | Field | Offset (byte) | Data Type | Description |
|----------------|---------------|-------------|------------------------------------| | -------------- | ------------- | ----------- | ------------------------------------------------------------ |
| broadcast_code | 0 | uint8_t[16] | LiDAR Broadcast Code | | broadcast_code | 0 | uint8_t[16] | LiDAR Broadcast Code |
| LiDAR_mode | 16 | uint8_t | LiDAR Mode: <br>User can configure as follows:<br>0x01: Normal Mode <br>0x02: Power-Saving Mode <br>0x03: Standby Mode | | LiDAR_mode | 16 | uint8_t | LiDAR Mode: <br>User can configure as follows:<br>0x01: Normal Mode <br>0x02: Power-Saving Mode <br>0x03: Standby Mode |
@@ -602,11 +606,11 @@ In ‘return_list’, each return information has the following format:
request request
| CMD | Name | Offset (byte) | Data Type | Description | | CMD | Name | Offset (byte) | Data Type | Description |
|------|------------|---------------|-----------|-----------------------------------------------------------| | ---- | ---------- | ------------- | --------- | --------------------------------------------------- |
| data | cmd_set | 0 | uint8_t | Hub Command: 0x02 | | data | cmd_set | 0 | uint8_t | Hub Command: 0x02 |
| | cmd_id | 1 | uint8_t | Command ID: 0x02 | | | cmd_id | 1 | uint8_t | Command ID: 0x02 |
| | slot_id | 2 | uint8_t | Slot id of Hub Range: 1 ~ 9 | | | slot_id | 2 | uint8_t | Slot id of Hub Range: 1 ~ 9 |
| | power_ctrl | 3 | uint8_t | Power Control (Default 0x00) <br>0x00: Turn Off <br>0x01: Turn On | | | power_ctrl | 3 | uint8_t | Power Control: <br>0x00: Turn Off <br>0x01: Turn On |
response response
@@ -642,17 +646,17 @@ In ‘param_list’, each LiDAR parameter configuration has the following format
response response
| ACK | Name | Offset (byte) | Data Type | Description | | ACK | Name | Offset (byte) | Data Type | Description |
|------|-------------|---------------|-----------|-----------------------------------------| | ---- | ----------- | ------------- | --------- | --------------------------------------------- |
| data | cmd_set | 0 | uint8_t | Hub Command: 0x02 | | data | cmd_set | 0 | uint8_t | Hub Command: 0x02 |
| | cmd_id | 1 | uint8_t | Command ID: 0x03 | | | cmd_id | 1 | uint8_t | Command ID: 0x03 |
| | ret_code | 2 | uint8_t | Return Code: 0x00: Success 0x01: Fail | | | ret_code | 2 | uint8_t | Return Code: <br>0x00: Success <br>0x01: Fail |
| | count | 3 | uint8_t | Number of LiDAR to Write Range: 1 ~ 27 | | | count | 3 | uint8_t | Number of LiDAR to Write Range: 1 ~ 27 |
| | return_list | 4 | -- | Return Information List | | | return_list | 4 | -- | Return Information List |
In ‘return_list’, each return information has the following format: In ‘return_list’, each return information has the following format:
| Field | Offset (byte) | Data Type | Description | | Field | Offset (byte) | Data Type | Description |
|----------------|---------------|-------------|---------------------------------------------| | -------------- | ------------- | ----------- | -------------------------------------------------- |
| ret_code | 0 | uint8_t | LiDAR Return Code:<br>0x00: Success <br>0x01: Fail | | ret_code | 0 | uint8_t | LiDAR Return Code:<br>0x00: Success <br>0x01: Fail |
| broadcast_code | 1 | uint8_t[16] | LiDAR Broadcast Code | | broadcast_code | 1 | uint8_t[16] | LiDAR Broadcast Code |
@@ -773,3 +777,21 @@ In ‘return_list’, each return information has the following format:
|----------------|---------------|-------------|---------------------------------------------| |----------------|---------------|-------------|---------------------------------------------|
| ret_code | 0 | uint8_t | LiDAR Return Code: <br>0x00: Success <br>0x01: Fail | | ret_code | 0 | uint8_t | LiDAR Return Code: <br>0x00: Success <br>0x01: Fail |
| broadcast_code | 1 | uint8_t[16] | LiDAR Broadcast Code | | broadcast_code | 1 | uint8_t[16] | LiDAR Broadcast Code |
### 0x08 Query Hub Slot Power Status
request
| CMD | Name | Offset (byte) | Data Type | Description |
| ---- | ------- | ------------- | --------- | ----------------- |
| data | cmd_set | 0 | uint8_t | Hub Command: 0x02 |
| | cmd_id | 1 | uint8_t | Command ID: 0x08 |
response
| ACK | Name | Offset (byte) | Data Type | Description |
| ---- | ---------------- | ------------- | --------- | ------------------------------------------------------------ |
| data | cmd_set | 0 | uint8_t | Hub Command: 0x02 |
| | cmd_id | 1 | uint8_t | Command ID: 0x08 |
| | ret_code | 2 | uint8_t | Return Code: <br>0x00: Success <br>0x01: Fail |
| | slot_power_state | 3 | uint16_t | Slot Power Status: <br>0x00: Turn Off <br>0x01: Turn On <br>bit0: First Slot <br>bit1: Second Slot <br>... <br>bit8: Ninth Slot |
Timestamp-Synchronization.md
+171
@@ -0,0 +1,171 @@
**Livox LiDAR Timestamp Synchronization**
| **Document Release History** | | |
| ------------------------------ | ----------- | ---------------------- |
| **Date** | **Release** | **Change Description** |
| 2019/6/19 | v1.0.0 | Initial release |
| | | |
# 1 Summary
| **Device** | **Supported Time Synchronization Method** |
| ----------- | ------------------------------------------- |
| Livox LiDAR | 1. PTP v2<br>2. 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.
### Connection:
Connect Livox LiDAR/Hub normally without additional wiring.
### 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:
Hundreds of nanoseconds
## 2.2 PPS
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;
```
### Connection:
GPS uses 485 level:
![](images/gps_485.png)
GPS uses TTL level:
![](images/gps_ttl.png)
### 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.
### 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
# 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.
images/gps_485.png
BIN
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.9 KiB

images/gps_485_1.png
BIN
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.3 KiB

images/gps_ttl.png
BIN
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.7 KiB

images/gps_ttl_1.png
BIN
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.5 KiB