控制指南
本页讲解如何正确、安全地控制 Wuji Hand 2：单位约定、MIT 控制律、关节表、参数安全边界与安全控制循环。接口定义与完整 API 见 SDK 接口。
单位与符号
| 量 | 单位 | 来源与说明 |
|---|---|---|
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) + τ_ffq_d/dq_d/τ_ff来自joint_command的position/velocity/effort，每次发布恰好 20 个JointCommandKp/Kd通过mit_params读写，力矩上限通过effort_limit读写。写入拒绝 NaN、Inf、负值与超出设备上限的值，写入被拒时当前生效值保持不变
上电默认值为 kp = 5.0、kd = 0.01、effort_limit = 1.0 A，设备重启后恢复默认值。设置控制参数时，kp 不低于 3.0，kd 使用 0.01–0.05，effort_limit 不超过 1.5 A。设备允许的 effort_limit 硬上限为 2.0 A。
关节表
编号规则：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），详见 Wuji Description 文档。
SDK 标签 S1..S4 与模型执行器 J0..J3 的轴序对应关系暂不提供，将在后续更新。
零位与运动方向
set_origin/clear_origin支持把当前物理位置标定为用户零点，关节运动中延迟到下次 IDLE 生效，见 SDK 接口
控制频率与命令频率
- 设备控制频率 1000 Hz × 20 轴。1 kHz 为上下行报文频率，一条报文含 20 轴的控制与信息
joint_states原生输出率 1000 Hz，可通过订阅句柄调低推送频率，见 SDK 接口- GET 查询建议不超过 100 Hz，PUB 命令最高支持 1 kHz
参数安全边界
高 kp 且无限速时直接下发大幅目标位置，会导致关节全速运动，有夹伤与撞击风险。修改控制参数前确保设备周围无人且工作区已清空。
- 首次调试从低力矩限幅开始（如
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()（整手立即停止，不接受掩码） - 故障等级、停机行为与清故障流程见故障、恢复与维护
单关节小幅运动的完整入门示例见快速开始，更多参考实现见 examples/python/wuji_hand_2/。