Skip to main content
This page explains how to control Wuji Hand 2 correctly and safely: unit conventions, MIT control mode, the joint table, parameter safety limits, and a safe control loop. For interface definitions and the full API, see SDK Reference.

​
Units and Symbols

The joint_diagnostics stream carries no joint angles. Read joint angles only from joint_states.

​
MIT Control Mode

The device runs in MIT force-position hybrid control by default, and the control mode isn’t switched from the Python API:
  • q_d / dq_d / τ_ff come from the position / velocity / effort fields of joint_command, with exactly 20 JointCommand entries per publish
  • Read and write Kp / Kd through mit_params, and the torque cap through effort_limit. Writes reject NaN, Inf, negative values, and values above the device ceiling. A rejected write leaves the value in effect unchanged
At power-on, the device loads the default values of kp, kd, and effort_limit. Values written through the SDK apply to the current session only, and a restart returns each one to its default value. When setting control parameters, refer to the teleoperation example 1.teleop_real.py for recommended values. The device hard ceiling for effort_limit is 2.0 A.

​
Joint Table

Numbering: thumb 0–3, index 4–7, middle 8–11, ring 12–15, pinky 16–19. SDK labels use the format {finger}_S{1..4}. The motion ranges match the joint limits in the model files (URDF / MJCF / USD) and are mirrored between the left and right hands. Model joints and links are named with an {l,r}_ prefix plus the finger name, and the root link is {l,r}_wrist ({l,r}_mount in the variant with a mount). For details, see Coordinate Frames and Models.
The axis-order mapping between the SDK labels S1..S4 and the model actuators J0..J3 isn’t available yet and will be added later.

​
Origin and Motion Direction

  • set_origin / clear_origin calibrate the current physical position as the user origin. While a joint moves, the change is deferred to the next IDLE, see SDK Reference

​
Control Rate and Command Rate

  • The device control rate is 1000 Hz × 20 axes. The 1 kHz figure is the uplink and downlink message rate, and one message carries the control and status data of all 20 axes
  • The native output rate of joint_states is 1000 Hz, and the subscription handle lowers the push rate, see SDK Reference
  • Keep GET queries at or below 100 Hz. PUB commands support rates up to 1 kHz

​
Parameter Safety Limits

Sending a large target position with a high kp and no rate limiting drives the joints at full speed, which risks pinch injuries and impacts. Before changing control parameters, make sure nobody is near the device and the workspace is clear.
  • Start first-time debugging with a low torque cap (such as effort_limit().set(0.5), in A), then raise it once the behavior matches your expectations
  • For gentle position holding, use kp = 3.0, kd = 0.05, and effort_limit = 1.5 A as a conservative parameter example
  • Split large position changes into small steps instead of one step change
  • In grasping tasks, probe contact at a low cap first, then raise it as needed

​
Safe Control Loop

A recommended control loop: send commands → read state → check error codes → stop on a fault.
  • Read state from joint_states, and decode error codes from joint_diagnostics with describe_error
  • On a fault, call disable(). In an emergency, call emergency_stop() (the whole hand stops immediately and the call takes no mask)
  • For fault severity, stop behavior, and the fault-clearing flow, see Troubleshooting, Recovery, and Maintenance
For a full beginner example of a small single-joint motion, see Quick Start. For more reference implementations, see examples/python/wuji_hand_2/. For measured runs of the matching examples, including smooth homing and both motion examples, see SDK Practice.