Skip to main content

Wuji Hand 2

Wuji Glove

Wuji SDK

Wuji CLI

​
2026 年 10 月

​
Wuji Hand 2、Wuji Glove、Wuji SDK、Wuji CLI 与 Wuji Description
本次版本重点
  • 兼容性与迁移：Wuji Description 迁移为 Hand 2.1 和 Hand 2.2 ROS 2 包。需更新资源路径、依赖项和启动配置。
  • 运行与运维：Wuji SDK 和 Wuji CLI 的 Linux 产物支持 Ubuntu 20.04 LTS 及以上版本的 x86_64 和 arm64 平台。Python SDK 支持 Python 3.8 及以上版本。Wuji CLI 会检查已安装的 agent skills 是否过期，并在过期时提示。它还改进了设备连接、数据订阅和固件升级。
  • 状态与诊断：Wuji Hand 2 对应的 Wuji SDK 会在连接后读取全部 20 个关节的 kp 和 kd。通信诊断和固件升级错误提示提供更有用的结果。固件 v2.10.0 起，选定关节离线时升级会提前停止，并显示设备返回的拒绝原因。
破坏性变更Wuji Description 模型迁移
  • Wuji Description：移除 Beta 1 和 Beta 2 包、对应的 _with_mount 变体及整手 STEP 装配体。改用以手臂法兰安装座为根节点的 Hand 2.1 和 Hand 2.2 模型，并将 colcon --packages-select、package:// URI、依赖项和启动配置更新为 wuji_hand2_1_description 或 wuji_hand2_2_description。
新增功能运行环境与版本支持
  • Wuji SDK 和 Wuji CLI：Python SDK、C SDK 和 CLI Linux 产物支持 Ubuntu 20.04 LTS（glibc 2.31）及以上版本的 x86_64 和 arm64 平台。Python SDK 支持 Python 3.8 及以上版本。
  • Wuji CLI：wuji --help 新增 agent skills 和文档链接，方便 agent 查找 Wuji CLI 使用指引。Wuji CLI 会检查已安装的 agent skills 是否过期，并在每次运行命令时提示。运行 wuji update 也会同步更新匹配的 skills。
关节参数回读
  • Wuji Hand 2：连接建立后，Wuji Hand 2 对应的 Wuji SDK 会读取全部 20 个关节的 kp 和 kd，并将结果以一行 param readback sn=<SN> path=mit_params thumb/S1 kp=… kd=… … 写入 SDK 日志。离线关节记录为 offline。读取失败时，SDK 会记录 warning，但不会影响连接。
CLI 设备操作
  • Wuji CLI：Wuji CLI 现在记录命令、退出码、耗时和错误。通过 wuji logs list 查看，或在导出日志时使用 --source cli 筛选。
Wuji Description 模型与资源
  1. 新增 Hand 2.1 模型，位于 hand2/hand2_1/body/，作为独立 ROS 2 包 wuji_hand2_1_description，提供左手和右手模型及 URDF、MuJoCo MJCF、Isaac Sim USD 资源。
  2. 新增 Hand 2.2 模型，位于 hand2/hand2_2/body/，作为独立 ROS 2 包 wuji_hand2_2_description。
  3. 新增每只手的掌部安装接口 STEP 装配体，位于对应的 attachment/ 目录。文件位于 ROS 2 包根目录之外。
变更固件参数
  • Wuji Hand 2 固件：对于新建或重置的关节配置，本版本将 MIT 阻抗控制的默认 kd 增益更新为 0.1，kp 使用 5.0。固件升级会保留此前保存的关节参数。
改进与修复共 22 项改动，分为 5 个领域。设备连接与动作示例
  1. Wuji SDK：连接 SDK 在网络中发现的设备，或按地址连接设备时，即使同一台机器上的 DDS 或 ROS 2 等程序占用 UDP 7446 端口，也不会再失败。SDK 会跳过对等发现，并记录警告，提示其他 SDK 进程无法自行发现和共享该设备。仅能通过其他 SDK 进程访问的设备仍需要该端口。
  2. Wuji Hand 2：Python 2.publish.py 和 C 1_control_motion.c 现在会等待一次诊断更新，确认全部 20 个关节均为 Enabled 后再控制灵巧手。此前，仅包含在线关节的更新可能被当作整只手已就绪，导致例程在部分关节仍禁用时开始下发控制指令。
  3. Wuji Hand 2：Python opposition.py、7.mit_sweep.py 以及 C opposition.c、7_mit_sweep.c 现在会扫描 Wuji Hand 2 设备，列出序列号并连接所选设备。发现多只手时，按 Enter 或标准输入关闭会选择第一台设备。此前，例程可能连接错误类型的设备，或因发现多台设备而失败。
  4. Wuji Hand 2：实时遥操作例程（1.teleop_real.py 和 1_teleop_real.c）启动时不再导致灵巧手跳动。例程要求全部 20 个关节在线且已启用，读取当前手部姿态，再在约 1 秒内过渡到手套姿态，并在每帧读取手套数据。
  5. Wuji Glove：右手设备现在使用配置的 IP 地址。
  6. Wuji Glove：左右手检测现在能正确处理不一致的侧别检测信号。
数据接收与订阅
  1. Wuji SDK：SDK 短暂落后后，订阅现在会继续传送新数据。此前，内部缓冲区溢出可能会静默停止订阅。
  2. Wuji Glove：其他程序大量写入同一磁盘时，包括 emf_poses 在内的设备数据不再暂停约 1 秒、丢帧或产生 lagged 警告。
  3. Wuji Hand 2：主机繁忙时，joint_states 和 joint_diagnostics 订阅不再丢帧，也不再记录 Virtual subscription '...' lagged N messages。
  4. Wuji Glove：tactile_point_cloud 中小指根部附近的每个点现在都会报告实际压力值。此前，小指根部附近有 3 个点报告 -1，对应的 3 个触觉单元缺失。点数保持不变。
  5. Wuji Hand 2：对于运行固件 v2.6.0 及更早版本、并通过 7447 端口接受 SDK 连接的设备，数据流频率请求无响应时，Python Subscription.set_rate() 会抛出带有 Operation timeout - device not responding 的 WujiException，C wuji_sub_set_rate() 返回 WUJI_STATUS_ERR_TIMEOUT。此前 Python 返回以 Internal error: 开头的 WujiException，C 返回 WUJI_STATUS_ERR_INTERNAL。
  6. Wuji Glove：固件升级失败或被拒绝后，EMF 流现在无需重启即可恢复。
  7. Wuji Glove：带时间戳的传感器订阅前几帧不再使用设备首次上电时间。
  8. Wuji Glove：其他主机向数据端口发送无效或被拒绝的请求时，不再将订阅数据转发给该主机，也不会导致原客户端丢帧。
通信诊断
  1. Wuji Hand 2：joint_diagnostics 通信汇总中的 sdk_dropped 现在包含订阅转发器丢弃的数据帧，补上此前遗漏的转发阶段。
  2. Wuji Hand 2：joint_diagnostics.comm.e2e_lost 不再将 set_rate() 跳过的数据帧计为丢失，因此降低数据流频率不会增加丢帧计数。
固件升级
  • Wuji Hand 2：从固件 v2.10.0 起，选定关节离线时，SDK 固件升级会在发送数据前停止并列出离线关节。若灵巧手拒绝升级目标并返回原因，升级会失败并显示该原因。此前只报告通用错误，固件 v2.6.0 及更早版本还可能将被拒绝的升级误报为成功。
CLI 升级与可视化
  1. Wuji CLI：wuji upgrade 在耗时较长的升级过程中显示进度，并在升级后显示已安装的固件版本。
  2. Wuji CLI：wuji upgrade 使用 --json 或 --jsonl 且未提供 --yes 时，会返回正确的错误码。
  3. Wuji CLI：设备拒绝原始 .bin 固件文件时，wuji upgrade 不再报告成功。
  4. Wuji CLI：修复 wuji update --skills 更新 agent skills 时卡住的问题。
  5. Wuji CLI：改进 wuji viz 中 Wuji Glove 触觉显示的初始缩放比例，并修复 Wuji Glove TX 模型。
产品版本与获取方式

​
2026 年 9 月

​
固件 v2.10.0 · Wuji SDK v2026.9.22
重要变更：SDK 连接端口支持配置，默认端口由 7447 改为 50001。直接连接 7447 端口的应用需改为 50001。
组件版本主要更新
  • 关节控制器新增默认启用的内置前馈补偿。需要 Wuji Hand 2 固件 v2.10.0 和 Wuji SDK v2026.9.22 及更高版本，仅适用于 2026 年 10 月起发货的设备
  • Python SDK 的公开操作在 SDK 内部发生失败时统一抛出 WujiException 或其子类
​
v2026.9.22
组件版本主要更新
  • Python SDK 的公开操作在 SDK 内部发生失败时统一抛出 WujiException 或其子类。Python 解释器在 SDK 调用前抛出的参数类型和溢出错误仍保留内置异常类型
  • 修复 MCAP 源事件时间与主机接收时间记录混用的问题
  • 修复多设备访问、跨应用访问和设备断连后的句柄调用问题
​
固件 v1.0.2
组件版本主要更新
  • 固件升级失败或被拒后，EMF 数据流会自动恢复，无需重启设备
  • 修复时间戳、右手 IP 地址和左右手别检测问题
​
v2026.9.22
组件版本主要更新
  • wuji viz 支持 Wuji Glove 实时可视化
  • wuji update --check 显示最新版本的发布说明，并同步对应版本的 agent skills
​
v2026.9.14
重要变更：本次含 4 项破坏性变更。
  • Python SDK 的操作失败统一抛出 WujiException 或其子类，应用捕获 WujiException 即可
  • WujiHand2.joint_id_from_bus_node() 与 C wuji_hand_2_joint_id_from_bus_node() 已移除，改用 WujiHand2.nid_to_joint_index() 与 wuji_hand_2_nid_to_joint_index() 解码流 nid
  • 带手指参数的 hand.get_fingertip_info(finger) 与 C wuji_hand_2_get_fingertip_info() 已移除，改用按指的无参访问器
  • 运行固件 v2.7.0 及以上的 Wuji Hand 2 改在 50001 端口接受 SDK 连接，直接连接 7447 端口的应用需改为 50001
组件版本主要更新通用破坏性变更（Python）：
  • Python SDK 所有公开操作在 SDK 侧发生的失败统一抛出 WujiException 或其子类，SDK 侧的值转换失败也是如此，应用捕获 WujiException 即可。此前这些失败可能以 ValueError、TypeError、RuntimeError、TimeoutError、PermissionError 或 OSError 抛出。Python 解释器在进入 SDK 调用前抛出的参数类型或溢出错误仍是 Python 内置异常
修复：
  • 录制的 MCAP 消息在数据流提供源事件时间时保留该时间，并单独保留主机接收时间。此前两个时间戳都使用主机接收时间，时间轴和跨数据流对齐会因传输与缓冲延迟而偏移
  • 修复同一应用共享多台设备时的读写超时
  • 修复从另一应用访问共享设备时的连接失败
  • 修复 Linux 主机关闭 IPv6 时跨进程设备发现与共享失败的问题
  • 修复设备断开后通过原句柄调用 SDK 操作时，协议会话报 Internal error、数据流订阅报 Resource not found 的问题。断连后的调用统一抛出 WujiException，错误信息说明设备已断开
设备Wuji Hand 2破坏性变更：
  • 移除 Python WujiHand2.joint_id_from_bus_node() 与 C wuji_hand_2_joint_id_from_bus_node()，解码流 nid 改用 Python WujiHand2.nid_to_joint_index()（C：wuji_hand_2_nid_to_joint_index()）。被移除的方法计算的是节点位图的位序，而非文档所称的固件流编码，用于解码流 nid 会静默错配关节
  • 移除带手指参数的指尖信息读取方法，Python hand.get_fingertip_info(finger) 与 C wuji_hand_2_get_fingertip_info(dev, finger, &out)。每根手指现在各有一个无参访问器，Python 为 hand.fingertip_thumb_info().get()，C 为 wuji_hand_2_get_fingertip_thumb_info(dev, &out)，index、middle、ring、pinky 同理。新命名与已在使用的按指数据流一致，即 fingertip_thumb_data 与 wuji_hand_2_subscribe_fingertip_thumb_data。没有兼容垫片，Python 对旧名抛出 AttributeError，C 链接已移除的符号失败。结构体布局不变，旧二进制会直接报错，而不是误读数据
  • 运行固件 v2.7.0 及以上的 Wuji Hand 2 在 50001 端口接受 SDK 连接，不再使用 7447 端口。SDK 设备发现会自动选择正确端口。直接连接 7447 端口的应用需改为 50001，只放行 7447 的防火墙规则也需更新
新增能力：
  • 新增单关节前馈开关（Python 与 C），也可整手设置并用可选关节掩码限定范围：constant（Python：hand.set_constant(mode)，C：wuji_hand_2_set_constant，mode 为 FeedForwardMode）和 position_table（Python：hand.set_position_table(on)，C：wuji_hand_2_set_position_table）。需要 Wuji Hand 2 固件 v2.7.0 及以上。两项的开关状态在设备重启后恢复为已保存或默认的配置
  • 新增关节编号换算方法。Python WujiHand2.nid_to_joint_index() 与 WujiHand2.joint_index_to_nid()（C：wuji_hand_2_nid_to_joint_index() / wuji_hand_2_joint_index_to_nid()）在 JointStateEntry.nid 携带的流 nid 与命令数组使用的 0–19 关节索引之间换算。无效输入在 Python 抛出 WujiException，在 C 返回 WUJI_STATUS_ERR_INVALID_ARG
变更：
  • Wuji Hand 2 固件 v2.7.0 及以上通过 SDK Bridge 共享设备时，只有直接连接设备的应用可以写入，其他应用可以读取数据并接收实时更新
  • 关节错误的描述、原因与建议操作改为英文，不再是中文。错误码与名称不变
  • C 与 Python 的指尖例程遇到无法读取传感器信息的手指时，跳过该手指并继续解码其余手指，不再在首次失败时结束整个程序。指尖传感器自行上报信息，所以手指可能暂时没有信息：未安装传感器、传感器固件较旧，或上电后灵巧手仍在收集信息时读取。只有所有手指都没有信息时，例程才停止
修复：
  • 修复 C SDK wuji_hand_2_describe_error 返回 WUJI_STATUS_ERR_NOT_FOUND 时在传入的 WujiErrorInfo 中残留旧数据的问题，码值 0 也在此列。此前复用同一个结构体可能读到上一次的结果。放不下完整文本的字段现在保持为空，不再截断
  • 修复 joint_diagnostics 通信摘要中 sdk_dropped 漏计 SDK 内部部分处理环节丢帧的问题。此前这些丢帧只写日志不计数，header.seq 已有跳号时 sdk_dropped 仍可能为 0。现在 SDK 内部每一级丢弃的帧都会计入
  • 修复断开连接后立即重连时，新连接可能在约两秒后被断开的问题。重连后的连接现在保持存活
  • 修复灵巧手重启进入新固件后，主机端可能停止响应、升级流程始终不结束的问题，即便灵巧手本身已升级成功
  • 修复运动例程 6、7 启动时第一条指令为固定零位、灵巧手从启动时所在姿态直接跳变的问题。例程现在启动时先从 joint_states 读取当前姿态，用约 1 秒平滑过渡到轨迹起点，再执行固定序列
  • 修复 C 例程 6 每次失败都输出同一条通用提示的问题。例程现在指明失败发生在哪一步，SDK 返回错误信息时一并输出。未找到设备时提示检查设备供电与网络连接
子模块Retargeting变更：
  • Wuji Hand 2 实时遥操作例程（examples/python/retargeting/1.teleop_real.py 与 examples/c/retargeting/1_teleop_real.c）默认下发刚度更高的 MIT 阻抗增益，向全部关节下发 (kp, kd) = (5.0, 0.1)，此前默认值为 (3.0, 0.05)
​
固件 v2.7.1 · Wuji SDK v2026.9.14
重要变更：固件 v2.7.0 起灵巧手在 50001 端口接受 SDK 连接，不再使用 7447 端口。通过 SDK 设备发现连接的应用不受影响，直接连接 7447 端口的程序需改为 50001，防火墙规则同步更新。
组件版本主要更新破坏性变更：
  • 灵巧手在 50001 端口接受 SDK 连接，不再使用 7447 端口。通过 SDK 设备发现连接的应用不受影响。直接连接 7447 端口的程序需改为 50001，只放行 7447 的防火墙规则也需更新
修复：
  • 修复部分已知问题
​
固件 v1.0.0
组件版本主要更新固件修复：
  • 修复新建带时间戳的传感器数据订阅后，起始若干帧的时间戳是设备开机至今的时长而非真实日期时间，时间同步生效后才切换的问题。修复后，订阅从第一帧起就使用与主机同步的真实时间
  • 修复右手设备设置的 IP 地址与实际生效地址不一致的问题。此前将右手设备 IP 设为 192.168.1.200 时，设备重启后实际监听 .201，而读取配置仍显示 .200，与设备发现广播的地址互相矛盾。现在两只手均按设置值原样生效。从 1.0.0 之前的版本升级的设备会自动迁移配置，升级前后以及回退到旧版本固件时，实际生效的 IP 地址均保持不变，无需任何操作
​
v2026.9.14
组件版本主要更新新增能力：
  • wuji viz 支持 Wuji Glove 实时可视化
  • wuji update --check 在版本对比之外一并显示最新可用版本的发布说明。二进制升级成功后，wuji update 会把 Wuji CLI 的 agent skills 同步到对应的 CLI 版本，同步失败不影响升级结果。wuji update --skills 只把 skills 同步到当前 CLI 版本
  • 新增 wuji record teleop，把 Wuji Glove 驱动 Wuji Hand 2 的遥操作会话录制为受管理的 MCAP 文件
  • 新增 wuji record list 与 wuji logs export --recording <RUN_ID>，用于查看并打包选定的录制文件
  • 新增 wuji-cli-support agent skill，用于收集故障信息并整理成带可用附件的支持报告
变更：
  • Wuji Hand 2 的可视化与运行时触觉归零按连接的硬件自适应：无触觉的设备只显示关节姿态，带触觉的设备保留触觉视图
修复：
  • 修复 wuji logs dump / export 一次对多台设备执行时报 session closed 失败的问题。现在每台设备的日志包都会导出
  • 修复一键安装脚本的 agent skills 步骤误报 Failed to install N 与 PromptScript does not support global skill installation 的问题。现在只为机器上检测到的 agent 安装 skills，没有可用 agent 时直接复制到 ~/.agents/skills

​
2026 年 8 月

​
v2026.8.31
组件版本主要更新通用变更：
  • Python 示例会在正常退出路径的 finally 中调用 manager.disconnect_all() 释放设备。设备会由 SdkManager 持有，直至调用 disconnect()、disconnect_all() 或进程退出。仅丢弃设备句柄不会断开连接，长时间运行的程序应主动断开连接
修复：
  • 读取设备已定义但从未写入的 SDK 参数时，错误信息改为 Parameter not set。Path not found 仅用于不存在的路径。C SDK 仍统一返回 WUJI_STATUS_ERR_NOT_FOUND，可通过 wuji_last_error() 区分两种情况
  • 预览或导入用户数据文件时，若文件中的用户名不符合 SDK 要求，操作会在修改数据前停止并显示被拒绝的用户名。此前预览可能通过，导入则返回内部错误
  • 连接缺少端口的地址时，例如 192.168.1.110，错误信息会提示必须提供端口，不再误报不支持 USB 路径直连
设备Wuji Hand 2新增能力：
  • C SDK 新增 wuji_hand_2_decode_joint_status，将关节状态字解码为四态 ext_state、便捷字段 enabled，以及位置、速度和电流限位标志。应用无需再自行解析状态位
  • 新增阻塞式 Python hand.export_flash_logs() 和 C wuji_hand_2_export_flash_logs()，用于将设备 Flash 历史日志导出为 JSONL。默认写入 ~/.wuji/logs/，同名文件会自动加编号。未保存 Flash 日志的固件会提示不支持。固件 v2.6.0 及以上支持并发导出。同一设备被多个程序同时导出时，导出会完成或提示设备忙，输出目录只保留完整的单次结果。较早固件无法检测并发导出，请依次导出
变更：
  • 活跃的 joint_diagnostics 订阅会在关节错误出现、变化或清除时写入易读的 SDK 日志，包含十六进制错误码、名称、描述、原因、建议操作和清除策略。持续存在的错误不会重复记录。Python 的 JointDiagnosticsEntry 输出会显示 0x2102(Overcurrent)，零值仍显示为 0x0000，未知错误码显示为 0xFFFF(Unknown)
  • 更新指尖触觉示例
  • 更新指尖传感器合力作用点和姿态示例
修复：
  • Python 创建索引超出 0..=19 的关节句柄时会立即抛出 ValueError。此前会生成无效句柄，其元数据可能抛出 PanicException 或暴露无效索引
  • describe_error() 返回 dict，应通过 info["severity"] 等键读取。类型提示会列出全部 8 个键。此前文档将返回值描述为属性对象，使用 info.severity 会抛出 AttributeError
  • 修复部分已知问题
Wuji Glove新增能力：
  • C SDK 新增 wuji_glove_get_tactile_binary_sensitivity，用于读取已连接 Wuji Glove 当前生效的触觉接触灵敏度，并与现有 setter 配套。未设置灵敏度时返回默认值 1.0，存储值会限制在 0.5 到 3.0 的运行范围内
变更：
  • 手部模型标定相关文案统一为手部模型标定
修复：
  • 设备连接后时间戳切换为同步时间时，融合 IMU 姿态和腕部坐标变换保持稳定，不再发生姿态跳变
子模块Retargeting变更：
  • Python 和 C SDK 的捏合手势重定向改进拇指与其他指尖的接触效果
​
固件 v2.6.0 · Wuji SDK v2026.8.31
组件版本主要更新新增能力：
  • 错误码目录新增 0x2115，表示电机相电流不平衡。当前固件仅观测该异常，不会上报错误或停止关节
  • 指尖传感器元数据新增合力作用点和坐标轴方向信息。应用可据此在指尖位置计算力和力矩，未使用这些信息的现有应用不受影响
变更：
  • 编码器帧损坏时会立即提示。持续损坏时，受影响关节会停止
  • 更新指尖传感器安装信息
  • 同步更新 Wuji SDK 的指尖传感器合力作用点和姿态示例
  • 优化系统性能
修复：
  • 修复读取 Flash 时设备可能无响应的问题
  • 修复拇指与其他手指捏合时，关节可能误报过流并停止的问题
​
固件 v0.12.0
组件版本主要更新固件
  • 修复部分已知问题
​
v2026.8.31
重要变更：手部模型标定命令改为 wuji calib hand-model，已移除的 wuji calib ik 不提供兼容别名。--json 和 --jsonl 事件改用 schema_version: 2 与 calibration: "hand_model"。
组件版本主要更新新增能力：
  • 新增 wuji viz 实时可视化，可查看 Wuji Hand 2 的姿态和指尖触觉数据
变更：
  • 手部模型标定命令统一为 wuji calib hand-model。已移除的 wuji calib ik 不提供兼容别名
  • wuji calib hand-model 的引导、姿势反馈和结果展示更清晰
  • wuji user 管理 Profile 和迁移标定数据时，终端提示更一致
  • wuji calib hand-model 的 --json 和 --jsonl 事件使用 schema_version: 2 与 calibration: "hand_model"。wuji user import 使用 legacy_hand_model_ignored 和 default_user_hand_model_disabled 标识组件被跳过的原因
  • wuji upgrade --file 会在本地校验固件文件，无效文件不会发送到设备
  • 一键安装脚本会将 Agent Skills 安装到用户全局位置，供所有项目使用
修复：
  • Windows 上下载固件时会使用用户配置目录，不再依赖 Unix 专用的 HOME 变量。标定导出失败路径在各平台使用稳定的 / 分隔符
  • 修复部分已知问题
  • wuji doctor 遇到没有诊断方案的设备时会标记为跳过，不再标记失败，并以退出码 0 结束。真实连接或采集失败仍标记失败并返回退出码 1
  • wuji logs list 和 wuji logs export 支持包含非 UTF-8 字符的日志目录名称
​
v2026.8.17
重要变更：本次含 Wuji Glove 破坏性变更——EMF 姿态输出率分频器接口移除（Python 与 C），改用 emf_poses 订阅上的 set_rate。
组件版本主要更新通用新增能力：
  • 新增 Subscription.set_rate(frequency_hz)，运行时调低已订阅流的固件推送频率（单位为每秒采样数）。需先将设备固件升级到支持流频率调节的版本（Wuji Glove v0.11.4 及以上、Wuji Hand 2 v2.3.0 及以上），传入 0 恢复设备默认，返回值为设备实际生效的频率（可能被量化）。可调流为 Wuji Glove 的 emf_poses、tactile、tactile_zones、imu_raw/* 与 Wuji Hand 2 的 joint_states、joint_diagnostics、imu、fingertip/*/data。派生流（hand_joint_angles、hand_skeleton、tip_poses、imu_data/* 等）跟随源流频率并拒绝 set_rate。设置作用于该流的所有订阅者，最后一个订阅关闭或设备重连后恢复设备默认。Python 与 C 示例分别见 examples/python/wuji_glove/6.set_stream_rate.py、examples/c/wuji_glove/1_set_stream_rate.c 与 examples/python/wuji_hand_2/4.set_stream_rate.py、examples/c/wuji_hand_2/4_set_stream_rate.c
  • C SDK：新增 wuji_sub_set_rate(sub, frequency_hz, out_actual_hz)，可在任意订阅句柄上调用，语义与 Python Subscription.set_rate 一致。不支持频率调节的流返回 WUJI_STATUS_ERR_UNSUPPORTED (-8)，且不向设备发送调频请求
变更：
  • device.get() / manager.get() 读取不存在的参数路径时现抛出 WujiException，此前会静默返回 None
修复：
  • C SDK：对资源执行其不允许的操作（如读取只写资源、订阅只发布主题）现返回 WUJI_STATUS_ERR_UNSUPPORTED，不再返回 WUJI_STATUS_ERR_INTERNAL
  • Python 与 C SDK：设备断连或被其他主机接管后，Python 的 recv() / recv_async() 立即抛出 WujiException，C 订阅回调不再投递缓冲帧并终止。此前 Python 可能返回缓冲帧或 None，C 回调可能在终止前投递缓冲帧
设备Wuji Hand 2变更：
  • 打印 JointDiagnosticsEntry 时 error_code_current 改按 16 进制显示（0x2103 而非 8451），与文档中错误码写法一致。error_code().get() 仍返回整数，直接打印时自行按 f"0x{code:04X}" 格式化
  • 设备固件 v2.4.0 起，指尖分点力按传感器满量程归一化上报：法向轴 0 到 1，切向轴 -1 到 1，超量程截断。v2.4.0 之前的固件仍按牛顿上报分点力。合力与温度不受影响，两版固件均为牛顿与摄氏度。解码时从 info.format 读取 scale 与 unit，不要固定假设任一约定，固件升级后重新获取 info 以获得新量程
Wuji Glove破坏性变更：
  • 移除 EMF 姿态输出率分频器：Python glove.emf_poses_rate_divider()、C wuji_glove_get_emf_poses_rate_divider / wuji_glove_set_emf_poses_rate_divider 及对应示例。请先将设备固件升级到 v0.11.4 及以上，改用 emf_poses 订阅上的 set_rate。设置在最后一个订阅关闭或设备重连后重置。调低 emf_poses 同时降低手部追踪使用的 EMF 输入频率
Wuji Hand修复：
  • 直连手部方法（read_joint_state()、enable() / disable()、clear_all_faults()、力矩限幅与诊断读取、打开实时控制器）在 disconnect() 后返回断连错误，不再继续操作设备。Python 抛出 WujiException，C 返回 WUJI_STATUS_ERR_DISCONNECTED
  • 断连时即使关节状态订阅仍打开也会释放 USB 设备，同一进程可立即重连，无需先关闭订阅或删除手对象
子模块Retargeting变更：
  • 实时遥操作示例（examples/python/retargeting/1.teleop_real.py 与 examples/c/retargeting/1_teleop_real.c）启动时列出 SDK 用户并提示选择，不再固定切换到默认用户。按回车保持当前用户，选默认用户使用内置手部 URDF，选具名用户使用该用户标定的手部模型，未标定的具名用户同样使用内置 URDF。退出时仍还原此前选中的用户
​
固件 v2.4.0 · Wuji SDK v2026.8.17
组件版本主要更新固件新增能力：
  • 订阅数据流支持调节推送频率：主机可要求设备降低某条流的发送频率，节省带宽与主机侧处理。设备按其支持的档位生效并回报实际频率。可调流为实时关节流、五路指尖触觉流与 IMU 流。流的最后一个订阅者退出、主机断开或重连后恢复满速。需 Wuji SDK v2026.8.17 及以上
变更：
  • 指尖分点力从绝对力读数改为归一化数值，读数可跨手指与传感器型号直接比较，无需知道各传感器量程
    • 各触点法向轴 0 到 1、两切向轴 -1 到 1，按满量程基准折算，超量程截断
    • 三轴合力与温度读数不变
    • 传感器元数据仍描述各读数适用的量程与单位，按元数据解码的应用自动获得新量程
修复：
  • 修复指尖力在 2 N 以下无响应的问题
  • 修复接触释放后指尖读数未回到零位的问题
  • 改进拇指指尖各传感器读数一致性
Wuji SDK新增能力：
  • 新增 Subscription.set_rate(frequency_hz)，运行时调低已订阅流的固件推送频率（单位为每秒采样数）。需先将设备固件升级到支持流频率调节的版本（Wuji Glove v0.11.4 及以上、Wuji Hand 2 v2.3.0 及以上），传入 0 恢复设备默认，返回值为设备实际生效的频率（可能被量化）。可调流为 Wuji Glove 的 emf_poses、tactile、tactile_zones、imu_raw/* 与 Wuji Hand 2 的 joint_states、joint_diagnostics、imu、fingertip/*/data。派生流（hand_joint_angles、hand_skeleton、tip_poses、imu_data/* 等）跟随源流频率并拒绝 set_rate。设置作用于该流的所有订阅者，最后一个订阅关闭或设备重连后恢复设备默认。Python 与 C 示例分别见 examples/python/wuji_glove/6.set_stream_rate.py、examples/c/wuji_glove/1_set_stream_rate.c 与 examples/python/wuji_hand_2/4.set_stream_rate.py、examples/c/wuji_hand_2/4_set_stream_rate.c
  • C SDK：新增 wuji_sub_set_rate(sub, frequency_hz, out_actual_hz)，可在任意订阅句柄上调用，语义与 Python Subscription.set_rate 一致。不支持频率调节的流返回 WUJI_STATUS_ERR_UNSUPPORTED (-8)，且不向设备发送调频请求
变更：
  • 打印 JointDiagnosticsEntry 时 error_code_current 改按 16 进制显示（0x2103 而非 8451），与文档中错误码写法一致。error_code().get() 仍返回整数，直接打印时自行按 f"0x{code:04X}" 格式化
  • 设备固件 v2.4.0 起，指尖分点力按传感器满量程归一化上报：法向轴 0 到 1，切向轴 -1 到 1，超量程截断。v2.4.0 之前的固件仍按牛顿上报分点力。合力与温度不受影响，两版固件均为牛顿与摄氏度。解码时从 info.format 读取 scale 与 unit，不要固定假设任一约定，固件升级后重新获取 info 以获得新量程
  • device.get() / manager.get() 读取不存在的参数路径时现抛出 WujiException，此前会静默返回 None
修复：
  • C SDK：对资源执行其不允许的操作（如读取只写资源、订阅只发布主题）现返回 WUJI_STATUS_ERR_UNSUPPORTED，不再返回 WUJI_STATUS_ERR_INTERNAL
  • Python 与 C SDK：设备断连或被其他主机接管后，Python 的 recv() / recv_async() 立即抛出 WujiException，C 订阅回调不再投递缓冲帧并终止。此前 Python 可能返回缓冲帧或 None，C 回调可能在终止前投递缓冲帧
Wuji Studio修复：
  • 修复设备连接部分问题
  • 修复设备固件升级中错误的固件列表状态
Wuji Retargeting变更：
  • 实时遥操作示例（examples/python/retargeting/1.teleop_real.py 与 examples/c/retargeting/1_teleop_real.c）启动时列出 SDK 用户并提示选择，不再固定切换到默认用户。按回车保持当前用户，选默认用户使用内置手部 URDF，选具名用户使用该用户标定的手部模型，未标定的具名用户同样使用内置 URDF。退出时仍还原此前选中的用户
  • 手部模型子模块 wuji-description 更新到 v2026.8.3，Wuji Hand 2 示例配置（adaptive_analytical_wuji_glove_wuji_hand_2_{left,right}.yaml）指向新的 hand2/hand2_beta1/body/ 资产布局，并按新模型朝向重调 mediapipe_rotation（左 x = 180、右 y = 180、双侧 z = -90）。IK 与仿真行为无变化
Wuji Description新增能力：
  • 新增 Wuji Hand 2（Beta 2）交付——Beta 1 基础上每指尖增加一块触觉传感 pad 连杆，双手均以无座机器人模型交付（根连杆 {l,r}_wrist）
    • 触觉传感 pad：每块 pad（{p}_{finger}_tip_sensor_frame）经 {p}_{finger}_tip_sensor_frame_fixed 固定焊接到远节，银色本体上显示浅蓝。各 pad 携带实测质量——拇指 6.3 g、其余四指各 3.0 g，远节质量同步重测，拇指远节降为 10.9 g、其余各 5.0 g
    • 坐标契约：与 Beta 1 一致并经验证——同样 20 个转动关节与相同整数单位轴，零位指尖间距左右差 0.56 mm 以内。五个指尖查询 site（{l,r}_{finger}_tip）沿袭 Beta 1，仍以 MJCF <site> 形式在显示组 3 提供
    • 格式：URDF（含 package://wuji_hand2_beta2_description ROS 变体）、MuJoCo MJCF、分层 Isaac Sim USD 与解剖学命名 STL 网格（每手 31 个），外加每手一份带座整手 STEP CAD 装配（hand2/hand2_beta2/body/step/wuji-hand2-description-{left,right}_beta2_with_mount_step.STEP）用于机械集成。STEP 文件与 Beta 1 装配逐字节相同、暂不含指尖触觉 pad，包络与安装接口工作用它，pad 以 body/ 下模型为准
  • Wuji Hand 2（Beta 2）模型命名带修订版标识：无座 robot/model 名 wujihand2-beta2-{side}，带座 wujihand2-beta2-{side}-mount，USD 入口 wujihand2_beta2.usd（子层 wujihand2_beta2_{base,physics,robot,sensor}.usd），USD 根 prim wujihand2_beta2_{side}，不再与 Beta 1 资产重名
  • 新增独立 ROS2 包 wuji_hand2_beta2_description（包根 hand2/hand2_beta2/body/，含 CMakeLists.txt 与 package.xml），Beta 2 的 {left,right}-ros.urdf 经 package://wuji_hand2_beta2_description/meshes/... 解析网格。与 Beta 1 的 wuji_hand2_description 包名不同、网格集各异，两个修订版可在同一工作区共存
  • 新增 Wuji Hand 2 掌心安装接口 CAD 与标注图纸，每手一对文件，位于 hand2/hand2_beta1/attachment/ 与 hand2/hand2_beta2/attachment/
    • STEP 装配（wuji-hand2-description-{left,right}-mount_beta{1,2}_step.STEP）：仅掌壳与线束，非整手
    • A3 图纸（wuji-hand2-description-{left,right}-mount_beta{1,2}.pdf）：单页标注转接件对接的螺纹孔——一个 M3×0.5 细牙 6H（牙深 >5.5 mm，⌀4 (0/+0.05) 沉孔深 2.35 ±0.03）与两个 M4×0.5 细牙 6H（牙深 >4 mm，⌀7 (0/+0.06) 沉孔深 1 mm），由 28.00 (0/−0.05) 与 5.15 (+0.15/−0.05) 基准尺寸定位
    • 适用范围：自制臂侧转接板或工装时使用，仿真仍以 body/ 下模型为准
    • 文件：左右手互为镜像，Beta 1 与 Beta 2 逐字节相同（两修订掌心接口未变）。attachment/ 位于 ROS2 包根 body/ 之外，colcon 不安装
  • 新增 Wuji Hand 2 两个修订版的带座变体：臂法兰安装座连杆（{l,r}_mount，69 g）作为模型根，腕壳经 {l,r}_wrist_fixed 固定焊接其上
    • 选型：安装到机械臂时用带座变体，以腕部为安装点用无座变体。两变体关节名、轴、限位与执行器完全一致，每个修订版安装一个包即可加载任一变体
    • 布局：两变体并存于各修订版 body/ 目录，以 _with_mount 文件名后缀区分——urdf/{left,right}_with_mount.urdf、urdf/{left,right}_with_mount-ros.urdf、mjcf/{left,right}_with_mount.xml 与 usd/{left,right}_with_mount/
    • Beta 2（hand2/hand2_beta2/body/）：ROS URDF 经 package://wuji_hand2_beta2_description/meshes/... 解析，与无座同前缀。两变体逐字节共享 meshes/{left,right}/ 的 31 个手部网格，带座仅增 {l,r}_mount.STL，每手目录 32 个网格
    • Beta 1（hand2/hand2_beta1/body/）：ROS URDF 经 package://wuji_hand2_description/meshes/... 解析（与无座同前缀），USD 入口文件名保持 wujihand2.usd、仅所在目录不同。MJCF 中腕壳 {l,r}_wrist 是 {l,r}_mount 下的独立 body 而非并入，腕法兰坐标系保持可寻址。26 个手部网格逐字节共享，带座仅增 {l,r}_mount.STL（每手 27 个）。两变体运动学等价：扣除固定安装偏移后指尖位姿一致性 0.006 mm 以内
变更：
  • Wuji Hand 2（Beta 1）右手换用新机械 CAD 导出。运动学与动力学不变，左手与上一版本逐字节相同
    • 运动与质量：同样 20 个转动关节与相同整数单位轴，零位指尖 site 移动至多 0.0022 mm、body 原点至多 0.0018 mm，逐 body 与整手质量与上版一致（无座 0.6207 kg）
    • 拇指坐标系：无座导出的 r_thumb_middle 现与带座导出同坐标系——r_thumb_mcp 与 r_thumb_ip 均零 roll，旧导出在前者加 +6.3186° 又在后者减回。两变体逐字节共享 r_thumb_middle.STL，meshes/right/ 与 meshes/left/ 保持对称
    • 网格：本次导出只改右手的 r_thumb_middle.STL，其余全部网格（含全部远节与指尖网格）与上一版本逐字节相同，MJCF 碰撞几何与渲染不受影响
  • Wuji Hand 2（Beta 2）MJCF body 树中每个指尖触觉 pad 现为独立 body（{p}_{finger}_tip_sensor_frame），不再并入远节
    • 原因：MuJoCo 的 URDF 编译器默认合并零自由度焊接连杆，pad 因此没有自己的 body——无法挂 force / torque 传感器、无法做 body 级位姿查询、body 清单与 URDF 和 USD 不一致
    • 质量：各 pad 携带自身质量与惯量（拇指 6.3 g、其余 3.0 g），远节只携带自己的（拇指 10.9 g、其余 5.0 g）。pad 碰撞几何不变，接触参与如前
    • Site：空的 {p}_{finger}_tip 坐标连杆仍合并，保持以 MJCF <site> 形式提供（MuJoCo 中可查询坐标系的惯用形式）
    • 运动学与动力学：不变——总质量、指尖 site 位姿、整手质心、复合惯量与接触数与上版一致（浮点噪声以内）。带座变体同理，腕壳 {l,r}_wrist 为 {l,r}_mount 下独立 body，腕法兰坐标系可寻址
​
固件 v0.11.4 · Wuji SDK v2026.8.17
重要变更：本次含 Wuji SDK 破坏性变更——EMF 姿态输出率分频器接口移除（Python 与 C），改用 emf_poses 订阅上的 set_rate。
组件版本主要更新固件新增能力：
  • 订阅数据流支持调节推送频率：主机可要求设备降低某条流的发送频率，节省带宽与主机侧处理。设备按其支持的档位生效并回报实际频率。可调流为触觉帧、触觉分区、EMF 追踪流与六路 IMU 流。流不再使用或设备重连后恢复满速。需 Wuji SDK v2026.8.17 及以上
修复：
  • 修复掌部 IMU 帧序号在链路正常时跳号的问题：FrameHeader.seq 现严格逐帧加一，序号断档即代表真实丢帧，此前计数器可能虚报 0.35% 丢帧
Wuji SDK破坏性变更：
  • 移除 EMF 姿态输出率分频器：Python glove.emf_poses_rate_divider()、C wuji_glove_get_emf_poses_rate_divider / wuji_glove_set_emf_poses_rate_divider 及对应示例。请先将设备固件升级到 v0.11.4 及以上，改用 emf_poses 订阅上的 set_rate。设置在最后一个订阅关闭或设备重连后重置。调低 emf_poses 同时降低手部追踪使用的 EMF 输入频率
新增能力：
  • 新增 Subscription.set_rate(frequency_hz)，运行时调低已订阅流的固件推送频率（单位为每秒采样数）。需先将设备固件升级到支持流频率调节的版本（Wuji Glove v0.11.4 及以上、Wuji Hand 2 v2.3.0 及以上），传入 0 恢复设备默认，返回值为设备实际生效的频率（可能被量化）。可调流为 Wuji Glove 的 emf_poses、tactile、tactile_zones、imu_raw/* 与 Wuji Hand 2 的 joint_states、joint_diagnostics、imu、fingertip/*/data。派生流（hand_joint_angles、hand_skeleton、tip_poses、imu_data/* 等）跟随源流频率并拒绝 set_rate。设置作用于该流的所有订阅者，最后一个订阅关闭或设备重连后恢复设备默认。Python 与 C 示例分别见 examples/python/wuji_glove/6.set_stream_rate.py、examples/c/wuji_glove/1_set_stream_rate.c 与 examples/python/wuji_hand_2/4.set_stream_rate.py、examples/c/wuji_hand_2/4_set_stream_rate.c
  • C SDK：新增 wuji_sub_set_rate(sub, frequency_hz, out_actual_hz)，可在任意订阅句柄上调用，语义与 Python Subscription.set_rate 一致。不支持频率调节的流返回 WUJI_STATUS_ERR_UNSUPPORTED (-8)，且不向设备发送调频请求
变更：
  • device.get() / manager.get() 读取不存在的参数路径时现抛出 WujiException，此前会静默返回 None
修复：
  • C SDK：对资源执行其不允许的操作（如读取只写资源、订阅只发布主题）现返回 WUJI_STATUS_ERR_UNSUPPORTED，不再返回 WUJI_STATUS_ERR_INTERNAL
  • Python 与 C SDK：设备断连或被其他主机接管后，Python 的 recv() / recv_async() 立即抛出 WujiException，C 订阅回调不再投递缓冲帧并终止。此前 Python 可能返回缓冲帧或 None，C 回调可能在终止前投递缓冲帧
​
v2026.8.17
重要变更：wuji doctor --json 输出结构由平铺的 system / devices 改为按诊断层组织的 env / device，按旧字段名取值的脚本需迁移。
组件版本主要更新新增能力：
  • 主机环境诊断：wuji doctor 在扫描设备前先检查主机软件版本、系统信息与网络接口，并报告扫描中发现的地址冲突。破坏性变更：--json 输出改按诊断层组织为 env（主机环境检查）与 device（设备发现作为不带 sn 的通用条目，加逐设备结果），替代旧的平铺 system / devices 结构。未连接设备不再是错误，正常退出（主机检查失败才非 0）
  • 新增 wuji logs dump 子命令，采集 Wuji Hand 2 设备侧诊断快照：默认扫描全部设备，可用 --sn / --address / --handedness 指定单台。采集设备身份、故障与状态、母线电压与温度、通信诊断及 Flash KV 历史，产出 <sn>_<ts>_device.json 与 <sn>_<ts>_flash.jsonl。单个字段采集失败记入快照 failures 列表不中断，任一设备失败时退出码非 0
  • 设备快照进支持包：wuji logs export 现默认把设备诊断快照与 Flash 日志打包进支持包的 devices/ 目录，无需额外参数
  • 手部模型标定录制进支持包：wuji logs export 自动纳入 ~/.wuji/calibration/recordings/ 中与所选本地日期范围相交的手部模型标定 run，包括 manifest、完整录制和已完成步骤录制
  • 脚本友好 JSON 字段：wuji user show --json 新增 missing_model_files，清单中被跳过的组件行新增 detail 字段（reason 取值 incomplete_model / not_in_bundle / not_declared_in_manifest）
变更：
  • 结构化 JSON 错误：--json / --jsonl 下的多数命令错误以结构化 JSON 输出到 stderr，stdout 仅输出数据，供脚本消费
  • 彩色错误标签：human 模式错误打印红色 error: 标签（rustc 风格），与既有 warning: 标签一致
修复：
  • 未知资源路径：wuji get 读取未知资源路径现明确报错，不再静默返回成功且无值
  • 不完整触觉模型如实上报：wuji user export / import / import --preview / show 把缺 contact.safetensors、contact.npz 或 contact.json 的触觉模型列为跳过并列明设备 SN 与缺失文件，不再静默丢弃。仅有不完整模型时导出不再声称无标定数据，报错列明设备与文件并指向 wuji calib tactile
  • --json 恒返 current_user：wuji user create / switch / rename / delete 的 --json 输出固定报告命令结束后的 current_user（rename 另报 previous_name），脚本无需再运行一次 user list
​
v2026.8.3
重要变更：本次含 C SDK 破坏性变更（joint diagnostics 结构体 ABI 变化），使用相关结构体的 C 应用需用新头文件重新编译。
组件版本主要更新通用变更：
  • 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 手部模型标定示例现为 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
​
固件 v2.2.3 · Wuji SDK v2026.8.3
重要变更：本次含 C SDK 破坏性变更（joint diagnostics 结构体 ABI 变化），使用相关结构体的 C 应用需用新头文件重新编译。
组件版本主要更新固件新增能力：
  • 手背 logo 新增状态灯，开机、就绪、运行、固件升级、告警与故障状态一眼可辨，参见灯语说明
  • 新增告警码 0x0015：电机参数异常
修复：
  • 修复若干已知问题
Wuji SDK新增能力：
  • joint_diagnostics 流内置通信健康数据：逐关节上报总线应答率与超时计数，每帧附带端到端（以太网）流丢失、请求重试/超时计数与指尖触觉在线 bitmap 汇总，SDK 在后台自动维护，无需轮询
破坏性变更（C SDK）：
  • joint diagnostics 结构体新增字段导致 C ABI 变化，使用 WujiJointDiagnosticsEntry 或 WujiJointDiagnosticsFrame 的应用必须用新头文件重新编译后再链接新库。既有字段的含义与顺序不变，源代码无需修改，新增字段承载上面描述的逐关节总线通信质量与帧级通信汇总
变更：
  • 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 可以删除
修复：
  • 修复连接时绑定固定本地网络端口的问题，本地端口现由操作系统自动分配，SDK 不再与应用已占用的端口冲突
  • 修复设备扫描在网络对端于发现过程中消失这一罕见场景下无限挂起的问题，网络发现步骤现有时间上限，扫描总能在数秒内返回已发现的设备，覆盖 Python SDK 与 C SDK
  • 修复 Linux 多网卡或多 IP 主机上、主 IP 不在设备网段时网络设备发现永远找不到设备的问题，覆盖 Python SDK 与 C SDK
  • effort_limit 设置被设备拒绝的值（如超过当前上限）时现抛出 ValueError 而非笼统错误，设备保持原有上限
Wuji Studio修复：
  • 修复固件升级成功偶尔被报告为失败的问题
  • 修复连接 Wuji Hand 2 时误报「read-only mode」的问题
Wuji Retargeting变更：
  • 为新的按序列号标定重新调校了 Wuji Glove 示例配置中的 mediapipe_rotation 偏置（adaptive_analytical_wuji_glove_{left,right}.yaml 与 adaptive_analytical_wuji_glove_wuji_hand_2_{left,right}.yaml），手动 wrist_offset_cm / thumb_offset_cm 保持停用——SDK 会应用按序列号标定的 URDF
修复：
  • 修复 teleop_real.py 在 Wuji Hand 2（网络）后端上因 Wuji SDK 2026.7.1 资源 API 重构而启动即抛 AttributeError 的问题，控制行为不变。需要 Wuji SDK ≥ 2026.7.1 及匹配的固件
​
Wuji SDK v2026.8.3
组件版本主要更新Wuji SDK新增能力：
  • 新增引导式触觉标定——按提示录制手部动作，为该只手套训练接触模型，在 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 手部模型标定示例现为 examples/c/wuji_glove/4_user_calibration.c（由 3_user_calibration.c 重命名），标定当前所在的 SDK 用户而不再创建或切换用户，需要创建或切换用户时先用新增的 3_user_management.c 示例。新增 --blocking 模式，运行至完成，不含默认异步路径提供的协作式 Ctrl+C 取消
修复：
  • EMF 手指位姿现使用所选手型 URDF 拒绝不可达的镜像位置，减少瞬时干扰导致的位置翻转
  • 修复设备扫描在网络对端于发现过程中消失这一罕见场景下无限挂起的问题，网络发现步骤现有时间上限，扫描总能在数秒内返回已发现的设备，覆盖 Python SDK 与 C SDK
  • 修复 Linux 多网卡或多 IP 主机上、主 IP 不在设备网段时网络设备发现永远找不到设备的问题，覆盖 Python SDK 与 C SDK
Wuji Description
  • 新增 PICO 4 Ultra 手柄安装座 CAD 装配（STEP AP214），用于把手柄固定在 Wuji Glove 上，与既有的 Wuji Glove 安装接口、PICO 追踪器适配件同目录提供
​
v2026.8.3
重要变更：设备类型显示名统一为小写 snake_case（wuji upgrade --type 取值随之变化），按旧输出做字符串匹配的脚本需更新。
组件版本主要更新新增能力：
  • 新增 Wuji Hand 2 支持：wuji upgrade 可为带触觉传感器的 Wuji Hand 2 升级固件
  • 新增触觉标定：wuji calib tactile 为 Wuji Glove 采集、训练、验证并安装接触模型，--non-interactive 模式支持无人值守运行
  • 新增手部模型标定：wuji calib hand-model（发布时为 wuji calib ik，现已更名）引导设备选择、实时姿势与参考图示，完成后为当前 Profile 保存并热加载标定模型。它构建与真实手型匹配的手部模型，让捏合、四指弯曲等手势在 Wuji Glove 上输出符合预期
  • 新增用户 Profile：wuji user 管理 Wuji Glove 标定 Profile——创建、描述、切换、列出、查看、重命名与删除，并导入/导出 IK 与触觉标定数据。结果按 Profile、按手存储，同一只手上的手套在同一 Profile 下共享同一份结果
  • 新增日志命令组：wuji logs（path、list、export）覆盖日志目录查看、文件列出与支持包导出，可把主机侧日志（SDK、Studio 等工具）打包，连同设备 SN 发送至 [email protected]
  • 新增 Agent skills：逐一覆盖上述命令——Profile 管理、标定与日志
破坏性变更：
  • 设备类型显示名统一为小写 snake_case，wuji upgrade --type 现要求 snake_case 取值（如 wuji_glove），影响 ping 的 Device Type 列、doctor 报告标题、upgrade --check 输出、帮助示例与全部文档

​
2026 年 7 月

​
Wuji Hand 2
组件版本主要更新Wuji Description
  • 新增 Wuji Hand 2（Beta 1）交付，这是按新坐标系规则重新标定的首个修订版，以下坐标约定自本版起定版——整数单位关节轴、解剖学连杆/关节命名（如 r_thumb_cmc_flex）、根连杆 {l,r}_wrist、执行器命名方案（{l,r}_{THJ|FFJ|MFJ|RFJ|LFJ}{0-3}，J0 = 屈曲 … J3 = DIP）——后续修订版保持兼容，仅更新物理参数和几何细节，每只手有 20 个驱动旋转关节（5 指 × 4 关节）。
  • 新增 Wuji Hand 2（Beta 1）左右手模型：URDF（相对网格路径）及其 ROS 变体（package://wuji_hand2_description 路径）、MuJoCo MJCF（碰撞几何取各连杆网格凸包）、分层 Isaac Sim USD 资产（驱动增益可在直接 Play 时保持姿态）、按解剖学命名的 STL 网格——kp/kv 驱动增益沿用 Wuji Hand 平台标定结果，待 Wuji Hand 2 硬件系统辨识完成后更新。
  • 每只手新增 5 个指尖查询 site（{l,r}_{finger}_tip，显示分组 3），用于抓取点查询和指尖轨迹评估。
  • 新增整机 STEP CAD 装配（左右手），用于机械集成与夹具设计。
  • 新增独立 ROS2 包 wuji_hand2_description，Wuji Hand 2（Beta 1）ROS URDF 的网格解析独立于 Wuji Hand wuji_description 包。
  • 调整 Wuji Hand 2（Beta 1）碰撞策略：全部连杆参与碰撞，仅排除 10 组装配重叠对（各指 proximal 与 proximal_abd 对手腕），指间与指尖-手掌接触保持生效，显示分层为 group 1 视觉（银色）、group 2 碰撞（半透明浅紫）、group 3 指尖 site，指尖软体随包提供但尚未挂为碰撞几何——指尖接触由末节几何承载，接触点与真实指腹略有偏移。
  • 移除旧版 Wuji Hand 2（Beta）模型修订（根连杆为 {l,r}_base_link）及其结构 STEP 装配体和机械臂法兰适配座——已由重新标定的 Wuji Hand 2（Beta 1）修订取代。
​
v2026.7.21
重要变更：重定向接口移至包顶层（Python 破坏性更新），wuji_sdk.retargeting 子模块已移除，请按新导入方式更新调用方代码。
组件版本主要更新设备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 输出，改进拇指关节动作——相同输入的关节角度可能与之前版本不同
​
固件 v2.1.0 · Wuji SDK v2026.7.21
组件版本主要更新固件新增能力：
  • 提供逐指触觉数据流，数据帧布局由自描述传感器元数据定义：主机先获取元数据，再按元数据解码数据流
  • 支持查询触觉传感器状态（型号与标定状态）
  • 支持运行时重新标定指尖触觉传感器，将全部 5 个指尖重置到全新零基线（经 SDK tactile_calibrate 触发）
变更：
  • 使能状态的关节与主控通信中断时，现在会停止电机并上报故障，不再按最后一次收到的指令继续运行，重新使能需要主机显式下发指令
  • 改进编码器健康监测：高速运行不再误触发编码器警告，真实的编码器链路退化可更早、更可靠地被检出
修复：
  • 修复实时数据流时间戳逐渐偏离主机时间，以及设备保持上电时重连 SDK 后时间戳无法重新对齐的问题
Wuji SDK新增能力：
  • 指尖触觉感知首次正式发布：订阅按手指的自描述传感器数据流（FingertipSensorInfo 元数据描述如何解码每帧 FingertipSensorData，参见 3.fingertip_typed.py 示例），在传感器表面无负载时用 hand.tactile_calibrate()（Python）/wuji_hand_2_tactile_calibrate(dev)（C）将全部 5 个指尖重新标定到全新零基线，并用 hand.tactile_status(finger) 查询各传感器的型号与标定状态、确认重新标定已完成
修复：
  • 固件升级失败时报告详细错误（具体原因、错误码和失败节点），不再只显示笼统的 “Unknown error”
​
v2026.7.15
组件版本主要更新
  • 修复安装脚本未安装 agent skills 就退出的问题
​
v2026.7.14
重要变更：Wuji Hand 的 Python 接口对齐 Wuji Hand 2 资源式 API（破坏性更新），Wuji Glove 手部标定改为归属 SDK 用户与左右手。请升级 SDK 并按新接口更新调用方代码，Wuji Glove 用户请重新标定。
组件版本主要更新通用新增能力：
  • 用户数据导入导出：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 手部模型标定接口：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 打包，下载与安装体积显著减小，无功能变化
​
固件 v2.0.0 · Wuji SDK v2026.7.14
组件版本主要更新固件破坏性变更：
  • 本版固件面向 Beta 2 硬件。Beta 1 硬件不会收到本版更新——固件列表只提供与设备硬件匹配的固件包
修复：
  • 修复其他已知问题，提升整体稳定性
Wuji SDK
  • disconnect() 现在完全释放设备：断开后手立即可被任何其他程序或机器占用，与程序退出效果一致，此前手可能仍被程序持有直到退出
  • 修复反复连接 / 断开的程序中每次连接耗时递增的问题，现在无论程序运行多久连接都保持稳定快速
Wuji Studio
  • 固件升级视图按设备实际产品类型分组，Wuji Hand 设备不再显示在 “Wuji Glove” 分组下，无法识别的设备归入新的 “Other Devices” 分组
Wuji Description
  • 修复 Wuji Hand 2（Beta 1）URDF 的 ROS package:// mesh 路径解析问题：wuji_description 包现将该模型资产装入 share 目录，mesh 路径按模型隔离，可在 ROS 下正确加载
​
固件 v0.11.2 · Wuji SDK v2026.7.14
重要变更：Wuji Glove 手部标定改为归属 SDK 用户与左右手（破坏性更新）。请一并升级固件与 SDK，并在所用用户档案下重新标定左手和右手。
组件版本主要更新固件
  • 触觉点云主动接触点契约对齐到 526 个 taxel。固件仍扫描原始 24×32 传感器阵列，剔除无效列后对外发布 24×31 / 744 值触觉帧，点云主动掩码在此基础上再移除 8 个硬件屏蔽 taxel。请把 SDK 升级到匹配版本，让点云解码采用一致的 526-taxel 映射
Wuji SDK破坏性变更：
  • 标定结果（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 才能导入
新增能力（C SDK）：
  • 新增与 Python 对齐的 SDK 用户管理与 Wuji Glove 手部模型标定接口：C 程序可创建、切换 SDK 用户，运行带结构化反馈的标定，取消异步标定 session，并获取按用户隔离的标定 URDF 路径，标定示例提供与 Python 示例一致的原地终端仪表盘与限流 API 日志模式
  • 新增用户数据导入导出与预览，与 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
  • 扫描结果新增设备类型：WujiDiscovered.device_id 为 WujiDeviceType 枚举（WUJI_DEVICE_TYPE_WUJI_GLOVE / _WUJI_HAND_2 / _WUJI_HAND / _UNKNOWN），model 为对应类型字符串，连接前即可判断设备类型
破坏性变更（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()
修复：
  • Default 档案默认使用 Wuji 内置 URDF，历史标定结果不生效，需要标定请先新建并切换到自己的用户档案
Wuji Studio破坏性变更：
  • 标定文件格式变更，本版本之前生成的标定文件与新格式不兼容且不会迁移，升级后请分别重新标定左手和右手
新增能力：
  • 用户数据导入导出：从头像菜单把标定手部模型、触觉模型与采集记录导出为可移植的 .zip 并可再导入，导入前会预览包内容、显示所属用户并提示覆盖同名数据，数据恢复到包所属的用户档案（不存在则新建）后可切换到该档案，仅桌面端可用
变更：
  • 标定结果按所选 Wuji Studio 用户与左右手保存，同一用户下同侧的 Wuji Glove 共用一份结果
  • Hand Profile 更名为 Hand Model Source，Wuji Hand 2 与 Wuji Hand 两个手型 profile 已弃用，已有布局改为显示 SDK Managed（取用对应的标定模型，未标定时使用 SDK 默认模型），Custom URDF 仍然可用
修复：
  • 修复标定状态误判：兼容的 Wuji Glove 不再被误判为不支持标定，也不再显示错误的标定状态，无法查询标定状态时给出可重试的提示
  • 回放时拦截不兼容的历史触觉录制并给出明确警告，避免触觉渲染错误
  • 回放旧格式（v2026.6.18 之前）的触觉录制会出现不兼容警告，警告以右下角消息通知展示
  • 修复覆盖安装升级后触觉 Matrix 面板仍按 24×32 预设布局渲染的问题，布局现在于启动时自动迁移，用户自定义的列数不受影响
Wuji Description
  • 新增 Wuji Glove 安装夹具 CAD：Wuji-glove-attachment.STEP（Wuji Glove 安装接口）与 Pico-tracker-attachment.STEP（Pico tracker 适配件），均为 STEP AP214 装配体，供机械集成使用
​
v2026.7.14
组件版本主要更新Wuji CLI 全新发布：Wuji 设备的官方命令行工具，无 GUI 也能连接设备、批量升级、脚本自动化，wuji doctor 一键诊断排障。
  • 设备管理：wuji devices 扫描并列出 USB / UDP 设备，wuji ping 握手探测设备连通性，默认覆盖全部发现的设备，也可按 SN、IP 或左右手指定
  • 参数读写：wuji get / wuji set 以类型化 JSON 读写设备参数
  • 资源发现：wuji resources 列出设备的可读写参数与可订阅 topic
  • 数据订阅：wuji sub <topic> 订阅实时数据，--count 控制接收帧数
  • 健康诊断：wuji doctor 检查设备健康，支持 EMF 断线检测与触觉无效点 / 无效列检测，目前仅支持 Wuji Glove，后续扩展更多诊断项与设备类型
  • 固件升级：wuji upgrade 从官方固件源升级设备固件。--check 查看哪些设备有更新，支持单台或批量升级，--to 安装指定版本，--file 刷写本地固件包，--list 浏览可用版本。下载经 sha256 校验并缓存，刷写前有确认交互（--yes 跳过），逐台输出结果报告
  • 自更新：wuji update 下载、校验并原地安装最新版 CLI，--check 仅检查不安装
  • Shell 补全：wuji completions 生成 bash、zsh、fish、powershell 和 elvish 补全脚本
  • 输出格式：多数命令支持 --json / --jsonl 结构化输出，以及按 --sn / --address / --handedness 选择设备
  • 彩色输出：状态、警告与数值使用一致的语义配色，支持 NO_COLOR，非 TTY 输出自动降级为纯文本
​
v2026.7.2
组件版本主要更新设备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 直连修复
​
v2026.7.1
重要变更：Wuji Hand 2 接口重设计为统一资源式 API（破坏性更新）。请同步升级设备固件与 SDK，并按新接口更新调用方代码。
组件版本主要更新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
​
固件 v0.11.1
组件版本主要更新固件
  • 修复手部姿态偶现跳变：IMU FIFO 数据加入有效性校验，丢弃异常包，避免错误数据进入姿态融合
  • 修复 IMU 初始化未按出厂配置启用对应槽位的问题，掌部 IMU 配置不再因检测空槽位而上报部分初始化失败

​
2026 年 6 月

​
v2026.6.18
组件版本主要更新Wuji Glove
  • 触觉数据布局更新为 744 值 24×31（原 768 值 24×32），tactile、tactile_residual、tactile_binary 帧及分区触觉布局相应变小，无效触觉点仍报 -1.0
​
Wuji SDK v2026.6.18 · Wuji Studio v2026.6.18
组件版本主要更新Wuji SDK
  • 触觉数据布局更新为 744 值 24×31（原 768 值 24×32），tactile、tactile_residual、tactile_binary 帧及分区触觉布局相应变小，无效触觉点仍报 -1.0
Wuji Studio
  • 触觉矩阵和分区矩阵面板已更新为 24×31 (744) 新布局
  • MCAP 回放遇到旧版 24×32 (768) 或损坏的触觉录制时会拒绝播放并提示警告，避免按错误维度渲染
固件
  • 触觉数据升级为 24×31 矩阵格式，需将 Wuji Studio 与 SDK 升级到匹配版本，旧版 768 点固件不再兼容
​
v2026.6.16
组件版本主要更新通用
  • 新增预编译 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 侧手部模型标定接口 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 SDK v2026.6.16 · Wuji Studio v2026.6.15
组件版本主要更新Wuji SDK
  • 新增 glove.tactile_residual()，与 tactile 同频率发布 768 维连续接触残差（正值=按压、~0=无接触、-1.0=无效），沿用 TactileFrame 形状原有触觉网格可视化无需改动，可自定义阈值替代内置 tactile_binary
  • 新增预编译 C SDK（libwuji_sdk_c.so + wuji_sdk.h），覆盖设备连接、跨设备坐标变换（tf / tf_static）与多种数据流订阅（触觉、触觉区域、EMF 位姿、手部关节角度、手部骨架、触觉点云），支持 x86_64-linux-gnu / aarch64-linux-gnu / aarch64-android 三平台
  • 手部姿态求解改为多核并行，hand_joint_angles 及衍生手部追踪数据耗时降低，输出与 schema 不变
  • 新增 Python 标定 API glove.calibrate() / calibrate_blocking()，支持超时、约束跳过和 on_feedback 反馈回调，详见 标定
  • 实时 IK 支持手型代数选择，新增 calibration.hand_profile 参数（"wujihand" / "wujihand2"），不指定时同时生成两代 URDF 运行时即时切换无需重标定
  • 新增本机用户隔离 API（SdkManager.create_user 等），多名操作者共用同一设备时互不覆盖，切换用户自动重载参数无需重连
  • 新增 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 Studio
  • 新增设备工具 Modify Device Port 命令，修改设备数据端口后自动重启生效
  • 新增 wujistudio.recording 扩展 API，授权扩展可启动 / 查看 / 停止 Studio 录制（可选指定 source / topic）
  • 3D 面板 Hand Skeleton 支持手型 profile 切换（wujihand / wujihand2 / Custom URDF），Custom URDF 让 SDK 端 IK 使用本地 URDF
  • Calibration 启动时自动创建当前设备调试录制，供后续排查
  • Modify Device IP 限制目标地址为私有子网，其他地址会被拒绝
  • wujistudio.devices.subscribeTopic 现需 robotics.topics.read 权限，扩展须在 wujistudio.extension.json 的 permissions 中声明
  • 内置设备 SDK 集成更新：按用户标定与 SDK 端管理手型 profile 选择
  • 修复 3D 面板点云颜色错乱、半透明的问题，点云颜色现按所选 colormap 正确渲染
  • 修复设备被动重连（如固件升级重启）后设备日志不恢复的问题
Wuji Description
  • 首版 Wuji Glove URDF 模型上线，21 关节含腕部电磁发射器与指尖接收线圈，用于手部动作追踪
  • 新增电磁发射器与接收线圈的 STL meshes，以及发射器顶盖 STEP 与装配 PDF
  • 独立 attachment STEP 已移除，Wuji Glove 模型资产统一归位 glove/body/
​
v2026.6.2
组件版本主要更新
  • Wuji Glove：新增二值接触触觉数据流 glove.tactile_binary()，与 tactile() 同频率发布 768 维接触状态（1.0 接触、0.0 未接触、-1.0 无效触点），与 TactileFrame 同形，现有触觉网格可视化无需改动即可复用
  • 新增按手性连接 SdkManager.connect(handedness=Handedness.Left | Handedness.Right, ...)，可直接指定左手或右手连接双手设备

​
2026 年 5 月

​
v0.10.0
组件版本主要更新
  • 新增 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 v0.10.0 · Wuji Studio v2026.5.18
组件版本主要更新Wuji SDK
  • hand_joint_angles 和 tip_poses 改为基于 URDF 运动学链推导，输出 schema 不变，数值与旧版本可能不同。
  • 移除 glove.tactile_raw()，请改用 glove.tactile() 订阅标定后的触觉帧。
  • 移除 glove.factory_reset()。
  • 新增 device.export_flash_logs(out_dir)，将设备历史日志导出为 JSONL 文件。
  • 新增通道级录制健康指标 QualityMetrics.channels：每路 topic 的帧率、丢帧率、抖动、is_online、last_downtime_ms。
Wuji Studio
  • 新增 Extensions 视图，集中查看已安装扩展、安装或卸载本地扩展。
  • 内置标定、遥操作和设备工具三个首方扩展，开箱即用。
  • 修复 Linux 上全新安装后布局预设、已保存的布局和用户偏好为空的问题。
  • 修复 Windows 上 3D 面板加载本地 URDF 文件失败的问题。
  • 修复 URDF mesh 不跟随 /joint_states 实时更新的问题。

​
2026 年 4 月

​
固件 v0.10.1
组件版本主要更新
  • 修复一些已知问题。
​
固件 v0.10.0 · Wuji Studio v0.10.0
组件版本主要更新固件
  • 修复触觉数据周期性掉零问题，提升采样稳定性。
Wuji Studio
  • 自动检查 Studio 与设备固件更新，发现新版时通过弹窗和通知中心提示，点击直达下载页或升级视图。
​
v0.9.0
组件版本主要更新
  • 修复了部分已知问题
​
固件 v0.9.0 · Wuji SDK v0.9.0
组件版本主要更新
  • 修复了部分已知问题。

​
2026 年 3 月

​
固件 v0.8.0 · Wuji SDK v0.8.0
组件版本主要更新
  • 修复一些已知问题。
​
v0.8.0
组件版本主要更新
  • Wuji SDK 和 Wuji Studio 支持共享同一设备
  • 提升启动和运行期间的日志可用性与可靠性
  • 提升升级稳定性，减少升级失败误报
​
固件 v0.7.0 · Wuji SDK v0.8.0
组件版本主要更新
  • 提升启动和运行期间的日志可用性与可靠性。
  • 提升升级稳定性，减少升级失败误报。
​
v0.7.0
组件版本主要更新
  • 新增跨设备合并订阅，多设备场景下一次获取所有设备的聚合数据
  • 新增数据录制，支持多通道录制、暂停/恢复、分集切换和实时质量监控
  • 修复回调模式下偶发崩溃的问题
  • 修复同时订阅多个数据流时部分数据丢失的问题
  • 修复 Wuji Glove 部分 IMU 数据流无法订阅的问题

​
2026 年 2 月

​
v0.6.0
组件版本主要更新
  • 新增 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）
​
固件 v0.6.0 · Wuji SDK v0.6.0
组件版本主要更新Wuji Studio
  • 新增手部骨架和指尖姿态可视化，支持单指置信度着色、关节轴显示和透明度设置。
  • 3D 面板新增触觉点云压力着色，支持标准色谱（plasma、viridis 等）和多种映射函数。
  • 底部栏新增设备日志面板，支持按来源和级别过滤。
  • 可视化界面新增 LAYOUT 面板，支持一键恢复默认面板。
  • Raw Messages 面板
    • Topic 列表改为树形结构，支持按层级浏览 Topic 和 Schema 字段。
    • 支持显示 IMU 数据。
  • 固件升级页面展示累积更新日志，降级时显示警告。
  • 新增色觉无障碍设置，适配三种常见色觉类型。
  • 3D 视图默认配置适配 TF 树变更。
Wuji SDK
  • EmfPose error 字段更名为 confidence。
  • 新增 IMU 姿态数据及 ImuData API（掌心、拇指、食指、中指、无名指、小指）。
  • 新增 tf/tf_static 坐标变换 API，基准坐标系为 waist，支持用户自定义腕部偏移。
  • 新增手部追踪数据：tip_poses()（指尖姿态）、hand_joint_angles()（21 DoF 关节角度）、hand_skeleton()（21 个手部关键点）。
  • 新增触觉点云数据：tactile_point_cloud()，用于 3D 触觉可视化。
  • 新增设备日志模块。
  • 设备参数管理接口变更：load_profile()/has_profile() 替换为 get()/set()/save_params()。
​
v0.5.0
组件版本主要更新
  • Wuji SDK 首发：Wuji 设备的 Python 开发套件
  • 回调订阅支持 subscribe_with_callback()
  • 异步接收支持 recv_async()
  • IDE 自动补全支持
  • 数据流订阅：触觉矩阵、触觉区域、EMF 位姿
支持设备
  • Wuji Glove — 集成触觉感知和动作捕捉的智能手套
​
固件 v0.4.0 · Wuji SDK v0.5.0
组件版本主要更新全新设备 Wuji Glove 发布
  • 集成触觉感知和动作捕捉的智能手套。
  • 触觉感知：全手触觉数据采集，支持按区域输出（手掌、拇指、食指、中指、无名指、小指）。
  • 动作捕捉：指尖动捕模块实现五指动作捕捉。
  • LED 指示灯：多状态多模式反馈设备运行状态。
Wuji Studio 首发
  • 全新桌面应用，支持多设备同时连接、设备管理与数据可视化。
  • 可视化面板：3D 视图、波形图、原始消息、触觉矩阵，直观呈现设备数据。
  • 设备管理：支持设备发现、连接历史、重命名、标定、导出标定数据和设备信息查看。
  • 固件升级：支持在线下载和本地上传固件，带有进度跟踪与错误诊断。
  • 自动左/右手识别：设备命名时自动检测左右手。
  • 3D 手套可视化：关键点可视化，定位误差以颜色直观标注。
  • 亮色/暗色主题切换。
Wuji SDK 首发
  • 提供 Wuji Glove 语义化 API，支持回调订阅和异步调用。