Documentation Guide

Changelog

Version updates and changelog for Wuji SDK

Introduction

Wuji SDK overview, core features, system requirements, and installation

• Overview
  Product positioning, supported devices, and core features
• Getting Started
  System requirements, Python and C SDK installation

Quick Start

Three complete examples to get started quickly

• Callback Subscription (0.subscribe_callback.py)
  Receive tactile data using callback functions
• Async Subscription (1.subscribe_async.py)
  Receive tactile data using async/await
• Data Recording (2.recording.py)
  Record multi-channel sensor data to MCAP files
• Wuji Hand Quick Start
  Connect a Wuji Hand through wuji-sdk and run a clench-and-release cycle

Device Discovery & Connection

Discover, connect, and manage Wuji devices

• Device Discovery
  Scan for Wuji devices on the local network
• Connecting to a Device
  Five connect modes (auto, SN, address, USB, handedness) plus ConnectOptions
• Multi-device Management
  Operate multiple devices simultaneously
• Disconnecting
  Disconnect a single device or all devices

Data Subscription

Subscribe to device data streams

• Subscription Modes
  Async, synchronous non-blocking, and callback modes
• Closing Subscriptions
  Unsubscribe and release resources
• Cross-device Merged Subscription
  Subscribe to global resources merged from all devices
• Available Data Streams
  Device-specific data streams with links to device documentation
• Dexterous Hand Data Subscription
  Subscribe to 20-joint state, send real-time commands, set effort limits, and stream IMU and tactile glove data

Data Recording

Record multi-channel sensor data to MCAP files

• Compression Options
  LZ4, Zstd, or no compression
• Recording Global Resources
  Record cross-device merged resources alongside device data
• Pause and Resume
  Pause and resume recording without losing session state
• Episode Switching
  Split continuous capture into separate files
• Quality Monitoring
  Real-time frame drop rate, jitter, and sync offset
• Recording Summary
  Aggregate statistics returned when recording stops
• Examples
  Basic and full recording examples

Data Structure Reference

Common data type field definitions

• Common Types
  FrameHeader, Vector3, Quaternion, Pose
• Coordinate Transforms
  FrameTransform, FrameTransforms
• Recording Types
  TopicRecorder, RecordingHandle, RecordingSummary, QualityMetrics
• Wuji Hand 2 Types
  WujiHand2 feedback and command schemas, online joints identified by nid
• Wuji Hand Types
  HandJointState, HandJointCommand, and TactileGloveFrame

Device Parameters & Calibration

Read/write device parameters, user isolation, and calibration entry

• Reading Parameters
  Serial number, firmware version, IP address, etc.
• Writing Parameters
  Modify IP, port, and other writable parameters
• Device Operations
  Parameter persistence, reboot, and other device operations vary by product
• SDK User Management
  Isolate SDK local parameters and calibration files per operator
• User Data Export and Import
  Pack a user's data into a zip to back it up or move hosts
• Calibration
  Hand models per SDK user and hand side, parameters and tactile calibration per serial number
• Available Parameters
  Device-specific parameters with links to device documentation
• Listing All Resources
  List all resources, parameters, and topics on the device

Time Synchronization

Timestamp semantics, PTP-like sync mechanism, and manual sync API

• Data frame timestamps
  FrameHeader.timestamp_us semantics before and after sync, stamping time, and derived-data timestamp sources
• How synchronization works
  NTP four-timestamp client-driven sync flow
• Automatic synchronization
  ConnectOptions.auto_time_sync_interval_ms configuration
• Manual synchronization
  sync_time() API and TimeSyncResult fields
• Timestamp monotonicity
  Strictly monotonic across syncs, safe for ordering frames directly
• Sync accuracy
  round_trip_us as a quality indicator

Hand Retargeting

Map 21 hand keypoints to 20 joint angle commands

• Quick start
  Create a RetargetSession and run per-frame retargeting
• API reference
  for_hand, step, and reset
• Input format
  MediaPipe Hands 21-landmark convention and units
• Live teleoperation example
  Wuji Glove-driven dexterous hand control example
• Platform and limits
  Linux x86_64/aarch64 only, precompiled extension

Best Practices

Error handling, reconnection, multi-device, and logging

• Error Handling
  WujiException with 8 error types
• Reconnection Strategy
  Automatic reconnection with exponential backoff
• Multi-device Coordination
  Patterns and considerations for parallel multi-device operations
• Log Control
  6 log level configurations
• Device Logging
  Read device-side defmt logs
• Recording Best Practices
  Episode management, quality monitoring, and storage tips
• Performance Optimization
  Reduce subscriptions, close unused subscriptions promptly

Troubleshooting

Problem-based troubleshooting guide

• Installation
  SDK installation failure resolution
• Runtime Errors
  Exception message reference table and data latency/frame drop troubleshooting
• Compatibility
  SDK and firmware version compatibility
• Support
  Contact technical support for unresolved issues

C API Reference

C API reference with Python equivalents

• Initialization and conventions
  wuji_init/shutdown + return value taxonomy + resource cleanup functions
• Device discovery and connection
  wuji_scan / wuji_connect / target and options
• SDK User Management
  Create, switch, and update SDK users from C + WujiUserInfo cleanup
• User Data Export and Import
  Export, preview, and import user data bundles from C
• Subscribe to per-device data streams
  typed wuji_<device>_subscribe_* callbacks
• Wuji Hand 2 C API
  C-side WujiHand2 interface with 20-joint masks and subscription feedback
• Wuji Hand C API
  Wuji Hand connection and control, real-time commands and controller, paired tactile glove (Linux gnu tarball only)
• Wuji Glove resource API
  Wuji Glove exposes resource APIs aligned with Python
• Glove tactile contact calibration
  wuji_glove_calibrate_tactile_blocking runs the guided tactile contact calibration in one call: you record a few prompted hand motions, then the SDK collects the data, validates it, and trains the model. See Wuji Glove Tactile Data for the streams.
• Subscribe to global resources
  wuji_subscribe_tf / wuji_subscribe_tf_static
• Retargeting
  Maps 21 human hand keypoints (MediaPipe order) to 20 joint angles in firmware order, matching the Python RetargetSession. For concepts and input format, see Hand Retargeting.
• Usage constraints
  Callback pointer lifetime, no self-close, wuji_last_error per-thread semantics, END/ERROR terminal frames
• Python equivalents
  Python and C functions mapped side-by-side
• CMake project example
  Minimal cc link command and CMake project pointer