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
  Auto-connect, connect by SN, or connect by address
• 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
• Wuji Hand Data Subscription
  Subscribe to 20-joint state, send realtime commands, set effort limits, and stream 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 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
• Calibration
  Results scoped by SDK user and device serial number, procedures per product
• 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
• 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

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
• Subscribe to per-device data streams
  typed wuji_<device>_subscribe_* callbacks
• Subscribe to global resources
  wuji_subscribe_tf / wuji_subscribe_tf_static
• 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