> ## 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]
>
> 本页覆盖 2.1 设备的机械安装、坐标系与模型资产、电气与网络接入。掌心安装接口与整机结构在 2.1 与 2.2 之间没有变化，模型资产各有一套独立目录。首次连接的分步操作见[快速开始](https://docs.wuji.tech/docs/zh/wuji-hand/beta1/quick-start)。

## 机械集成

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

### 腕部安装接口

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

### 掌心安装接口

掌心底部提供标准安装接口，供加工臂侧转接板使用。左右手接口一致，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-与图纸)。

### 左右手差异

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

### 载荷与线缆边界

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

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

### 掌心安装接口 STEP 与图纸

掌心安装接口 STEP 与图纸位于下列路径。如需 Beta 模型的整机 STEP 装配，使用 [wuji-description v2026.9.11](https://github.com/wuji-technology/wuji-description/tree/v2026.9.11)。

| 资源 | 路径与用途 |
| - | - |
| 掌心安装接口 STEP | `hand2/hand2_1/attachment/wuji-hand2-description-{left,right}-mount_hand2_1_step.STEP`，仅含掌部与线束，用于自制机械臂侧转接件或工装 |
| A3 标注图纸 | `hand2/hand2_1/attachment/wuji-hand2-description-{left,right}-mount_hand2_1.pdf`，标注转接件对接的螺纹孔位，规格见[掌心安装接口](#掌心安装接口) |

左右手文件互为镜像。掌心安装接口在 2.1 与 2.2 之间没有变化，文件名中的版本标记仅用于与目录对齐。`attachment/` 位于 ROS 2 包根 `body/` 之外，colcon 不会安装。

## 坐标系与模型

### 模型资产

2.1 的模型资产在 `hand2/hand2_1/` 目录下，与 2.2 的 `hand2/hand2_2/` 互不冲突。

| 项 | 2.1 的约定 |
| - | - |
| 关节 | 每手 20 个 revolute 关节 |
| 命名 | thumb / index / middle / ring / pinky 解剖学命名 |
| 根连杆 | 臂法兰安装座 `{l,r}_mount` |
| 执行器 | `{l,r}_{THJ｜FFJ｜MFJ｜RFJ｜LFJ}{0-3}` |
| 指尖 site | 每手 5 个查询 site，用于抓取点查询与指尖轨迹评估 |
| ROS 2 包 | `wuji_hand2_1_description`，包根 `hand2/hand2_1/body/` |

模型以臂法兰安装座为根，腕壳通过固定关节连接到安装座。腕部安装坐标系与根连杆的相对关系以 URDF 定义为准。

> [!WARNING]
>
> 2.1 已提供包含软体外形的刚体模型，暂不支持软体变形仿真。模型差异见[版本识别与兼容性](https://docs.wuji.tech/docs/zh/wuji-hand/beta1/version-identification-and-compatibility)。

### 环境要求

| 用途 | 要求 |
| - | - |
| MuJoCo | Python 与 `mujoco` 包 |
| ROS 2 与 RViz | ROS 2 Lyrical，Ubuntu 26.04 |
| Isaac Sim USD | Isaac Sim |
| URDF 预览 | 任意 URDF 查看器，例如 urdf-viz |
| STEP / CAD | 支持 STEP 格式的 CAD 工具，例如 FreeCAD、SolidWorks |

### 获取与加载

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

MuJoCo：

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

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

```

ROS 2 与 RViz 的依赖安装、描述包安装和启动方法见 [ROS 2 集成](https://docs.wuji.tech/docs/zh/wuji-hand/beta1/ros2-integration.md)。

Isaac Sim USD：

| 变体 | 路径 |
| - | - |
| 左手 | `hand2/hand2_1/body/usd/left/wujihand2_1.usd` |
| 右手 | `hand2/hand2_1/body/usd/right/wujihand2_1.usd` |

URDF 预览：

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

### 验证

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

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

## 电气与网络集成

### 供电

> [!WARNING]
>
> 2.1 仅支持 12 V 直流供电，请严格按 12 V 接入，其他电压范围不兼容。后续版本的对外接口形式与供电电压范围会变化，集成方案请预留改动空间。

| 项 | 规格 |
| - | - |
| 工作电压 | 12 V 直流 |
| 建议供电额定功率 | 不低于 200 W，标配电源适配器满足该要求 |
| 外部线束 | 腕部直接引出 XT30 与 RJ45 网口两根线 |
| 网口 | 标准 RJ45，支持 100BASE-TX |

详见[使用约束的电气与供电](https://docs.wuji.tech/docs/zh/wuji-hand/beta1/usage-constraints.md#电气与供电（强约束）)。

### 上下电时序

上电顺序：先连接设备端 XT30，再接通电源适配器。下电顺序：确认设备静止，断开电源，拔下线缆。

### 网络配置

设备使用静态 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 |

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

### 多设备与多客户端

* 多台设备接在同一网段时，出厂 IP 按左右手区分，第三台起需先改 IP 再接入
* 连接时用 `--sn` 或 `manager.connect(sn=...)` 指定目标，避免连错设备

### 超时、断连与重连

通信中断时设备的停机行为、重连策略与清故障流程见[维护](https://docs.wuji.tech/docs/zh/wuji-hand/beta1/maintenance#安全停止与异常恢复)。


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