Common Data Types

Developer Guide

This page lists all common data type field definitions in the Wuji SDK.

Common Types

FrameHeader

Header information for each data frame.

Vector3 / Vector3F64

Three-dimensional vector. Vector3 uses f32 precision, Vector3F64 uses f64 precision (used for IMU data, ROS compatible).

Quaternion

Quaternion representing 3D rotation. Python has a single Quaternion, while C splits it into WujiQuaternionF32 and WujiQuaternionF64 to match the precision each stream carries.

Pose

Position and orientation.

Handedness

Device handedness enum, used for connecting by handedness. The C constants are WUJI_HANDEDNESS_LEFT (0) and WUJI_HANDEDNESS_RIGHT (1). The two Wuji Hand handedness getters return a raw uint8_t rather than this enum, and their encodings are opposites — see Wuji Hand Data Subscription for the convention.

ImuData

IMU sensor data, following the ROS sensor_msgs/Imu convention.

Coordinate Transforms

FrameTransform

Single coordinate transform.

FrameTransforms

Collection of coordinate transforms.

Recording Types

For complete usage and code examples, see Data Recording.

TopicRecorder

MCAP recording session configurator. Register channels, then call start() to begin recording.

RecordingHandle

Recording control handle returned by TopicRecorder.start().

RecordingSummary

Recording statistics returned by handle.stop().

channels is ordered by channel ID and includes registered channels with no messages. Each ChannelRecordingSummary contains channel_id, channel_name, and frame_count. duration_s includes pauses and buffer draining during stop. It excludes MCAP file finalization, flushing, and waiting for monitor callbacks to exit.

QualityMetrics

Real-time quality metrics (5-second sliding window).

ChannelHealth

Per-channel health details (elements of channels on QualityMetrics).

QualitySummary

Aggregate recording quality statistics.

RecordingAlert

Quality alert.

RecordingStatus

Recording runtime status.

Device-Specific Types

Error Code Categories

The following three categories of error codes are unrelated. A value from one category means nothing in another:

Use Code Values

Device fault codes use the 0xSCNN layout. Don’t decode the hexadecimal digits yourself. Treat each complete code as an opaque identifier for logs, user displays, and bug reports.

Read Decoded Results

In Python, describe_error() returns a dict. Read values by key, such as info["severity"] and info["clear_policy"].

The following fields contain text from the firmware’s error catalog:

Handle None Results

When describe_error(code) returns None, check the original error code:

For the differences between SDK exceptions, C return codes, and device fault codes, see the Error Code Index. For device fault-code lookup, see Fault Logs and Error Codes.

C SDK conventions

This section covers C SDK initialization, error handling, memory lifetime, callback constraints, and CMake setup. Device-specific capabilities remain documented on the corresponding product pages.

Initialization and conventions

Initialization

Call once at process start and release at shutdown:

#include "wuji_sdk.h"

if (wuji_init(NULL) != WUJI_STATUS_OK) {
    fprintf(stderr, "init failed: %s\n", wuji_last_error());
    return 1;
}

// ... your code

wuji_shutdown();

Return value taxonomy

• WujiStatus — most operations (wuji_init / wuji_scan / wuji_connect / opening subscriptions, etc.). WUJI_STATUS_OK means success. On failure, retrieve the per-thread error string via wuji_last_error().
• int32_t — metadata readers (wuji_dev_serial_number / wuji_dev_device_name) return the number of bytes written.
• uint8_t — status query wuji_dev_is_connected.
• void — wuji_shutdown and resource cleanup functions.

Resource cleanup functions

• wuji_discovered_free — release the device list returned by wuji_scan
• wuji_dev_release — paired with wuji_connect, release the device handle after disconnecting
• wuji_sub_close — close the subscription handle

User Info Struct

WujiUserInfo holds seven fields: user_id, display_name, description, external_id, is_default, created_at, and updated_at. wuji_update_user takes a WujiUserUpdate carrying only the fields to change, and setting clear_description / clear_external_id clears the matching value. For the full user management API list, see SDK Users and Calibration Data.

Usage constraints

C SDK users must observe the following constraints to avoid use-after-free, deadlocks, and reading stale error strings.

• A typed callback’s frame pointer is valid only for the duration of the callback. Heap fields are released after the callback returns. Copy whatever you need to retain inside the callback. Do not store the pointer.
• Never call wuji_sub_close from inside that subscription’s own callback. close joins the worker thread and will deadlock if called from the callback itself. Close from a different thread.
• The return value of wuji_last_error() is only valid until the next wuji_* call on the same thread. Copy the message immediately if you need to retain it.
• END and ERROR are terminal frames — no further data will arrive after them, but you still need to call wuji_sub_close to release the subscription handle.
• String getters use a two-call query: first call with buf=NULL, buf_len=0 to read *needed (required bytes including NUL), then allocate and call again to fill. Passing an undersized buffer returns WUJI_STATUS_ERR_BUFFER_TOO_SMALL and never truncates.
• Whole-hand batch reads (get_all_effort_limit / get_all_mit_params) return a flat-20 array plus an online bitmap. Use the WUJI_JOINT_ONLINE(mask, i) macro to check slot validity, otherwise you will read offline-joint placeholders (0 or NaN).
• The calibration feedback callback runs on the calibration worker thread, and the feedback pointer is valid only during the callback. The SDK guards the session calls made from inside it rather than deadlocking: wuji_glove_calibration_wait and wuji_glove_calibration_try_finish return WUJI_STATUS_ERR_INVALID_ARG, and wuji_glove_calibration_session_free records the reason in wuji_last_error() and skips the release — so the session stays alive and you must free it again after the callback returns. wuji_glove_calibration_cancel is safe to call from the callback. Free the session with wuji_glove_calibration_session_free and the result with wuji_glove_calibration_result_free.
• WujiUserInfo holds heap strings: free a single struct with wuji_user_info_free, and free an array returned by wuji_list_users with wuji_user_info_array_free.

Python equivalents

The table below maps each C API to its Python counterpart by capability. For full usage of cross-device capabilities and per-device APIs, see the C API Reference.

CMake project example

A complete runnable C project (with CMakeLists.txt plus a subscription callback demo) lives in the examples/c/ directory of the wuji-sdk repo, organized into examples/c/wuji_glove/ (stream output rate control, custom hand model for online IK, SDK user management, and hand model calibration), examples/c/wuji_hand_2/ (joint-state subscriptions, control actions, device info, fingertip tactile data, stream output rate control, flash-log export, opposition replay, and MIT sweep), and examples/c/wuji_hand/ (subscriptions, publishing, grasp loops, and tactile status) subdirectories. See that directory’s README for build instructions. Minimal link:

• Linux

• macOS arm64

cc my_app.c -I "${SDK}/include" -L "${SDK}/lib" -lwuji_sdk_c -o my_app
LD_LIBRARY_PATH="${SDK}/lib" ./my_app

cc my_app.c -I "${SDK}/include" -L "${SDK}/lib" \
  -lwuji_sdk_c -Wl,-rpath,"${SDK}/lib" -o my_app
./my_app

Use an absolute path for ${SDK}, the extracted package directory. In CMake, set WUJI_SDK_INCLUDE_DIR to ${SDK}/include, and set WUJI_SDK_LIB to ${SDK}/lib/libwuji_sdk_c.so on Linux or ${SDK}/lib/libwuji_sdk_c.dylib on macOS.

Interface List

Python and C types map one to one with the same field semantics. Naming and memory layout follow each language’s conventions:

Three representation differences stand out. A Python str field is a fixed-length char array in C, such as frame_id[32] and parent_frame_id[32]. A Python list field is a pointer plus a length in C, such as transforms and transforms_len on WujiFrameTransforms. Python has a single Quaternion, while C splits it into WujiQuaternionF32 and WujiQuaternionF64 to match the precision each stream carries. C frame pointers stay valid only for the duration of a subscription callback, so copy anything you need to keep. See the C Interface Reference for the full constraints.