This guide provides detailed instructions for installing the Voyant API and development packages.

Installation Options

Option 1: Docker Installation (Recommended)

The Docker container approach is recommended as it:

• Works across different operating systems
• Includes all dependencies pre-installed
• Provides a consistent development environment

Prerequisites (docker engine)

• Docker Engine installed on your system - Docker installation guide.

⚠️ You need to install docker engine and not docker desktop because while docker desktop describes itself as being a GUI packaged with docker engine, it is in fact slightly different, most notably (for our purposes) in regards to how it handles ethernet connection. If you attempt to connect to your Voyant device with docker desktop, it will not work.

Steps

1. Clone the repository:

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

2. Build the container:

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

   Note: You can force a rebuild that will update to the latest release by adding the --no-cache flag.

   docker build --no-cache -t voyant-sdk-container -f docker/Dockerfile .

3. Run the container:

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

   If either of the above commands returns an error that asked if you are a root user (or something along those lines), then run them with sudo.

   Note: Running the docker run command will open a docker container that allows you to send commands to the LiDAR and receive LiDAR data. It does, however, not allow a lot of normal terminal commands such as ip addr. If you wish to return to the regular terminal without opening a new window, simply type exit. If you want to reopen the container, run the docker run command again. Alternatively, packages can be installed with apt while inside the container, but will not persist once the container is closed.

   Note: For Windows or macOS, the --network host flag works differently. You might need to adjust networking settings.

4. Access a running container (in a new terminal):

   docker exec -it voyant-sdk-container bash
   

Option 2: Native Installation (Ubuntu 22.04)

Prerequisites (native)

• Ubuntu 22.04 LTS
• Administrator (sudo) access

Install Dependencies

1. Install Cap’n Proto:

   curl -O https://capnproto.org/capnproto-c++-1.1.0.tar.gz
   tar zxf capnproto-c++-1.1.0.tar.gz
   cd capnproto-c++-1.1.0
   ./configure
   make -j6 check
   sudo make install
   

Install Voyant Packages

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

2. Install the packages:

   sudo apt update
   sudo dpkg -i voyant-api*.deb
   

3. Fix any missing dependencies (if needed):

   sudo apt --fix-broken install
   

[Optional] Clone the repository

1. Clone the repository:

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

Verifying Installation

To verify your installation, check that the Voyant tools are available. You can run:

voyant_hello_world

And you should see something like:

Welcome to the Voyant Photonics, Inc. API!
You have successfully installed the voyant-api package with:
- Proto version: 0.1.0 (Proto)
- API version:   0.1.0 (API)

How to see the headers

You can find the header files included in voyant-api-dev installed at /usr/include/voyant_api/.

You can also refer to the full API reference.

Uninstalling

To remove the Voyant packages from a native installation:

sudo apt remove voyant-api voyant-api-dev

For the Docker installation, simply remove the container and image:

docker rm -f voyant-sdk-container
docker rmi voyant-sdk-container

Next Steps

Once installation is complete, refer back to the Quickstart Guide to verify your setup with a simple example.