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

Before you begin, ensure you have:

Note: For other operating systems, we recommend using Docker. See our Docker Installation Guide for details.

Initial Setup

Choose one of the two installation dropdown options from the drop down options:

  1. Manual Setup: Install the voyant-api on your host OS and manually connect to your sensor.
  2. [Experimental] Automated Setup Script: use a docker container that facilitates installation and connection to your sensor.
Manual Setup

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

Install the API

These instructions install the Voyant API Debian packages directly on your native Ubuntu system. If you’re using a different operating system or prefer to use Docker instead, please refer to our Installation Guide.

  1. Download packages from voyant-sdk/releases/latest

  2. Install the packages:

    Tip: Provide the relative path to the .deb debian packages for the dpkg command.

    cd Downloads/ # or location of debian files
sudo apt update
sudo dpkg -i voyant-api*.deb

  3. Fix any missing dependencies

    sudo apt --fix-broken install

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.

  1. 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.

  2. 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.)

  3. 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.

[Experimental] Automated Setup Script

For native system installation: If you wish to install the API on your native system instead of using Docker, please use the Manual Setup instructions.

Prerequisites: The automated setup script requires Docker Engine and git to be installed. If you don’t have these installed, please refer to our Installation Guide.

The Voyant SDK includes an automated setup script designed to make connecting to your Voyant lidar faster and easier using Docker. If you prefer to configure the connection manually or if this script doesn’t work for your setup, you can also use the Manual Setup instructions.

Note: This script has only been tested on Linux-based operating systems and may not function properly on other platforms.

  1. Clone the SDK repository:

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

  2. Run the script:

    cd voyant-sdk
sudo python3 automated_voyant_client_setup.py

  3. 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.

  4. 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.

  5. 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).

Start the sensor

⚠️ Ensure you successfully followed one of the above setup workflows before continuing!

Your Voyant sensor does not start the laser and data stream on boot. Instead, the sensor waits for your command. To start the sensor, run this command in your terminal (if you are using Docker, this should be from within the container):

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

  1. Start the Voyant Foxglove Bridge in your terminal (if you are using Docker, this should be from within the container):

    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.

  2. Open Foxglove Studio in your browser at https://studio.foxglove.dev/ or launch the desktop application if installed.

  3. Select Open connection... in the upper left section of the window to bring up the connection dialog

  4. In the connection dialog, select “Foxglove WebSocket” as the connection type.

  5. Enter the WebSocket URL: ws://localhost:8765 and click “Connect”.

  6. Download the config/voyant_foxglove_cfg.json file from the voyant-sdk/ repository.

    If you have cloned the voyant-sdk/ repo, you already have this file.

  7. In the layout selector (top right corner), choose “Import from file…” and select the voyant_foxglove_cfg.json.

  8. 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 so you can see what you are recording, open another terminal and run this command:

If using Docker, open another terminal and access your running docker container with:

docker exec -it voyant-sdk-container bash

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 with ctrl + c to avoid starting simultaneous clients to your Foxglove visualizer.

Play the recording back, streaming the data to the same Foxglove window (if you are using Docker, this should be from within the container):

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.

Run this command in your terminal (if you are using Docker, this should be from within the container):

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:

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

Copyright © Voyant Photonics, Inc.