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

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:             # throughput / error rate for each of the 5 fingers
    print(finger.tx_kbps, finger.rx_kbps, finger.error_per_sec)

hand.effort_limit().set(1.5)            # set all joints to 1.5 A
limits = hand.effort_limit().get()      # → list[Optional[float]]

hand.mit_params().set((1.0, 0.05))           # same kp / kd for all joints
hand.mit_params().set([(1.0, 0.05)] * 20)    # list of 20, per joint
mp = hand.mit_params().get()                 # → list[Optional[MitParam]]; offline joints are None

hand.clear_fault()                  # clear faults on all joints
hand.clear_fault(joints=mask)       # optional: 0/1 mask of length 20 — only joints with a 1 are cleared

hand.set_origin()                   # whole hand: refresh the user origin of all joints
hand.clear_origin()                 # whole hand: clear the user origin of all joints
hand.set_origin(joints=mask)        # optional: 0/1 mask of length 20 — only joints with a 1 are affected

hand.enable()               # enable all joints
hand.disable()              # disable all joints
hand.enable(joints=mask)    # optional: 0/1 mask of length 20 — acts on joints with a 1
hand.emergency_stop()       # emergency stop: whole-hand action, no mask

sub = hand.joint_states().subscribe()   # → Subscription[JointStateFrame]
frame = sub.recv()                      # synchronous, non-blocking; None = no data yet
frame = await sub.recv_async()          # asynchronous wait
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)                   # the format fully describes the frame layout — never hardcode it

sub = hand.fingertip_thumb_data().subscribe()   # one resource per finger: fingertip_{thumb,index,middle,ring,pinky}_data
frame = await sub.recv_async()                  # → FingertipSensorData
if frame.info_digest != info.digest:            # a digest mismatch means the info changed
    info = hand.get_fingertip_info(0)           # re-fetch and rebuild the decoder
# decode frame.data per fmt's point_fields / aggregate_fields
sub.close()

hand.tactile_calibrate()      # whole-hand action; fails fast on the first offline finger

from wuji_sdk import TactileState

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

# This call blocks until the export finishes.
result = hand.export_flash_logs("./logs")
print(result["path"])      # str: absolute path to the exported JSONL file
print(result["frames"])    # int: number of exported log records

hand.ip().get()                    # read the current IP, e.g. "192.168.3.110"
hand.ip().set("192.168.2.111")     # write to flash, takes effect after reboot

hand.ip().set("192.168.2.111")
hand.reboot()
manager.disconnect_all()
# wait for the device to reboot and Ethernet to come up, about 8 seconds
hand = manager.connect(address="192.168.2.111:50001", device_name="wuji_hand_2")
hand.ip().get()                    # → "192.168.2.111"

hand.reboot()

sub = hand.imu().subscribe()                 # → Subscription[ImuData]
s = await sub.recv_async()
a, g = s.linear_acceleration, s.angular_velocity   # m/s² and 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 joints per finger, in S1..S4 order
        print(joint.label)                 # "thumb_S1", "thumb_S2", ...

class JointDiagnosticsFrame:
    header: FrameHeader                    # seq / timestamp_us / frame_id
    num_joints: int
    joints: list[JointDiagnosticsEntry]
    comm: Hand2CommSummary                 # frame-level comm health summary, 1 Hz refresh (see Hand2CommSummary)

class JointDiagnosticsEntry:
    nid: int                               # node ID — identifies the joint across frames
    status_word: StatusWord                # status word
    current: float                         # current (A)
    vbus_v_fb: float                       # bus voltage (V)
    mcu_temp_c_fb: float                   # MCU temperature (°C)
    error_code_current: int                # current error code (integer value, shown in hex when the entry is printed) — decode with describe_error()
    comm_response_rate_pct: int            # bus response rate over the last second, 0–100
    comm_timeout_total: int                # cumulative bus timeouts for this joint

class MitParam:
    kp: float
    kd: float

class JointCommand:
    position: float    # position (rad)
    velocity: float    # velocity (rad/s)
    effort: float      # torque feedforward (A)

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

class FingertipSensorInfo:
    header: FrameHeader    # seq / timestamp_us / frame_id
    digest: int            # CRC32 of the info content — binds data frames to this info
    model: str             # sensor model string (may be empty)
    device_type: int       # sensor type enum
    rate_hz: float         # native output rate of the data stream (Hz, currently 100) — unchanged when the push rate is lowered
    format: str            # JSON: data-frame layout (point_count / point_stride / point_fields / aggregate_fields / encoding)

class FingertipSensorData:
    header: FrameHeader
    info_digest: int       # digest of the info in effect — on mismatch, re-fetch the info
    data: list[int]        # pure value payload, interpreted per info.format

class TactileStatus:
    model: TactileType     # Standard (34-point fingertip) or Thumb (40-point thumb)
    state: TactileState    # Ready or Calibrating

from wuji_sdk import WujiException

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