SDK Reference

from wuji_sdk import SdkManager, Handedness

manager = SdkManager.instance()

# Auto-discover and connect to the first Wuji Hand 2 on the LAN
hand = manager.auto_connect(device_name="wuji_hand_2")

# Connect explicitly by serial number or address
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")

# Or connect by handedness directly, without a serial number
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,    # Default True: lets multiple clients (Wuji Studio + recording scripts + your app) connect at once
)
hand = manager.connect(sn=<device_sn>, device_name="wuji_hand_2", options=opts)

side = hand.handedness().get()   # → "left" or "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 like "thumb_S1"; level: 0=OK / 1=WARN / 2=ERROR

diag = hand.comm_diag().get()           # → HandCommunicationDiagnostics
for finger in diag.fingers:             # throughput / error rate for each of the 5 fingers
    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)            # set all joints to 1.5 A
limits = hand.effort_limit().get()      # → list[Optional[float]]

kp = [[1.0]*4 for _ in range(5)]        # 5 fingers × 4 joints
kd = [[0.05]*4 for _ in range(5)]
hand.mit_params().set(kp=kp, kd=kd)     # per-joint kp / kd

mp = hand.mit_params().get()            # → MitParams(kp=[[...]], kd=[[...]]); offline joints are NaN

hand.clear_fault().set(1)

hand.set_origin(joint_index)            # single joint: set the current position of joint_index (0..19) as the new zero
hand.clear_origin(joint_index)          # single joint: clear the user origin (offset3 → 0)
hand.set_origin_all()                   # whole hand: refresh the user origin of all joints at once
hand.clear_origin_all()                 # whole hand: clear the user origin of all joints

hand.set_soft_limit(joint_index, min_rad, max_rad, enabled=True)   # configure, min <= max
min_rad, max_rad, enabled = hand.get_soft_limit(joint_index)       # read back

hand.enable()      # enable all joints
hand.disable()     # disable all joints

sub = hand.joint_state().subscribe()    # → Subscription[JointState]
data = sub.recv()                       # synchronous, non-blocking; None = no data yet
data = await sub.recv_async()           # asynchronous wait
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 positions (rad)
pub.send(positions, velocities)         # + velocities
pub.send(positions, velocities, efforts) # + torque feedforward
pub.close()

# Export the running logs of the current firmware (use this for most troubleshooting)
result = await hand.dump_hand_logs(bank="current", out_dir="./logs")

result = await hand.dump_hand_logs(bank="current")
print(result["session_dir"])    # str: absolute path of this session directory
print(result["files"])          # list[str]: paths of the written .log files

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 joints per finger, in S1..S4 order
        print(joint.label)                 # "thumb_S1", "thumb_S2", ...

class DiagnosticArray:
    seq: int
    timestamp_us: int
    frame_id: str
    status: list[DiagnosticStatus]    # 20 items, indexed to match hand.joints()

class DiagnosticStatus:
    level: int                        # 0=OK / 1=WARN / 2=ERROR
    name: str                         # joint label, e.g. "thumb_S1"
    message: str                      # human-readable message
    hardware_id: str                  # device SN
    values: list[tuple[str, str]]     # diagnostic key-value pairs (empty for offline joints)

class MitParam:        # single joint
    kp: float
    kd: float

class MitParams:       # whole-hand matrix (returned by hand.mit_params().get())
    kp: list[list[float]]   # 5×4, offline joints are NaN
    kd: list[list[float]]

class HandCommunicationDiagnostics:
    fingers: list[FingerCommunicationDiagnostics]   # length 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}")