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
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 example clients
libncurses5-dev \
# Only required for visual studio debugging
gdb \
&& apt-get clean
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
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:
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
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
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:
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
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
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:
cd /var/local/git/grpc && \
make -j$(nproc) && \
make install && \
make clean && \
ldconfig
cd /var/local/git/grpc && make -j$(nproc) && make install && make clean && ldconfig
cd /var/local/git/grpc && sudo make -j$(nproc) && sudo make install && sudo make clean && sudo ldconfig
Core Integrated
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
apt-get update && apt-get install -y build-essential libusb-1.0-0-dev libudev-dev gdb libncurses5-dev && apt-get clean
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
Prime 3 support
If you want to use the Prime 3 series glove, you need to place the following file in the etc/udev/rules.d/
directory. This will allow the glove to be recognized by the system. After doing this, a full reboot is recommended to apply the changes. The naming of the file is relevant so naming it 70-manus-hid.rules
is recommended.
# 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:
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.
docker run -p 5000:5000 --privileged -v /dev:/dev -v /run/udev:/run/udev -i -t manus-linux-integrated /bin/bash
# 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:
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.
docker run --net==host --privileged -v /dev:/dev -v /run/udev:/run/udev -i -t manus-linux /bin/bash
# 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.
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 toLinker > 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.