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.3.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

report = hand.diagnostics().get()       # → DiagnosticArray
for s in report.status:
    print(s.name, s.level, s.message)   # name 形如 "thumb_S1"，level：0=OK / 1=WARN / 2=ERROR

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

hand.control_mode().set("mit")          # "off" / "mit" / "position" / "velocity" / "current"

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

kp = [[1.0]*4 for _ in range(5)]        # 5 手指 × 4 关节
kd = [[0.05]*4 for _ in range(5)]
hand.mit_params().set(kp=kp, kd=kd)     # 每关节独立的 kp / kd

mp = hand.mit_params().get()            # → MitParams(kp=[[...]], kd=[[...]])，离线关节填 NaN

hand.clear_fault().set(1)

hand.set_origin(joint_index)            # 单关节：把 joint_index (0..19) 当前位置当成新的零位
hand.clear_origin(joint_index)          # 单关节：清除用户零点（offset3 → 0）
hand.set_origin_all()                   # 整手：所有关节同时刷新用户零点
hand.clear_origin_all()                 # 整手：清除所有关节的用户零点

hand.set_soft_limit(joint_index, min_rad, max_rad, enabled=True)   # 配置，min <= max
min_rad, max_rad, enabled = hand.get_soft_limit(joint_index)       # 读回

hand.enable()      # 使能全部关节
hand.disable()     # 失能全部关节

sub = hand.joint_state().subscribe()    # → Subscription[JointState]
data = sub.recv()                       # 同步非阻塞，None = 暂无数据
data = await sub.recv_async()           # 异步等待
print(data.cycle_id)
for j in data.joints:
    print(j.actual_pos, j.actual_vel, j.torque)
sub.close()

def on_state(state):
    print(state.cycle_id, [j.actual_pos for j in state.joints[:4]])

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

pub = hand.joint_command_publisher()    # → JointCommandPublisher
pub.send(positions)                     # list[float]，20 个位置 (rad)
pub.send(positions, velocities)         # + 速度
pub.send(positions, velocities, efforts) # + 力矩前馈
pub.close()

# 导出当前固件的运行日志（绝大多数排查场景用这个）
result = await hand.dump_hand_logs(bank="current", out_dir="./logs")

result = await hand.dump_hand_logs(bank="current")
print(result["session_dir"])    # str: 本次会话目录绝对路径
print(result["files"])          # list[str]: 已写入的 .log 文件路径

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 DiagnosticArray:
    seq: int
    timestamp_us: int
    frame_id: str
    status: list[DiagnosticStatus]    # 20 条，下标对齐 hand.joints()

class DiagnosticStatus:
    level: int                        # 0=OK / 1=WARN / 2=ERROR
    name: str                         # 关节标签，如 "thumb_S1"
    message: str                      # 人类可读信息
    hardware_id: str                  # 设备 SN
    values: list[tuple[str, str]]     # 诊断键值对（离线关节为空）

class MitParam:        # 单关节
    kp: float
    kd: float

class MitParams:       # 整手矩阵（hand.mit_params().get() 返回）
    kp: list[list[float]]   # 5×4，离线关节为 NaN
    kd: list[list[float]]

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

from wuji_sdk import WujiException

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