Skip to content

License requirement

The functionality described requires a MANUS Bodypack or a MANUS license key with the SDK feature and the Linux feature enabled. When using the SDK in integrated mode the SDK (integrated) feature is required as well.

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 Architectures

The Linux SDK runs natively on both x86_64 (Intel/AMD 64-bit) and ARM64 (aarch64) processors. The libManusSDK.so in the ManusSDK/lib folder is architecture-specific, so make sure you use the SDK package built for your platform. You can check your architecture with uname -m, which reports x86_64 or aarch64.

32-bit platforms

32-bit platforms such as armhf (e.g. Raspberry Pi OS 32-bit) and x86 are not supported. On Raspberry Pi devices, make sure you are running a 64-bit OS image.

Supported Devices

The SDK has been verified on the devices listed below. Since the SDK only depends on the architecture and a supported distribution, comparable devices are expected to work as well — the second table lists common ARM64 devices with official Ubuntu support that fall within that expectation.

Device SoC Architecture Verified OS Status
Generic Intel/AMD PC - x86_64 Ubuntu 20.04 / 22.04 / 24.04 Verified
Raspberry Pi 4 Broadcom BCM2711 ARM64 Raspberry Pi OS 13 (64-bit) Verified
NVIDIA Jetson Orin Nano NVIDIA Orin (Ampere) ARM64 Ubuntu 22.04 (JetPack 6) Verified
NVIDIA DGX Spark NVIDIA GB10 (Grace Blackwell) ARM64 DGX OS (Ubuntu 24.04-based) Verified
Device SoC Architecture Ubuntu support Status
Raspberry Pi 5 Broadcom BCM2712 ARM64 Ubuntu 24.04 (certified) Expected to work
NVIDIA Jetson Orin NX NVIDIA Orin (Ampere) ARM64 Ubuntu 20.04 / 22.04 (JetPack) Expected to work
NVIDIA Jetson AGX Orin NVIDIA Orin (Ampere) ARM64 Ubuntu 20.04 / 22.04 (JetPack) Expected to work

Cloud and headless devices

Devices without USB access to MANUS hardware (such as cloud instances) can only use the SDK in remote mode, connecting to a MANUS Core installation elsewhere on the network. Integrated mode requires the MANUS devices to be physically connected to the machine running the SDK.

Supported Distros

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

Distro Version Tag Architectures
Ubuntu 20.04 Focal Fossa x86_64, ARM64
Ubuntu 22.04 Jammy Jellyfish x86_64, ARM64
Ubuntu 24.04 Noble Numbat x86_64, ARM64
Raspberry Pi OS 13 Debian Trixie ARM64

Packages

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

gRPC and protobuf

As of MANUS Core 3.2, gRPC and protobuf are statically linked into libManusSDK.so and no longer need to be installed separately on Linux.

Package Version
build-essential 12.8 (latest)
gcc 11.3.0
g++ 11.3.0
cmake 3.16 or newer
git 2.25.1 (latest)
libtool 2.4.6 (latest)
ZMQ 4.3.2 (latest)
libtool 2.4.6 (latest)
libudev latest
libusb 1.0.0 (latest)
zLib 1.3.1 (latest)
libcurl 7.68 (latest)
Ncurses 6.2.0 (latest)
OpenSSH-Server 8.2 (latest)
GDB 9.2 (latest)

Installation

The Linux SDK ships as MANUS_Core_<version>_SDK_Linux.tar.gz. Extract it to a location of your choice:

Extracting the SDK package
tar -xzf MANUS_Core_<version>_SDK_Linux.tar.gz

To get started, you'll need to install a few required packages. Follow the steps below for a guide to install them on your environment.

Bundled with the SDK is a script that will install all the required packages for you. You can find it in the C++/SDKClient and C++/SDKMinimalClient folders of the SDK package. Run the script with the following commands:

Installing required dependencies
chmod +x install-dependencies.sh
./install-dependencies.sh

Note

Please make sure to run the script with sudo if you are not running as root.

This will install all the required build packages and configure the udev rules for both integrated mode and remote mode. gRPC and protobuf are statically linked into libManusSDK.so, so they are no longer built or installed by this script.

The final output of the script should look something like this:

Setup complete message
=== Dependency Setup for Debian/Ubuntu ===
[1/1] Installing build dependencies...

=== Setup Complete ===

Udev rules have been configured to allow read/write access to manus devices.
You may need to reload udev rules for the changes to take effect:
  sudo udevadm control --reload-rules
  sudo udevadm trigger

Packages

If you prefer to install the packages manually instead of using the bundled script, use the following commands. Some packages can be removed depending on your specific use case.

Installing required packages
apt-get update && apt-get install -y \
  build-essential \
  cmake \
  # Required for remote mode (network connection)
  libzmq3-dev \
  # Required for core
  libusb-1.0-0-dev \
  libudev-dev \
  libcurl4-openssl-dev \
  # Only required for building the example clients
  libncurses5-dev \ 
  # Only required for visual studio debugging
  gdb \
  && apt-get clean
Single line: Installing required packages
apt-get update && apt-get install -y build-essential cmake libzmq3-dev libusb-1.0-0-dev libudev-dev libcurl4-openssl-dev libncurses5-dev gdb && apt-get clean
Single line sudo: Installing required packages
sudo apt-get update && sudo apt-get install -y build-essential cmake libzmq3-dev libusb-1.0-0-dev libudev-dev libcurl4-openssl-dev libncurses5-dev gdb && sudo apt-get clean

gRPC and protobuf

Previous versions of this guide required you to manually clone, build, and install gRPC and protobuf. As of MANUS Core 3.2 these are statically linked into libManusSDK.so, so those steps are no longer necessary. When only using the SDK in integrated mode, the libzmq3-dev package (used for remote network connections) can also be omitted.

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"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1915", ATTRS{idProduct}=="83fd", 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. A single Dockerfile is included within the SDK package and shown at the bottom of this section. The previously separate integrated and remote Dockerfiles have been merged into one, since gRPC and protobuf are now statically linked into libManusSDK.so and no longer need to be built in the image. Please be mindful to replace the username and password.

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

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

Architecture

The ubuntu base image used in the Dockerfile is multi-arch, so the same Dockerfile builds on both x86_64 and ARM64 hosts — Docker automatically selects the image matching your host architecture. When building on one architecture for another (for example building an ARM64 image on an x86_64 machine), pass --platform linux/arm64 to docker build/docker run and ensure QEMU emulation (binfmt) is set up.

Once the Docker image is built, run a container with the manus-linux image. The --net=host parameter will make the application look like it is 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, as is mounting the /dev and /run/udev directories. If you plan to only use the SDK in remote mode, you can omit these.

Run docker container
docker run --net=host --privileged -v /dev:/dev -v /run/udev:/run/udev -i -t manus-linux /bin/bash
DockerFile
# 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.#

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

# To Run (Linux)
#   docker run -p 5000:5000 --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 osrf/ros:jazzy-desktop-full
# 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
  libusb-1.0-0-dev \
  libudev-dev \
  zlib1g-dev \
  libcurl4-openssl-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

Compilation

For compiling the examples we have the following options.

1. CMake (SDK Client)
2. Make (SDK Minimal Client)
3. Visual Studio Code
4. Visual Studio (remote cross compile)

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

The SDK Client requires CMake

The SDK Client example is built with CMake (3.16 or newer) on all platforms. The Makefile and Visual Studio Code workspace apply to the SDK Minimal Client only.

Note

A single libManusSDK.so library (located in the ManusSDK/lib folder of the SDK package) now supports both integrated and remote modes. gRPC and protobuf are statically linked into it, so no additional dependencies need to be installed and the separate libManusSDK_Integrated.so library is no longer required.

CMake (SDK Client)

The SDK Client is built with CMake. From inside the C++/SDKClient folder of the SDK package run:

Building the SDK Client with CMake
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

-DCMAKE_BUILD_TYPE=Release is required on Linux: the default generator (Unix Makefiles) is single-config and picks the build type at configure time, so without it you get an unoptimized build with no warning. The build creates the SDKClient executable inside the build folder.

The build supports both x86_64 and ARM64 and automatically selects the SDK library matching the target processor (libManusSDK-amd64.so or libManusSDK-aarch64.so from the ManusSDK/lib/<arch> folder). When running the client, make sure LD_LIBRARY_PATH points at that folder (or set an rpath).

Make (SDK Minimal Client)

A Makefile is present within the C++/SDKMinimalClient folder 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.

Note

The SDK Client is built with CMake, not Make.

Visual Studio Code

A VScode workspace file is provided with the SDK package for the SDK Minimal Client. 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 file and press F5 to start debugging. It should compile and run the project.

Since the SDK Client is a regular CMake project, it can also be opened in Visual Studio Code using the CMake Tools extension: open the SDKClient folder and use the extension's configure/build/debug commands.

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

alt text

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

alt text

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.