Skip to content

feat(revohuman): add the RevoHuman glove plugin - #1407

Open
HAOTianGa03 wants to merge 10 commits into
NVIDIA:mainfrom
HAOTianGa03:feat/revohuman-glove
Open

HAOTianGa03 wants to merge 10 commits into
NVIDIA:mainfrom
HAOTianGa03:feat/revohuman-glove

Conversation

@HAOTianGa03

@HAOTianGa03 HAOTianGa03 commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Description

Adds an optional, Linux-only plugin for BrainCo RevoHuman exoskeleton gloves, built on the RevoHuman C SDK release that its CMake pins (0.1.3).

  • Opens the gloves through the SDK's autokit, which opens, retries and reopens them and re-syncs a two-hand pair on its own. Each glove's /glove status gives the SDK's reason when the glove is degraded, for example streaming without hardware sync to the other glove, or given up; the plugin keeps running.
  • Fits the 26 OpenXR hand joints to the SDK's link poses for the hand models of the pinned release (core/hand_fit.inc) and injects them into the OpenXR hand-tracking layer, placed at a wrist pose from optical hand tracking or a controller aim pose (REVOHUMAN_WRIST_SOURCE). A glove whose hand model the plugin is not fitted to is reported as failed.
  • Pushes the 21 encoder angles as joint states and the taxel forces in newtons with the common tactile contract, under a TactileMetadata built from the SDK's taxel layout when each glove opens. Supports PTV1 (with tactile sensors) and P1 (without).
  • Opens tactile split from the glove frames: a glove whose firmware splits it sends every tactile sample on its own at about 215 Hz, and the plugin pushes each one in sampling order; otherwise the plugin takes one sample per frame.
  • SIGUSR1 tares the tactile sensors of each streaming glove that has them. This writes to the gloves; the README gives the procedure and how each request is logged.
  • From start-up until a hand's first glove sample, for at most 5 s, the plugin injects that hand with no valid joints, so an OpenXR client does not see the headset's optical hand followed by the glove's while the gloves open.
  • Publishes <id>/device_status, and TeleopSession monitors it, as it does manus_hand_plugin, avatar_hand_plugin, spacemouse and gamepad. Its collections are recorded and played back with the DeviceIO MCAP configs, as for the other trackers.
  • BUILD_PLUGIN_REVOHUMAN is OFF by default. With it ON, the plugin's CMake downloads the pinned C SDK release for the build's arch (x86_64 or aarch64) with FetchContent and checks its SHA-256; REVOHUMAN_SDK_ROOT points it at a local SDK instead, and an incomplete SDK fails the configure. cmake --install build --component revohuman installs the plugin with the SDK library and its licence.
  • Adds the device page under hand tracking and a row in the ecosystem device table.
  • Outside src/plugins/revohuman: the BUILD_PLUGIN_REVOHUMAN option in the root CMakeLists.txt, its add_subdirectory gates in src/plugins/ and tests/cpp/plugins/, and the revohuman entry in the plugins TeleopSession monitors, with its test case.

The glove's WRIST is a point of its mechanical model, not the anatomical wrist centre. The device page and the plugin README give the nominal offset between the two and how to set the wrist source for it.

Changes since the last review

Appended to the squashed commit; nothing is force-pushed.

  • install.sh is gone: the plugin's CMake downloads and checks the SDK, so cmake -B build -DBUILD_PLUGIN_REVOHUMAN=ON && cmake --build build builds it with any other plugins.
  • The pipeline owns each injected hand as a move-only object, so a push without a hand cannot be written; PipelineConfig became constants, and a reopened glove keeps nothing of the earlier glove's tactile metadata.
  • The glove source holds the SDK and the autokit in RAII members, throws on SDK errors that are not an empty queue or the end of a glove's stream, maps SDK log levels to spdlog levels, and reports the tactile of a glove without a taxel layout as failed. Tactile samples own their values.
  • The hand model names the SDK's points instead of indexing them, is built by a constructor, and keeps its fitting out of the public header.
  • The SDK pin moves to the re-published 0.1.3 assets, which regenerate the taxel positions and normals on the glove surface; the point order, the links and the hand models are unchanged, so the hand fits do not change.

Changes in the previous round

  • The plugin is rebuilt on the C SDK 0.1.3 release and takes from the SDK what it computed itself before: opening and reconnecting the gloves, the hand link poses and the taxel layout. The device clock, event log, serialization, SHA-256 and pose-math code and the separate kinematics and live libraries are gone with their tests.
  • New: split tactile, the SIGUSR1 tare and the start-up hold above.
  • The commits are squashed into one on current main. tests/cpp/plugins/CMakeLists.txt, which main has also changed, keeps both blocks.

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Testing

At this commit, from a clean source tree:

  • On Ubuntu 22.04 x86_64, cmake -B build -DBUILD_PLUGIN_REVOHUMAN=ON with no SDK given downloads the pinned SDK release anonymously and checks its SHA-256, and cmake --install build --component revohuman installs the plugin with the SDK library next to it. The aarch64 release was downloaded anonymously and its SHA-256 checked against the pin.
  • On Ubuntu 22.04 x86_64, a full build with the pinned SDK release: no warnings from the plugin, and the C++ format check passes. revohuman_core_tests (24 test cases, 756 assertions) and the full ctest (548 tests) pass. Two tests are skipped: this plugin's "A device that cannot be opened reports why", which skips when run as root, and one manus_calibration test.
  • SKIP=check-copyright-year pre-commit run --all-files: all hooks pass.
  • make current-docs (sphinx-build -W --keep-going): build succeeded.

With two RevoHuman PTV1 gloves (firmware 0.20.4) on x86_64, before this round's changes (not repeated on the appended commits):

  • A 90 s two-hand recording of the tactile and joint-state collections through DeviceIOSession, with a SIGUSR1 tare at 30 s. Each hand's tactile ran split at about 215 Hz and its joint states at 200 Hz. Each hand's tactile paused once, for 245 ms, at the tare; no other gap in any of the four collections exceeded 20 ms.
  • A 600 s run of the plugin's glove source and pipeline: every split tactile sample of both hands was pushed, none was skipped, and the tactile status stayed live throughout.

Video

The Tactile Metadata Editor (scripts/tactile_metadata) in Live mode, fed by the plugin with RevoHuman PTV1 gloves.

revohuman_tactile_editor_live.github.mp4

Device conformance

Device conformance
Suite:    hand
Take:     revohuman_2026-11-12_033507
Verdict:  fail
Archive:  revohuman_2026-11-12_033507-hand.fail.zip, sha256 d109451094c3
Notes:    No wrist source was connected, so the five checks that need one fail:
          values.zero_pose_on_valid_joint (WRIST stays at the origin),
          placement.not_at_origin, placement.wrist_not_frozen,
          segmentation.labelled_step_actually_performed and
          segmentation.step_order_matches_labels. The ten checks that depend
          on the step order read n/a. skeleton.joint_index_assignment fails on
          the thumb base (65% of frames on the index half, 90% required).
          Recorded at an earlier development commit that is not on this PR;
          packaged with the checker at d2cc0a27, the head of this PR before
          it was squashed. Details below.

Note: this take was recorded at an earlier development commit that is not on this PR (the repo_commit in the take's .json). The archive was packaged with the checker at d2cc0a27, unmodified (tool in report.json), which was the head of this PR before it was squashed onto current main. The checker code under src/python/isaaccapture/cts/hand/ is the same at the recording commit, at d2cc0a27 and at the head of this PR, except that at the head of this PR checker/setup_env.sh has the change main has since made to how the checker's venv is installed. So the checker can be re-run on the take at the head of this PR. The plugin's mapping to the OpenXR joints has been reworked since this take, so the take shows the earlier mapping.

Summary

  1. The latest hardware revision changed the structure of the thumb base, so the OpenXR skeleton output by the plugin needs to be updated to match. Our algorithm team is working on this update.
  2. Current results: apart from the checks that need a wrist pose or depend on one (listed under Scope), all checks pass, with two exceptions:
    • The thumb base is slightly misplaced because the OpenXR skeleton has not been updated yet. See below.
    • The right fist was not clenched tightly enough, in the run of the four gesture checks on their own (see Results). This is a performance issue and a retake will resolve it.

Scope

As requested, this take covers only the three gestures that do not depend on the wrist: open hand, pinch and fist. No wrist source was connected during recording, so the five checks that need one read FAIL:

  • values.zero_pose_on_valid_joint: WRIST stays at the origin. It is one of the 22 valid joints, hence 4.5% of samples.
  • placement.not_at_origin and placement.wrist_not_frozen: no wrist pose is applied.
  • segmentation.labelled_step_actually_performed: palms together and tip roll need the hands to move and turn.
  • segmentation.step_order_matches_labels: the order is judged from how far each hand turns.

The ten checks that depend on the step order then read n/a, and consistency.position_orientation_same_frame reads n/a because the hand did not turn.

Results for the three gestures

Gesture Check Left Right
Open hand (flat, at start and end) posture.flat_hand_extension pass, straightness 0.98 / 0.98 pass, straightness 0.98 / 0.98
Pinch pinch.finger_identity pass, 4/4 land on the named finger pass, 4/4
Pinch distance (index / middle / ring / little) pinch.contact_distance meas, 14 / 13 / 20 / 22 mm meas, 24 / 18 / 14 / 10 mm
Fist posture.fist_closure pass, 0.57 FAIL, 0.70 (must be ≤ 0.60)
  • The right fist was not clenched tightly enough. The checker attributes this to performance, so the three gestures alone give retake.
  • In the full check, these four checks depend on the step-order check, which needs the wrist, so they read n/a. The measured values are the same.

To reproduce, run only these four checks:

python -m hand_cts.cli <take>-hand.mcap \
    --check posture.flat_hand_extension --check posture.fist_closure \
    --check pinch.finger_identity --check pinch.contact_distance

Thumb base position: skeleton.joint_index_assignment

This check does not depend on the wrist. It reads FAIL.

  • How it is judged: the thumb base (THUMB_METACARPAL) is projected onto the line from INDEX_PROXIMAL to LITTLE_PROXIMAL and must fall on the index half. It must do so in at least 90% of frames to pass.
  • Result: 65.2% of frames for the left hand and 65.1% for the right. The other two parts of the same check are both at 100%: the order of the four finger bases across the palm, and the root-to-tip order along each finger when extended. Only the thumb base position is off.
  • Cause: the latest hardware revision changed the structure of the thumb base, and the OpenXR skeleton output by the plugin has not yet been updated to match. As a result, the thumb base is slightly misplaced.

Checklist

  • I have read and understood the contribution guidelines
  • I have run the linter and formatter with SKIP=check-copyright-year pre-commit run --all-files
  • I have made corresponding changes to the documentation
  • I have added tests that prove my fix/feature works (or explained why not)
  • I have signed off all my commits (git commit -s) per the DCO

Summary by CodeRabbit

  • New Features
    • Added a RevoHuman glove plugin for Linux, supporting hand tracking, joint-state data, and tactile sensing.
    • Supports glove discovery, pairing, reconnection, wrist-pose selection, and device status reporting.
  • Documentation
    • Added setup, SDK requirements, usage, supported-device details, and troubleshooting guidance.
  • Build & Testing
    • Added an opt-in build option and coverage for plugin behavior, integration, and SDK compatibility.

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants