版本发布记录

组件版本

主要更新

通用

变更：

• C SDK：Linux x86_64 与 aarch64（gnu）压缩包现只带一个库文件 libwuji_sdk_c.so，Wuji Hand 支持不再需要随包的 libwujihandcpp.so，libstdc++.so.6 与 libusb-1.0.so.0 也不再是运行时依赖。C API 与链接行不变，既有应用无需重新构建，早前部署的 libwujihandcpp.so 可以删除

修复：

• 修复设备扫描在网络对端于发现过程中消失这一罕见场景下无限挂起的问题，网络发现步骤现有时间上限，扫描总能在数秒内返回已发现的设备，覆盖 Python SDK 与 C SDK
• 修复 Linux 多网卡或多 IP 主机上、主 IP 不在设备网段时网络设备发现永远找不到设备的问题，覆盖 Python SDK 与 C SDK

设备

Wuji Hand 2

新增能力：

• joint_diagnostics 流内置通信健康数据：逐关节上报总线应答率与超时计数，每帧附带端到端（以太网）流丢失、请求重试/超时计数与指尖触觉在线 bitmap 汇总，SDK 在后台自动维护，无需轮询

破坏性变更（C SDK）：

• joint diagnostics 结构体新增字段导致 C ABI 变化，使用 WujiJointDiagnosticsEntry 或 WujiJointDiagnosticsFrame 的应用必须用新头文件重新编译后再链接新库。既有字段的含义与顺序不变，源代码无需修改，新增字段承载上面描述的逐关节总线通信质量与帧级通信汇总

修复：

• 修复连接时绑定固定本地网络端口的问题，本地端口现由操作系统自动分配，SDK 不再与你的应用占用的端口冲突
• effort_limit 设置被设备拒绝的值（如超过当前上限）时现抛出 ValueError 而非笼统错误，设备保持原有上限

Wuji Glove

新增能力：

• 新增引导式触觉标定——按提示录制手部动作，为该只手套训练接触模型，在 tactile_binary 流上获得实时接触检测。Python 用 glove.calibrate_tactile() / glove.calibrate_tactile_blocking()，C 为带动作提示回调的阻塞式引导流程。模型自动加载，训练需带 model-export 特性的构建，动作指南参见触觉标定
• C SDK 新增 wuji_glove_set_tactile_binary_sensitivity，供独立的 tactile_binary 观察工具调整所连手套的 SDK 本地接触灵敏度，拒绝非有限值与非正值
• C SDK 新增可运行的用户管理示例 examples/c/wuji_glove/3_user_management.c，覆盖查看当前 SDK 用户、创建或更新具名用户、标定前切换用户
• 新增 tactile_residual 观察示例——它是 tactile_binary 背后连续、带符号的信号，接触阈值由你自行设定而非使用内置阈值。Python 用 glove.tactile_residual()，C 用 wuji_glove_subscribe_tactile_residual 类型化回调，使用前先完成手套标定

变更：

• C IK 标定示例现为 examples/c/wuji_glove/4_user_calibration.c（由 3_user_calibration.c 重命名），标定当前所在的 SDK 用户而不再创建或切换用户，需要创建或切换用户时先用新增的 3_user_management.c 示例。新增 --blocking 模式，运行至完成，不含默认异步路径提供的协作式 Ctrl+C 取消

修复：

• EMF 手指位姿现使用所选手型 URDF 拒绝不可达的镜像位置，减少瞬时干扰导致的位置翻转

Wuji Hand

变更：

• RealtimeController 现可跨 Python 线程共享——如写线程持续下发目标、读线程轮询实际位置——无需任何加锁，此前从第二个线程访问会抛错

修复：

• 运行中物理拔出触觉手套现可被检测：is_tactile_attached() 返回 false，触觉状态流通常在 200 ms 内上报 NotPresent（state 0），其余触觉读取返回明确的「触觉不在位」错误——此前它们会一直上报手套健康在位，只能靠帧龄察觉。手本体不受影响继续工作，重新接入手套仍需重新连接手。覆盖 Python SDK 与 C SDK（wuji_hand_is_tactile_attached）
• C SDK 的 Wuji Hand 触觉手套调用在手套缺失或故障时不再导致进程崩溃，改为返回错误状态（详情见 wuji_last_error()）
• 连接未就绪的手不再让应用崩溃，改为抛出可捕获的错误并指明未响应的关节，覆盖 Python SDK 与 C SDK

组件版本

主要更新

设备

Wuji Hand 2

新增能力：

• 指尖触觉感知首次正式发布：订阅按手指的自描述传感器数据流（FingertipSensorInfo 元数据描述如何解码每帧 FingertipSensorData，参见 3.fingertip_typed.py 示例），在传感器表面无负载时用 hand.tactile_calibrate()（Python）/wuji_hand_2_tactile_calibrate(dev)（C）将全部 5 个指尖重新标定到全新零基线，并用 hand.tactile_status(finger) 查询各传感器的型号与标定状态、确认重新标定已完成

修复：

• 固件升级失败时报告详细错误（具体原因、错误码和失败节点），不再只显示笼统的 "Unknown error"

子模块

Retargeting

新增能力：

• 新增手部重定向 API（wuji_retarget_session_create / _step / _reset / _free），将 21 个手部关键点（MediaPipe 顺序）映射为固件顺序的 20 个关节角度，与 Python RetargetSession 行为一致，退化或无效的关键点帧返回新增的 WUJI_STATUS_ERR_ALGORITHM 状态，详情可通过 wuji_last_error() 获取

破坏性变更（Python）：

• RetargetSession 和 HandModel 移至包顶层，wuji_sdk.retargeting 子模块已移除（Python 破坏性变更），导入需改为 from wuji_sdk import RetargetSession, HandModel

变更：

• RetargetSession 现在开箱即用，无需安装 [retarget] extra，单步延迟更低——numpy 仍用于 keypoint/qpos 数组
• 优化 retargeting 输出，改进拇指关节动作——相同输入的关节角度可能与之前版本不同

组件版本

主要更新

通用

新增能力：

• 用户数据导入导出：SdkManager.export_user_data(user_id, out_path) 将某个用户拥有的全部数据（标定手模型、触觉模型及其最近一次完整标定）打包为可移植的 .zip，preview_user_data(zip_path) 校验并查看包内容而不导入，import_user_data(zip_path) 将包恢复到其创建者用户（用户不存在则新建）并覆盖该用户已有数据，不改变当前用户
• scan() 返回结果新增设备类型：DiscoveredDevice.device_type 为 DeviceType 枚举（WujiGlove / WujiHand2 / WujiHand），连接前即可判断设备类型，Unknown 表示扫描时未获取到类型
• C SDK 扫描结果新增设备类型：WujiDiscovered.device_id 为 WujiDeviceType 枚举（WUJI_DEVICE_TYPE_WUJI_GLOVE / _WUJI_HAND_2 / _WUJI_HAND / _UNKNOWN），model 为对应类型字符串，连接前即可判断设备类型
• C SDK 新增与 Python 对齐的 SDK 用户管理与 Wuji Glove IK 标定接口：C 程序可创建、切换 SDK 用户，运行带结构化反馈的标定，取消异步标定 session，并拿到按用户隔离的标定 URDF 路径，标定示例提供与 Python 示例一致的原地终端仪表盘与限流 API 日志模式
• C SDK 新增用户数据导入导出与预览，与 Python 接口对齐：wuji_user_data_export / wuji_user_data_import 用可迁移的 zip 包导出、恢复一位用户的数据，wuji_user_data_preview 只校验并列出包内容而不写盘，三个接口都返回状态码，失败原因用 wuji_last_error() 取，包文件不存在返回 WUJI_STATUS_ERR_NOT_FOUND，包在但校验不通过（zip 损坏、manifest 非法、校验和不匹配、路径不安全）返回 WUJI_STATUS_ERR_INVALID_DATA

破坏性变更（C SDK）：

• WujiConnectOptions 结构体布局调整为与 Python ConnectOptions 一致（bridge 与后台时间同步设置）。需针对更新后的 wuji_sdk.h 重新编译，传入非 NULL options 前先调用 wuji_connect_options_default() 再覆盖字段，或传 opts_or_null = NULL 保持默认连接行为
• 移除未使用的 wuji_glove_subscribe_tactile_zones_cache()

修复：

• 修复同一进程连接多台设备（如 Wuji Glove 与 Wuji Hand 2）时因连接顺序不同可能失败的问题
• 修复程序退出时崩溃的问题：设备在回调订阅仍在运行时断开、随后进程退出，可能触发致命 Python 错误或段错误，现在后台订阅线程会在解释器关闭前干净停止

设备

Wuji Hand

新增能力：

• Wuji SDK 的实时控制器新增 get_actual_effort()（按关节返回电流值，单位安培，与 get_actual_position() 共用非阻塞上游缓存），C SDK 对应新增 wuji_hand_realtime_controller_get_actual_effort，该接口属于 wuji-sdk，不是 wujihandcpp
• C SDK 新增 Wuji Hand（一代灵巧手）支持：wuji_hand_connect_sn 按 USB 序列号连接后，可读取关节位置、按关节诊断（母线电压 / 温度 / 错误码）、固件软限位、左右手、是否挂载触觉手套，执行 enable / disable / clear_all_faults，设置与读取 effort 上限，通过关节指令 publisher 下发 20 个 JointCommand（每关节 position / velocity / effort，与 Wuji Hand 2 结构一致，指令代码可在两代间复用），并运行带低通滤波的实时位置控制器。关节状态与触觉压力订阅流同样可用。仅支持 Linux x86_64 / aarch64 (gnu)，Android 上这些函数存在但返回 WUJI_STATUS_ERR_UNSUPPORTED，示例见 examples/c/wuji_hand/

破坏性变更（Python）：

• 关节指令 publisher 改为接收结构体数组。JointCommandPublisher.send(...) 从三个并列列表 send(positions, velocities, efforts) 改为单个每关节指令列表 send(joints)，每项为 JointCommand(position, velocity, effort)，须传满 20 个，旧 publish(...) 别名已移除，与 Wuji Hand 2 完全一致
• 关节指令 publisher 改为经 hand.joint_command().publish() 打开，资源访问器由 .publisher() 更名为 .publish()，快捷方法 hand.joint_command_publisher() 已移除，返回的 JointCommandPublisher（send(...) / close()）不变
• 触觉手套相关类统一加 TactileGlove 前缀，避免与 Wuji Glove 的通用触觉流混淆：TactileStatus → TactileGloveStatus、TactileDiagnostics → TactileGloveDiagnostics、TactileDeviceInfo → TactileGloveDeviceInfo、子模块句柄 WujiTactile → WujiTactileGlove。访问器与传输格式不变，更新类型引用与 isinstance 判断即可
• 关节状态订阅流更名为 hand.joint_states()（原 hand.joint_state()），帧类 HandJointState → HandJointStates，与 Wuji Hand 2 及 ROS /joint_states 约定一致

Wuji Hand 2

• disconnect() 现在完全释放设备：断开后手立即可被任何其他程序或机器占用，与程序退出效果一致，此前手可能仍被程序持有直到退出
• 修复反复连接 / 断开的程序中每次连接耗时递增的问题，现在无论程序运行多久连接都保持稳定快速

Wuji Glove

破坏性变更：

• 标定结果（URDF 手部模型）改为归属 SDK 用户与左右手，而非单只手套，更换同侧的另一只手套不再需要重新标定，早期 SDK 版本记录的标定不再加载，请在你的用户档案下重新标定
• hand_profile 标定选项已弃用并忽略（传入会触发 DeprecationWarning）。标定结果简化为 handedness 加单一 calibrated_urdf 路径，calibration.hand_profile 与 calibration.hand_model_paths.* 参数已移除，设置将失败，早期版本残留值被忽略
• 触觉接触模型改为按当前 SDK 用户与设备序列号自动定位，与标定手模型同一套约定，存放在 SDK 自有触觉目录下，algorithms.tactile_binary.model_dir 参数已移除，设置将失败，此前用该参数指定触觉模型目录的集成方请停止设置，选定 SDK 用户后模型自动解析
• 标定 bundle 采用新格式（用户级手模型加每手套触觉数据）。导入早期 SDK 版本的 bundle 会保留触觉数据但跳过其中的手部标定（请重新标定），本版本导出的 bundle 需最新 SDK 才能导入

修复：

• Default 档案默认使用 Wuji 内置 URDF，历史标定结果不生效，需要标定请先新建并切换到自己的用户档案

子模块

Retargeting

• 优化 wheel 打包，下载与安装体积显著减小，无功能变化

组件版本

主要更新

设备

Wuji Hand

• 修复同一进程内重连失败的问题：disconnect() 后再次 connect() 连接同一只手会失败，此前需退出进程才能恢复。现在 disconnect() 后原句柄不再可用，重连请创建新的连接

子模块

Retargeting

• 修复遥操作示例 examples/python/retargeting/1.teleop_real.py 无法运行的问题：manager.connect() 默认启用 Zenoh Bridge（enable_bridge=True），示例沿用默认连接选项时 glove → retarget → hand 遥操作回路无法正常运行。示例改为以 ConnectOptions(enable_bridge=False) 连接手套与手，绕过 Bridge 直连修复

组件版本

主要更新

C SDK

• 新增 Wuji Hand 2 支持，与 Python 端资源式接口一致：joint_states / joint_diagnostics 订阅流、mit_params / effort_limit 配置、控制动作（enable / disable / clear_fault / emergency_stop / 用户零点）、joint command 发布，整手读覆盖 20 关节并带在线 bitmap 用于区分离线关节，字符串 getter 采用两步 size 查询（先传 NULL buffer 获取所需长度，再次调用填充）
• 新增 wuji_glove_get_emf_poses_rate_divider / wuji_glove_set_emf_poses_rate_divider，分频降低 Wuji Glove EMF 输出率（N ≥ 1，输出率 = 输入率 / N，例如 N=4 → 30 Hz），所有派生流（hand_joint_angles / tip_poses / hand_skeleton / tactile_point_cloud）自动同步降率，降低 IK CPU 占用，运行时生效并跨重连保留
• 新增 wuji_glove_sync_time 触发一次与 Wuji Glove 的时间同步往返，回填 WujiTimeSyncResult（时钟偏移、往返耗时与测量时间戳，单位均为微秒），与 Python glove.sync_time() 对齐
• 新增 wuji_glove_get_hand_model_path / wuji_glove_set_hand_model_path（及 Python glove.hand_model_path().get()/set(path)），为 Wuji Glove 在线 IK 指定自定义手部 URDF，Python 订阅示例新增 --hand-model-path 参数

设备

Wuji Hand 2

破坏性变更：

• 接口重设计为统一资源式 API，每个能力通过 .get() / .set() / .subscribe() / .publish() 访问，整手与单关节同套方法
• 控制动作 enable() / disable() / clear_fault() / set_origin() / clear_origin() 支持 length-20 mask 子集操作，emergency_stop() 始终全手生效
• 反馈以订阅流形式：hand.joint_states() / hand.joint_diagnostics()，反馈帧带 FrameHeader（seq / timestamp_us / frame_id l_wrist / r_wrist），仅含在线关节
• 实时控制改为 publish 模式：hand.joint_command().publish().send(joints) 接收 20 个 JointCommand（每个含 position / velocity / effort），原 send(positions, velocities, efforts) 三列表写法停用
• 配置资源 mit_params（kp/kd）与 effort_limit（A），写入拒绝 NaN / inf / 负值
• 控制模式不再由 Python 设置，设备默认 MIT 控制

新增能力：

describe_error(code) 把状态 / 错误码翻译为可读说明。

Wuji Glove

破坏性变更：

• tactile_point_cloud 主动接触点契约对齐到 526 个 taxel，需配合匹配版本固件保证点云帧稳定输出 526 个点
• 默认 SDK 用户始终使用内置默认手 URDF 输出 IK 衍生数据流（hand_skeleton / hand_joint_angles / tip_poses），忽略已保存的标定 URDF 路径，直接调用 calibrate 会快速失败并返回错误码 0x4108，需先创建并切换到命名用户后再标定，标定 URDF 仅对该用户生效

默认模型刷新：

指段长度与关节原点按最新标定更新，未加载用户标定档案时默认手部追踪输出（hand_skeleton / hand_joint_angles / tip_poses）更准确，关节与 link 结构不变。

子模块

Retargeting

随 wuji-sdk 一同发布，把人手关键点映射到 Wuji Hand / Wuji Hand 2 的关节角度。安装 pip install wuji-sdk[retarget]（仅 Linux x86_64 / aarch64）。原独立 Wuji Retargeting 仓暂停更新。

• 把 21 个 MediaPipe 格式手部关键点映射到 Wuji Hand 关节角度，wuji_sdk.retargeting.RetargetSession.for_hand(HandModel.WujiHand2, side=Handedness.Right) 一行创建会话，session.step(keypoints) 返回 20 维关节指令可直发设备，无需额外排序
• 附带 Wuji Glove → retargeting → Wuji Hand / Wuji Hand 2 真机遥操作示例 examples/python/retargeting/1.teleop_real.py

组件版本

主要更新

Wuji Glove

• 触觉数据布局更新为 744 值 24×31（原 768 值 24×32），tactile、tactile_residual、tactile_binary 帧及分区触觉布局相应变小，无效触觉点仍报 -1.0

组件版本

主要更新

通用

• 新增预编译 C SDK（libwuji_sdk_c.so + wuji_sdk.h），当前仅支持 Wuji Glove 接口，覆盖设备连接、跨设备坐标变换（tf / tf_static）与多种数据流订阅（触觉、触觉区域、EMF 位姿、手部关节角度、手部骨架、触觉点云），支持 x86_64-linux-gnu / aarch64-linux-gnu / aarch64-android 三平台
• 新增本机 SDK 用户隔离，通过 SdkManager.create_user(display_name) 创建用户、switch_user() 切换，每位用户的标定数据按设备独立保存，切换后已连接设备的标定立即重新加载

Wuji Glove

• 新增 glove.tactile_residual()，与 tactile 同频率发布 768 维连续接触残差（正值=按压、~0=无接触、-1.0=无效），沿用 TactileFrame 形状原有触觉网格可视化无需改动，可自定义阈值替代内置 tactile_binary
• 手部姿态求解改为多核并行，hand_joint_angles 及衍生手部追踪数据耗时降低，输出与 schema 不变
• 新增 Python 侧 IK 标定接口 glove.calibrate()，支持 on_feedback 每姿势进度回调，通过 hand_profile 选 Wuji Hand 或 Wuji Hand 2 模型，留空时单次采集生成两个手型的 URDF 供实时追踪后切换
• 新增 glove.emf_poses_rate_divider() 降频 EMF pose 输出（默认 1，设 N 后频率变 input_rate/N，如 N=4 → 120Hz 降到 ~30Hz），所有 EMF pose 衍生流（emf_poses / hand_joint_angles / tip_poses / hand_skeleton / tactile_point_cloud）同步降频减 IK 计算耗时，IMU 与原始触觉流（tactile / tactile_zones / tactile_residual / tactile_binary）不受影响，运行时生效跨重连持久化

Wuji Hand

• 新增 wuji_sdk.WujiHand 类，Wuji Hand 现可直接通过 wuji-sdk 使用（与 wujihandpy 并存），支持 USB 自动发现与连接、电机使能/失能、按关节 effort 上限、20 关节实时位置订阅与指令发布（带 LowPass 平滑控制），可选挂载触觉手套数据流
• WujiHand 接口完全镜像 Wuji Hand 2 API surface（scan / connect / joint_state / joint_command），两代产品代码可基本互通复用

组件版本

主要更新

• Wuji Glove：新增二值接触触觉数据流 glove.tactile_binary()，与 tactile() 同频率发布 768 维接触状态（1.0 接触、0.0 未接触、-1.0 无效触点），与 TactileFrame 同形，现有触觉网格可视化无需改动即可复用
• 新增按手性连接 SdkManager.connect(handedness=Handedness.Left | Handedness.Right, ...)，可直接指定左手或右手连接双手设备

组件版本

主要更新

• 新增 device.export_flash_logs(out_dir)，将设备历史日志导出为 JSONL 文件
• 新增通道级录制健康指标 QualityMetrics.channels：每路 topic 的帧率、丢帧率、抖动、is_online、last_downtime_ms
• Wuji Glove：hand_joint_angles 和 tip_poses 改为基于 URDF 运动学链推导，输出 schema 不变，数值与旧版本可能不同
• Wuji Glove：移除 glove.tactile_raw()，请改用 glove.tactile() 订阅标定后的触觉帧
• Wuji Glove：移除 glove.factory_reset()
• 修复在非异步上下文中调用 disconnect_all() 时设备离线状态可能未上报的问题

组件版本

主要更新

• 修复了部分已知问题

组件版本

主要更新

• Wuji SDK 和 Wuji Studio 支持共享同一设备
• 提升启动和运行期间的日志可用性与可靠性
• 提升升级稳定性，减少升级失败误报

组件版本

主要更新

• 新增跨设备合并订阅，多设备场景下一次获取所有设备的聚合数据
• 新增数据录制，支持多通道录制、暂停/恢复、分集切换和实时质量监控
• 修复回调模式下偶发崩溃的问题
• 修复同时订阅多个数据流时部分数据丢失的问题
• 修复 Wuji Glove 部分 IMU 数据流无法订阅的问题

组件版本

主要更新

• 新增 get() / set() 接口，支持读写设备配置参数
• 新增 save_params() 将参数变更持久化到设备 Flash
• 新增 SDK/设备日志支持，通过 set_log_level() 控制日志级别
• 新增 6 路 IMU 数据：imu_palm()、imu_thumb()、imu_index()、imu_middle()、imu_ring()、imu_pinky()
• 新增坐标变换 API：tf_static().subscribe() 和 tf().subscribe()
• 新增手部追踪数据：tip_poses()（指尖姿态）、hand_joint_angles()（21 DoF 关节角度）、hand_skeleton()（21 个手部关键点）
• 新增触觉点云数据：tactile_point_cloud()，用于 3D 触觉可视化
• 定位质量指标 EmfPose.confidence — 表示 EMF 位姿估计可靠性（0.0~1.0）

组件版本

主要更新

• Wuji SDK 首发：Wuji 设备的 Python 开发套件
• 回调订阅支持 subscribe_with_callback()
• 异步接收支持 recv_async()
• IDE 自动补全支持
• 数据流订阅：触觉矩阵、触觉区域、EMF 位姿

支持设备

• Wuji Glove — 集成触觉感知和动作捕捉的智能手套