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

# 控制指南

> [!NOTE]
>
> 本页讲解如何正确、安全地控制 Wuji Hand 2.1：单位约定、MIT 控制模式、关节表、参数安全边界与安全控制循环。接口定义与完整 API 见 [SDK 接口](https://docs.wuji.tech/docs/zh/wuji-hand/beta1/sdk-reference.md)。

## 单位与符号

| 量 | 单位 | 来源字段 |
| - | - | - |
| 位置 | 弧度 | `joint_states` 的 `position`、`joint_command` 的 `position` |
| 速度 | 弧度每秒 | `joint_states` 的 `velocity`、`joint_command` 的 `velocity` |
| 力矩 | 安培（电机电流） | `joint_states` 的 `effort`、`joint_command` 的 `effort`、`effort_limit` |

正方向与零位的定义见[零位与运动方向](#零位与运动方向)。

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

## 关节表

编号规则：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` | 掌根展收 / 掌根侧摆 / MCP 屈伸 / IP 屈伸 | `{l,r}_thumb_*` | `{l,r}_THJ{0-3}` |
| 4–7 | `index_S1..S4` | MCP 屈伸 / MCP 侧摆 / PIP 屈伸 / DIP 屈伸 | `{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}` |

各关节的运动方向与角度范围见[产品介绍](https://docs.wuji.tech/docs/zh/wuji-hand/beta1/overview.md#各关节运动方向与范围)。命名约定自 2.1 修订定版，后续修订保持兼容。

## 零位与运动方向

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

`set_origin` 与 `clear_origin` 把当前物理位置标定为用户零点，关节运动中延迟到下次 IDLE 生效，操作见[标定与配置](https://docs.wuji.tech/docs/zh/wuji-hand/beta1/calibration#关节零位标定)。

## 控制频率与命令频率

`joint_states` 与 `joint_diagnostics` 共用同一条设备流，调低其中一个的推送频率，另一个会同步降低。订阅模式与输出率调节见 [SDK 接口](https://docs.wuji.tech/docs/zh/wuji-hand/beta1/sdk-reference/joint-control#joint_states（sub）)。

## 参数安全边界

`effort_limit` 与 `mit_params` 的写入都会校验：拒绝 NaN、Inf 与负值，`effort_limit` 还会拒绝超出设备上限的值。写入被拒时报错，当前生效值保持不变。上限由固件设定，具体数值以设备读回为准。

> [!WARNING]
>
> 提高 `effort_limit` 或 `Kp` 会同时提高夹持力与碰撞冲击。调参从小到大逐步逼近，每次改动后先做低速小幅度动作确认行为，再进入正常工况。

## 安全控制循环

1. 连接设备并确认 20 个关节在线、无活跃错误码
2. 清空工作空间，确认无人接触
3. 使能关节，等待全部进入 Enabled 状态
4. 从当前姿态插值到目标姿态，避免直接下发阶跃
5. 循环中持续订阅 `joint_diagnostics`，出现活跃错误码立即停止
6. 结束时失能并断开连接

异常时的停机行为与清故障流程见[维护](https://docs.wuji.tech/docs/zh/wuji-hand/beta1/maintenance#安全停止与异常恢复)。

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


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