diff --git a/Livox-SDK-Communication-Protocol.md b/Livox-SDK-Communication-Protocol.md index 3667c88..3f02cd9 100644 --- a/Livox-SDK-Communication-Protocol.md +++ b/Livox-SDK-Communication-Protocol.md @@ -1,12 +1,15 @@ -**Livox SDK Communication Protocol** +**Livox SDK Communication Protocol** -| **Document Release History** | | | -| ---------------------------- | ----------- | --------------------------------- | -| **Date** | **Release** | **Change 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/2/25 | v1.0.1 | Update 3.2 Time Stamp description | -| 2019/1/16 | v1.0.0 | Initial release | +| **Document Release History** | | | +| ---------------------------- | ----------- | ------------------------------------------------------------ | +| **Date** | **Release** | **Change Description** | +| 2019/7/08 | v1.0.6 | 1. Fix crc32 bits error
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+)
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/3/25 | v1.0.2 | Update 3.2 Time Stamp description | +| 2019/2/25 | v1.0.1 | Update 3.2 Time Stamp description | +| 2019/1/16 | v1.0.0 | Initial release | # 1 Summary @@ -50,7 +53,7 @@ follows: | seq_num | 5 | 2 | Frame Sequence Number | | crc_16 | 7 | 2 | Frame Header Checksum | | data | 9 | n | Payload Data | -| crc_32 | 9+n | 2 | Whole Frame Checksum | +| crc_32 | 9+n | 4 | Whole Frame Checksum | Command type description: > - **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. | CMD Set | CMD ID | Function | -|--------------------------|--------|-----------------------------------------------------| +| ------------------------ | ------ | --------------------------------------------------- | | 0x00 General Command Set | 0x00 | Broadcast Message | | | 0x01 | Handshake | | | 0x02 | Query Device Information | @@ -108,6 +111,7 @@ There are three kinds of CMD sets: | | 0x05 | Query LiDAR Device Status | | | 0x06 | Turn On/Off Hub Calculation of Extrinsic Parameters | | | 0x07 | Turn On/Off LiDAR Rain/Fog Suppression | +| | 0x08 | Query Hub Slot Power Status | ## 2.3 SDK Connection @@ -243,7 +247,7 @@ Spherical coordinate format: | reflectivity | 8 | uin8_t | Reflectivity | ## 3.4 Status Code -### 3.4.1 LiDARStatus Code +### 3.4.1 LiDAR Status Code LiDAR status_code consists of 32 bits, which has the following meanings: @@ -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
1: High or Low
2: Extremely High or Extremely Low | | Bit2:3 | volt_status | Voltage Status of Internal Module
0: Voltage in Normal State
1: High
2: Extremely High | -| Bit4:5 | motor_status | 0: Motor in Normal State
1: Motor in Abnormal State, Unable to Work | +| Bit4:5 | motor_status | 0: Motor in Normal State
1: Motor in Warning State
2: Motor in Error State, Unable to Work | | Bit6:7 | dirty_warn | 0: Not Dirty or Blocked
1: Dirty or Blocked | | Bit8 | firmware_status | 0: Firmware is OK
1: Firmware is Abnormal, Need to be Upgraded | | Bit9 | pps_status | 0: No PPS Signal
1: PPS Signal is OK | | Bit10 | device_status | 0: Normal
1: Warning for Approaching the End of Service Life | | Bit11:29 | RSVD | | -| Bit30:31 | system_status | 0: Normal
1: Warning
Any of the following situations will trigger warning:
Temperature becomes High or Low;
Voltage becomes High;
Optical system is Dirty or Blocked;
2: Error
Causes the LiDAR to Shut Down and Enter the Error State
Any of the following situations will trigger error:
Temperature becomes Extremely High or Extremely Low;
Voltage becomes Extremely High;
Motor is Abnormal;
Firmware is Abnormal; | +| Bit30:31 | system_status | 0: Normal
1: Warning
Any of the following situations will trigger warning:
1.1 'temp_status' is 1;
1.2 'volt_status' is 1;
1.3 'motor_status' is 1;
1.4 'dirty_warn' is 1;
1.5 'device_status' is 1;
2: Error
Causes the LiDAR to Shut Down and Enter the Error State.
Any of the following situations will trigger error:
2.1 'temp_status' is 2;
2.2 'volt_status' is 2;
2.3 'motor_status' is 2;
2.4 'firmware_status' is 1; | ### 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
1: LiDAR Connection is Abnormal | | Bit6 | firmware_status | 0: LiDAR Firmware is OK
1: LiDAR Firmware is Abnormal, Need to be Upgraded | | Bit7:29 | RSVD | | -| Bit30:31 | system_status | 0: Normal
1: Warning
Any of the following situations will trigger warning:
Temperature becomes High or Low;
2: Error
Any of the following situations will trigger error:
Temperature becomes Extremely High or Extremely Low;
LiDAR State is Abnormal;
Firmware is Abnormal; | +| Bit30:31 | system_status | 0: Normal
1: Warning
Any of the following situations will trigger warning:
1.1 'temp_status' is 1;
2: Error
Any of the following situations will trigger error:
2.1 'temp_status' is 2;
2.2 'LiDAR_status' is 1;
2.3 'firmware_status' is 1; | # 4 Control Command Detail ## 4.1 General CMD Set @@ -345,18 +349,18 @@ response | | cmd_id | 1 | uint8_t | Command ID: 0x03 | | | ret_code | 2 | uint8_t | Return Code:
0x00: Success
0x01: Fail | | | work_state | 3 | uint8_t | LiDAR State:
0x00: Initializing
0x01: Normal
0x02: Power-Saving
0x03: Standby
0x04: Error
Hub State:
0x00: Initializing
0x01: Normal
0x04: Error | -| | feature_msg | 4 | uint8_t | LiDAR Feature Message:
Bit0: Rain/Fog Suppression Switch
0x00: Turn Off 0x01: Turn On
Bit1 ~ Bit7: Reserved
**Hub is Reserved** | +| | feature_msg | 4 | uint8_t | LiDAR Feature Message:
Bit0: Rain/Fog Suppression Switch
0x00: Turn Off
0x01: Turn On
Bit1 ~ Bit7: Reserved
**Hub is Reserved** | | | ack_msg | 5 | uint32_t | ACK Message:
Related to ‘work_state’:
work_state is 0x00: Initialization Progress
work_state is other: Status Code | ### 0x04 Start/Stop Sampling request -| CMD | Name | Offset (byte) | Data Type | Description | -|------|-------------|---------------|-----------|------------------------------------------| -| data | cmd_set | 0 | uint8_t | General Command: 0x00 | -| | cmd_id | 1 | uint8_t | Command ID: 0x04 | -| | sample_ctrl | 2 | uint8_t | 0x00: Start Sampling
0x01: Stop Sampling | +| CMD | Name | Offset (byte) | Data Type | Description | +| ---- | ----------- | ------------- | --------- | -------------------------------------------- | +| data | cmd_set | 0 | uint8_t | General Command: 0x00 | +| | cmd_id | 1 | uint8_t | Command ID: 0x04 | +| | sample_ctrl | 2 | uint8_t | 0x00: Stop Sampling
0x01: Start Sampling | response @@ -450,7 +454,7 @@ response | | cmd_id | 1 | uint8_t | Command ID: 0x09 | | | ret_code | 2 | uint8_t | Return Code:
0x00: Success
0x01: Fail | | | ip_mode | 3 | uint8_t | 0x00: Dynamic IP
0x01: Static IP | -| | ip_addr | 4 | uint8_t[4] | Device IPV4 Address
Example: AA.BB.CC.DD
user_ip[0] = AA
user_ip[1] = BB
user_ip[2] = CC
user_ip[3] = DD | +| | ip_addr | 4 | uint8_t[4] | Device IPV4 Address
Example: AA.BB.CC.DD
user_ip[0] = AA
user_ip[1] = BB
user_ip[2] = CC
user_ip[3] = DD | ## 4.2 LiDAR CMD Set @@ -458,11 +462,11 @@ response request -| CMD | Name | Offset (byte) | Data Type | Description | -|------|------------|---------------|-----------|---------------------| -| data | cmd_set | 0 | uint8_t | LiDAR Command: 0x01 | -| | cmd_id | 1 | uint8_t | Command ID: 0x00 | -| | LiDAR_mode | 2 | uint8_t | LiDAR Mode:
User can configure as follow:
0x01: Normal Mode
0x02: Power-Saving Mode
0x03: Standby Mode | +| CMD | Name | Offset (byte) | Data Type | Description | +| ---- | ---------- | ------------- | --------- | ------------------------------------------------------------ | +| data | cmd_set | 0 | uint8_t | LiDAR Command: 0x01 | +| | cmd_id | 1 | uint8_t | Command ID: 0x00 | +| | LiDAR_mode | 2 | uint8_t | LiDAR Mode:
User can configure as follow:
0x01: Normal Mode
0x02: Power-Saving Mode
0x03: Standby Mode | response @@ -519,11 +523,11 @@ response ### 0x03 Turn On/Off Rain/Fog Suppression request -| CMD | Name | Offset (byte) | Data Type | Description | -|------|---------|---------------|-----------|----------------------------------------------------------------| -| data | cmd_set | 0 | uint8_t | LiDAR Command: 0x01 | -| | cmd_id | 1 | uint8_t | Command ID: 0x03 | -| | state | 2 | uint8_t | Turn On/Off Rain/Fog Suppression:
0x00: Turn Off
0x01: Turn On | +| CMD | Name | Offset (byte) | Data Type | Description | +| ---- | ------- | ------------- | --------- | ------------------------------------------------------------ | +| data | cmd_set | 0 | uint8_t | LiDAR Command: 0x01 | +| | cmd_id | 1 | uint8_t | Command ID: 0x03 | +| | state | 2 | uint8_t | Turn On/Off Rain/Fog Suppression:
0x00: Turn Off
0x01: Turn On | response @@ -554,13 +558,13 @@ response In ‘info_list’, each LiDAR device information has the following format: -| Field | Offset (byte) | Data Type | Description | -|----------------|---------------|-------------|-----------------------------------------------------| -| broadcast_code | 0 | uint8_t[16] | LiDAR Broadcast Code | -| dev_type | 16 | uint8_t | Device Type:
1: Mid-40
2: Tele-15
3: Horizon | +| Field | Offset (byte) | Data Type | Description | +| -------------- | ------------- | ----------- | ------------------------------------------------------------ | +| broadcast_code | 0 | uint8_t[16] | LiDAR Broadcast Code | +| dev_type | 16 | uint8_t | Device Type:
1: Mid-40
2: Tele-15
3: Horizon | | version | 17 | uint8_t[4] | LiDAR Firmware Version
Example: AA.BB.CC.DD
version[0] = AA
version[1] = BB
version[2] = CC
version[3] = DD | -| slot_id | 21 | uin8_t | Slot Used to Install LiDAR | -| LiDAR_id | 22 | uint8_t | LiDAR ID:
1: Mid-100 Left / Mid-40 / Tele-15 / Horizon
2: Mid-100 Middle
3: Mid-100 Right | +| slot_id | 21 | uin8_t | Slot Used to Install LiDAR | +| LiDAR_id | 22 | uint8_t | LiDAR ID:
1: Mid-100 Left / Mid-40 / Tele-15 / Horizon
2: Mid-100 Middle
3: Mid-100 Right | ### 0x01 Set LiDAR Mode @@ -575,10 +579,10 @@ request In ‘config_list’, each LiDAR mode configuration has the following format: -| Field | Offset (byte) | Data Type | Description | -|----------------|---------------|-------------|------------------------------------| -| broadcast_code | 0 | uint8_t[16] | LiDAR Broadcast Code | -| LiDAR_mode | 16 | uint8_t | LiDAR Mode:
User can configure as follows:
0x01: Normal Mode
0x02: Power-Saving Mode
0x03: Standby Mode | +| Field | Offset (byte) | Data Type | Description | +| -------------- | ------------- | ----------- | ------------------------------------------------------------ | +| broadcast_code | 0 | uint8_t[16] | LiDAR Broadcast Code | +| LiDAR_mode | 16 | uint8_t | LiDAR Mode:
User can configure as follows:
0x01: Normal Mode
0x02: Power-Saving Mode
0x03: Standby Mode | response @@ -601,12 +605,12 @@ In ‘return_list’, each return information has the following format: request -| CMD | Name | Offset (byte) | Data Type | Description | -|------|------------|---------------|-----------|-----------------------------------------------------------| -| data | cmd_set | 0 | uint8_t | Hub Command: 0x02 | -| | cmd_id | 1 | uint8_t | Command ID: 0x02 | -| | slot_id | 2 | uint8_t | Slot id of Hub Range: 1 ~ 9 | -| | power_ctrl | 3 | uint8_t | Power Control (Default 0x00)
0x00: Turn Off
0x01: Turn On | +| CMD | Name | Offset (byte) | Data Type | Description | +| ---- | ---------- | ------------- | --------- | --------------------------------------------------- | +| data | cmd_set | 0 | uint8_t | Hub Command: 0x02 | +| | cmd_id | 1 | uint8_t | Command ID: 0x02 | +| | slot_id | 2 | uint8_t | Slot id of Hub Range: 1 ~ 9 | +| | power_ctrl | 3 | uint8_t | Power Control:
0x00: Turn Off
0x01: Turn On | response @@ -641,20 +645,20 @@ In ‘param_list’, each LiDAR parameter configuration has the following format response -| ACK | Name | Offset (byte) | Data Type | Description | -|------|-------------|---------------|-----------|-----------------------------------------| -| data | cmd_set | 0 | uint8_t | Hub Command: 0x02 | -| | cmd_id | 1 | uint8_t | Command ID: 0x03 | -| | ret_code | 2 | uint8_t | Return Code: 0x00: Success 0x01: Fail | -| | count | 3 | uint8_t | Number of LiDAR to Write Range: 1 ~ 27 | -| | return_list | 4 | -- | Return Information List | +| ACK | Name | Offset (byte) | Data Type | Description | +| ---- | ----------- | ------------- | --------- | --------------------------------------------- | +| data | cmd_set | 0 | uint8_t | Hub Command: 0x02 | +| | cmd_id | 1 | uint8_t | Command ID: 0x03 | +| | ret_code | 2 | uint8_t | Return Code:
0x00: Success
0x01: Fail | +| | count | 3 | uint8_t | Number of LiDAR to Write Range: 1 ~ 27 | +| | return_list | 4 | -- | Return Information List | In ‘return_list’, each return information has the following format: -| Field | Offset (byte) | Data Type | Description | -|----------------|---------------|-------------|---------------------------------------------| -| ret_code | 0 | uint8_t | LiDAR Return Code:
0x00: Success
0x01: Fail | -| broadcast_code | 1 | uint8_t[16] | LiDAR Broadcast Code | +| Field | Offset (byte) | Data Type | Description | +| -------------- | ------------- | ----------- | -------------------------------------------------- | +| ret_code | 0 | uint8_t | LiDAR Return Code:
0x00: Success
0x01: Fail | +| broadcast_code | 1 | uint8_t[16] | LiDAR Broadcast Code | ### 0x04 Read LiDAR Extrinsic Parameters @@ -773,3 +777,21 @@ In ‘return_list’, each return information has the following format: |----------------|---------------|-------------|---------------------------------------------| | ret_code | 0 | uint8_t | LiDAR Return Code:
0x00: Success
0x01: Fail | | 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:
0x00: Success
0x01: Fail | +| | slot_power_state | 3 | uint16_t | Slot Power Status:
0x00: Turn Off
0x01: Turn On
bit0: First Slot
bit1: Second Slot
...
bit8: Ninth Slot | \ No newline at end of file diff --git a/Timestamp-Synchronization.md b/Timestamp-Synchronization.md new file mode 100644 index 0000000..7437356 --- /dev/null +++ b/Timestamp-Synchronization.md @@ -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
2. Pulse Per Second (PPS) | +| Livox Hub | 1. PTP v2
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. \ No newline at end of file diff --git a/images/gps_485.png b/images/gps_485.png new file mode 100644 index 0000000..71adf1d Binary files /dev/null and b/images/gps_485.png differ diff --git a/images/gps_485_1.png b/images/gps_485_1.png new file mode 100644 index 0000000..feea85e Binary files /dev/null and b/images/gps_485_1.png differ diff --git a/images/gps_ttl.png b/images/gps_ttl.png new file mode 100644 index 0000000..b658543 Binary files /dev/null and b/images/gps_ttl.png differ diff --git a/images/gps_ttl_1.png b/images/gps_ttl_1.png new file mode 100644 index 0000000..7469c8f Binary files /dev/null and b/images/gps_ttl_1.png differ