HMI 使用说明

1. 启动 HMI

访问 GitHub Releases 页面，下载对应平台安装包。

平台	启动方式
Windows	解压后，双击 `wuji-hand-hmi_<version>-windows` 文件启动
Ubuntu	1. 安装：`sudo apt install ./wuji-hand-hmi_<version>_amd64.deb` 2. 在应用菜单中打开，或终端执行 `wuji-hand-hmi` 启动

若启动过程中遇到问题，请参考故障排除章节。

2. 面板介绍

Wuji Hand HMI 软件面板由全局面板、单轴面板、日志面板构成。面板总览

2.1 全局面板

全局面板用于整手级操作与状态查看，操作对象是整手，反馈信息来源于脊髓板。

名称	说明
端口选择	Linux 版 HMI 自动筛选端口。Windows 版 HMI 不自动筛选端口，先启动 HMI，再连接灵巧手，可在日志面板的操作日志中看到 `[INFO] New ports: ['COM XX']` 提示，据此确定 Wuji Hand 所在端口。
连接 / 断开	选择正确端口后点击连接建立通信，需要结束会话时点击断开。
脊髓板状态显示框	显示：左/右手、系统固件版本号、在线时长，如 `Left 1.2.0 24m59s`。
SN	显示设备序列号。
使能	点击使能所有关节轴电机使能，电机状态为 `RUN`。
失能	点击失能所有关节轴电机失能，电机状态为 `READY`。
清错	若出现 `WARNING/ERROR/FATAL`，请先点击清错，状态恢复后再尝试使能。
位置模式 / 位置回零	点击位置模式将电机模式设为 `RT_FCL`，在使能状态下点击位置回零，整手恢复到零点姿态。
软件复位	需要重启整手驱动时，点击软件复位，电机状态短暂为 `DISCONN`，完成后电机状态为 `READY`。
中文 / EN	中英文切换。
运行例程	点击运行例程后，按预置执行动作序列。用于快速验证通信与基础运动链路。
回放倍率	控制例程回放的速度倍数，拖动滑条调节。范围 0.5x ~ 3.0x，默认 1.0x。
手套姿势	点击手套姿势后，整手自动调整至适合拆装的姿态，供拆装软体/手套时便于操作。
Effort 限制	Effort 限制输入框，用于填写目标值，配合设置 Effort 限制按钮使用。
设置 Effort 限制	设置关节允许的最大 effort 输出。范围为 0-3.5 (A)，默认值为 1.5 (A)。在输入框中填入目标值后点击设置 Effort 限制。什么是 Effort？ Effort 是电流空间的执行器作用量，经过滤波处理后输出。它不是实际测量的电流值，应将其理解为相对驱动强度，适用于负载监控和碰撞检测等场景。警告：修改 Effort 限制可能导致设备损坏提高 Effort 限制值会提升电机输出扭矩，同时增加电机发热。如因调整设置导致设备损坏，用户需自行承担责任。影响相关关节运动寿命，加速各零件磨损且无法预估影响大小可能在某工况下直接造成相关关节出现不可逆的损坏可能加速关节热保护触发，减少持续运动时间可能出现除以上情况下的其他严重后果
帮助	点击帮助跳转到本篇文档。

2.2 单轴面板

单轴面板用于单轴操作与状态查看，操作对象是单个关节轴，反馈信息来源于驱动板。

名称	说明
关节	关节名称。
电机状态	`DEFAULT`：默认状态，当读取到预设状态之外的异常状态会显示为 `DEFAULT` `READY`：就绪状态，表明电机当前处于失能状态 `RUN`：运行状态，表明电机当前处于使能状态 `CALIBRATE`：校准状态，表明电机当前处于校准状态，请不要再次校准或其它操作 `DISCONN`：断联状态，表明电机当前与脊髓板断开连接或上位机没有连接灵巧手 `WARNING`：警告状态，表明电机当前运行状态出现异常，可以通过清错恢复正常状态 `ERROR`：错误状态，表明电机当前运行状态出现错误，可以通过清错恢复正常状态 `FATAL`：严重错误状态，表明电机当前运行状态出现不可逆的错误，若多次重新上电后仍无法恢复，请联系售后
电机温度	显示当前电机温度。
当前模式	显示当前控制模式，如 `RT_FCL`。
当前位置	显示位置反馈在限位标定行程范围之内的百分比。
目标位置	显示位置期望在限位标定行程范围之内的百分比。
位置控制	当前模式为 `RT_FCL` 且电机状态为 `RUN` 时，拖动滑条设定目标位置。
开环+ / 开环-	对应电机运动的顺时针/逆时针两个极性，长按开环+或开环-，电机朝向一侧转动。
恢复出厂	点击恢复出厂出现弹窗：恢复：恢复部分参数到出厂值恢复出厂后，点击全局面板中的软件复位按钮，变更参数即可生效。保存用户参数：保存现有参数到 Flash 保存：保存出厂标定参数到 Flash 重置所有参数：将所有参数恢复到出厂值
设置零点 / 重置零点	由于出厂时标定的零点可能与 URDF 零点存在细微偏差，为满足用户 Sim2Real 需要，可以手动设置一个接近 URDF 零点的用户零点。设置零点：将用户零点设置为当前位置反馈所在的位置重置零点：将零点恢复到出厂时标定的零点

2.3 日志面板

日志面板

日志面板分为左右两栏。左侧为系统日志，记录 WARNING 等级及以上的警告或错误。右侧为操作日志，记录必要的初始化信息及用户操作过程。在日志区域右键，可执行：

复制系统日志 / 复制操作日志：复制所选日志内容到剪贴板。
导出日志：打包导出系统日志与操作日志全部内容，用于问题排查。
清除系统日志 / 清除操作日志：清除对应区域的日志记录。
清除所有日志：同时清除系统日志与操作日志。

当设备或上位机出现异常时，请先在日志面板导出日志并保存，再与问题现象描述一并提供给售后，以便快速定位原因。

3. 连接与使能

3.1 设备连接

确认硬件连接正确，按启动 HMI中的方式打开上位机软件。启动成功后，日志面板的操作日志中显示以下信息：

[INFO] Successfully bound SDO socket to 127.0.0.1:xxxxx
[INFO] Successfully bound PDO socket to 127.0.0.1:xxxxx
[INFO] heart beat timer is enabled
[INFO] connection established
[INFO] Device SN displayed: xxxx.xxxxxx.xxx
[INFO] System Version: x.x.x

点击全局面板中的连接按钮，成功连接后：

全局面板中的脊髓板状态显示框显示：左/右手、系统固件版本号、在线时长，如 Left 1.2.0 24m59s。
单轴面板中的电机状态为 READY，电机温度等数据持续刷新。

3.2 快速验证动作

点击全局面板中的运行例程，整手将循环执行一段预设动作序列，用于验证通信与运动功能。

在动作序列执行期间请勿进行其他操作。

4. 故障排除

4.1 端口访问权限

启动 Ubuntu 版上位机时，出现无法找到端口问题：

方法一：将当前用户加入 dialout 组
```
sudo usermod -a -G dialout $USER
```
执行后需使权限生效：
- 仅当前终端生效：newgrp dialout
- 全局生效：sudo reboot
方法二：sudo 启动上位机
```
sudo wuji-hand-hmi
```

4.2 显示缩放警告

若启动时弹出显示缩放警告，说明当前系统显示缩放比例大于 100%。请在系统设置中将显示缩放比例调整到 100% (1:1)，然后重新启动 HMI。

目录