> ## Documentation Index > Fetch the complete documentation index at: https://docs.wuji.tech/llms.txt > Use this file to discover all available pages before exploring further. # C API Reference Wuji SDK ships a C API (`libwuji_sdk_c.so` + `wuji_sdk.h`) with the same semantics as the Python interface. For installation alongside Python, see [Installation and Environment](/en/docs/wuji-sdk/quick-start#installation). This page covers the C-side initialization conventions, memory and callback constraints, error code decoding, and project build setup. Per-device C APIs live with each product's docs: [Wuji Hand 2 SDK Reference](/en/docs/wuji-hand/latest/sdk-reference) and [Wuji Glove SDK and Data Reference](/en/docs/wuji-glove/sdk-data-reference). Cross-device capabilities live in the capability chapters, each with an operation / Python / C table: [Device Discovery & Connection](/en/docs/wuji-sdk/device-connection), [SDK Users and Calibration Data](/en/docs/wuji-sdk/device-params), [Data Subscription Mechanism](/en/docs/wuji-sdk/data-subscription), [Time Synchronization and Coordinate Transforms](/en/docs/wuji-sdk/time-sync), and [Hand Retargeting](/en/docs/wuji-sdk/retargeting). The complete typed callback signatures and struct definitions live in `include/wuji_sdk.h` of the extracted tarball (download it from [wuji-sdk Releases](https://github.com/wuji-technology/wuji-sdk/releases)). The CMake example and build instructions are in the [`examples/c/` directory of the wuji-sdk repo](https://github.com/wuji-technology/wuji-sdk/blob/main/examples/c/README.md). ## Initialization and conventions **Initialization** Call once at process start and release at shutdown: ```c theme={null} #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](/en/docs/wuji-sdk/device-params#sdk-user-management). ## Error Code Description `wuji_hand_2_describe_error` is a static function (no device connection needed) that decodes a device fault code (from `joint_diagnostics`'s `error_code_current` — the same values carried by the error history and calibration results in the Python SDK) into `WujiErrorInfo`. It accepts device fault codes only. Calibration in the Python SDK also reports a separate encoder-only error byte — that one is a different, unrelated enum and must not be passed in. The `WujiHandJointDiagnostics.error_code` bitfield from Wuji Hand joint diagnostics (returned by `wuji_hand_get_all_diagnostics`) must not be passed in either: ```c theme={null} WujiErrorInfo info = {0}; // 0x2102 = Overcurrent (ImmediateStop / ManualClear), a real production fault code if (wuji_hand_2_describe_error(0x2102, &info) == WUJI_STATUS_OK) { printf("name=%s severity=%s\ndesc=%s\ncause=%s\n", info.name, info.severity, info.desc, info.cause); } ``` Unknown codes return `WUJI_STATUS_ERR_NOT_FOUND`. `severity` values: `Warning` / `DeferredStop` / `ImmediateStop` / `Fatal`. `clear_policy` values: `AutoClear` / `ManualClear` / `NonClearable`. ## 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 the cross-device capabilities, see the capability chapters listed at the top of this page. For per-device APIs, see the matching section on this page.
CapabilityCPython
Initwuji\_init(NULL)SdkManager.instance()
Scanwuji\_scan(\&devs, \&count)manager.scan()
Connectwuji\_connect(\&target, alias, \&opts, \&dev)manager.connect(...) / manager.auto\_connect(...)
Default connect optionswuji\_connect\_options\_default()ConnectOptions()
Device subscribewuji\_glove\_subscribe\_tactile(dev, cb, user, \&sub)glove.tactile().subscribe\_with\_callback(...)
Global subscribewuji\_subscribe\_tf(cb, user, \&sub)manager.tf().subscribe()
Stream output ratewuji\_sub\_set\_rate(sub, hz, \&actual)sub.set\_rate(hz)
Hand 2 control actionwuji\_hand\_2\_enable(dev, mask)hand.enable(joints=mask)
Hand 2 realtime commandwuji\_hand\_2\_joint\_command\_publish + wuji\_joint\_command\_publisher\_sendhand.joint\_command().publish().send(\[...])
Hand 2 joint state subscribewuji\_hand\_2\_subscribe\_joint\_stateshand.joint\_states().subscribe()
Hand 2 joint diagnostics subscribewuji\_hand\_2\_subscribe\_joint\_diagnosticshand.joint\_diagnostics().subscribe()
Hand 2 IMU subscribewuji\_hand\_2\_subscribe\_imuhand.imu().subscribe()
Hand 2 error descriptionwuji\_hand\_2\_describe\_error(code, \&info)WujiHand2.describe\_error(code)
Hand 2 flash log exportwuji\_hand\_2\_export\_flash\_logs + wuji\_hand\_2\_flash\_log\_export\_freehand.export\_flash\_logs()
Hand connect (USB SN)wuji\_hand\_connect\_sn(sn, alias, \&dev)WujiHand.connect\_sn(sn, alias)
Hand joint state subscribewuji\_hand\_subscribe\_joint\_stateshand.joint\_states().subscribe()
Hand realtime commandwuji\_hand\_joint\_command\_publish + wuji\_hand\_joint\_command\_publisher\_sendhand.joint\_command().publish().send(\[...])
Hand realtime controllerwuji\_hand\_realtime\_controller\_open / \_set\_target\_position / *get\_actual*\*hand.realtime\_controller(LowPass(...))
Glove time syncwuji\_glove\_sync\_time(dev, \&tsr)glove.sync\_time()
Glove hand model pathwuji\_glove\_get\_hand\_model\_path / wuji\_glove\_set\_hand\_model\_pathglove.hand\_model\_path().get() / .set(path)
SDK user managementwuji\_create\_user / wuji\_switch\_user / wuji\_list\_usersmanager.create\_user() / switch\_user() / list\_users()
User data export and importwuji\_user\_data\_export / wuji\_user\_data\_preview / wuji\_user\_data\_importmanager.export\_user\_data() / preview\_user\_data() / import\_user\_data()
Glove hand model calibration (async)wuji\_glove\_calibration\_start + wuji\_glove\_calibration\_try\_finishglove.calibrate()
Glove hand model calibration (sync)wuji\_glove\_calibrateglove.calibrate\_blocking()
Glove tactile contact calibration (sync)wuji\_glove\_calibrate\_tactile\_blockingglove.calibrate\_tactile\_blocking()
Disconnectwuji\_dev\_disconnect + wuji\_dev\_releasedevice.disconnect()
## 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](https://github.com/wuji-technology/wuji-sdk/blob/main/examples/c/README.md), 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](/en/docs/wuji-sdk/wuji-hand-2-tactile), 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: ```bash theme={null} cc my_app.c -I "${SDK}/include" -L "${SDK}/lib" -lwuji_sdk_c -o my_app LD_LIBRARY_PATH="${SDK}/lib" ./my_app ``` `${SDK}` is the extracted tarball root. The CMake project uses `-DWUJI_SDK_INCLUDE_DIR` and `-DWUJI_SDK_LIB` to point at the same paths. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.