设备参数与标定 - 文档中心

参数读取

通过语义化 API 读取设备属性：

sn = glove.sn().get()                # 序列号
version = glove.version().get()      # 固件版本
hand_side = glove.hand_side().get()  # 手别（"left" 或 "right"）
ip = glove.ip().get()                # IP 地址
port = glove.port().get()            # 数据端口

参数写入

部分参数支持写入：

glove.ip().set("192.168.1.100")     # 修改 IP 地址
glove.port().set(50001)             # 修改数据端口

修改网络参数（IP 地址、端口）后可能需要重新连接设备。

设备操作

参数持久化、重启等设备操作因产品而异。Wuji Glove 的具体操作见 Wuji Glove 设备操作。

SDK 用户管理

不同操作者共用同一台设备时，各自的标定参数和本地参数会互相覆盖。SDK 支持本机用户隔离，按 ~/.wuji/sdk/users/<user_id>/ 分目录存放每位用户的参数与标定文件。

不创建用户时，参数文件与触觉标定直接落到 ~/.wuji/sdk/params/、~/.wuji/sdk/tactile/，位姿标定则完全不可用。需要按操作者隔离、或需要做位姿标定时，创建具名用户：

from wuji_sdk import SdkManager

manager = SdkManager.instance()

# 创建用户
alice = manager.create_user("Alice", description="右手操作员")

# 切换到指定用户
manager.switch_user(alice["user_id"])

# 查看当前用户
print(manager.current_user())

# 列出所有用户
for user in manager.list_users():
    marker = "*" if user["is_default"] else " "
    print(f"{marker} {user['display_name']} ({user['user_id']})")

# 切回默认用户
manager.switch_to_default_user()

切换用户后，已连接的设备立即重新加载该用户的标定参数，无需重连。删除当前用户会自动切回默认用户。

C SDK 也提供用户管理接口，详见 C SDK 参考。

用户数据导入导出

一位 SDK 用户的全部数据可以打包成一个 zip 文件，用于备份或在主机之间迁移。包内含该用户的手部标定模型、每台设备的触觉模型，以及最新一次完整的触觉标定数据。

# 导出：把该用户的全部数据写入一个 zip 文件
report = manager.export_user_data(alice["user_id"], "alice.zip")
print(report["out_path"], report["device_sns"])

# 预览：只校验包内容，不写盘
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"))

# 导入：恢复到包内记录的所属用户
result = manager.import_user_data("alice.zip")
print(result["owner_user_id"], result["imported_at"])

三个方法都返回报告字典，components 逐项列出组件状态：

字段	说明
`name`	组件名，如 `hand_model.left`、`tactile.model`、`tactile.run`
`state`	`present` 组件已包含并写入，`missing` 用户没有这项数据，`skipped` 包里有但本次未写入
`reason`	`missing` 或 `skipped` 时给出原因
`device_sn`	设备级组件对应的设备序列号
`path`	组件在包内或落盘后的路径

导入行为：

包内记录的所属用户不存在时自动创建，当前用户不变
除被跳过的组件外，每个 present 组件都会写入，覆盖该用户已有的同名文件
跳过优先于写入：被跳过的组件不落盘、不覆盖已有文件，报告里的 state 为 skipped。所属用户是默认用户时，手部模型即按此跳过（默认用户不加载本地手部标定），其余组件照常写入
校验（路径安全、大小上限、sha256、数据格式、所属用户）在写盘前全部完成，任一项失败直接抛异常，不写入任何文件

导出路径必须以 .zip 结尾，父目录不存在时自动创建。C SDK 也提供这三个接口，返回状态码而非报告字典，详见 C SDK 参考。

触觉数据路径

触觉模型由 Wuji Studio 触觉接触标定训练产出，与标定数据一起按 SDK 用户和设备序列号存放：

SDK 用户	触觉目录
默认用户	`~/.wuji/sdk/tactile/<sn>/`
具名用户	`~/.wuji/sdk/users/<user_id>/tactile/<sn>/`

目录下 model/ 存训练好的触觉模型（contact.safetensors 与 contact.npz），calibration-data/ 存原始标定数据，每次标定一个子目录。一次完整的标定数据包含 4 段引导动作各一个数据文件，导出只取最新一次完整的标定数据。

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))

标定

标定是把 SDK 算法适配到具体物理设备的过程，结果落盘到 SDK 本地参数与模型文件，设备订阅时自动加载。

标定文件先按当前 SDK 用户隔离，再分三类存放：

SDK 用户	参数文件（按设备序列号）	触觉目录（按设备序列号）	位姿手部模型（按左右手）
默认用户	`~/.wuji/sdk/params/<sn>.toml`	`~/.wuji/sdk/tactile/<sn>/`	不保存、不加载，使用内置默认模型
具名用户	`~/.wuji/sdk/users/<user_id>/params/<sn>.toml`	`~/.wuji/sdk/users/<user_id>/tactile/<sn>/`	`~/.wuji/sdk/users/<user_id>/models/`

参数文件与触觉目录仍按设备序列号细分。触觉目录下 model/ 存训练好的接触模型，calibration-data/ 存最新一次标定数据。

位姿手部 URDF 只按 SDK 用户与左右手保存（如 left_hand.urdf / right_hand.urdf），不再包含设备序列号与手型信息，同一用户下任意同侧设备共享同一模型。默认用户没有位姿手部模型：标定与导入都不会写入，实时 IK 始终回退到内置默认模型。Wuji Glove 的具体行为见 Wuji Glove 标定。

切换 SDK 用户时已连接设备自动重载对应文件，无需重连。

默认用户下标定能力受限，多人共用同一台设备时务必先切换到具名用户：

默认用户调用 calibrate 直接失败，返回 ExecuteError(operation="calibrate", code=0x4108)。先 SdkManager.create_user(...) + switch_user(...) 切换到具名用户后再标定，生成的 URDF 才会按用户隔离保存
默认用户设置自定义手部 URDF 直接失败：语义 API glove.hand_model_path().set(path) 与通用写入口（device.set / manager.set）写 calibration.hand_model_path 都返回 UnsupportedOperation，参数存储保持不变，按错误提示切换到具名用户后再设置。语义 API 还会校验路径，文件不可读时返回 InvalidConfig 且不保存
默认用户下，IK 衍生流（hand_skeleton / hand_joint_angles / tip_poses）始终使用 SDK 内置默认 URDF，不读取本地已保存的 calibration.hand_model_path，避免未显式切换用户时意外复用他人标定结果

何时需要标定：首次使用一台设备、更换穿戴者（针对可穿戴设备）、上层模型或算法代际切换、标定精度明显退化。具体触发条件因产品而异
失败行为：标定失败时 SDK 保留上一次成功的结果，本轮新文件自动回滚，可直接重试。常见失败场景：超时、算法不收敛、文件持久化失败、中途切换 SDK 用户。具体异常类型见各产品文档
备份与迁移：用用户数据导入导出打包整位用户的标定结果，导入时 SDK 按目标主机的用户目录重建路径。也可以整目录拷贝，但参数表里可能存有指向 ~/.wuji/sdk/ 下其他文件的绝对路径（如模型文件），跨机器迁移到不同 home 路径时需同步更新或重新标定

Wuji Glove 的标定流程和 API 见 Wuji Glove 标定。

可用参数

Wuji Glove 的可用参数表见 Wuji Glove 可用参数。

查看所有资源

列出设备上所有可用的资源、参数和 Topic：

# 所有资源
for res in glove.resources():
    print(res.path)

# 可读写参数
for param in glove.params():
    print(param.path)

# 可订阅 Topic
for topic in glove.topics():
    print(topic.path)