SDK 接口

from wuji_sdk import SdkManager, Handedness

manager = SdkManager.instance()

# 自动发现并连接局域网内首个 Wuji Hand 2
hand = manager.auto_connect(device_name="wuji_hand_2")

# 已知序列号或地址时显式连接
hand = manager.connect(sn=<device_sn>, device_name="wuji_hand_2")
hand = manager.connect(address="192.168.1.110:50001", device_name="wuji_hand_2")

# 或按左右手直接连接，无需序列号
hand = manager.connect(handedness=Handedness.Right, device_name="wuji_hand_2")

from wuji_sdk import SdkManager, ConnectOptions

opts = ConnectOptions(
    timeout_ms=1000,
    retry_count=3,
    enable_bridge=True,    # 默认 True：允许多个客户端（Wuji Studio + 录制脚本 + 业务程序）同时连接
)
hand = manager.connect(sn=<device_sn>, device_name="wuji_hand_2", options=opts)

side = hand.handedness().get()   # → "left" 或 "right"

n = hand.online_joints_count().get()   # → int，0–20

sub = hand.joint_diagnostics().subscribe()   # → Subscription[JointDiagnosticsFrame]
frame = await sub.recv_async()
for j in frame.joints:
    print(j.nid, j.vbus_v_fb, j.mcu_temp_c_fb, f"0x{j.error_code_current:04X}")
sub.close()

diag = hand.comm_diag().get()           # → HandCommunicationDiagnostics
for finger in diag.fingers:             # 5 根手指各自的吞吐 / 错误率
    print(finger.tx_kbps, finger.rx_kbps, finger.error_per_sec)

hand.effort_limit().set(1.5)            # 全部关节设为 1.5 A
limits = hand.effort_limit().get()      # → list[Optional[float]]

hand.mit_params().set((1.0, 0.05))           # 全部关节统一 kp / kd
hand.mit_params().set([(1.0, 0.05)] * 20)    # 长度 20 的列表逐关节设置
mp = hand.mit_params().get()                 # → list[Optional[MitParam]]，离线关节为 None

hand.clear_fault()                  # 清除全部关节故障
hand.clear_fault(joints=mask)       # 可选：长度 20 的 0/1 掩码，只清除掩码位为 1 的关节

hand.set_origin()                   # 整手：所有关节刷新用户零点
hand.clear_origin()                 # 整手：清除所有关节的用户零点
hand.set_origin(joints=mask)        # 可选：长度 20 的 0/1 掩码，只作用于掩码位为 1 的关节

hand.enable()               # 使能全部关节
hand.disable()              # 失能全部关节
hand.enable(joints=mask)    # 可选：长度 20 的 0/1 掩码，作用于掩码位为 1 的关节
hand.emergency_stop()       # 急停：整手动作，不接受掩码

sub = hand.joint_states().subscribe()   # → Subscription[JointStateFrame]
frame = sub.recv()                      # 同步非阻塞，None = 暂无数据
frame = await sub.recv_async()          # 异步等待
print(frame.header.seq, frame.header.timestamp_us)
for j in frame.joints:
    print(j.nid, j.position, j.velocity, j.effort)
sub.close()

def on_state(frame):
    print(frame.header.seq, [j.position for j in frame.joints[:4]])

cb = hand.joint_states().subscribe_with_callback(on_state)
# ...
cb.close()

from wuji_sdk import JointCommand

pub = hand.joint_command().publish()    # → JointCommandPublisher
pub.send([JointCommand(position=p, velocity=0.0, effort=0.0) for p in positions])
pub.close()

import json

info = hand.get_fingertip_info(0)               # 0=thumb … 4=pinky → FingertipSensorInfo
fmt = json.loads(info.format)                   # 帧布局完全由 format 描述，不要硬编码

sub = hand.fingertip_thumb_data().subscribe()   # 每指一个资源：fingertip_{thumb,index,middle,ring,pinky}_data
frame = await sub.recv_async()                  # → FingertipSensorData
if frame.info_digest != info.digest:            # digest 不匹配说明 info 已变化
    info = hand.get_fingertip_info(0)           # 重新获取并重建解码器
# 按 fmt 的 point_fields / aggregate_fields 解码 frame.data
sub.close()

hand.tactile_calibrate()      # 整手动作，遇到离线手指立即报错

from wuji_sdk import TactileState

status = hand.tactile_status("thumb")   # "thumb" / "index" / "middle" / "ring" / "pinky"
print(status.model)                     # TactileType.Thumb（40 点）或 TactileType.Standard（34 点）
print(status.state)                     # TactileState.Ready / TactileState.Calibrating

# 该调用会阻塞，直至导出完成
result = hand.export_flash_logs("./logs")
print(result["path"])      # str：导出 JSONL 文件的绝对路径
print(result["frames"])    # int：导出的日志记录数

hand.ip().get()                    # 读当前 IP，如 "192.168.1.110"
hand.ip().set("192.168.1.201")     # 写入 flash，重启后生效

hand.ip().set("192.168.1.201")
hand.reboot()
manager.disconnect_all()
# 等设备重启且以太网就绪，约 8 秒
hand = manager.connect(address="192.168.1.201:50001", device_name="wuji_hand_2")
hand.ip().get()                    # → "192.168.1.201"

hand.reboot()

sub = hand.imu().subscribe()                 # → Subscription[ImuData]
s = await sub.recv_async()
a, g = s.linear_acceleration, s.angular_velocity   # m/s² 与 rad/s
print(s.header.seq, a.x, a.y, a.z, g.x, g.y, g.z)
sub.close()

for joint in hand.joints():
    print(joint.label, joint.index)        # e.g. "thumb_S1" 0

for finger in hand.fingers():
    for joint in finger.joints():          # 每根手指 4 个关节，按 S1..S4 顺序
        print(joint.label)                 # "thumb_S1", "thumb_S2", ...

class JointDiagnosticsFrame:
    header: FrameHeader                    # seq / timestamp_us / frame_id
    num_joints: int
    joints: list[JointDiagnosticsEntry]
    comm: Hand2CommSummary                 # 帧级通信健康摘要，1 Hz 刷新（见 Hand2CommSummary）

class JointDiagnosticsEntry:
    nid: int                               # 节点编号，跨帧定位关节
    status_word: StatusWord                # 状态字
    current: float                         # 电流 (A)
    vbus_v_fb: float                       # 母线电压 (V)
    mcu_temp_c_fb: float                   # MCU 温度 (°C)
    error_code_current: int                # 当前错误码（整数值，打印条目对象时按 16 进制显示），用 describe_error() 解码
    comm_response_rate_pct: int            # 该关节最近 1 秒的总线响应率，0–100
    comm_timeout_total: int                # 该关节累计总线超时次数

class MitParam:
    kp: float
    kd: float

class JointCommand:
    position: float    # 位置 (rad)
    velocity: float    # 速度 (rad/s)
    effort: float      # 力矩前馈 (A)

class HandCommunicationDiagnostics:
    fingers: list[FingerCommunicationDiagnostics]   # 长度 5

class FingerCommunicationDiagnostics:
    tx_frame_total: int
    rx_frame_total: int
    tx_kbps: int
    rx_kbps: int
    error_per_sec: int
    crc_error_total: int
    frame_format_error_total: int
    uart_hw_error_total: int
    transfer_stats: list[TransferStats]
    nodes: list[NodeDiagnostics]    # per-node：online / ms_since_last_response / response_rate_pct

class FingertipSensorInfo:
    header: FrameHeader    # seq / timestamp_us / frame_id
    digest: int            # info 内容 CRC32，供 data 帧绑定校验
    model: str             # 传感器型号字符串（可为空）
    device_type: int       # 传感器类型枚举
    rate_hz: float         # data 流原生输出率（Hz，当前 100），调低推送频率后不随之变化
    format: str            # JSON：数据帧布局（point_count / point_stride / point_fields / aggregate_fields / encoding）

class FingertipSensorData:
    header: FrameHeader
    info_digest: int       # 绑定生效 info 的 digest，不匹配时重新获取 info
    data: list[int]        # 纯 value payload，按 info.format 解释

class TactileStatus:
    model: TactileType     # Standard（34 点标准指）或 Thumb（40 点拇指）
    state: TactileState    # Ready（就绪）或 Calibrating（标定中）

from wuji_sdk import WujiException

try:
    hand.joint_states().subscribe()
except WujiException as e:
    print(f"SDK error: {e}")