Documentation Knowledge Base › Software › Wuji SDK
Appendix
Operations and Appendix
This page collects term definitions, error code carriers, and version requirements. The full explanations stay in the capability chapters.
Glossary
| Term | Description |
|---|---|
| Resource | The uniform representation of a device capability in the SDK, reached through semantic methods. A resource is either a readable or writable parameter or a subscribable topic. To list them, see SDK Users and Calibration Data — Listing All Resources |
| Topic | The identifier of a subscribable data stream. One topic carries one sensor output or computed result |
| Subscription | The handle that receives data from a topic, with async, sync non-blocking, and callback delivery. See Data Subscription Mechanism — Subscription Modes |
| Global resource | A resource that merges data from every connected device, subscribed through the SdkManager-level API. See Data Subscription Mechanism — Cross-device Merged Subscription |
| Derived stream | A stream computed from a device source stream, such as hand_joint_angles, hand_skeleton, tip_poses, and imu_data_palm. A derived stream follows the rate of its source stream and can’t be adjusted on its own |
| Output rate | The frequency at which the firmware pushes a stream. To change it, see Data Subscription Mechanism — Adjusting the Stream Output Rate |
| MCAP | The recording file format. Multiple sensor streams are written to one file in sync. See Data Recording |
| Episode | A self-contained segment of a recording session. Switching writes a new file and reuses the registered channels. See Data Recording — Episode Switching |
| SDK user | The isolation unit for local parameters and calibration files, keyed by operator. See SDK Users and Calibration Data — SDK User Management |
| Hand model calibration | The process that builds a hand model for the current SDK user and hand side. Artifacts are stored per user. See SDK Users and Calibration Data — Calibration |
| Hand retargeting | The computation that maps 21 MediaPipe-format hand keypoints to a 20-dimensional joint angle command. See Hand Retargeting |
| Handedness | The left or right hand marker on a frame or device. For the field definition, see Common Data Types — Handedness |
| FrameHeader | The header shared by data frames, carrying frame_id and the 64-bit microsecond timestamp timestamp_us. See Common Data Types — FrameHeader |
Sync offset (offset_us) | The difference between the device clock and the host UTC clock computed by one synchronization, in microseconds |
Round trip (round_trip_us) | The round-trip time of one synchronization. A smaller value means better sync quality. See Time Synchronization and Coordinate Transforms — Sync accuracy |
| Typed callback | The strongly typed subscription callback the C API provides per device type. The frame pointer is valid only during the callback. See C API Reference — Usage constraints |
Error Code Index
SDK errors appear in several forms. Device-side codes from different categories cannot be interpreted interchangeably.
| Carrier | Shape | Where it comes from | How to decode |
|---|---|---|---|
| Python exception | WujiException and more specific subclasses | Most Python API calls | Catch it and branch on the error name. For common types, see Python Exception Types on this page |
| C return code | The WujiStatus enum | Most C API calls | WUJI_STATUS_OK means success. On failure, read the current thread’s description with wuji_last_error(). See C API Reference — Initialization and conventions |
| Full device fault code | AA-BB-CCCC string | Wuji Hand 2 and Wuji Glove fault logs | See Fault Logs and Error Codes |
| Device fault code | u16 | Wuji Hand 2 joint diagnostics, error status, error history, and encoder calibration results | Decode with WujiHand2.describe_error() or wuji_hand_2_describe_error(). |
| Encoder calibration code | u8 | enc1_error_code and enc2_error_code in encoder calibration results | A calibration-only enum. Read enc1_error_name and enc2_error_name from the result object, and don’t pass the value to the decode function. |
| Wuji Hand error bitfield | u32 | error_code in Wuji Hand joint diagnostics | One bit per fault condition. Check it bit by bit, and don’t pass the value to the decode function. |
Code 0 means no active fault and isn’t in the catalog. When a nonzero code won’t decode, keep the raw value for logs and bug reports.
Python Exception Types
Most Python API calls raise WujiException on failure, and the message carries an error type prefix. Some APIs raise more specific exceptions for file system or validation errors. Check the API reference for details.
| Error | Description |
|---|---|
DeviceNotFound | Specified device not found |
DeviceMismatch | Device type mismatch |
Disconnected | Device has been disconnected |
ConnectionTimeout | Connection timed out |
OperationTimeout | Operation timed out |
PathNotFound | Resource path does not exist |
SchemaMismatch | Data type mismatch |
NoData | No data available |
StreamClosed | Subscription stream has been closed |
For catch-and-branch examples, see Best Practices — Error Handling. For reconnecting after a drop, see Best Practices — Reconnection Strategy.
Version Compatibility
For runtime requirements, see Installation and Environment — System Requirements. Hand retargeting ships prebuilt packages for Linux x86_64, Linux aarch64, and macOS arm64. See Hand Retargeting — Platform and limits.
The capabilities below set a minimum firmware or SDK version. Everything not listed here works with the installed SDK version.
| Capability | Minimum firmware | Minimum SDK | Details |
|---|---|---|---|
| Fingertip tactile data | Wuji Hand 2 v2.1.0 | v2026.7.21 | Fingertip Tactile — Requirements |
| Fingertip tactile stream rate control | Wuji Hand 2 v2.3.0 | v2026.8.17 | Fingertip Tactile — Requirements |
| Normalized per-point force format | Wuji Hand 2 v2.4.0 | v2026.8.17 | Fingertip Tactile — Self-Describing Data Format |
| Contact point placement on the hand model | Wuji Hand 2 v2.5.0 | Follows firmware | Fingertip Tactile — Place Points on the Hand Model |
| Application point of the resultant force | Wuji Hand 2 v2.6.0 | Follows firmware | Fingertip Tactile — Place Points on the Hand Model |
NodeOfflineError when calibration hits an offline finger | Wuji Hand 2 v2.6.0 | v2026.8.31 | Fingertip Tactile — Zero-Baseline Calibration and Status |
| Flash log export | No extra requirement | v2026.8.31 | Troubleshooting — Device Log Export |
| Concurrent Flash log export on one device | Wuji Hand 2 v2.6.0 | v2026.8.31 | Wuji Hand 2 Diagnostics and Logs — Flash Log Export |
For the full change history, see the Changelog.