SDK Users and Calibration Data

Developer Guide

Common device parameters include identity parameters (serial number, firmware version, handedness) and network parameters (IP address, data port). Every device connected through the Wuji SDK (Wuji Hand 2, Wuji Glove, and more) accesses them through the same resource-style API.

This page covers four cross-device mechanisms: parameter read/write, SDK user management with data import/export, local calibration storage with per-user isolation, and resource introspection. For each product’s parameter list and device operations, see the product docs linked in each section.

Reading Parameters

Read device properties through the semantic API:

• Python

• C

sn = glove.sn().get()                # Serial number
version = glove.version().get()      # Firmware version
hand_side = glove.hand_side().get()  # Hand side ("left" or "right")
ip = glove.ip().get()                # IP address
port = glove.port().get()            # Data port

// String parameters use a two-step size query: probe, then allocate and fill
size_t needed = 0;
wuji_glove_get_sn(glove, NULL, 0, &needed);
char *sn = malloc(needed);
wuji_glove_get_sn(glove, sn, needed, NULL);   // Serial number

uint16_t port = 0;
wuji_glove_get_port(glove, &port);            // Data port

// Firmware version, hand side, and IP address follow the same two-step query
// wuji_glove_get_version / wuji_glove_get_hand_side / wuji_glove_get_ip

free(sn);

Writing Parameters

Some parameters support writing:

• Python

• C

glove.ip().set("192.168.1.200")     # Change IP address
glove.port().set(50001)             # Change data port

wuji_glove_set_ip(glove, "192.168.1.200");   // Change IP address
wuji_glove_set_port(glove, 50001);           // Change data port

The IP must be unique on the subnet. Avoid addresses already used by other devices or the host network adapter.

Device Operations

Parameter persistence, reboot, and other device operations vary by product:

SDK User Management

When several operators share the same device, calibration and local parameters from one operator overwrite another’s. The SDK keeps a local user profile per operator at ~/.wuji/sdk/users/<user_id>/, isolating each user’s parameter and calibration files.

Without a named user, parameter files and tactile calibration land in ~/.wuji/sdk/params/ and ~/.wuji/sdk/tactile/ directly, and pose calibration isn’t available at all. Create a named user when you need to isolate by operator, or when you need pose calibration:

• Python

• C

from wuji_sdk import SdkManager

manager = SdkManager.instance()

# Create a user
alice = manager.create_user("Alice", description="right-hand operator")

# Switch to a specific user
manager.switch_user(alice["user_id"])

# Inspect the current user
print(manager.current_user())

# List all users
for user in manager.list_users():
    marker = "*" if user["is_default"] else " "
    print(f"{marker} {user['display_name']} ({user['user_id']})")

# Switch back to the default user
manager.switch_to_default_user()

// Create a user
WujiUserInfo alice = {0};
wuji_create_user("Alice", "right-hand operator", /*external_id=*/NULL, &alice);

// Switch to a specific user
WujiUserInfo current = {0};
wuji_switch_user(alice.user_id, &current);

// List all users
WujiUserInfo *users = NULL;
size_t n = 0;
wuji_list_users(&users, &n);
for (size_t i = 0; i < n; i++) {
    printf("%c %s (%s)\n", users[i].is_default ? '*' : ' ',
           users[i].display_name, users[i].user_id);
}
wuji_user_info_array_free(users, n);

// Switch back to the default user
WujiUserInfo def = {0};
wuji_switch_to_default_user(&def);

wuji_user_info_free(&alice);
wuji_user_info_free(&current);
wuji_user_info_free(&def);

Switching reloads calibration parameters for connected devices immediately, no reconnect needed. Deleting the current user automatically switches back to the default user.

For measured edges around creating, updating, switching, and deleting users, and how the change persists across processes and languages, see Local SDK User Management.

User Data Export and Import

Pack everything an SDK user owns into a single zip file to back it up or move it to another host. A bundle holds the user’s hand calibration models, the tactile model for each device, and the latest complete tactile calibration run.

• Python

• C

# Export: write everything the user owns into one zip file
report = manager.export_user_data(alice["user_id"], "alice.zip")
print(report["out_path"], report["device_sns"])

# Preview: validate a bundle and list its contents without writing anything
preview = manager.preview_user_data("alice.zip")
print(preview["owner_display_name"], preview["created_at"])
for component in preview["components"]:
    print(component["name"], component["state"], component.get("reason"))

# Import: restore the bundle to the user who created it
result = manager.import_user_data("alice.zip")
print(result["owner_user_id"], result["imported_at"])

// Export: pass "" as user_id for the default user. The path must end in .zip
if (wuji_user_data_export(alice.user_id, "alice.zip") != WUJI_STATUS_OK) {
    fprintf(stderr, "export failed: %s\n", wuji_last_error());
}

// Preview: run the full validation without writing. OK means the bundle imports
if (wuji_user_data_preview("alice.zip") != WUJI_STATUS_OK) {
    fprintf(stderr, "bundle rejected: %s\n", wuji_last_error());
}

// Import: restore the bundle to the user who created it
wuji_user_data_import("alice.zip");

In Python, all three methods return a report dict whose components list the state of each component:

Import behavior:

• The owner recorded in the bundle is created if it doesn’t exist, and the current user stays the same
• Every present component that isn’t skipped is written and overwrites that user’s existing file
• Skipping wins over writing: a skipped component is never written and never overwrites an existing file, and its state in the report is skipped. Hand models are skipped this way when the owner is the default user (which doesn’t load local hand calibration), while the other components are still written
• Validation (path safety, size caps, sha256, data format, and owner id) finishes before anything is written. Any failure raises an exception and leaves no file behind

Tactile Data Paths

The tactile model is trained in Wuji CLI tactile contact calibration. Models and calibration data are scoped by SDK user and device serial number:

model/ holds the trained tactile model (contact.safetensors and contact.npz), and calibration-data/ holds the raw calibration runs, one subdirectory per run. A complete run has one data file per guided motion, 4 in total. Export takes the latest complete run only.

sn = "WG1JA00XXXXXXXXX"

print(manager.tactile_dir(alice["user_id"], sn))
print(manager.tactile_model_paths(alice["user_id"], sn))  # dir / safetensors / npz
print(manager.tactile_run_dir(alice["user_id"], sn))

Calibration

Calibration fits the SDK’s algorithms to a specific physical device. The results are written to SDK-local parameter and model files and loaded automatically when the device subscribes to them.

Calibration files are scoped by the current SDK user first, then split into three resource types:

Parameter files and the tactile directory are still keyed by device serial number. The tactile directory holds the trained model under model/ and the latest calibration run under calibration-data/.

The pose hand URDF is stored per SDK user and hand side only (such as left_hand.urdf / right_hand.urdf), without the serial number or hand-profile dimension, so any device of the same side under the same user shares one model. The default user has no pose hand model at all: calibration and import never write one, and real-time IK always falls back to the built-in default. For Wuji Glove specifics, see Wuji Glove Calibration.

Switching the SDK user reloads the matching files for connected devices automatically, no reconnect required.

For each product’s calibration procedure, see the product docs:

• Wuji Hand 2 fingertip tactile calibration (runs on the device and doesn’t write the SDK-local calibration files described in this section): Wuji Hand 2 Fingertip Tactile — Zero-Baseline Calibration and Status
• Wuji Glove calibration procedure and APIs: Wuji Glove Calibration

Available Parameters

Listing All Resources

List all available resources, parameters, and topics on a device:

• Python

• C

# All resources
for res in glove.resources():
    print(res.path)

# Read/write parameters
for param in glove.params():
    print(param.path)

# Subscribable topics
for topic in glove.topics():
    print(topic.path)

// Read/write parameters
WujiParam *params = NULL;
size_t n = 0;
wuji_dev_list_params(glove, &params, &n);
for (size_t i = 0; i < n; i++) printf("%s\n", params[i].path);
wuji_param_array_free(params, n);

// Subscribable topics
WujiTopic *topics = NULL;
size_t m = 0;
wuji_dev_list_topics(glove, &topics, &m);
for (size_t i = 0; i < m; i++) printf("%s\n", topics[i].path);
wuji_topic_array_free(topics, m);

Interface List

Every C string getter uses a two-step size query: pass buf = NULL and buf_len = 0 to learn the required byte count, then allocate and call again to fill the buffer. APIs that return a report dictionary in Python return only a WujiStatus in C, because the per-component detail doesn’t cross the FFI boundary. For the WujiUserInfo and WujiUserUpdate fields, memory ownership, and the release functions, see the C Interface Reference.