GRIPLINK Core - Example Programs
=================================

This folder contains FANUC TP/LS example programs that demonstrate typical
usage patterns of the GRIPLINK Core plugin. Each example uses the low-level
GRIPLINK command interface directly via CALL GRIPLINK("CMD"=<code>, ...) and
can be loaded into a RoboGuide workcell or a real controller.

NOTE: All programs require the GRIPLINK Core KAREL binaries to be installed
on the controller and a valid COM_TAG entry in the robot system variables.

NOTE ON SYNTAX: The Core programs call GRIPLINK commands using named keyword
parameters, e.g.:
  CALL GRIPLINK("GRIP"=20,"PORT"=0,"PRESETIDX"=0,"DOBLOCK"=1)
This is different from the CRX plugin examples, which use the
IPL_WR_GRIPLINK_* wrapper macros.


OVERVIEW
--------

Program                 Description
---------------------------------------------------------------------------------------
GRIPLINK_DEMO           Basic GRIP/RELEASE loop - entry-level example, no fault exit
SIMPLE_GRIP_RELEASE     Blocking grip/release cycle with full state checking and fault handler
MULTI_GRIP_RELEASE      Simultaneous operation of multiple grippers across ports 0-3
ASYNC_PREPOSITION       Asynchronous pre-positioning during robot motion
FLEXGRIP_CYCLE          Full FlexGrip/FlexRelease cycle with speed, force, and no-part detection
CHECK_WORKPIECE         Workpiece size measurement and acceptance check


PROGRAM DETAILS
---------------

GRIPLINK_DEMO
  The most basic example. Connects to the GRIPLINK controller (COM_TAG=1),
  homes the gripper on port 0, and runs three consecutive GRIP/RELEASE cycles
  using a FOR loop with preset 0. The device state (R[10]) is evaluated after
  each GRIP to distinguish HOLDING (5) from no part, but no fault recovery or
  exit jump is implemented. Intended as a first functional test after
  installation.

  Key calls: CONNECT -> HOME -> RELEASE -> (GRIP -> STATE -> RELEASE) x3 -> BYE

  Register usage:
    R[10]  Device state return value
    R[20]  Loop counter (1..3)


SIMPLE_GRIP_RELEASE
  A self-contained, continuously running GRIP/RELEASE demonstration with
  complete error handling. After each operation the device state is read
  explicitly with STATE and checked:

    State 5 (HOLDING)  -> part gripped successfully
    State 4 (NO PART)  -> gripper closed but nothing detected
    Any other state    -> fault, jumps to LBL[99] which calls BYE and aborts

  The normal cycle loops back via JMP LBL[1]. This is the recommended
  starting template when building a new application from scratch.

  Key calls: CONNECT -> HOME -> RELEASE -> GRIP -> STATE -> check
             -> RELEASE -> STATE -> check -> loop / BYE + ABORT

  Register usage:
    R[10]  Device state return value


MULTI_GRIP_RELEASE
  Demonstrates parallel operation of multiple grippers on a GRIPLINK-ET4
  controller. The program first scans ports 0-3 with STATE to auto-detect
  how many grippers are connected (R[2] stores the last active port index).
  Each detected gripper is homed and initially released.

  The grip phase issues GRIP with DOBLOCK=0 (non-blocking) for all ports in
  sequence, then uses a second loop with WSTR (Wait-State-Return) to
  synchronize all grippers at once. The same pattern is repeated for release.
  This minimises total cycle time when multiple grippers must act
  simultaneously.

  Key calls: CONNECT
             -> (STATE / HOME / RELEASE) per detected port
             -> GRIP (DOBLOCK=0) x N -> WSTR x N
             -> RELEASE (DOBLOCK=0) x N -> WSTR x N
             -> loop / BYE + ABORT

  Register usage:
    R[1]   Port iterator
    R[2]   Last detected port index (= number of grippers - 1)
    R[10]  Device state return value


ASYNC_PREPOSITION
  Shows how to pipeline gripper pre-positioning with robot travel. FLEXRELEASE
  is called with DOBLOCK=0, so the controller returns immediately and the
  robot can move to the pick/place position while the gripper is opening in
  parallel. After the robot motion (simulated here with WAIT 1.0 sec), WSTR
  is called to confirm the gripper has reached its target state (3 = RELEASED)
  before the program continues.

  Key calls: CONNECT -> HOME
             -> FLEXRELEASE (DOBLOCK=0)
             -> robot motion (WAIT placeholder)
             -> WSTR -> check -> BYE + ABORT / BYE

  Register usage:
    R[1]   Target finger position for FLEXRELEASE (50 mm, adjust to geometry)
    R[10]  Device state return value


FLEXGRIP_CYCLE
  A continuously running FlexGrip/FlexRelease cycle that demonstrates
  preset-free, fully parametric gripper control. All motion parameters are
  passed directly to the command:

    FLEXRELEASE: position=R[2] mm, speed=200 mm/s, acceleration=500 mm/s2
      Opens fingers to the release position.

    FLEXGRIP: position=R[1] mm, force=150 N, speed=50 mm/s, acceleration=default
      Closes until contact or until fingers reach R[1] mm (no-part limit).

  After gripping, STATE is called and the result evaluated:
    5 (HOLDING)  -> part gripped
    4 (NO PART)  -> gripper closed without contact
    other        -> FAULT, exit via LBL[99]

  After a 2-second hold the gripper is released; the release state is verified
  before the cycle loops.

  Key calls: CONNECT -> HOME -> FLEXRELEASE -> FLEXGRIP -> STATE -> check
             -> wait -> FLEXRELEASE -> STATE -> check -> loop / BYE + ABORT

  Register usage:
    R[1]   FlexGrip no-part limit (80 mm, adjust to part geometry)
    R[2]   FlexRelease release position (100 mm, adjust to part geometry)
    R[10]  Device state return value


CHECK_WORKPIECE
  Demonstrates in-process workpiece size measurement. After a standard
  blocking GRIP the device state is checked; only if HOLDING (5) is the
  measurement performed. A short settling wait (0.2 sec) is followed by a
  VALUE command that reads the actual finger spread (value index 0) into R[5].
  The measured value is compared against a configurable tolerance window:

    Within tolerance  -> MESSAGE[WORKPIECE ACCEPTED]
    Out of tolerance  -> MESSAGE[WORKPIECE REJECTED]

  After evaluation the gripper is released and the cycle loops.

  Key calls: CONNECT -> HOME -> RELEASE -> GRIP -> STATE -> check
             -> VALUE -> size check -> RELEASE -> STATE -> check -> loop
             / BYE + ABORT

  Register usage:
    R[1]   Lower size limit (79.9 mm, adjust to part tolerance)
    R[2]   Upper size limit (80.1 mm, adjust to part tolerance)
    R[5]   Measured workpiece size (mm)
    R[10]  Device state return value


DEVICE STATE REFERENCE
----------------------

Code  Name      Description
----  --------  ----------------------------------------
  3   RELEASED  Gripper fully open / released
  4   NO PART   Grip completed, no workpiece detected
  5   HOLDING   Workpiece gripped successfully
  7   FAULT     Error condition


GRIPLINK COMMAND REFERENCE (used in these examples)
----------------------------------------------------

Keyword       Code  Description
------------- ----  -------------------------------------------------
CONNECT          1  Open connection to GRIPLINK controller
BYE              2  Close connection
HOME            13  Home the gripper on the specified port
GRIP            20  Grip using a preset
RELEASE         22  Release using a preset
FLEXGRIP        26  Grip with explicit position / force / speed params
FLEXRELEASE     27  Release with explicit position / speed / accel params
STATE           10  Read current device state into a register
WSTR            80  Wait for gripper to reach its target state (non-blocking sync)
VALUE           41  Read a numeric value (e.g. finger spread) into a register
