Livox SDK API  V2.1.0
README.md
Go to the documentation of this file.
1 # 1 Introduction
2 
3 Livox SDK is the software development kit designed for all Livox products. It is developed based on C/C++ following Livox SDK Communication Protocol, and provides easy-to-use C style API. With Livox SDK, users can quickly connect to Livox products and receive point cloud data.
4 
5 Livox SDK consists of Livox SDK communication protocol, Livox SDK core, Livox SDK API, Linux sample, and ROS demo.
6 
7 ## Prerequisites
8 * Ubuntu 14.04/Ubuntu 16.04/Ubuntu 18.04, both x86 and ARM (Nvidia TX2)
9 * Windows 7/10, Visual Studio 2015/2017
10 * C++11 compiler
11 
12 # 2 Livox SDK Communication Protocol
13 
14 Livox SDK communication protocol opens to all users. It is the communication protocol between user programs and Livox products. The protocol consists of control commands and data format. Please refer to the [Livox SDK Communication Protocol](<https://github.com/Livox-SDK/Livox-SDK/wiki/Livox-SDK-Communication-Protocol>) for detailed information.
15 
16 # 3 Livox SDK Core
17 
18 Livox SDK provides the implementation of control commands and point cloud data transmission, as well as the C/C++ API. The basic structure of Livox SDK core is shown as below:
19 
20 ![Livox SDK Architecture](doc/images/sdk.png)
21 
22 User Datagram Protocol (UDP) is used for communication between Livox SDK and LiDAR sensors. Please refer to the Livox SDK Communication Protocol for further information. Point cloud data handler supports point cloud data transmission, while command handler receives and sends control commands. And the C/C++ API is based on command handler and point cloud data handler.
23 
24 The Livox LiDAR sensors can be connected to host directly or through the Livox Hub. Livox SDK supports both connection methods. When LiDAR units are connected to host directly, the host will establish communication with each LiDAR unit individually. And if the LiDAR units connect to host through Hub, then the host only communicates with the Livox Hub while the Hub communicates with each LiDAR unit.
25 
26 # 4 Livox SDK API
27 
28 Livox SDK API provides a set of C style functions which can be conveniently integrated in C/C++ programs. Please refer to the [Livox SDK API Reference](https://livox-sdk.github.io/Livox-SDK/) for further information.
29 
30 ## 4.1 Installation
31 The installation procedures in Ubuntu 18.04/16.04/14.04 LTS and Windows 7/10 are shown here as examples. For Ubuntu 18.04/16.04/14.04 32-bit LTS and Mac, you can get it in [Livox-SDK wiki](https://github.com/Livox-SDK/Livox-SDK/wiki).
32 ### 4.1.1 Ubuntu 18.04/16.04/14.04 LTS
33 #### Dependencies
34 Livox SDK requires [CMake 3.0.0+](https://cmake.org/) as dependencies. You can install these packages using apt:
35 ```
36 sudo apt install cmake pkg-config
37 ```
38 #### Compile Livox SDK
39 
40 In the Livox SDK directory, run the following commands to compile the project:
41 ```
42 git clone https://github.com/Livox-SDK/Livox-SDK.git
43 cd Livox-SDK
44 sudo ./third_party/apr/apr_build.sh
45 cd build && cmake ..
46 make
47 sudo make install
48 ```
49 ### 4.1.2 Windows 7/10
50 #### Dependencies
51 Livox SDK supports Visual Studio 2015/2017 and requires install [CMake 3.0.0+](https://cmake.org/) as dependencies.
52 
53 In the Livox SDK directory, run the following commands to create the Visual Studio solution file.
54 Generate the 32-bit project:
55 
56 ```
57 .\third_party\apr\apr_build.bat
58 cd build && \
59 cmake ..
60 ```
61 Generate the 64-bit project:
62 ```
63 cd Livox-SDK
64 .\third_party\apr\apr_build.bat amd64
65 cd build && \
66 cmake .. -G "Visual Studio 15 2017 Win64"
67 ```
68 #### Compile Livox SDK
69 You can now compile the Livox SDK in Visual Studio.
70 
71 ### 4.1.3 ARM-Linux Cross Compile
72 
73 The procedure of cross compile Livox-SDK in ARM-Linux are shown below。
74 
75 #### Dependencies
76 
77 Host machine requires install cmake and gcc。You can install these packages using apt:
78 
79 ```
80 sudo apt install cmake gcc
81 ```
82 
83 #### Cross Compile Toolchain
84 
85 If your ARM board vendor provides a cross compile toolchain, you can skip the following step of installing the toolchain and use the vendor-supplied cross compile toolchain instead.
86 
87 The following commands will install C and C++ cross compiler toolchains for 32bit and 64bit ARM board. You need to install the correct toolchain for your ARM board. For 64bit SoC ARM board, only install 64bit toolchain, and for 32bit SoC ARM board, only install 32bit toolchain.
88 
89 Install **ARM 32 bits cross compile toolchain**：
90 
91 ```
92  sudo apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi
93 ```
94 
95 Install **ARM 64 bits cross compile toolchain**：
96 
97 ```
98 sudo apt-get install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
99 ```
100 
101 #### Cross Compile Livox-SDK
102 
103 For **ARM 32 bits toolchain**，In the Livox SDK directory，run the following commands to cross compile the project:
104 
105 ```
106 cd Livox-SDK
107 cd build && \
108 cmake .. -DCMAKE_SYSTEM_NAME=Linux -DCMAKE_C_COMPILER=arm-linux-gnueabi-gcc -DCMAKE_CXX_COMPILER=arm-linux-gnueabi-g++
109 make
110 ```
111 
112 For **ARM 64 bits toolchain**，In the Livox SDK directory，run the following commands to cross compile the project:
113 
114 ```
115 cd Livox-SDK
116 cd build && \
117 cmake .. -DCMAKE_SYSTEM_NAME=Linux -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc -DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++
118 make
119 ```
120 
121 **Note:**
122 
123 - gcc cross compiler need to support C ++11 standard
124 
125 ## 4.2 Run Livox SDK Sample
126 Two samples are provided in Sample/Lidar and Sample/Hub, which demonstrate how to configure Livox LiDAR units and receive the point cloud data when directly connecting Livox SDK to LiDAR units or by using a Livox Hub, respectively. The sequence diagram is shown as below:
127 
128 ![](doc/images/sample.png)
129 
130 ### 4.2.1 Ubuntu 18.04/16.04 /14.04 LTS
131 For Ubuntun 18.04/16.04/14.04 LTS, run the *lidar_sample* if connect with the LiDAR unit(s):
132 ```
133 cd sample/lidar && ./lidar_sample
134 ```
135 or run the *hub_sample* if connect with the hub unit(s):
136 ```
137 cd sample/hub && ./hub_sample
138 ```
139 ### 4.2.2 Windows 7/10
140 After compiling the Livox SDK as shown in section 4.1.2, you can find `hub_sample.exe` or `lidar_sample.exe` in the {Livox-SDK}\build\sample\hub\Debug or {Livox-SDK}\build\sample\lidar\Debug folder, respectively, which can be run directly.
141 
142 Then you can see the information as below:
143 
144 ![](doc/images/sdk_init.png)
145 
146 ### 4.3 Connect to the specific LiDAR units
147 
148 Samples we provided will connect all the broadcast device in you LAN in default.There are two ways to connect the specific units:
149 
150 * run sample with input options
151 
152 * edit the Broadcast Code list in source code
153 
154 **NOTE:**
155 
156 Each Livox LiDAR unit owns a unique Broadcast Code . The broadcast code consists of its serial number and an additional number (1,2, or 3). The serial number can be found on the body of the LiDAR unit (below the QR code).The Broadcast Code may be used when you want to connect to the specific LiDAR unit(s). The detailed format is shown as below:
157 
158 ![Broadcast Code](doc/images/broadcast_code.png)
159 
160 #### 4.3.1 Program Options
161 
162 We provide the following program options for connecting the specific units and saving log file:
163 ```
164 [-c]:Register LiDAR units by Broadcast Code. Connect the registered units ONLY.
165 [-l]:Save the log file(In the executable file's directory).
166 [-h]:Show help.
167 ```
168 Here is the example:
169 ```
170 ./lidar_sample -c "00000000000002&00000000000003&00000000000004" -l
171 ./hub_sample -c "00000000000001" -l
172 ```
173 
174 #### 4.3.2 Edit Broadcast Code List
175 
176  Comment the following code section:
177 
178 ```
179 /** Connect all the broadcast device. */
180 int lidar_count = 0;
181 char broadcast_code_list[kMaxLidarCount][kBroadcastCodeSize];
182 ```
183 
184 Remove the comment of the following code section, set the BROADCAST_CODE_LIST_SIZE and replace the broadcast code lists in the `main.c` for both LiDAR sample ({Livox-SDK}/sample/lidar/main.c) and Hub sample ({Livox-SDK}/sample/hub/main.c) with the broadcast code of your devices before building.
185 
186 ```
187 /** Connect the broadcast device in list, please input the broadcast code and modify the BROADCAST_CODE_LIST_SIZE. */
188 /*#define BROADCAST_CODE_LIST_SIZE 3
189 int lidar_count = BROADCAST_CODE_LIST_SIZE;
190 char broadcast_code_list[kMaxLidarCount][kBroadcastCodeSize] = {
191  "000000000000002",
192  "000000000000003",
193  "000000000000004"
194 };*/
195 ```
196 
197 ### 4.4 Generate the lvx file
198 
199 We provide the C++ sample to generate the lvx file for hub and LiDAR unit(s). You can use the same way in `4.2.1` and `4.2.2` to run them.
200 
201 #### 4.4.1 Program Options
202 
203 You can alse use the program options in `4.3.1` to connect specific device and generate the log file, and we provide two new options for lvx file:
204 ```
205 [-t] Time to save point cloud to the lvx file.(unit: s)
206 [-p] Get the extrinsic parameter from standard extrinsic.xml file(The same as viewer) in the executable file's directory.(Especially for LiDAR unit(s) as the hub will calculate the extrinsic parameter by itself)
207 ```
208 Here is the example:
209 ```
210 ./lidar_lvx_sample -c "00000000000002&00000000000003&00000000000004" -l -t 10 -p
211 ./hub_lvx_sample -c "00000000000001" -l -t 10
212 ```
213 
214 # 5 Support
215 
216 You can get support from Livox with the following methods:
217 * Send email to dev@livoxtech.com with a clear description of your problem and your setup
218 * Github Issues