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

# 控制指南

<Info>
  本页讲解如何正确、安全地控制 Wuji Hand 2：单位约定、MIT 控制模式、关节表、参数安全边界与安全控制循环。接口定义与完整 API 见 [SDK 接口](/docs/wuji-hand/latest/sdk-reference)。
</Info>

## 单位与符号

| 量 | 单位 | 来源与说明 |
| - | - | - |
| `position` | rad（关节侧） | `joint_states` 流，获取关节角的唯一推荐路径 |
| `velocity` | rad/s（关节侧） | `joint_states` 流 |
| `effort` | A（电流，非 N·m） | `joint_states` 流反馈与 `joint_command` 前馈同单位 |

`joint_diagnostics` 流不含关节角，关节角只从 `joint_states` 读取。

## MIT 控制模式

设备默认运行在 MIT 力位混合控制模式，控制模式不通过 Python API 切换：

```
τ = Kp · (q_d − q) + Kd · (dq_d − dq) + τ_ff
```

* `q_d` / `dq_d` / `τ_ff` 来自 `joint_command` 的 `position` / `velocity` / `effort`，每次发布恰好 20 个 `JointCommand`
* `Kp` / `Kd` 通过 `mit_params` 读写，力矩上限通过 `effort_limit` 读写。写入拒绝 NaN、Inf、负值与超出设备上限的值，写入被拒时当前生效值保持不变

<Info>
  设备上电时加载 `kp`、`kd` 与 `effort_limit` 的默认值，通过 SDK 写入的值只在本次运行期间生效，重启后回到默认值。设置控制参数时，推荐取值可以参考遥操作例程 [1.teleop\_real.py](https://github.com/wuji-technology/wuji-sdk/blob/main/examples/python/retargeting/1.teleop_real.py)。设备允许的 `effort_limit` 硬上限为 `2.0 A`。
</Info>

## 关节表

编号规则：thumb 0–3、index 4–7、middle 8–11、ring 12–15、pinky 16–19，SDK 标签格式 `{finger}_S{1..4}`。

| 索引 | SDK 标签 | 关节（按 S1 → S4） | 运动范围 | 模型关节名 | 模型执行器名 |
| - | - | - | - | - | - |
| 0–3 | `thumb_S1..S4` | 掌根展收（cmc\_flex）/ 掌根侧摆（cmc\_abd）/ MCP 屈伸（mcp）/ IP 屈伸（ip） | -68°\~74° / -85°\~40° / -60°\~90° / -60°\~90° | `{l,r}_thumb_*` | `{l,r}_THJ{0-3}` |
| 4–7 | `index_S1..S4` | MCP 屈伸（mcp\_flex）/ MCP 侧摆（mcp\_abd）/ PIP 屈伸（pip）/ DIP 屈伸（dip） | -60°\~90° / -40°\~40° / -60°\~120° / -60°\~90° | `{l,r}_index_finger_*` | `{l,r}_FFJ{0-3}` |
| 8–11 | `middle_S1..S4` | 同四指通用 | 同四指通用 | `{l,r}_middle_finger_*` | `{l,r}_MFJ{0-3}` |
| 12–15 | `ring_S1..S4` | 同四指通用 | 同四指通用 | `{l,r}_ring_finger_*` | `{l,r}_RFJ{0-3}` |
| 16–19 | `pinky_S1..S4` | 同四指通用 | 同四指通用 | `{l,r}_pinky_*` | `{l,r}_LFJ{0-3}` |

运动范围与模型文件（URDF / MJCF / USD）关节限位一致，左右手对称。模型关节与连杆按 `{l,r}_` 前缀加手指名命名，根连杆为 `{l,r}_wrist`（带安装座变体为 `{l,r}_mount`），详见[坐标系与模型](/docs/wuji-hand/latest/hardware-integration#坐标系与模型)。

<Info>
  SDK 标签 `S1..S4` 与模型执行器 `J0..J3` 的轴序对应关系暂不提供，将在后续更新。
</Info>

## 零位与运动方向

* `set_origin` / `clear_origin` 支持把当前物理位置标定为用户零点，关节运动中延迟到下次 IDLE 生效，见 [SDK 接口](/docs/wuji-hand/latest/sdk-reference/effort-and-mit#用户零点（origin）)

## 控制频率与命令频率

* 设备控制频率 1000 Hz × 20 轴。1 kHz 为上下行报文频率，一条报文含 20 轴的控制与信息
* `joint_states` 原生输出率 1000 Hz，可通过订阅句柄调低推送频率，见 [SDK 接口](/docs/wuji-hand/latest/sdk-reference/joint-control#joint_states（sub）)
* GET 查询建议不超过 100 Hz，PUB 命令最高支持 1 kHz

## 参数安全边界

<Warning>
  高 kp 且无限速时直接下发大幅目标位置，会导致关节全速运动，有夹伤与撞击风险。修改控制参数前确保设备周围无人且工作区已清空。
</Warning>

* 首次调试从低力矩限幅开始（如 `effort_limit().set(0.5)`，单位 A），确认行为符合预期后再逐步放宽
* 柔和保持位置可使用 `kp = 3.0`、`kd = 0.05`、`effort_limit = 1.5 A` 作为保守参数示例
* 大幅位置变化拆分为小步下发，避免单次阶跃
* 抓握任务中先以低限幅试探接触，再按需提高

## 安全控制循环

推荐的控制循环要素：发送命令 → 读取状态 → 检查错误码 → 异常时停止。

* 状态读取用 `joint_states`，错误码用 `joint_diagnostics` 配合 `describe_error` 解码
* 异常时执行 `disable()`，紧急情况执行 `emergency_stop()`（整手立即停止，不接受掩码）
* 故障等级、停机行为与清故障流程见[故障、恢复与维护](/docs/wuji-hand/latest/troubleshooting)

单关节小幅运动的完整入门示例见[快速开始](/docs/wuji-hand/latest/quick-start#步骤九：执行第一个安全动作)，更多参考实现见 [`examples/python/wuji_hand_2/`](https://github.com/wuji-technology/wuji-sdk/tree/main/examples/python/wuji_hand_2)。

对应示例的实跑记录见 [SDK 使用实践](/docs/wuji-hand/latest/sdk-practice)，含平滑归零与两个运动示例的实测数据。


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