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

# 软硬件集成

本页按机械安装、电气与网络两部分组织，覆盖把 Wuji Hand 2 装上机械臂或工装、接通供电与网络所需的接口、规格与边界。

<Info>
  机械部分包含安装接口与图纸，坐标系与模型部分包含模型资产、加载方式与验证，电气部分包含供电、上下电时序、网络配置与连接可靠性。首次连接的分步操作见[快速开始](/docs/wuji-hand/latest/quick-start)。
</Info>

## 机械集成

整手通过腕部法兰或掌心接口固定到机械臂与工装，安装尺寸、模型坐标系约定、左右手差异与载荷线缆边界共同决定可行的安装方案。

### 腕部安装接口

产品腕部标配法兰，随箱附转接座与转接法兰（见[产品介绍](/docs/wuji-hand/latest/product-introduction#内容物清单)）。基于随附件可直接完成桌面固定与常见法兰对接。

### 掌心安装接口

掌心底部提供标准安装接口，供加工臂侧转接板使用。左右手接口一致，2.1 与 2.2 接口一致：

| 项 | 规格 |
| - | - |
| 螺纹孔 1 | M3×0.5 细牙 6H，牙深大于 5.5 mm，⌀4 (0/+0.05) 沉孔深 2.35 ± 0.03 |
| 螺纹孔 2、3 | M4×0.5 细牙 6H，牙深大于 4 mm，⌀7 (0/+0.06) 沉孔深 1 mm |
| 定位基准 | 28.00 (0/−0.05) 与 5.15 (+0.15/−0.05) 基准尺寸定位 |

掌心安装接口的 STEP 装配（掌壳与线束）与单页 A3 标注图纸的获取方式见[整机 STEP 与图纸](#整机-step-与图纸)。

### 软体拆装

拆装软体前先关闭设备电源：

1. 拆下掌心与虎口处的十字螺钉
2. 将灵巧手平放，向上推动拇指，直至五指并拢
3. 向外推动掌心塑料件，直至掌心软体翘起并露出转接座螺钉
4. 拆卸时取下转接座螺钉。安装时将掌心塑料件扣回原位，再紧固掌心与虎口处的两颗螺钉

### 左右手差异

左右手为镜像件，模型网格对称。出厂默认 IP 按左右手区分（见下文[网络配置](#网络配置)）。

### 载荷与线缆边界

<Warning>
  以下集成边界数据暂不提供，将在后续更新：允许的腕部载荷、弯矩与冲击边界，线缆最小弯曲半径与出线方向，运动空间预留，安装螺钉规格与建议扭矩。集成方案设计请先与技术支持确认边界。
</Warning>

* 结合实际工况评估腕部载荷、弯矩与冲击，未确认边界前避免高负载与冲击
* 按集成方案预留线缆弯曲半径、出线方向与运动空间
* 使用时须始终佩戴软体 / 皮肤层。手指表面排线外露脆弱，仅限维护状态短时操作，防止刮擦（见[用户须知](/docs/wuji-hand/latest/user-notice#线缆与排线保护)）
* 与机械臂联合运行的安全责任边界见[维护](/docs/wuji-hand/latest/maintenance#与机械臂联合运行的安全责任边界)

### 整机 STEP 与图纸

整机装配与掌心安装接口的 CAD 随 wuji-description v2026.8.14 及以上版本提供。

| 资源 | 路径与用途 |
| - | - |
| 整机 STEP 装配（带安装座） | `hand2/hand2_beta2/body/step/wuji-hand2-description-{left,right}_beta2_with_mount_step.STEP`，用于包络与安装接口设计。该装配暂不含指尖软体，接触仿真以 `body/` 下的模型为准 |
| 掌心安装接口 STEP | `hand2/hand2_beta2/attachment/wuji-hand2-description-{left,right}-mount_beta2_step.STEP`，仅含掌部与线束，用于自制机械臂侧转接件或工装 |
| A3 标注图纸 | `hand2/hand2_beta2/attachment/wuji-hand2-description-{left,right}-mount_beta2.pdf`，标注转接件对接的螺纹孔位，规格见[掌心安装接口](#掌心安装接口) |

左右手文件互为镜像。整机 STEP 与掌心安装接口的 STEP、图纸在 2.2 与 2.1 下内容相同，文件名中的版本标记仅用于与目录对齐，掌心安装接口在两个修订版之间没有变化。`attachment/` 位于 ROS 2 包根 `body/` 之外，colcon 不会安装。

## 坐标系与模型

* **根连杆**：无座模型根连杆为 `{l,r}_wrist`，与 URDF / MJCF / USD 一致
* **带安装座变体**：文件名带 `_with_mount` 后缀，根连杆为臂法兰安装座 `{l,r}_mount`（69 g），腕壳保持独立 body，腕法兰坐标系可寻址
* **运动学等价**：无座与带座两变体扣除固定安装偏移后，指尖位姿一致性在 0.006 mm 以内
* **执行器命名**：`{l,r}_{THJ|FFJ|MFJ|RFJ|LFJ}{0-3}`，解剖学命名对照见[关节表](/docs/wuji-hand/latest/control-guide#关节表)

腕部安装坐标系与根连杆的相对关系以 URDF 定义为准。

### 模型资产

模型与 CAD 资源随 wuji-description v2026.8.14 及以上版本提供。

| 类别 | 内容 |
| - | - |
| 仿真模型 | 左右手 URDF（含 ROS 版）、MJCF、USD、Meshes |
| 安装座变体 | 文件名带 `_with_mount` 后缀，根连杆为 `{l,r}_mount` |
| ROS 2 包 | `wuji_hand2_beta2_description`，包根 `hand2/hand2_beta2/body/` |

模型命名为 `wujihand2-beta2-{side}`，USD 入口为 `wujihand2_beta2.usd`。

### 环境要求

| 用途 | 要求 |
| - | - |
| MuJoCo 可视化 | Python 3.8 及以上，MuJoCo 2.3 及以上 |
| ROS 2 可视化（RViz） | ROS 2（Kilted Kaiju / Jazzy Jalisco），Ubuntu 24.04 及以上 |
| Isaac Sim USD | Isaac Sim 2024.x 及以上 |
| STEP / CAD | 支持 STEP 格式的 CAD 工具，例如 FreeCAD、SolidWorks |

### 获取与加载

```bash theme={null}
git clone https://github.com/wuji-technology/wuji-description.git
cd wuji-description
```

MuJoCo：

```bash theme={null}
# 右手
python -m mujoco.viewer --mjcf=hand2/hand2_beta2/body/mjcf/right.xml

# 左手
python -m mujoco.viewer --mjcf=hand2/hand2_beta2/body/mjcf/left.xml

# 带安装座变体
python -m mujoco.viewer --mjcf=hand2/hand2_beta2/body/mjcf/right_with_mount.xml
```

MJCF 的碰撞几何取各链接 mesh 的凸包，全部链接参与碰撞，仅排除 10 对装配重叠。指间接触与指尖到手掌的接触保持有效。显示分组为组 1 视觉外观、组 2 碰撞几何、组 3 指尖 site。

ROS 2 与 RViz：把整个仓库克隆到工作空间 `src/`，再单独构建描述包。

```bash theme={null}
cd ~/ros2_ws
colcon build --packages-select wuji_hand2_beta2_description
source install/setup.bash
```

构建后，ROS 版 URDF（`hand2/hand2_beta2/body/urdf/{left,right}-ros.urdf`）中的 `package://` 路径即可解析，在自定义 launch 文件或 `robot_state_publisher` 中加载。带安装座变体与无座版共用同一前缀，包构建一次即可加载任一变体。

Isaac Sim USD：

| 变体 | 路径 |
| - | - |
| 左手 | `hand2/hand2_beta2/body/usd/left/wujihand2_beta2.usd` |
| 右手 | `hand2/hand2_beta2/body/usd/right/wujihand2_beta2.usd` |
| 带安装座 | `hand2/hand2_beta2/body/usd/{left,right}_with_mount/wujihand2_beta2.usd` |

USD 为分层资产，包含 base、physics、robot、sensor 子层与 Logo 纹理。无座版根 prim 为 `wujihand2_beta2_{side}`，带安装座变体为 `wujihand2_beta2_{side}_mount`。点击 **Play** 时驱动增益保持当前位姿。当前 kp / kv 驱动增益沿用 Wuji Hand 平台标定值，Wuji Hand 2 硬件系统辨识完成后更新。

URDF 预览：

```bash theme={null}
pip install urdf-viz
urdf-viz hand2/hand2_beta2/body/urdf/right.urdf
```

### 验证

1. 确认 MuJoCo 或 URDF viewer 正常打开，没有缺失网格
2. 确认模型显示 20 个 revolute 关节
3. 确认所用目录与 ROS 2 包名对应 2.2

模型加载成功说明资产、路径与可视化链路可用。固件、网络、传感器与真实设备控制需要接入设备后单独验证。

## 电气与网络集成

设备使用标称 12 V 的直流供电与静态 IP 的以太网连接，上下电时序、多设备寻址与断连恢复行为均有固定约定。

### 供电

| 项 | 数值 |
| - | - |
| 输入电压 | 11–13 V DC（标称 12 V） |
| 电源要求 | 额定功率不低于 200 W，标配适配器 12 V 20 A |
| 电源接口 | XT30，随附公对母延长线（14 AWG，2 m） |
| 通信接口 | RJ45，100BASE-TX |

<Warning>
  严禁反接。严禁运行中拔插电源线与通信线。产品具备过压、过流保护，但保护动作不作为常规操作依赖。
</Warning>

<Warning>
  后续版本的对外接口形式与供电电压范围会变化（不再是 XT30 + RJ45 两线直引方案），集成方案请预留改动空间。
</Warning>

<Info>
  以下电气数据暂不提供，将在后续更新：XT30 引脚极性定义图，工作 / 峰值 / 待机功耗，启动浪涌、电源保护、保险与接地建议。
</Info>

### 上下电时序

* **上电**：先连接设备端 XT30，再接通电源适配器。状态灯蓝色呼吸（自检）转白色呼吸（就绪）后可连接
* **下电**：停止运动并执行 `disable()`，确认设备静止后断开电源，再拔下线缆
* **热插拔**：通信线与电源线均不支持运行中插拔。意外拔出后，按下文[超时、断连与重连](#超时、断连与重连)步骤恢复

### 网络配置

设备使用静态 IP，不支持 DHCP。出厂默认地址：

| 项 | 左手 | 右手 |
| - | - | - |
| IP | 192.168.1.110 | 192.168.1.111 |
| 网关 | 192.168.1.1 | 192.168.1.1 |
| 子网掩码 | 255.255.255.0 | 255.255.255.0 |
| 端口 | 50001 | 50001 |

电脑网卡设置为同网段静态 IP（如 `192.168.1.50`）。修改 IP 分四步：set 写入新地址、reboot 重启设备、按新 IP 重连、get 确认，见 [SDK 接口](/docs/wuji-hand/latest/sdk-reference/device-operations#ip（set/get）)。

### 多设备与多客户端

* 同一网段部署多只手时，连接用序列号（`sn`）或左右手（`handedness`）区分。同手性多设备在网时必须用 `sn`，否则抛 `AmbiguousHandedness`
* 多客户端并存（如可视化工具、录制脚本与业务程序同时连接）为默认行为（`enable_bridge=True`），可切换为独占单客户端模式，见 [Wuji SDK 的设备连接](/docs/wuji-sdk/device-connection/)

### 超时、断连与重连

* 连接参数：`ConnectOptions(timeout_ms=1000, retry_count=3)`
* **使能状态下通信中断**：设备停止电机并上报故障。恢复通信后设备不会自动恢复运动，需重新调用 `enable()` 使能（固件 v2.1.0 起）

恢复通信：

1. 检查网线两端与网络设备，确认与上位机的链路已恢复
2. 订阅 `joint_diagnostics` 读取活跃错误码，用 `WujiHand2.describe_error(code)` 解码并按提示排除原因
3. 重新调用 `enable()`，确认状态灯转为白色常亮


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