Skip to content

Sensor SDK User Guide for Ubuntu

Jump to bottom Edit New page
Bethany edited this page Oct 23, 2020 · 8 revisions

Sensor SDK User Guide for Ubuntu

1. Getting Started

Quanergy’s software development kit (SDK) helps developers integrate the Quanergy LiDAR sensor into their computing environment. It has been tested on Ubuntu, Windows, and DrivePX. This user guide explains specifically how to achieve an Ubuntu computing environment that is suitable for visualizing data collected by Quanergy’s LiDAR sensor as enabled by the SDK.

Open-source Ubuntu is the operating system of choice for Quanergy products, and the host computer may run Ubuntu natively or virtually. Options for running Ubuntu virtually using either a Mac or non-Mac (“PC”) machine are described in this document.

Required Functionality

For complete functionality, the Quanergy software requires the Mac or PC host computer to have:

  • x86-64 architecture.
  • Ubuntu 14.04.5 LTS or 16.04 LTS operating system running either natively or virtually via VMware Fusion, VMware Workstation, or Oracle VirtualBox.

Although Quanergy fully supports only Ubuntu, the LiDAR sensor is also compatible with any operating system that is capable of initiating a TCP connection with the sensor. In particular, the Windows 7 operating system can be a suitable environment when running the SDK provided by Quanergy. This setup is explained in the Sensor SDK User Guide for Windows. With such a non-Ubuntu environment, users can visualize a basic point cloud, but cannot immediately manipulate it beyond rotating and zooming. However, to manipulate the data in more significant ways, users are welcome to write their own software solutions.

Required Documents

The latest versions of essential Quanergy user guides are downloadable through these links:

Other materials such as data sheets and other user guides are available through:

Conventions

In this user guide, we use the following conventions:

  • PC means “personal computer,” and the term is used here to refer to any non-Mac computer that has the required functionality as described above.

  • To communicate properly within a network, devices must share a single network address, which could be 192.168.0.x or 10.0.0.x or other. We use the 10.0.0.x example in this user guide, but you can substitute the network address you prefer.

2. Accessing the SDK Build Instructions

Depending on how you acquired your sensor, you may need to purchase and/or request access to the SDK source code using the following process:

  1. Email your GitHub username to your support representative with the subject line Request GitHub SDK Access. While you await a response, continue to the next section.

  2. After the details of your request are confirmed, and you have been given permission by email to access the SDK, refer to Figure 1 while you:

  • Log in to your account at https://github.com.
  • Navigate to https://github.com/QuanergySystems, where SDK clients are listed.
  • Accept the invitation to join QuanergySystems by clicking the View invitation button.
  • Click the Join QuanergySystems button in the confirmation window that appeared.
  • View a confirmation of your acceptance and the populated website.
  1. Select the quanergy_client item, as shown in Figure 1.

Figure 1. GitHub Quanergy Systems Private Repository

On the resulting QuanergySystems/quanergy_client page (Figure 2), you can see an upper list of sample source code packages and a lower list of OS-specific links to Build Instructions:

  • Click through to the instructions for Ubuntu14.04 LTS or Ubuntu16.04 LTS, which are associated with the latest release.

If you prefer other releases or recent pre-releases:

  • Click the releases heading to see notes for each release
  • Click the branches drop-down menu to access a specific release listed there.

Before you actually deploy the SDK, you need to set up your host computer and the computing environment, as instructed in the next few sections of this user guide.

Figure 2. GitHub quanergy_client Source Code

3. Setting Up the Network Port

Depending on whether your computing environment is a Mac or a PC, you will select the appropriate network port setup instructions. You may run the LiDAR sensor on either platform through one of the following virtual machines (VMs):

  • VMware Fusion (Mac) or VMware Workstation (PC) : well-tested, well-functioning, and well-supported applications.

  • Oracle VirtualBox (Mac or PC) : free application has not been rigorously tested with the LIDAR sensor, but we include basic instructions as a courtesy to users who are curious about it.

Both methods are provided here, but Quanergy highly recommends using VMware Fusion if a virtual machine is necessary.

There are many factors involved in enabling the sensor’s Ethernet connection on a MacBook or a PC using a VM, so the procedures in this section are a general guide, where you can implement your own preferred workarounds. Contact your support representative if you need additional help.

For MacBook Port Via VMware Fusion

This section is for users who are setting up a network port in an Ubuntu virtual environment on a MacBook, using the recommended VMware Fusion application.

  1. Start the 64-bit Ubuntu virtual machine, which you previously defined through VMware Fusion.

  2. The VMware Fusion window looks different depending on whether a single VM or multiple VMs are defined:

  • If a single VM is defined (such as SDK Only in the Figure 3 example), click the Settings button to set up a network adapter.

  • If multiple VMs are defined (Figure 4), the left side of the Virtual Machine Library window lists them. For the VM you prefer to use, control-click its name (such as Security Demo in this example), and from the drop-down menu that appears, select the Settings item.

Figure 3. Mac VMware Fusion with Single VM Defined

Figure 4. Mac VMware Fusion with Multiple VMs Defined

  1. In the ...Settings dialog box that appears, click the Add Device button (Figure 5).

Figure 5. Mac VMware Fusion ...Settings Dialog Box

  1. In the ...Add Device dialog box that appears, select the Network Adapter icon, then click the Add button (Figure 6).

Figure 6. Mac VMware Fusion ...Add Device Dialog Box

  1. In the Network Adapter # dialog box that appears (Figure 7, where # indicates how many network adapters have been added previously):
  • Select the Thunderbolt Ethernet item.
  • Click the System Preferences button.

Figure 7. Mac VMware Fusion Network Adapter # Dialog Box

  1. In the System Preferences > Network dialog box (Figure 8), select the Thunderbolt Ethernet item to highlight it in the left column, then fill out the related fields, as follows:

  • Set the Configure IPv4 field to Using DHCP with manual address. This option allows the computer’s WiFi to still connect while in VM mode.

  • Specify the IP Address field of the MacBook, where the network address is 10.0.0, and the host address is any number from 2-254 that does not conflict.

  • Specify the Subnet Mask to be 255.255.255.0.

  • Specify the Router on the Thunderbolt Ethernet port to be 10.0.0.1.

  • To distinguish this Thunderbolt Ethernet port from others, you can rename it and make other changes through the Settings menu.

  • Click the Apply button in the lower right corner. After a few seconds, the red button next to the Thunderbolt Ethernet item turns green if the sensor is plugged in and powered on.

Figure 8. Mac Host Computer System Preferences > Network Dialog Box

  1. Click the close button to dismiss the Network dialog box.

  2. Continue with the “Setting Up the DHCP Server” section on page 24.

For MacBook Port Via Oracle VirtualBox

This section is for users who are setting up a network port in an Ubuntu virtual environment on a MacBook, using the Oracle VirtualBox application.

NOTE: The use of Oracle VirtualBox is not recommended. However, we provide it here as a courtesy.

  1. Start the 64-bit Ubuntu virtual machine, which you previously defined through Oracle VirtualBox .

  2. In the VirtualBox Manager window, select the name of one of the VMs that is listed in the right column (such as Ubuntu in the Figure 9 example).

  3. From the drop-down menu that appears, select the Settings item.

Figure 9. Mac VirtualBox Manager Window

  1. In the ubuntu – General dialog box that appears, select the Network tab (Figure 10).

Figure 10. Mac VirtualBox ubuntu – General Dialog Box

  1. In the ubuntu – Network dialog box (Figure 11):

  • Of the four pre-defined adapters, select whichever is associated with the port your sensor is connected to, which is Adapter 2 in this figure.

  • Check the Enable Network Adapter checkbox.

  • From the Attached to drop-down menu, select the Bridged Adapter item.

  • From the Name drop-down menu, select en1: Thunderbolt 1.

  • Click the OK button to apply the changes and close the ubuntu – Network dialog box.

Figure 11. Mac VirtualBox ubuntu – Network Dialog Box

  1. Open the System Preferences > Network dialog box (Figure 12) as follows:

  • From the top-left corner of the MacBook screen, select the Apple icon.

  • From the drop-down menu, select the System Preferences item.

  • In the System Preferences dialog box that appears, select the Network tab.

Figure 12. Mac Host Computer System Preferences Window

  1. In the System Preferences > Network dialog box (Figure 8), select the Thunderbolt Ethernet item to highlight it in the left column, then fill out the related fields, as follows:

  • Set the Configure IPv4 field to Using DHCP with manual address. This option allows the computer’s WiFi to still connect while in VM mode.

  • Specify the IP Address field of the MacBook, where the network address is 10.0.0, and the host address is any number from 2-254 that does not conflict.

  • Specify the Subnet Mask to be 255.255.255.0.

  • Specify the Router on the Thunderbolt Ethernet port to be 10.0.0.1.

  • To distinguish this Thunderbolt Ethernet port from others, you can rename it and make other changes through the Settings menu.

  • Click the Apply button in the lower right corner. After a few seconds, the red button next to the Thunderbolt Ethernet item turns green if the sensor is plugged in and powered on.

  1. Click the close button to dismiss the Network dialog box.

  2. Continue with the “Setting Up the DHCP Server” section on page 24.

For PC Port Via VMware Workstation

This section is for users who are setting up a network port in an Ubuntu virtual environment on a PC, using the recommended VMware Workstation application.

  1. Start the VMware Workstation application (Figure 13). The 64-bit Ubuntu virtual machines that you previously defined through this application are listed in the VMware Workstation window’s Library bar.

  2. From the Library bar, select the name of the VM you prefer to use, such as Ubuntu 64-bit, as shown in the example. The Ubuntu 64-bit tab appears, listing the specifications of the Devices associated with this VM.

  3. From the menu bar, select the Edit virtual machine settings item.

Figure 13. PC VMware Workstation with VMs Defined

  1. In the Virtual Machine Settings pop-up window that appears (Figure 14):

  • In the Hardware tab, the Memory item is already selected by default.

  • In the Hardware tab’s Device list, the default Network Adapter item is a NAT connection, which is necessary for WiFi.

  • In addition to the WiFi connection, you’ll need a second Network Adapter that is Bridged to allow for a direct connection to the physical network, so click the Add... button.

Figure 14. PC VMware Workstation Virtual Machine Settings Pop-Up Window

  1. The Add Hardware Wizard window appears (Figure 15) with a list of hardware types:
  • The Hard Disk item is already selected by default.
  • From the Hardware types list, select the Network Adapter item.
  • Click the Next button to display the Network Adapter Type list).

  1. From the Network connection options, click the Bridged radio button, then check its Replicate... checkbox.

  2. Click the Finish button to close the Add Hardware Wizard window.

  3. Click the OK button in the Virtual Machine Settings window to apply the changes.

Figure 15. PC VMware Workstation Add Hardware Wizard

  1. If you are connecting your sensor directly to the computer (rather than through a router), continue with the next few steps, referring to a visual overview in Figure 16.

  2. On your PC host computer, open the Control Panel, select the Network and Internet item, then select the Network Connection item.

  3. In the Network Connections window, select the Local Area Connection tab.

  4. In the Local Area Connection Properties dialog box, select the Networking tab, and click the Configure button.

  5. Use the Internet Protocol Version 4 (TCP/IPv4) Properties dialog box to make sure the sensor and the host computer are on the same LAN:

  • Select the Use the following IP address radio button.

  • In the IP address field, type an IP address, where the network address is 10.0.0, and the host address is any number from 2-254 that does not conflict.

  • In the Subnet mask field, type the subnet that both computer and sensor are on.

  • In the Default gateway field, the first three values must match those of the IP address field (10.0.0), and the last value is a 1.

  • Select the OK button to apply the changes and close the dialog box.

  1. In the Local Area Connection Properties dialog box, select the OK button to close the box.

Figure 16. PC Host Computer Setting Subnet Mask and Gateway

  1. Continue with the “Setting Up the DHCP Server” section on page 24.

For PC Port Via Oracle VirtualBox

This section is for users who are setting up a network port in an Ubuntu virtual environment on a PC, using the Oracle VirtualBox application.

NOTE: The use of Oracle VirtualBox is not recommended. However, we provide it here as a courtesy.

  1. Start the 64-bit Ubuntu virtual machine, which you previously defined through Oracle VirtualBox .

  2. In the VirtualBox Manager window, select the name of one of the VMs that is listed in the right column (such as Ubuntu in the Figure 17 example).

  3. From the drop-down menu that appears, select the Settings item.

Figure 17. PC VirtualBox Manager Window

  1. In the ubuntu – Settings > General dialog box that appears, select the left-hand navigation bar’s Network tab, as shown in Figure 18.

Figure 18. Mac VirtualBox ubuntu – Settings > General Dialog Box

  1. In the ubuntu – Settings > Network dialog box (Figure 19):

  • Of the four pre-defined adapters, select whichever is associated with the port your sensor is connected to, which is Adapter 1 in this figure.

  • Check the Enable Network Adapter checkbox.

  • From the Attached to drop-down menu, select the Bridged Adapter item.

  • From the Name drop-down menu, select Broadcom 802.11ac Network Adapter.

  • Click the OK button to apply the changes and close the ubuntu – Settings dialog box.

Figure 19. PC VirtualBox ubuntu – Settings > Network Dialog Box

  1. On your PC host computer, open the Control Panel, and select the Network and Internet item, then the Network Connection item. Refer to Figure 16 for a visual example of the procedure described in the remaining steps.

  2. In the Network Connections window, select the Local Area Connection tab.

  3. In the Local Area Connection Properties dialog box, select the Networking tab, and click the Configure button.

  4. Use the Internet Protocol Version 4 (TCP/IPv4) Properties dialog box to make sure the sensor and the host computer are on the same LAN:

  • Select the Use the following IP address radio button.

  • In the IP address field, type an IP address, where the network address is 10.0.0, and the host address is any number from 2-254 that does not conflict.

  • In the Subnet mask field, type the subnet that both computer and sensor are on.

  • In the Default gateway field, the first three values must match those of the IP address field (10.0.0), and the last value is a 1.

  • Select the OK button to apply the changes and close the dialog box.

  1. In the Local Area Connection Properties dialog box, select the OK button to close the box.

  2. Continue with the “Setting Up the DHCP Server” section on page 24.

4. Setting Up the DHCP Server

NOTE: If you reconnect the sensor to a router or change to a different network, a new IP address may be dynamically assigned to the sensor that overwrites the current IP address.

Set up a DHCP server that can assign IP addresses on the network port of a PC or MacBook host computer, as follows:

  1. Download an installation script, as follows:

NOTE: Your specific system may not follow these steps exactly, so follow the general method appropriate for your platform to find, download, extract, and open the zipped attachment.

  • Open https://quanergy.desk.com in a web browser such as Firefox:

  • In the Customer Documentation and User Guides list that appears, select the DHCP Server Install Script for Linux item.

  • The new page that opens contains instructions and quanergy_net_install.zip file.

  • Click the quanergy_net_install.zip attachment. In the dialog box that opens, select Save File, and click the OK button (Figure 20).

Figure 20. DHCP Server Installation Script: Download

  1. In the pop-up window that appears (Figure 20), double-click the quanergy_net_install.zip item. The Downloads folder opens with the zip file in it (Figure 21).

Figure 21. DHCP Server Installation Script: Folder with Zip File

  1. Double-click the zip file (Figure 21). In the extraction window that appears, click the Extract button (Figure 22).

Figure 22. DHCP Server Installation Script: Extraction Window

  1. In the window that appears (Figure 23), navigate to your preferred location for saving the extracted file. (It’s fine to leave it in the Downloads folder.)

Figure 23. DHCP Server Installation Script: Assigned Location for Extracted File

  1. Click the Extract button (Figure 23). The file downloads to the location you previously specified on the local drive (Figure 24).

Figure 24. DHCP Server Installation Script: Extracted File in Downloads Folder

  1. Open a terminal window (Ctrl+Alt+T), then take the following actions in it to set up the DHCP server:

  • Execute this command to update all required packages:

    $ sudo apt-get update

  • When prompted for a password, enter your password.

  • Navigate to the directory where the installation script was extracted into (Figure 25, for example).

  • Execute this command to configure the network to be able to run the SDK (Figure 25):

    $ sudo bash quanergy_net_install

  • When prompted for Configure dhcp server? [y/n], type y, and press the Enter key. (If your DHCP server is already set up, this prompt won’t occur.)

  • When prompted for Ethernet interface, decide which Ethernet interface to set up the DHCP server on, which will be the port that is connected to the sensor. (You can use the ifconfig command (Figure 26) to list the available interfaces and notice which ones are defined for Ethernet.) From the prompts, type the number corresponding to the desired interface (0 or 1 in the Figure 25 example, but your situation may be different), and press the Enter key.

  • When prompted for IP address (of the Ethernet port), type 10.0.0.1 (which matches the 10.0.0 subnet, and whose host address is 1) (Figure 25), and press the Enter key.

Figure 25. DHCP Server Installation: Ethernet and IP Address Assignment

  1. Reboot the virtual machine to apply the changes, making the Ethernet port a DHCP server that can assign IP addresses of 2-255 on the 10.0.0 subnet.

CAUTION: If you connect the sensor to a router or change to a different network, a new IP address may be dynamically assigned to the sensor that overwrites the current IP address.

  1. Label the hardware for this port “DHCP” to prevent accidental connection to a LAN/internet cable.

5. Checking Network Connectivity

You’ve set up all essential connections and processes, so verify that the DHCP server and network port are working properly, as follows:

  1. Open a new terminal (Ctrl+Alt+T).

  2. Check the status of your DHCP server by executing this command:

$ ifconfig

If eth0 is working, you should see 10.0.0.1 display on screen, which confirms that the IP address of the virtual machine is set correctly.

Figure 26. Terminal Window Execution of ifconfig and sudo service Commands

  1. Check whether your DHCP server is running by executing this command:

$ sudo service isc-dhcp-server status

  • If it is running, the response is start/running, which means it is a successful.

  • If it is not running, the response is stop/waiting. Execute a restart command:

$ sudo service isc-dhcp-server restart

  1. If you’re running VMware Fusion or VMware Workstation, you also have the extra option of checking the network adapter status by clicking each network symbol on the Ubuntu VM desktop tool bar (Figure 27) and visually checking the drop-down menu to confirm:

  • In one menu (highlighted as yellow), the Bridged (Thunderbolt Ethernet) item is checked, as shown in Figure 27. The Ethernet port is able to act as a DHCP server.

  • In another menu (highlighted as blue), the NAT (network address translation) item should be checked (Figure 27). A checked NAT item is able to connect to the computer’s Internet service.

Figure 27. VM Network Adapter Dialog Box

6. Finding the Sensor’s IP Address

In order to communicate with the LIDAR sensor over the Ethernet TCP connection, an IP address is assigned to the sensor. Quanergy’s free, downloadable Q-View™ application allows you to discover the IP address, as well as to reveal diagnostic information, visualize data, record data, and calibrate sensors.

To discover the sensor’s IP address, which you must know for the next set of instructions, refer to the Q-View User Guide, ”Using the Dashboard Tab” section at https://quanergy.desk.com/customer/portal/articles/2717074.

7. Downloading and Deploying the SDK

Now that the virtualization environment is ready, this section discusses how you can download the SDK from the https://github.com/QuanergySystems GitHub page shown in Figure 1 on page 7, then integrate the sensor with the SDK. The sequence of the SDK acquisition is important: first quanergy_client and second quanergy_client_ros.

quanergy_client

Download the quanergy_client source code, as follows:

  1. Select quanergy_client from the Repositories list shown in Figure 1 on page 7.

  2. The resulting page (Figure 28) offers the latest formal release.

Figure 28. GitHub quanergy_client Source Code

  1. To properly download the source code to your local machine (instead of using the Clone or download button):

  • Click the link where indicated in Figure 28 to open the Ubuntu 14.04 LTS or Ubuntu 16.04 LTS README Build Instructions. (Example instructions that might be outdated are shown in Figure 29; cut and paste from the latest online version.)

  • Open a new terminal window, then execute each command in the order it appears in the README. Type y in response to each prompt question that comes up.

Figure 29. Example: Build QuanergyClient for Ubuntu 16.04 (left), 14.04 (right)

quanergy_client_ros

Download the quanergy_client_ros source code, as follows:

  1. Select quanergy_client from the Repositories list shown in Figure 1 on page 7.

  2. The resulting page (Figure 30) offers the latest formal release.

Figure 30. GitHub quanergy_client_ros Source Code

  1. To properly download the source code to your local machine (instead of using the Clone or download button):

  • Click the link where indicated in Figure 30 to open the nearly identical Ubuntu 14.04 LTS or Ubuntu 16.04 LTS README Build Instructions. (Example instructions that might be outdated are shown in Figure 31; cut and paste from the latest online version.)

  • Open a new terminal window, then execute each command in the order it appears in the README. Type y in response to each prompt question that comes up. After you provide the sensor’s IP address, you are ready to use the sensor.

Figure 31. Example: Build QuanergyClientROS for Ubuntu 16.04 (left), 14.04 (right)

8. Using the Code

Some questions that have been asked and answered about the SDK include the following:

  1. Q: Why does the code initialize last_azimuth to 65000?

A: The last_azimuth is set to an arbitrary number, which for historic reasons happens to be 65000. Once the sensor starts, it will have a new, significant value.

  1. Q: In your code, packet_counter is never initialized, only incremented. Is that okay?

A: Actually, the packet_counter is initialized in PointCloudGeneratorM8() with 0.

  1. Q: Is it possible for the M8 sensor to spin in two directions? We saw an if(spin) in the m8client code and weren't sure why that was there.

A: No, our M8 sensor rotates in only one direction. We are working on this feature, but right now we cannot change the spin direction.

  1. Q: What is bool spin for? Can the sensor scan while not spinning?

A: The bool spin was there because we could not control the spin direction in an early version. Please use the newest version of the SDK.

  1. Q: How is the intensity measurement from LiDAR represented?

A: LiDAR intensity is a unit less measure of the return strength of the laser. It is related to target reflectivity, among other things.

  1. Q: Can we adjust the code to get ALL returns, or to get only one return?

A: It may be more convenient to adjust the number of returns through the GUI discussed in the M8 Sensor User Guide, “Managing the Sensor > Edit Settings > Return Data Select” section, https://quanergy.desk.com/customer/portal/articles/2687038. However, the launch file that comes with the SDK includes a return argument, so you could just amend it to return:=all or substitute the preferred value 1, 2, or 3. These return values are defined in the M8 Sensor User Guide, “Multiple Returns” section.

Notices

Copyright © 2018, Quanergy Systems, Inc. All rights reserved.

This document is protected by copyright law, whereby all rights established therein remain with Quanergy Systems, Inc. Reproduction of this document or parts of this document is only permissible within the limits of the legal determination of Copyright Law. Alteration or abridgment of the document is not permitted without the explicit written approval of Quanergy.

The Quanergy logo is a trademark of Quanergy Systems, Inc. All other trademarks or registered trademarks are the property of their respective owners.

Specifications are subject to change without notice.

ISO 9001:2008 Certified

Contact

Quanergy Systems, Inc.
482 Mercury Drive
Sunnyvale, CA 94085-4706
http://quanergy.com

For purchases made directly from Quanergy contact: [email protected]

For purchases from a third party such as value-added reseller/system integrator: contact them for support

Add a custom footer

Home

Sensor SDK User Guide for Windows

Sensor SDK User Guide for Windows

Accessing the SDK Build Instructions for Windows

Installing Prerequisite Software on Windows

Setting Environment Variables on Windows

Downloading the SDK for Windows

Installing OpenNI and OpenNI2 Libraries

Creating Solution Files

Preparing the Executable for Visualizing Data

Finding the Sensor’s IP Address

Visualizing Data

Troubleshooting

Using the Code FAQ

Appendix 1: Connecting Without a Router

Sensor SDK User Guide for Ubuntu

Getting Started on Ubuntu

Accessing the SDK Build Instructions for Ubuntu

Setting Up the Network Port for Ubuntu

Setting Up the DHCP Server for Ubuntu

Checking Network Connectivity

Finding the Sensor’s IP Address for Ubuntu

Downloading and Deploying the SDK

Using the Code FAQ

ROS Quick Start Reference Card

Clone this wiki locally