ROS 2 Integration

Hardware and Software Integration

wuji_glove_driver publishes Wuji Glove joint angles, tracked poses, palm IMU data, and tactile data as ROS 2 topics. The driver doesn’t load a model, publish TF, or provide control or calibration services. Complete wearing and connection and any required calibration before starting.

Installation

Use Ubuntu 26.04 (resolute) with ROS 2 Lyrical installed, on x86_64 or aarch64. The commands below fetch the source, load ROS, install dependencies and Hand 2 descriptions, and build the workspace. The build downloads and verifies the Wuji SDK C package for the host architecture.

# Fetch the source and load ROS 2
git clone https://github.com/wuji-technology/wuji-ros2.git "$HOME/wuji-ros2"
cd "$HOME/wuji-ros2"
source /opt/ros/lyrical/setup.bash
# Install build tools and dependencies
sudo apt-get update
sudo apt-get install -y ros-dev-tools
rosdep update
# Install the Hand 2 descriptions and workspace dependencies
scripts/install_hand2_descriptions.sh
rosdep install --from-paths . --ignore-src -r -y
# Build the workspace. The SDK C package is downloaded and verified automatically
colcon build --cmake-args -DBUILD_TESTING=OFF
# Load the built workspace
source install/setup.bash

In each new terminal, enter the workspace and load ROS and the built packages:

cd "$HOME/wuji-ros2"
source /opt/ros/lyrical/setup.bash
source install/setup.bash

Select a Device

After putting on and connecting the glove, scan for devices:

ros2 run wuji_tools wuji_list

Record the target glove’s serial number. The driver accepts these selectors at startup:

Without a selector, the driver connects only if discovery finds one Wuji Glove. Multiple gloves cause an immediate error and exit. If none are found, the driver waits until connect_timeout and exits. The driver holds an exclusive connection, so other SDK programs and wuji viz cannot connect to the same glove at the same time. To connect multiple gloves, use a different serial number and namespace for each driver process.

Read Glove Data

Run the Validation

1. Start the driver

Replace GLOVE_SERIAL_NUMBER with the serial number recorded in Select a Device, then start the driver:

ros2 launch wuji_bringup glove.launch.py \
  serial_number:=GLOVE_SERIAL_NUMBER namespace:=glove

To connect by network address, replace GLOVE_ENDPOINT with the IP:port address from the scan and use this command:

ros2 launch wuji_bringup glove.launch.py \
  serial_number:=GLOVE_SERIAL_NUMBER endpoint:=GLOVE_ENDPOINT namespace:=glove

To validate the hand side, append hand_side:=left or hand_side:=right to the launch command.

2. Check data

Keep the driver running. Open a new terminal, load ROS and the built packages, then run the status demo:

cd "$HOME/wuji-ros2"
source /opt/ros/lyrical/setup.bash
source install/setup.bash
ros2 run wuji_bringup glove_status_demo --ros-args -r __ns:=/glove

The demo prints five-finger joint angles and confidence for each frame. By default, it runs for 10 seconds and then summarizes frame counts and average receive rates for each topic. The check passes if it receives at least one joint_angles frame. Missing optional streams produce warnings.

To measure receive rates for 30 seconds without printing each frame, run:

ros2 run wuji_bringup glove_status_demo \
  --duration 30 --rate-only --ros-args -r __ns:=/glove

Place --duration and --rate-only before --ros-args. Receive rates use the interval from the first callback to the last. They measure ROS messages processed by the demo, not the device’s source output rate.

sudo apt-get install ros-lyrical-rmw-cyclonedds-cpp

export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

3. Stop the driver

Press Ctrl+C in the driver terminal. The driver closes subscriptions and disconnects the device.

Data Topics

All 10 topics use SensorDataQoS: best-effort, volatile, and keep-last 5. Use best-effort subscribers. Reliable subscribers cannot receive data from these publishers.

The driver publishes glove data on the topics below. Subscribe using the listed message types. Topic names are relative: with namespace:=glove, joint_angles resolves to /glove/joint_angles.

After sourcing the workspace, run these commands to inspect the message fields in the installed version:

ros2 interface show wuji_msgs/msg/HandJointAngles
ros2 interface show wuji_msgs/msg/TrackedPoseArray
ros2 interface show wuji_msgs/msg/TactileGrid
ros2 interface show wuji_msgs/msg/TactileZoneArray

Interpret the Data

• Joint angles use rad, and pose positions use m. Read each finger’s angles array by its actual length: five entries for the thumb and four for each other finger. Don’t interpret confidence as a normalized probability.
• Messages preserve SDK timestamps, frame identifiers, and payload values. ROS namespaces don’t rewrite message frame_id values. See Coordinate Frames for frame definitions.
• The driver copies raw SDK IMU fields and covariance into imu/palm without computing a new orientation estimate. It doesn’t publish the SDK-derived imu_data/palm stream.
• Tactile grids use rows × columns row-major arrays. Value semantics depend on the topic. Residual and binary grids aren’t force measurements.
• Parse tactile point clouds using their own fields, point_step, and row_step. Don’t assume an xyz-only layout.

Configure Topic Publishing

Except for required joint_angles, the nine data streams in the table can be controlled by launch arguments. All are enabled by default. For example, to disable the tactile point cloud, run:

ros2 launch wuji_bringup glove.launch.py \
  serial_number:=GLOVE_SERIAL_NUMBER namespace:=glove \
  publish_tactile_points:=false

Boolean launch arguments accept only lowercase true / false. Use the corresponding publish_* argument in the table for other optional streams. joint_angles has no disable switch.

Handle Stream End and Errors

If required joint_angles can’t start, ends, or reports an error, the driver exits with a nonzero status and the launch shuts down. An optional-stream failure stops only that stream and records a log message. Other streams continue.

The driver doesn’t reconnect automatically. Restore the device and network, then restart the launch. Stream end or error events trigger this handling. Applications that need to check whether data continues to arrive should monitor message timestamps.