License requirement

The functionality described requires a MANUS Bodypack or a MANUS license dongle with one of the following licenses: Core Pro Core XR Core Xsens Pro Core Qualisys Pro Core OptiTrack Pro Demo, or a Feature license with the SDK feature enabled.

Getting started with Linux

This guide will guide you through setting up your Linux environment to use the MANUS SDK in C++. And how to compile and run the examples provided.

Note

This guide is about using our C++ SDK on Linux. The SDK can run in integrated mode, this works on Linux. Remote usage still requires an active MANUS Core installation reachable within the network. The MANUS devices would need to be connected to that machine. Currently MANUS Core only runs on windows.

Prerequisites

Supported Distros

These are the currently supported and verified Linux distributions. Unlisted distributions might work fine, but your mileage may vary.

Distro	Version	Tag	Core Integrated	Core Remote
`Ubuntu`	20.04	`Focal Fossa`	Yes	Yes
`Ubuntu`	22.04	`Jammy Jellyfish`	Yes	Yes
`Ubuntu`	24.04	`Noble Numbat`	Yes	No

Packages

Our Linux SDK requires you to have the following packages installed.

Package	Version	Required for Core Integrated	Required for Core Remote
`GRPC`	1.28.1	No	Yes
`Protobuf`	3.11.2	No	Yes
`ZMQ`	4.3.2 (latest)	No	Yes
`git`	2.25.1 (latest)	No	Yes
`libtool`	2.4.6 (latest)	No	Yes
`libudev`	latest	Yes	Yes
`build-essential`	12.8 (latest)	Yes	Yes
`libusb`	1.0.0 (latest)	Yes	Yes
`Ncurses`	6.2.0 (latest)	(for example client)	(for example minimal client)
`OpenSSH-Server`	8.2 (latest)	(for cross compiling with VS)	(for cross compiling with VS)
`GDB`	9.2 (latest)	(for debugging with VS)	(for debugging with VS)

Installation

To get started with the Linux SDK, you'll need to install a few required packages. The required packages are dependant on if you intend to use Core in integrated mode or in remote mode. Follow the steps below for a guide to install them on your environment.

Packages

Use the following commands to install the necessary packages, some packages can be removed depending on your specific use case.

Core Remote

Installing required packages

apt-get update && apt-get install -y \
  build-essential \
  git \
  libtool \
  libzmq3-dev \
  libusb-1.0-0-dev \
  libudev-dev \
  libncurses5-dev \ 
  gdb \
  && apt-get clean

Single line: Installing required packages

apt-get update && apt-get install -y build-essential git libtool libzmq3-dev libusb-1.0-0-dev libudev-dev gdb libncurses5-dev && apt-get clean

Single line sudo: Installing required packages

sudo apt-get update && sudo apt-get install -y build-essential git libtool libzmq3-dev libusb-1.0-0-dev libudev-dev gdb libncurses5-dev && sudo apt-get clean

GRPC

Clone the GRPC repository and all its submodules from GitHub to your local machine using the following command:

Cloning GRPC

git clone -b v1.28.1 https://github.com/grpc/grpc /var/local/git/grpc && \
    cd /var/local/git/grpc && \
    git submodule update --init --recursive

Single line: Cloning GRPC

git clone -b v1.28.1 https://github.com/grpc/grpc /var/local/git/grpc && cd /var/local/git/grpc && git submodule update --init --recursive

Single line sudo: Cloning GRPC

sudo git clone -b v1.28.1 https://github.com/grpc/grpc /var/local/git/grpc && cd /var/local/git/grpc && sudo git submodule update --init --recursive

Install the protobuf dependency by running the following command:

Installing Protobuf

cd /var/local/git/grpc/third_party/protobuf && \
    ./autogen.sh && \
    ./configure --enable-shared && \
    make -j$(nproc) && \
    make -j$(nproc) check && \
    make install && \
    make clean && \
    ldconfig

Single line: Installing Protobuf

cd /var/local/git/grpc/third_party/protobuf && ./autogen.sh && ./configure --enable-shared && make -j$(nproc) && make -j$(nproc) check && make install && make clean && ldconfig

Single line sudo: Installing Protobuf

cd /var/local/git/grpc/third_party/protobuf && sudo ./autogen.sh && sudo ./configure --enable-shared && sudo make -j$(nproc) && sudo make -j$(nproc) check && sudo make install && sudo make clean && sudo ldconfig

Finally install GRPC by running the command below:

Installing GRPC

cd /var/local/git/grpc && \
    make -j$(nproc) && \
    make install && \
    make clean && \
    ldconfig

Single line: Installing GRPC

cd /var/local/git/grpc && make -j$(nproc) && make install && make clean && ldconfig

Single line sudo: Installing GRPC

cd /var/local/git/grpc && sudo make -j$(nproc) && sudo make install && sudo make clean && sudo ldconfig

Core Integrated

Installing required packages

apt-get update && apt-get install -y \
  build-essential \
  libusb-1.0-0-dev \
  libudev-dev \
  libncurses5-dev \ 
  gdb \
  && apt-get clean

Single line: Installing required packages

apt-get update && apt-get install -y build-essential libusb-1.0-0-dev libudev-dev gdb libncurses5-dev && apt-get clean

Single line sudo: Installing required packages

sudo apt-get update && sudo apt-get install -y build-essential libusb-1.0-0-dev libudev-dev gdb libncurses5-dev && sudo apt-get clean

Device rules

To allow connections to MANUS hardware you need to place the following file in the etc/udev/rules.d/ directory. This will allow the devices to be recognized and accessed by the system. After doing this, a full reboot is recommended to apply the changes. The naming of the file is relevant we recommend naming it 70-manus-hid.rules.

70-manus-hid.rules

# HIDAPI/libusb
SUBSYSTEMS=="usb", ATTRS{idVendor}=="3325", MODE:="0666"

# HIDAPI/hidraw
KERNEL=="hidraw*", ATTRS{idVendor}=="3325", MODE:="0666"

Docker

Instead of setting up a linux machine, you can also use docker to set up your development environment. Dockerfiles for both integrated and remote are added at the bottom of this section, and also included within the SDK package. Please be mindful to replace the username and password.

Integrated

First, build the Docker image containing the necessary dependencies and tools:

Build integrated docker image

docker build -f ./Dockerfile.Integrated -t manus-linux-integrated .

Once the Docker image is built, run a container with the manus-linux-integrated image. The --net=host is not strictly necessary but helps the container communicate out of its context. The --privileged parameter is required to access the USB glove devices, so is mounting the /dev and /run/udev directories.

Run integrated docker container

docker run -p 5000:5000 --privileged -v /dev:/dev -v /run/udev:/run/udev -i -t manus-linux-integrated /bin/bash

Integrated DockerFile

# Copyright 2018 gRPC authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.#
#
# Based on https://hub.docker.com/r/grpc/cxx.

# To build
#   docker build -f ./Dockerfile.Integrated -t manus-linux-integrated .

# To Run (Linux)
#   docker run -p 5000:5000 --privileged -v /dev:/dev -v /run/udev:/run/udev -i -t manus-linux-integrated /bin/bash

# To Run (Windows)
#   docker run -p 5000:5000 -i -t manus-linux-integrated /bin/bash

# FROM ubuntu:jammy as build
FROM ubuntu:focal as build
LABEL description="Visual Studio Manus SDK Build container" 

ENV TZ=Europe/Amsterdam
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

RUN apt-get update && apt-get install -y \
  build-essential \
  # Required for core integrated
  libusb-1.0-0-dev \
  libudev-dev \
  # Only required for building the minimal client
  libncurses5-dev \ 
  # Only required for visual studio debugging
  gdb \
  && apt-get clean

# configure SSH for communication with Visual Studio 
RUN apt-get update && apt-get install -y openssh-server
RUN mkdir -p /var/run/sshd
RUN echo 'PasswordAuthentication yes' >> /etc/ssh/sshd_config && \ 
   ssh-keygen -A 

# please make sure to change the password
RUN id -u manus >/dev/null 2>&1 || useradd -m -d /home/manus -s /bin/bash -G sudo manus && \
echo "manus:password" | chpasswd

# copy dependencies to ~/ManusSDK/ directory
COPY ManusSDK /home/manus/ManusSDK

# Add read/write permissions for manus devices
RUN apt-get update && apt-get install -y udev
RUN echo "# HIDAPI/libusb" > /etc/udev/rules.d/99-manus.rules && \
    echo "SUBSYSTEMS==\"usb\", ATTRS{idVendor}==\"3325\", MODE:=\"0666\"" >> /etc/udev/rules.d/99-manus.rules && \
    echo "# HIDAPI/hidraw" >> /etc/udev/rules.d/99-manus.rules && \
    echo "KERNEL==\"hidraw*\", ATTRS{idVendor}==\"3325\", MODE:=\"0666\"" >> /etc/udev/rules.d/99-manus.rules

# change default SSH port to 5000 to not conflict with system ssh in host mode
RUN echo "Port 5000" >> /etc/ssh/sshd_config

ENTRYPOINT service ssh start && service udev start && bin/bash

EXPOSE 5000

Remote

First, build the Docker image containing the necessary dependencies and tools:

Build remote docker image

docker build -f ./Dockerfile -t manus-linux .

Once the Docker image is built, run a container with the ManusLinux image. The --net=host parameter will make the application look like they are running on the host itself (thus enabling it to find MANUS Core instances on the network). The --privileged parameter is required to access the USB glove devices, so is mounting the /dev and /run/udev directories. If you plan to only use the SDK in remote mode, you can omit these.

Run remote docker container

docker run --net==host --privileged -v /dev:/dev -v /run/udev:/run/udev -i -t manus-linux /bin/bash

Remote DockerFile

# Copyright 2018 gRPC authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.#
#
# Based on https://hub.docker.com/r/grpc/cxx.

# To build
#   docker build -f ./Dockerfile -t manus-linux .

# To Run (Linux)
#   docker run --net==host --privileged -v /dev:/dev -v /run/udev:/run/udev -i -t manus-linux /bin/bash

# To Run (Windows)
#   docker run -p 5000:5000 -i -t manus-linux /bin/bash

# FROM ubuntu:jammy as build
FROM ubuntu:focal as build
LABEL description="Visual Studio Manus SDK Build container" 

ENV TZ=Europe/Amsterdam
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

RUN apt-get update && apt-get install -y \
  build-essential \
  # Required to install GRPC
  git \
  libtool \
  libzmq3-dev \
  # Required for core integrated
  libusb-1.0-0-dev \
  libudev-dev \
  # Only required for building the minimal client
  libncurses5-dev \ 
  # Only required for visual studio debugging
  gdb \
  && apt-get clean

ENV GRPC_RELEASE_TAG="v1.28.1"

RUN git clone -b ${GRPC_RELEASE_TAG} https://github.com/grpc/grpc /var/local/git/grpc && \
    cd /var/local/git/grpc && \
    git submodule update --init --recursive

RUN echo "-- installing protobuf" && \
    cd /var/local/git/grpc/third_party/protobuf && \
    ./autogen.sh && ./configure --enable-shared && \
    make -j$(nproc) && make -j$(nproc) check && make install && make clean && ldconfig

RUN echo "-- installing grpc" && \
    cd /var/local/git/grpc && \
    make -j$(nproc) && make install && make clean && ldconfig

# configure SSH for communication with Visual Studio 
RUN apt-get update && apt-get install -y openssh-server
RUN mkdir -p /var/run/sshd
RUN echo 'PasswordAuthentication yes' >> /etc/ssh/sshd_config && \ 
   ssh-keygen -A 

# please make sure to change the password
RUN id -u manus >/dev/null 2>&1 || useradd -m -d /home/manus -s /bin/bash -G sudo manus && \
echo "manus:password" | chpasswd

# copy dependencies to ~/ManusSDK/ directory
COPY ManusSDK /home/manus/ManusSDK

# Add read/write permissions for manus devices
RUN apt-get update && apt-get install -y udev
RUN echo "# HIDAPI/libusb" > /etc/udev/rules.d/99-manus.rules && \
    echo "SUBSYSTEMS==\"usb\", ATTRS{idVendor}==\"3325\", MODE:=\"0666\"" >> /etc/udev/rules.d/99-manus.rules && \
    echo "# HIDAPI/hidraw" >> /etc/udev/rules.d/99-manus.rules && \
    echo "KERNEL==\"hidraw*\", ATTRS{idVendor}==\"3325\", MODE:=\"0666\"" >> /etc/udev/rules.d/99-manus.rules

# change default SSH port to 5000 to not conflict with system ssh in host mode
RUN echo "Port 5000" >> /etc/ssh/sshd_config

ENTRYPOINT service ssh start && service udev start && bin/bash

EXPOSE 5000

Compilation

For compiling the examples we have three different options.

1. Make
2. Visual Studio Code
3. Visual Studio (remote cross compile)

Make sure you have your prerequisite packages installed and set up according to the installation guide.

Note

When only using the SDK in integrated mode and skipping the required remote packages the libManusSDK_Integrated.so library needs to be used. This library is located in the ManusSDK/lib folder of the SDK package. You can either reference to this library in the makefile or Visual Studio (Code). Or rename the libManusSDK_Integrated.so to libManusSDK.so and replace the original libManusSDK.so in the ManusSDK/lib folder.

Make

A Makefile is present within the SDKMinimalCLient_Linux and SDKClient_Linux folders inside the MANUS SDK package. The example can be compiled using the following command.

make all

This creates a *.out file within the project root that can be run.

Visual Studio Code

A VScode workspace file is provided with the SDK package. Once opened you should be able to run the app directly from VScode, and will create a *.cpp.out file within the project root.

Open the SDKMinimalClient.cpp or SDKClient.cpp file and press F5 to start debugging. It should compile and run the project.

Visual Studio on Windows (remote cross compilation)

Cross compiling using Visual Studio requires you to have a Linux system to connect to. This can be whatever you prefer, our preference goes out to a Docker container.

We've provided Dockerfiles inside the Linux SDK packages. Please refer to our installation guide on how to use it, and it's recommended to replace the Dockerfile inside the SDK package with the latest version in this guide.

To connect Visual Studio to your remote machine, follow the steps outlined in the official Microsoft documentation. If you have your environment set up through docker, use the machine's ip address as host and 5000 for the port, and for username and password use whatever you replaced them with in the Dockerfile.

Ensure that you configure Visual Studio to include any additional include directories and linker settings: - Add the location of the MANUS headers to C/C++ > General > Additional Include Directories. For example ~/ManusSDK/include

Add the location of the libManusSDK.so file and directory to Linker > Input > Additional Dependencies. For example ~/ManusSDK/lib/libManusSDK.so

If you're using the Dockerfiles, the ManusSDK directory will have automatically been copied to the ~/ManusSDK directory. However if you're using a different setup, make sure to manually copy the ManusSDK directory to the ~/ManusSDK directory.

You should now be able to compile the example using Visual Studio.