test/gripper_control_02/README.md

Gripper Control 02

夹爪02是新的展示程序，和原来的定时开合逻辑分开。它不是定时循环开合；程序只是常驻监听单侧触发，每次触发后执行一次“闭合夹住 -> 监测变化 -> 直接张开”的流程。

展示流程

1. 程序启动后，夹爪先张开。
2. 程序等待任意一侧触觉传感器感受到法向力或切向力。
3. 展示时，把物体从某个侧边扫一下，触发单侧力变化。
4. 触发后夹爪开始闭合，你把物体移动到中间。
5. 闭合过程中检测到物体后，切到低力并保持当前位置。
6. 像 01 一样进入 gripping，慢慢加力到 HOLD_FORCE。
7. 进入 hold_check 后记录夹持参考力。
8. 后续法向力或切向力变化超过阈值，夹爪直接张开到 OPEN_POS。
9. 张开后进入 open_recover，保持张开并等待恢复条件。
10. 夹爪回到 OPEN_POS 初始点位，或法向/切向读数都低于恢复阈值并稳定后，回到 open_wait。
11. 回到 open_wait 后，程序必须先看到触发力清掉并稳定，才会重新武装；下一次扫过才允许闭合。

运行

从项目根目录运行：

conda activate py311
python -m gripper_control_02.main

只看逻辑、不打开串口：

python -m gripper_control_02.main --dry-run

PyQt 可视化展示：

python -m gripper_control_02.visualizer

窗口模式运行：

python -m gripper_control_02.visualizer --windowed

兼容入口：

python examples\gripper_demo_02_viewer.py

默认配置文件：

gripper_control_02\config\gripper_demo_02.py

关键配置

• TRIGGER_NORMAL_FORCE: 单侧法向力触发阈值。
• TRIGGER_SHEAR_FORCE: 单侧切向力触发阈值。
• TRIGGER_CLEAR_STABLE_SECONDS: 张开恢复后，触发力必须清掉并稳定多久，才允许下一次扫过触发。
• GRIP_NORMAL_FORCE: 夹住时左右接触阈值。
• GRIP_REQUIRES_BOTH: 是否必须左右都接触才算夹住。
• GRIP_START_FORCE: 检测到物体后先切到的低力。
• FORCE_RAMP_STEP: 慢慢加力时每次增加多少 force_pct。
• FORCE_RAMP_INTERVAL: 慢慢加力时两次加力的间隔。
• HOLD_FORCE: 慢慢加力到这个值后进入 hold_check。
• GRIP_SETTLE_SECONDS: 夹住后等待稳定多久再记录参考力。
• RELEASE_NORMAL_CHANGE: 夹住后法向力变化超过它就松开。
• RELEASE_SHEAR_CHANGE: 夹住后切向力变化超过它就松开。
• RELEASE_OPEN_SPEED: 检测到松开后，张开到 OPEN_POS 使用的速度。
• RELEASE_OPEN_ACCEL: release 张开的加速度。
• RELEASE_OPEN_DECEL: release 张开的减速度。
• REARM_SECONDS: 张开后最短等待时间，防止刚松开马上又误触发。
• RECOVER_NORMAL_FORCE: 张开恢复时允许重新触发的最大法向残余力。
• RECOVER_SHEAR_FORCE: 张开恢复时允许重新触发的最大切向残余力。
• RECOVER_STABLE_SECONDS: 力清空后需要连续稳定多久，才重新等待触发。
• OPEN_POSITION_RECOVER_ENABLED: 是否允许夹爪回到 OPEN_POS 后直接恢复等待。
• OPEN_POSITION_TOLERANCE: 当前点位和 OPEN_POS 差值小于它，就认为已经回到初始点位。
• OPEN_POSITION_STABLE_SECONDS: 回到初始点位后需要稳定多久，才重新等待触发。
• OPEN_POSITION_CHECK_INTERVAL: open_recover 中读取夹爪当前位置的间隔。

日志字段

• L/R: 左右法向力，单位 N。
• maxN: 左右法向力最大值，单位 N。
• shear: 左右切向力最大值，单位 N。
• trigger: 是否满足单侧触发条件。
• armed: 是否已经重新武装；只有 trigger=1 armed=1 才会闭合。
• grip_contact: 是否满足夹住接触条件。
• dN: 夹住后当前法向力相对参考值的最大变化，单位 N。
• dShear: 夹住后当前切向力相对参考值的变化，单位 N。
• state: 当前状态。
• hold_pos: 夹住后保持的位置。
• force_pct: 当前夹爪目标力百分比。
• action: 当前动作。

可视化展示

• 左右两边的光流箭头图。
• 左右两边的光流幅值图。
• 左右法向力、最大切向力、左右差值。
• 当前 state、action、trigger/armed、grip_contact。
• 当前 force_pct、速度 speed_pct、hold_pos。
• 左右传感器 FPS、接触标志、光流均值/最大值。

状态说明

• open_wait: 夹爪张开，等待任意单侧触发。
• closing: 单侧触发后正在闭合，等待检测到物体。
• gripping: 检测到物体后低力保持当前位置，并慢慢加力。
• hold_check: 已夹住并记录参考力，监测法向/切向变化；变化超过阈值会直接张开。
• open_recover: 已经发出张开命令，正在等待回到初始点位或等待法向/切向残余力清空；这个状态不会闭合夹爪。

常见动作说明

• force-change-release-open: 检测到夹住后的法向或切向变化，已经发出张开命令。
• open-recover-position: 夹爪当前位置已经接近 OPEN_POS，正在等待到位稳定。
• open-ready-position: 夹爪已经回到初始点位，重新进入等待下一次扫过触发。
• open-wait-clear-trigger: 已经回到等待状态，但当前力还超过触发阈值，暂时不会闭合。
• open-wait-trigger-clearing: 触发力已经低于阈值，正在等待清零稳定时间。
• open-wait-armed: 触发已经清掉并稳定，下一次扫过可以闭合。
• open-recover-wait-force-clear: 夹爪保持张开，但传感器还有残余力，不允许重新闭合。
• open-recover-stabilizing: 力已经低于恢复阈值，正在等待稳定时间。
• open-ready: 力已经清空并稳定，重新进入等待下一次扫过触发。