> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wuji.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# Control Guide
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](/en/docs/wuji-hand/latest/sdk-reference).
## Units and Symbols
| Quantity | Unit | Source and notes |
| - | - | - |
| `position` | rad (joint side) | The `joint_states` stream, the only recommended path for joint angles |
| `velocity` | rad/s (joint side) | The `joint_states` stream |
| `effort` | A (current, not N·m) | Feedback in `joint_states` and feedforward in `joint_command` share this unit |
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:
```
τ = Kp · (q_d − q) + Kd · (dq_d − dq) + τ_ff
```
* `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](https://github.com/wuji-technology/wuji-sdk/blob/main/examples/python/retargeting/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}`.
| Index | SDK label | Joints (S1 → S4) | Motion range | Model joint name | Model actuator name |
| - | - | - | - | - | - |
| 0–3 | `thumb_S1..S4` | Base abduction/adduction (cmc\_flex) / base lateral swing (cmc\_abd) / MCP flexion/extension (mcp) / IP flexion/extension (ip) | -68°\~74° / -85°\~40° / -60°\~90° / -60°\~90° | `{l,r}_thumb_*` | `{l,r}_THJ{0-3}` |
| 4–7 | `index_S1..S4` | MCP flexion/extension (mcp\_flex) / MCP lateral swing (mcp\_abd) / PIP flexion/extension (pip) / DIP flexion/extension (dip) | -60°\~90° / -40°\~40° / -60°\~120° / -60°\~90° | `{l,r}_index_finger_*` | `{l,r}_FFJ{0-3}` |
| 8–11 | `middle_S1..S4` | Same as the four fingers | Same as the four fingers | `{l,r}_middle_finger_*` | `{l,r}_MFJ{0-3}` |
| 12–15 | `ring_S1..S4` | Same as the four fingers | Same as the four fingers | `{l,r}_ring_finger_*` | `{l,r}_RFJ{0-3}` |
| 16–19 | `pinky_S1..S4` | Same as the four fingers | Same as the four fingers | `{l,r}_pinky_*` | `{l,r}_LFJ{0-3}` |
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](/en/docs/wuji-hand/latest/hardware-integration#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](/en/docs/wuji-hand/latest/sdk-reference/effort-and-mit#user-origin)
## 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](/en/docs/wuji-hand/latest/sdk-reference/joint-control#joint_states-sub)
* 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](/en/docs/wuji-hand/latest/troubleshooting)
For a full beginner example of a small single-joint motion, see [Quick Start](/en/docs/wuji-hand/latest/quick-start#step-9-run-your-first-safe-motion). For more reference implementations, see [`examples/python/wuji_hand_2/`](https://github.com/wuji-technology/wuji-sdk/tree/main/examples/python/wuji_hand_2).
For measured runs of the matching examples, including smooth homing and both motion examples, see [SDK Practice](/en/docs/wuji-hand/latest/sdk-practice).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.