> ## 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

> [!NOTE]
>
> This page explains how to control Wuji Hand 2.1 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](https://docs.wuji.tech/docs/en/wuji-hand/beta1/sdk-reference.md).

## Units and Symbols

| Quantity | Unit | Source field |
| - | - | - |
| Position | radians | `position` in `joint_states` and `joint_command` |
| Velocity | radians per second | `velocity` in `joint_states` and `joint_command` |
| Effort | amperes (motor current) | `effort` in `joint_states` and `joint_command`, and `effort_limit` |

For positive direction and the origin, see [Origin and Motion Direction](#origin-and-motion-direction).

## 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`

## Joint Table

Numbering: thumb 0–3, index 4–7, middle 8–11, ring 12–15, and pinky 16–19. SDK labels follow `{finger}_S{1..4}`.

| Index | SDK label | Joints (S1 → S4) | Model joint name | Model actuator name |
| - | - | - | - | - |
| 0–3 | `thumb_S1..S4` | CMC flexion / CMC abduction / MCP / IP | `{l,r}_thumb_*` | `{l,r}_THJ{0-3}` |
| 4–7 | `index_S1..S4` | MCP flexion / MCP abduction / PIP / DIP | `{l,r}_index_finger_*` | `{l,r}_FFJ{0-3}` |
| 8–11 | `middle_S1..S4` | Same as the other three fingers | `{l,r}_middle_finger_*` | `{l,r}_MFJ{0-3}` |
| 12–15 | `ring_S1..S4` | Same as the other three fingers | `{l,r}_ring_finger_*` | `{l,r}_RFJ{0-3}` |
| 16–19 | `pinky_S1..S4` | Same as the other three fingers | `{l,r}_pinky_*` | `{l,r}_LFJ{0-3}` |

For each joint's motion direction and angle range, see [Product Introduction](https://docs.wuji.tech/docs/en/wuji-hand/beta1/overview.md#mechanical-structure). The naming convention was fixed in the 2.1 revision and later revisions stay compatible.

## Origin and Motion Direction

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 the arm flange mount `{l,r}_mount`. See [Coordinate Frames and Models](https://docs.wuji.tech/docs/en/wuji-hand/beta1/hardware-integration#coordinate-frames-and-models).

`set_origin` and `clear_origin` calibrate the current physical position as the user origin. While a joint moves, the change is deferred to the next IDLE. For the procedure, see [Calibration and Configuration](https://docs.wuji.tech/docs/en/wuji-hand/beta1/calibration#joint-origin-calibration).

## Control Rate and Command Rate

`joint_states` and `joint_diagnostics` share one device stream, so lowering the push rate of either lowers the other. For subscription modes and output-rate control, see [SDK Reference](https://docs.wuji.tech/docs/en/wuji-hand/beta1/sdk-reference/joint-control#joint_states-sub).

## Parameter Safety Limits

Writes to `effort_limit` and `mit_params` are validated: NaN, Inf, and negative values are rejected, and `effort_limit` also rejects values above the device ceiling. A rejected write raises an error and leaves the value in effect unchanged. The ceiling comes from the firmware, so read it back from the device for the exact number.

> [!WARNING]
>
> Raising `effort_limit` or `Kp` raises both grip force and collision impact. Approach a new value in small steps, and after each change run a slow, small motion to confirm the behavior before returning to normal duty.

## Safe Control Loop

1. Connect the device and confirm all 20 joints are online with no active error codes.
2. Clear the workspace and confirm nobody is touching the hand.
3. Enable the joints and wait until all reach the Enabled state.
4. Interpolate from the current pose to the target pose instead of sending a step.
5. Keep `joint_diagnostics` subscribed during the loop, and stop as soon as an error code goes active.
6. Disable and disconnect when you finish.

For stop behavior and the fault-clearing flow, see [Maintenance](https://docs.wuji.tech/docs/en/wuji-hand/beta1/maintenance#safe-stop-and-fault-recovery).

For measured runs of the matching examples, including smooth homing and both motion examples, see [SDK Practice](https://docs.wuji.tech/docs/en/wuji-hand/beta1/sdk-practice/index).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.