Getting started with ROS2

The MANUS ROS2 package is a ROS2 wrapper around the MANUS C++ SDK. This package allows you to easily integrate MANUS gloves into your ROS2 project and provides a ROS2 interface for MANUS glove data.

Overview

The ROS2 package publishes MANUS glove data as ROS2 topics. A custom message type is used to represent glove data and exposes the following data for each glove connected.

Raw skeleton data: The raw skeleton data represented as a list of joint positions.
Ergonomics values: The ergonomics values represented as a list of joint angular rotations.
Raw sensor data: The raw sensor data represented as a list of sensor positions and rotation relative to the glove source (only available for MANUS Metagloves Pro series gloves).

Please refer to the ros2 package documentation for more information on the package.

Installation

Install ROS2: Ensure you have ROS2 installed on your system. You can follow the installation guide on the ROS2 website.
Install MANUS prerequisites: The ROS2 package is shipped as part of the Linux MANUS SDK package (MANUS_Core_<version>_SDK_Linux.tar.gz) in the ROS2 package folder. Please refer to the Linux installation for the required system dependencies.
Create a ROS2 Workspace: Create a new ROS2 workspace and navigate into it.
```
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws
```
Copy the package: Take the contents of the ROS2 package folder from the SDK package and copy it to the src folder of your workspace. Please refer to the Getting started guide for download instructions.
Set permissions: Ensure the manus_ros2 folder has the correct permissions. You can do this by running the following command:
```
chmod -R 777 ~/ros2_ws
```
Build the Package: Use colcon to build the package.
```
colcon build
```
Source the Setup Script: Source the setup script to overlay this workspace on your environment.
```
. install/setup.bash
```
Run the Manus Data Publisher: Execute the Manus data publisher to start publishing glove data messages.
```
ros2 run manus_ros2 manus_data_publisher
```

Architecture support

The ROS2 package builds and runs natively on both x86_64 (amd64) and ARM64 (aarch64) hosts, such as the Raspberry Pi 4 and NVIDIA Jetson Orin Nano. The build automatically selects the matching ManusSDK library for your architecture (libManusSDK-amd64.so or libManusSDK-aarch64.so), so no manual configuration is required.

Usage

Glove Calibration

The get the best possible tracking results, it is recommended to calibrate the gloves before use. Glove calibration data is stored on the machine's local file system and is automatically loaded when the MANUS Data publisher is started.

The recommended procesure for calibrating the gloves is to use the MANUS Core Dashboard in Integrated mode which is provided with the SDK package. Make sure no other MANUS SDK application is running and start the MANUS Core Dashboard. Then follow the calibration instructions. Once complete, shut down the MANUS Core Dashboard and start the MANUS Data publisher. The calibration data will be automatically loaded.

Topics

The MANUS ROS2 package publishes glove data as ROS2 topics. For each glove connected a subsequent topic is created. By default the topics are named according to an incremental naming scheme, starting from manus_glove_0 and incrementing for each glove connected. It is also possible to rename the topic, for more information on this see Topics.

Each glove is represented as a ManusGlove message type. The message types are structured as follows:

ManusGlove

glove_id (int32): The ID of the MANUS glove device
side (string): The side of the glove (left or right)
raw_node_count (int32): The number of raw skeleton nodes
raw_nodes (ManusRawNode[]): Array of raw skeleton nodes
ergonomics_count (int32): The number of ergonomics data points
ergonomics (ManusErgonomics[]): Array of ergonomics data
raw_sensor_orientation (geometry_msgs/Quaternion): Orientation of the raw wrist (Only for Metaglove Pro series gloves)
raw_sensor_count (int32): The number of raw sensors (Only for Metaglove Pro series gloves)
raw_sensor (geometry_msgs/Pose[]): Array of raw sensor data (Only for Metaglove Pro series gloves)

ManusRawNode

node_id (int32): The ID of the node
parent_node_id (int32): The ID of the parent node
joint_type (string): The type of joint (e.g., wrist, finger, etc.)
chain_type (string): The type of chain (e.g., mcp, pip, etc.)
pose (geometry_msgs/Pose): The pose of the node in 3D space

ManusErgonomics

type (string): The type of ergonomics data (which joint)
value (float32): The value of the ergonomics data (what angle)

This data is published at a rate of 120Hz by default and can be subscribed to by other ROS2 nodes.

The joint_type, chain_type, and side fields are string representations of the SDK enumerators and their values can be found in the ROS2 package article.

Haptics

The MANUS ROS2 package also supports haptic feedback for gloves types that support haptics. Haptic messages can be published to the /manus_glove_#/vibration_cmd topic by default. The message structure is as follows:

ManusVibrationCommand

intensities (float32[5]): The values for each finger's vibration intensity (Thumb, Index, Middle, Ring, Pinky)

The haptics motors will vibrate at that the specified intensity indefinitely until overwritten with a subsequent command. To return the haptic feedback to a neutral state, you can publish a message with all intensities set to 0.0.

Example Visualization

The MANUS ROS2 package comes with an example visualization node that subscribes to the glove data topics and visualizes the raw skeleton data in Open3D. To run the example visualization node, execute the following command:

Running the Python Visualization Example

To run the Python visualization example, follow these steps:

It's probably necessary to install the open3d and loop_rate_limiters Python packages. You can install them using pip:

Install Prerequisites: Ensure you have the required Python packages installed.
```
pip install open3d loop_rate_limiters
```
Run the Python Script: Execute the Python script to start visualizing the glove data.
```
python {ROS2-WORKSPACE}\manus_ros2\client_scripts\manus_data_viz.py
```

It will draw an Open3D view for each glove, showing the raw skeleton nodes in 3D space.