libwuji_sdk_c.so + wuji_sdk.h），与 Python 接口语义一致。安装方式与 Python 并列见 安装与环境。
本页覆盖 C 侧的初始化约定、内存与回调约束、错误码解码与工程构建。设备专属的 C 接口随各产品文档给出：Wuji Hand 2 SDK 接口与 Wuji Glove SDK 与数据参考。跨设备通用能力在各能力章按「操作 / Python / C」三列并列给出：设备发现与连接、SDK 用户与标定数据、数据订阅机制、时间同步与坐标变换与手部重定向。
完整 typed 回调与结构体定义参见 SDK tarball（从 wuji-sdk Releases 下载）解压后的 include/wuji_sdk.h，配套 CMake 工程示例与构建说明见 wuji-sdk 仓库 examples/c/ 目录。
初始化与约定
初始化 进程级初始化一次，结束时释放：WujiStatus— 多数操作（wuji_init/wuji_scan/wuji_connect/ 订阅打开等），WUJI_STATUS_OK表示成功，失败时通过wuji_last_error()获取当前线程错误描述。int32_t— 元信息读取（wuji_dev_serial_number/wuji_dev_device_name）返回写入字节数。uint8_t— 状态查询wuji_dev_is_connected。void—wuji_shutdown与资源释放函数。
wuji_discovered_free—wuji_scan后释放设备列表wuji_dev_release— 与wuji_connect配套，断开后释放设备句柄wuji_sub_close— 关闭订阅句柄
WujiUserInfo 含 7 个字段：user_id、display_name、description、external_id、is_default、created_at、updated_at。wuji_update_user 通过 WujiUserUpdate 只传要改的字段，置位 clear_description / clear_external_id 可清空对应值。用户管理的完整接口清单见 SDK 用户与标定数据。
错误码描述
wuji_hand_2_describe_error 是静态函数（无需设备连接），把设备故障码（来自 joint_diagnostics 的 error_code_current，与 Python SDK 错误历史、标定结果携带的是同一套码值）解码到 WujiErrorInfo。函数只接受设备故障码。Python SDK 的标定结果中另有编码器专用的错误字节，属不同枚举，不可传入本函数。Wuji Hand 关节诊断（wuji_hand_get_all_diagnostics 返回）的 WujiHandJointDiagnostics.error_code 位域同样不可传入：
WUJI_STATUS_ERR_NOT_FOUND。severity 取值：Warning / DeferredStop / ImmediateStop / Fatal。clear_policy 取值：AutoClear / ManualClear / NonClearable。
使用约束
C SDK 用户必须遵守以下约束，否则会出现 use-after-free、死锁或读到失效错误描述：- typed 回调的 frame 指针仅在回调期间有效，返回后堆字段即被释放。需要保留的数据必须在回调内拷贝出来，不得保存指针。
- 不要在订阅自身的回调里调
wuji_sub_close。close会 join worker 线程，在自身回调中调用必死锁。请在外部线程上 close。 wuji_last_error()返回值仅在同线程下一次wuji_*调用前有效。需要保留的错误描述应立即拷贝。END/ERROR是终止帧，回调收到这两类帧后流不再有新数据，但仍需调用wuji_sub_close释放订阅句柄。- 字符串 getter 使用两步查询：先用
buf=NULL, buf_len=0获取*needed（所需字节，含 NUL），再分配缓冲第二次调用填充。直接传不足缓冲会返回WUJI_STATUS_ERR_BUFFER_TOO_SMALL，不做截断。 - 整手批量读（
get_all_effort_limit/get_all_mit_params）返回 flat-20 数组 + 在线 bitmap，用WUJI_JOINT_ONLINE(mask, i)宏判断槽位是否有效，否则读到离线关节的占位值（0 或 NaN）。 - 标定反馈回调在标定 worker 线程触发，
feedback指针仅回调期间有效。回调内调用 session 接口不会死锁，SDK 会拦截：wuji_glove_calibration_wait与wuji_glove_calibration_try_finish返回WUJI_STATUS_ERR_INVALID_ARG，wuji_glove_calibration_session_free把原因记录到wuji_last_error()并跳过这次释放——session 仍然存活，必须在回调返回后再释放一次。wuji_glove_calibration_cancel可以在回调内安全调用。session 使用完毕后调用wuji_glove_calibration_session_free，标定结果使用完毕后调用wuji_glove_calibration_result_free。 WujiUserInfo持堆字符串：单个结构用wuji_user_info_free，wuji_list_users返回的数组用wuji_user_info_array_free。
Python 接口对照
下表按功能列出 C 与 Python 的对应接口。跨设备能力的完整用法见上方导语列出的能力章，设备专属接口见本页对应小节。| 功能 | C | Python |
|---|---|---|
| 初始化 | wuji_init(NULL) | SdkManager.instance() |
| 扫描 | wuji_scan(&devs, &count) | manager.scan() |
| 连接 | wuji_connect(&target, alias, &opts, &dev) | manager.connect(…) / manager.auto_connect(…) |
| 连接选项默认值 | wuji_connect_options_default() | ConnectOptions() |
| 设备订阅 | wuji_glove_subscribe_tactile(dev, cb, user, &sub) | glove.tactile().subscribe_with_callback(…) |
| 全局订阅 | wuji_subscribe_tf(cb, user, &sub) | manager.tf().subscribe() |
| 订阅流输出率 | wuji_sub_set_rate(sub, hz, &actual) | sub.set_rate(hz) |
| Hand 2 控制动作 | wuji_hand_2_enable(dev, mask) | hand.enable(joints=mask) |
| Hand 2 实时指令 | wuji_hand_2_joint_command_publish + wuji_joint_command_publisher_send | hand.joint_command().publish().send([…]) |
| Hand 2 关节状态订阅 | wuji_hand_2_subscribe_joint_states | hand.joint_states().subscribe() |
| Hand 2 关节诊断订阅 | wuji_hand_2_subscribe_joint_diagnostics | hand.joint_diagnostics().subscribe() |
| Hand 2 IMU 订阅 | wuji_hand_2_subscribe_imu | hand.imu().subscribe() |
| Hand 2 错误码描述 | wuji_hand_2_describe_error(code, &info) | WujiHand2.describe_error(code) |
| Hand 2 Flash 日志导出 | wuji_hand_2_export_flash_logs + wuji_hand_2_flash_log_export_free | hand.export_flash_logs() |
| Hand 连接（USB SN） | wuji_hand_connect_sn(sn, alias, &dev) | WujiHand.connect_sn(sn, alias) |
| Hand 关节状态订阅 | wuji_hand_subscribe_joint_states | hand.joint_states().subscribe() |
| Hand 实时指令 | wuji_hand_joint_command_publish + wuji_hand_joint_command_publisher_send | hand.joint_command().publish().send([…]) |
| Hand 实时控制器 | wuji_hand_realtime_controller_open / _set_target_position / get_actual* | hand.realtime_controller(LowPass(…)) |
| Glove 时间同步 | wuji_glove_sync_time(dev, &tsr) | glove.sync_time() |
| Glove 手部模型路径 | wuji_glove_get_hand_model_path / wuji_glove_set_hand_model_path | glove.hand_model_path().get() / .set(path) |
| SDK 用户管理 | wuji_create_user / wuji_switch_user / wuji_list_users | manager.create_user() / switch_user() / list_users() |
| 用户数据导入导出 | wuji_user_data_export / wuji_user_data_preview / wuji_user_data_import | manager.export_user_data() / preview_user_data() / import_user_data() |
| Glove 手部模型标定（异步） | wuji_glove_calibration_start + wuji_glove_calibration_try_finish | glove.calibrate() |
| Glove 手部模型标定（同步） | wuji_glove_calibrate | glove.calibrate_blocking() |
| Glove 触觉接触标定（同步） | wuji_glove_calibrate_tactile_blocking | glove.calibrate_tactile_blocking() |
| 断开 | wuji_dev_disconnect + wuji_dev_release | device.disconnect() |
CMake 工程示例
完整可运行 C 工程（含CMakeLists.txt + 订阅回调示例）见 wuji-sdk 仓库的 examples/c/ 目录，按设备分别存放在 examples/c/wuji_glove/（设置订阅流输出率、在线 IK 自定义手部模型、SDK 用户管理与手部模型标定）、examples/c/wuji_hand_2/（订阅关节状态、控制动作、设备信息、指尖触觉数据、设置订阅流输出率、Flash 日志导出、对掌回放与 MIT 扫频）与 examples/c/wuji_hand/（订阅、发布、抓握循环与触觉状态）子目录，构建步骤参见该目录 README。最小链接方式：
${SDK} 是解压后的 tarball 根目录。CMake 工程通过 -DWUJI_SDK_INCLUDE_DIR 与 -DWUJI_SDK_LIB 指向同样路径。