Skip to content

Commit eca1051

Browse files
author
Tim van Wankum
committed
Updated readme and converted it to .rst files
1 parent 5da5d83 commit eca1051

3 files changed

Lines changed: 181 additions & 8 deletions

File tree

‎docs/source/device/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,4 @@ See the `Plugins directory <https://github.com/NVIDIA/IsaacTeleop/tree/main/src/
1919

2020
trackers
2121
add_device
22+
manus

‎docs/source/device/manus.rst‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
..
2+
SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
3+
SPDX-License-Identifier: Apache-2.0
4+
5+
Manus Gloves
6+
============
7+
8+
A Linux-only plugin for integrating `Manus <https://www.manus-meta.com/>`_ gloves
9+
into the Isaac Teleop framework. It provides full hand-joint tracking via the
10+
Manus SDK and injects the resulting poses into the OpenXR hand-tracking layer so
11+
any downstream retargeter can consume them transparently.
12+
13+
Components
14+
----------
15+
16+
- **Core library** (``manus_plugin_core``) — wraps the Manus SDK
17+
(``libIsaacTeleopPluginsManus.so``) and exposes per-joint tracking data.
18+
- **Plugin executable** (``manus_hand_plugin``) — the main plugin binary that
19+
integrates with the Teleop system via CloudXR / OpenXR.
20+
- **CLI tool** (``manus_hand_tracker_printer``) — a standalone diagnostic tool
21+
that prints tracked joint data to the terminal for quick verification.
22+
23+
Prerequisites
24+
-------------
25+
26+
- **Linux** — x86_64 (tested on Ubuntu 22.04 / 24.04).
27+
- **Manus SDK** for Linux — downloaded automatically by the install script.
28+
- **System dependencies** — the install script prompts to install required packages.
29+
30+
Installation
31+
------------
32+
33+
Automated (recommended)
34+
~~~~~~~~~~~~~~~~~~~~~~~~
35+
36+
The install script handles SDK download, dependency installation, and building:
37+
38+
.. code-block:: bash
39+
40+
cd src/plugins/manus
41+
./install_manus.sh
42+
43+
The script will:
44+
45+
1. Ask whether to install **MANUS Core Integrated** dependencies only (faster) or
46+
both **Integrated and Remote** dependencies (includes gRPC, takes longer).
47+
2. Install the required system packages.
48+
3. Download MANUS SDK v3.1.1.
49+
4. Extract and place the SDK in the correct location.
50+
5. Build the plugin and the diagnostic tool
51+
52+
Manual
53+
~~~~~~
54+
55+
If you prefer to install manually:
56+
57+
1. Download the MANUS Core SDK from
58+
`MANUS Downloads <https://docs.manus-meta.com/3.1.1/Resources/>`_.
59+
2. Extract and place the ``ManusSDK`` folder inside ``src/plugins/manus/``, or
60+
point CMake at a different path by setting ``MANUS_SDK_ROOT``.
61+
3. Follow the
62+
`MANUS Getting Started guide for Linux <https://docs.manus-meta.com/3.1.1/Plugins/SDK/Linux/>`_
63+
to install the dependencies and configure device permissions.
64+
65+
Expected directory layout after placing the SDK:
66+
67+
.. code-block:: text
68+
69+
src/plugins/manus/
70+
app/
71+
main.cpp
72+
core/
73+
manus_hand_tracking_plugin.cpp
74+
inc/
75+
core/
76+
manus_hand_tracking_plugin.hpp
77+
tools/
78+
manus_hand_tracker_printer.cpp
79+
ManusSDK/ <-- placed here
80+
include/
81+
lib/
82+
83+
Then build from the root:
84+
85+
.. code-block:: bash
86+
87+
cd ../../.. # navigate to root
88+
cmake -S . -B build
89+
cmake --build build --target manus_hand_plugin manus_hand_tracker_printer -j
90+
cmake --install build --component manus
91+
92+
Running the Plugin
93+
------------------
94+
95+
1. Set up the CloudXR environment
96+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
97+
98+
Source the CloudXR environment and start the runtime before running the plugin:
99+
100+
.. code-block:: bash
101+
102+
export NV_CXR_RUNTIME_DIR=~/.cloudxr/run
103+
export XR_RUNTIME_JSON=~/.cloudxr/openxr_cloudxr.json
104+
105+
2. Verify with the CLI tool
106+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
107+
108+
Ensure Manus Core is running and the gloves are connected, then run:
109+
110+
.. code-block:: bash
111+
112+
./build/bin/manus_hand_tracker_printer
113+
114+
3. Run the plugin
115+
~~~~~~~~~~~~~~~~~~
116+
117+
.. code-block:: bash
118+
119+
./install/plugins/manus/manus_hand_plugin
120+
121+
Wrist Positioning — Controllers vs Optical Hand Tracking
122+
---------------------------------------------------------
123+
124+
Two sources are available for positioning the Manus gloves in 3D space:
125+
126+
- **Controller adapters** — attach Quest 3 controllers to the Manus Universal
127+
Mount on the back of the glove. The controller pose drives wrist placement.
128+
- **Optical hand tracking** — use the HMD's built-in optical hand tracking to
129+
position the hands. No physical controller adapter required.
130+
131+
The plugin selects the source automatically at runtime: optical hand tracking is
132+
preferred when ``XR_MNDX_xdev_space`` is supported and the runtime reports an
133+
actively tracked wrist pose; otherwise it falls back to the controller pose.
134+
135+
.. note::
136+
137+
When using controller adapters it is advisable to disable the HMD's automatic
138+
hand-tracking–to–controller switching to avoid unexpected source changes
139+
mid-session.
140+
141+
Troubleshooting
142+
---------------
143+
144+
.. list-table::
145+
:widths: 40 60
146+
:header-rows: 1
147+
148+
* - Symptom
149+
- Resolution
150+
* - SDK download fails
151+
- Check your internet connection and re-run the install script.
152+
* - Manus SDK not found at build time
153+
- With manual installation, ensure ``ManusSDK`` is inside
154+
``src/plugins/manus/`` or set ``MANUS_SDK_ROOT`` to your installation path.
155+
* - Manus SDK not found at runtime
156+
- The build configures RPATH automatically. If you moved the SDK after
157+
building, set ``LD_LIBRARY_PATH`` to its ``lib/`` directory.
158+
* - No data received
159+
- Ensure Manus Core is running and the gloves are connected and calibrated.
160+
* - CloudXR runtime errors
161+
- Make sure ``scripts/setup_cloudxr_env.sh`` has been sourced before running.
162+
* - Permission denied for USB devices
163+
- The install script configures udev rules. If the rules were not reloaded,
164+
run:
165+
166+
.. code-block:: bash
167+
168+
sudo udevadm control --reload-rules
169+
sudo udevadm trigger
170+
171+
Then reconnect your Manus devices.
172+
173+
License
174+
-------
175+
176+
Source files are covered by their stated licenses (Apache-2.0). The Manus SDK is
177+
proprietary to Manus and is subject to its own license; it is **not** redistributed
178+
by this project.

‎src/plugins/manus/README.md‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ The script will:
3535
2. Install required system packages
3636
3. Automatically download the MANUS SDK v3.1.1
3737
4. Extract and configure the SDK in the correct location
38-
5. Build the plugin from the TeleopCore root
38+
5. Build the plugin
3939

4040
### Manual Installation
4141

@@ -76,17 +76,11 @@ cmake --install build --component manus
7676
### 1. Setup CloudXR Environment
7777
Before running the plugin, ensure CloudXR environment is configured:
7878

79-
```bash
80-
cd /path/to/TeleopCore
81-
source scripts/setup_cloudxr_env.sh
82-
./scripts/run_cloudxr.sh # Start CloudXR runtime if not already running
83-
```
84-
8579
The following environment variables must be set before running either the CLI tool or the plugin (adjust paths if your CloudXR installation differs from the defaults):
8680

8781
```bash
8882
export NV_CXR_RUNTIME_DIR=~/.cloudxr/run
89-
export XR_RUNTIME_JSON=~/.cloudxr/share/openxr/1/openxr_cloudxr.json
83+
export XR_RUNTIME_JSON=~/.cloudxr/openxr_cloudxr.json
9084
```
9185

9286
### 2. Verify with CLI Tool

0 commit comments

Comments
 (0)