Orisys 夹爪

1.1 编写目的

本手册用于指导用户正确安装、配置、操作和维护 Orisys 夹爪软件（以下简称「本软件」）。用户应在使用本软件前通读第 2 章安全须知，并按本手册规定步骤进行操作。

1.2 产品简介

Orisys 夹爪是一套集成视觉触觉感知、智能夹持控制与图形化监控的演示系统。系统通过左右两个视觉触觉传感器采集法向力与切向力信息，经 Modbus RTU 串口驱动夹爪执行动作，并在 PyQt5 图形界面中同步显示 3D 模型、光流画面、力曲线及运行状态。

本软件主要实现以下功能：

• 单侧触觉触发后自动闭合、接触检测、分步加力、自适应夹持及取物释放；
• 实时显示夹爪三维姿态、左右传感器光流/幅值图像及六路力值曲线；
• 提供智能模式与手动模式，支持速度、力度、位置等参数调节；
• 支持运行参数在线编辑、工作区布局保存及运行日志记录。

1.3 术语与缩略语

1.4 引用文件

2.1 一般安全要求

1. 仅经培训人员方可操作本系统；
2. 运行前检查夹爪安装牢固、电源及通信线缆连接可靠；
3. 传感器标定及系统重启标定阶段，须保持两侧触觉传感器空载且静止；
4. 修改力度、速度及触发阈值前，应备份 config/gripper.json；
5. 程序异常退出后，以夹爪实际物理状态为准，必要时手动断电复位。

2.2 电气与设备安全

• 串口通信期间不得热插拔通信线缆（除非硬件支持）；
• USB 摄像头及串口设备应连接至稳定供电的 USB 端口，避免共用易过载的 USB Hub；
• Linux 环境下运行用户须具备 video、dialout 设备组权限。

3.1 系统组成

本系统由感知层、软件处理层及执行与呈现层构成。左、右触觉传感器采集视频帧并计算触觉力；智能夹持状态机根据力信号经 Modbus RTU 串口驱动夹爪；GUI 同步显示 3D 姿态、光流图像、力曲线及运行状态。

3.2 配置清单

3.3 软件目录结构

发布包解压后须保持完整目录结构。禁止仅复制可执行文件至其他路径单独运行。

GripperDemo02/
├── GripperDemo02.exe              # 主程序（Linux 无 .exe 后缀）
├── _internal/                     # 运行时依赖库（禁止删除）
├── config/
│   ├── gripper.json               # 主配置文件
│   ├── ddjx01_q6a.json                # 传感器配置文件
│   ├── compound_eye.png           # 传感器资源
│   └── gui_layout.json            # 界面布局（保存后生成）
├── sdk/                           # 夹爪通信 SDK
├── crt_ctag2f90d_gripper_visualization/   # 3D 模型资源
└── logs/                          # 运行日志（首次运行后自动生成）

4.1 安装前检查

4.2 基本配置

使用文本编辑器打开 config/gripper.json，至少须正确配置以下参数后方可运行。

4.3 系统要求

本系统默认随算力版主机一并交付，出厂已完成操作系统、驱动及软件环境配置，用户开箱连接夹爪与传感器即可使用。若用户自备运行计算机，须满足表 4-3 所列环境要求，并自行完成摄像头、串口及依赖库配置。

5.1 正常启动程序

1. 确认第 4 章检查项目均合格；
2. 双击运行 GripperDemo02.exe（Linux：./GripperDemo02）；
3. 程序启动后自动创建控制线程，夹爪执行张开动作；
4. 系统在 baseline_seconds（默认 1.0 s）内完成传感器空载基准标定，此期间保持两侧传感器无接触；
5. 待顶部状态栏显示 state=open_wait（等待触发），且 action=open-wait-armed（已就绪）；
6. 确认左右传感器状态指示为绿色，FPS 显示正常数值（非 --）。

5.2 正常停止与退出

当配置项 open_at_end=true（默认）时，控制流程结束时会尝试发送夹爪张开命令。若设备已断电或通信异常，以夹爪实际状态为准。

5.3 源码方式运行（调试人员）

# Windows
conda activate py311
python -m gripper.visualizer --windowed

# 跳过真实串口（传感器与 GUI 仍运行）
python -m gripper.visualizer --windowed --dry-run

本软件主界面由顶部状态控制栏、中央 3D 工作区及若干浮动功能面板组成。浮动面板可拖动、调整大小；布局可通过设置模块保存并在下次启动时恢复。

A

B

C左光流

C右光流

D

E

F

• A 顶部状态与控制栏
• B 夹爪 3D 模型工作区
• C 左/右光流窗口
• D 六路力曲线图
• E 夹爪控制区域
• F 传感器控制区域

1Logo

2state / action

3设置

4

5

6

7

• 1 品牌 Logo
• 2 运行状态（state / action）
• 3 设置
• 4 启动控制
• 5 停止控制
• 6 重启控制程序
• 7 最小化 / 全屏 / 关闭

7.1 夹爪 3D 模型

3D 模型区域根据实时夹爪位置在预缓存的开合档位间切换，显示当前机械姿态。区域下方叠加显示左/右法向力、夹爪位置、当前力百分比及自适应目标力百分比。

1state=hold_check

23D 开合姿态

3力/位置摘要

• 1 状态栏显示 hold_check / 当前动作
• 2 3D 模型反映当前开合档位
• 3 左/右法向力、位置、力比例摘要

7.2 光流窗口

左、右光流窗口为独立浮动面板，分别对应两路触觉传感器。用户可通过右上角模式按钮在「光流」与「幅值」显示模式间切换。

1左侧传感器

2右侧传感器

3光流/幅值切换

• 1 左传感器光流/幅值画面
• 2 右传感器光流/幅值画面
• 3 「光流 / 幅值」模式切换按钮

7.3 力曲线图

曲线区域以 3 行 × 2 列布局显示六路力值，横轴为时间（秒），纵轴为力（牛顿）。默认显示最近约 6 s 数据；显示值经平滑处理，绝对值低于 0.05 N 时归零显示。

D曲线图区域

1法向力

2

3

• D 曲线图浮动面板整体
• 1 第 1 行：左/右法向力
• 2 第 2 行：左/右切向力 X
• 3 第 3 行：左/右切向力 Y

7.4 传感器控制区域

F

1在线状态

2

3力值 / FPS

• F 传感器控制浮动面板
• 1 绿/红状态点（是否收到样本）
• 2 左/右 FPS 显示
• 3 法向/切向力读数及重启按钮

智能模式为本软件默认工作模式。该模式下，夹爪动作由触觉信号驱动的状态机自动控制，用户不应在演示过程中切换至手动模式或干预运动参数。

8.1 标准演示步骤

8.2 运行约束

• 默认配置要求左右两侧均达到接触阈值（grip_requires_both=true）方判定夹持成功；
• 闭合超时（默认 5 s，参数 close_timeout_seconds）未检测到物体时，系统自动张开；
• 释放后须满足位置/力恢复条件并经过最短休息时间（rearm_seconds，默认 0.5 s），方可再次触发；
• 休息期间即便传感器检测到扫过，也不会触发闭合。

控制程序处于运行状态时，用户可点击「手动模式」切换至手动控制。手动模式下，用户可直接设定速度、最大力及目标位置，并执行张开、闭合、保持等命令。

E

1智能模式（锁定）

2滑条禁用

3

• E 夹爪控制面板
• 1 「智能模式」高亮，「手动模式」不可切换干预
• 2 速度 / 最大力 / 位置滑条禁用
• 3 张开 / 闭合 / 保持按钮禁用

E

1手动模式

2动作按钮可用

• E 夹爪控制面板
• 1 「手动模式」激活，可调整速度/力度/位置
• 2 保持、张开、闭合按钮可点击

点击顶部设置图标打开设置窗口。设置窗口分为「画面」「布局」及若干参数分组页，参数分组内容直接映射 config/gripper.json 文件字段。

10.1 参数保存程序

在设置窗口中修改参数后，须按以下顺序操作，否则运行中的控制程序不会加载新值：

1. 点击「保存到 gripper.json」，确认保存成功提示；
2. 关闭设置窗口；
3. 点击顶部「重启控制程序」。

10.2 常用参数速查

完整参数分组及默认值见《GUI 详细技术说明》（docs/GUI_USER_MANUAL.zh-CN.md）第 14 章。

11.1 状态码说明

11.2 日志文件

打包版程序运行日志保存在程序目录下 logs/ 文件夹。程序自动保留最近 10 次运行会话。

logs/
├── latest.txt                      # 最近一次会话目录名
└── YYYYMMDD_HHMMSS_PID/
    ├── main.log                    # GUI、控制器、串口及异常信息
    └── worker_*.log                # 左、右传感器进程日志

建议故障排查顺序：读取 latest.txt → 打开对应会话目录 → 检查 main.log 末尾异常 → 必要时对照 worker_*.log。

11.3 快捷键

13.1 日常维护

• 保持触觉敏感面清洁，避免油污及硬质颗粒；
• 定期检查 USB 及串口线缆有无松动或外皮破损；
• 长期停用后重新启用前，执行一次完整重启并完成空载标定；
• 重要参数变更前备份 config/gripper.json 及 config/gui_layout.json。

13.2 标定参数维护

normal_force_calibration 与 shear_force_calibration 用于将传感器原始量映射至牛顿单位，直接影响触发、接触及释放判断。修改标定点须有实测数据支持，修改后须重新验证全流程。

附录 A　现场操作检查表

启动前检查

• 左右摄像头已被操作系统识别
• 夹爪电源及串口通信正常
• video1、video2、port 配置正确
• 夹爪开合范围内无人员及杂物
• 两侧触觉传感器无预加载

启动后确认

• 左右传感器 FPS 正常，状态点为绿色
• 3D 模型姿态与夹爪实际位置一致
• 顶部状态无 error
• 已等待 open-wait-armed（已就绪） 后再进行演示

附录 B　插图维护说明

本手册插图由软件界面自动截取生成。软件界面变更后，可在项目根目录执行以下命令重新生成插图：

conda activate py311
python build/capture_gui_screenshots.py
python build/generate_manual_diagrams.py

截图输出路径：docs/images/manual/；矢量示意图输出路径：docs/assets/diagrams/。

— 文档结束 · GD02-UM-001 V1.0 —
Orisys 夹爪产品使用说明书