Sensor Quickstart Guide

This guide is intended to be the fastest way to get you started working with your Voyant LiDAR sensor using our pre-packaged tools. You should follow this guide once you have a Voyant LiDAR sensor physically connected to your PC over ethernet.

You’ll learn:

how to connect to your sensor.
how to visualize point cloud data from your sensor.
how to record point cloud data from your sensor.
how to play back your recorded point cloud data.

Note: This guide goes through the steps very quickly. For more in-depth instructions, please refer to the Voyant API Usage Guide.

Prerequisites

A Voyant sensor connected to your PC over ethernet
A web browser for Foxglove Studio (or the Foxglove desktop application)
A linux laptop (Ubuntu 22.04 recommended)

Initial setup

These instructions assume you already have Docker Engine and git installed. If this is not the case, or you wish to use the api on your native system instead of through Docker, please refer to our Installation Guide.

[Experimental] Automated setup script

The Voyant SDK comes packaged with a setup script that is meant to make connecting to your Voyant lidar easier and quicker. If you would prefer to connect to your lidar manually or if this script does not work for you, please refer to Manual Setup.

Note: This script has only been tested on Linux based operating systems, and might not function properly if run on another OS.

Clone the SDK repository:

git clone https://github.com/Voyant-Photonics/voyant-sdk.git

Run the script:

cd voyant-sdk
sudo python3 automated_voyant_client_setup.py

Select the network interface of the lidar

The script will print out a list of all of the network interfaces attached to your device and ask you to select the one that represents your Voyant lidar.

In most cases, the script will indicate which it thinks is most likely to be the lidar by printing <- likely lidar in green next to the associated interface.

Since you are connecting the lidar over ethernet, you are looking for an interface name that begins with eth0, eno1, enx, or something similar.

Once you know which network interface is the lidar, input its assoasiated number in the list into the terminal and press enter.
Choosing to build Docker conteriner

The script will prompt you to build the docker container. If you have not done so since you last booted up your device or if you or Voyant have made changes to Dockerfile since you last built the docker container, then enter y to build the docker container. If not, enter n to skip the process.
You’re Done!

The script will now open a new terminal window inside of the docker container. For instructions on how to use your Voyant lidar from here, refer to Start the sensor for a continued quickstart guide or Voyant Pre-packaged Tools for a more in depth overview.

Note: A common problem can occur where the lidar disconnects from your device after building the docker container. If your lidar is unresponsive, exit the docker container by entering exit into the new terminal and rerun this script in to original window. When prompted to build docker, say no (n).

Manual Setup

This section will teach you how to quickly manually connect to your Voyant lidar and get it up and running.

Install the API

These quickstart installation instructions assume you already have Docker and git installed. If this is not the case, or you wish to install on your native system instead of through Docker, please refer to our Installation Guide.

Clone the SDK repository:

git clone https://github.com/Voyant-Photonics/voyant-sdk.git

Build the container:

cd voyant-sdk/
docker build -t voyant-sdk-container -f docker/Dockerfile .

This will use the latest available release by default.

Run the container:

docker run --rm -it --name voyant-sdk-container --network host -v $(pwd):/workspace voyant-sdk-container /bin/bash

If you experienced any issues, please refer to our Installation Guide.

Connect to your sensor

These quickstart connection instructions assume you have a foundational understanding of networking tools in a linux terminal. If you would like additional guidance, please refer to our Connections Guide.

Identify your network interface

Use ip addr to list all network interfaces. You are looking for the wired ethernet interface connected to the sensor, typically something like eth0, eno1, enx78e7d1ea46b2, etc.
Configure the network interface with a compatible IP address

The sensor uses the 192.168.20.x subnet. We recommend using 192.168.20.100 for your PC’s IP address on this subnet.
```
sudo ip addr add 192.168.20.100/24 dev <YOUR_INTERFACE_NAME>
sudo ip link set <YOUR_INTERFACE_NAME> up
```
Replace <YOUR_INTERFACE_NAME> with your actual network interface name (e.g., eth0, eno1, etc.)
Check connection to device

By default, Voyant LiDAR devices ship with a static IP of 192.168.20.20. Check that you can reach the sensor with:
```
ping 192.168.20.20
```
A successful connection will show ping responses with time statistics and 0% packet loss.

If you experience any persisting issues, please refer to our Connections Guide.

Start the sensor

Your Voyant sensor does not start the laser and data stream on boot. Instead, the sensor waits for your command. To start the sensor, simply run:

voyant_lidar_client --endpoint start

The startup procedure can take ~10 seconds. Upon successful completion, you will see:

✅ LiDAR service started successfully

⚠️ Now that you have started your sensor, be sure to safely stop the sensor before powering the system down when you are done with this tutorial.

More information about starting / stopping your sensor is available at voyant_lidar_client.

Visualize live sensor data with Foxglove Studio

Start the Voyant Foxglove Bridge in your docker terminal by running:
```
voyant_foxglove_bridge --bind-addr 0.0.0.0:4444 --group-addr 224.0.0.0 --interface-addr 192.168.20.100
```
If this error is thrown:
```
Error: No such device (os error 19)
```
then you have installed Docker Desktop instead of Docker Engine. To fix this problem, simply uninstall Docker Desktop and install Docker Engine. Make sure to close all Docker Desktop operations before uninstalling. Once Docker Engine has been installed, you should rebuild the docker container.

More information about the voyant_foxglove_bridge tool is available at Visualizing Live Sensor Data.
Open Foxglove Studio in your browser at https://studio.foxglove.dev/ or launch the desktop application if installed.
Select Open connection... in the upper left section of the window to bring up the connection dialog
In the connection dialog, select “Foxglove WebSocket” as the connection type.
Enter the WebSocket URL: ws://localhost:8765 and click “Connect”.
In the layout selector (top right corner), choose “Import from file…”
Navigate to the voyant-sdk/ repository you cloned and select the config/voyant_foxglove_cfg.json file.
Have some fun looking at your point cloud!

For more detailed Foxglove user instructions, please see our Pointcloud Visualization guide.

Record a log of data

Keeping the foxglove bridge running, open another terminal and access your running docker container with:

docker exec -it voyant-sdk-container bash

From within the container, run:

voyant_logger_binary --output my_first_recording.bin --bind-addr 0.0.0.0:4444 --group-addr 224.0.0.0 --interface-addr 192.168.20.100

Press ctrl + c to stop recording when you are ready.

More information about the voyant_logger_binary tool is available at Recording a Data Session.

Visualize your logged data

Stop the voyant_foxglove_bridge you have running in the first terminal with ctrl + c to avoid starting simultaneous clients to your Foxglove visualizer.

Play the recording back, streaming the data to the same Foxglove window with in the second terminal:

voyant_playback_foxglove --input my_first_recording.bin --loopback

When you want to stop the playback, kill the command with ctrl + c.

More information about the voyant_playback_foxglove tool is available at Replaying Recorded Data.

Safely stop the sensor

⚠️ Always safely stop the sensor before powering the system down.

To protect the internal components of your sensor, you should disable the lidar stream before powering the system down.

voyant_lidar_client --endpoint stop

The shutdown procedure can take ~10 seconds. Upon successful completion, you will see:

✅ LiDAR service stopped and system disabled

More information about starting / stopping your sensor is available at voyant_lidar_client.

Next Steps

Now that you’ve visualized and recorded point cloud data:

Explore the pre-packaged tools for more advanced functionality
Learn about point cloud visualization options for customizing your view
If you’re a developer, check out the Developer Quickstart Guide to build custom applications