GRIPLINK Example Programs
-------------------------
Example programs for WEISS ROBOTICS GRIPLINK-compatible devices on KUKA robots. Each example is
one .src and one .dat file and needs the GRIPLINK plugin and the error routine
GLDemo_ErrorHandling. Port, preset and the other parameters are in the .dat file of the example.
Before the first motion, every example except GLDemo_FaultRecovery and GLDemo_ConnectionCheck
reads the device state: a device in the state NOT_INITIALIZED (1) is homed and enabled, a device
in the state DISABLED (2) is enabled.

Program                 Description                                        Key commands
----------------------  -------------------------------------------------  -------------------
GLDemo_SimpleGrip       Blocking grip/release cycle with a grip preset,    GRIP, RELEASE,
                        state check after the grip. Starting point for     DEVSTATE, DISABLE
                        new integrations.
GLDemo_Main             Three blocking grip/release cycles with a preset   DEVASSERT, GRIPCFG,
                        written by GRIPCFG, HOLDING / NO PART check.       GRIP, RELEASE,
                                                                           DEVSTATE, VALUE, LED
GLDemo_FlexgripCycle    Grip/release with motion parameters (position,     FLEXGRIP,
                        force, speed, acceleration), without presets.      FLEXRELEASE, DEVSTATE
GLDemo_AsyncPrepos      Non-blocking pre-positioning of the fingers while  FLEXRELEASE
                        the robot travels; WAITVAL at the target.          (non-blocking),
                                                                           WAITVAL, VALUE
GLDemo_CheckWorkpiece   Grips, reads the finger position (VALUE index 0)   GRIP, RELEASE,
                        and shows ACCEPTED or REJECTED against a           DEVSTATE, VALUE
                        tolerance band.
GLDemo_MultiGrip        Non-blocking grip and release on two ports         GRIP, RELEASE
                        (default 0 and 1) with polling of the state.       (non-blocking),
                                                                           DEVSTATE
GLDemo_FaultRecovery    Clears the state FAULT (7) with DISABLE -> HOME    DEVSTATE, DISABLE,
                        -> ENABLE.                                         HOME, ENABLE
GLDemo_ConnectionCheck  Shows whether a connection is open, connects and   DEVSTATE, CONNECT,
                        shows the device state of every port               DISCONNECT
                        (GLD_FIRST_PORT to GLD_LAST_PORT). No device is
                        moved.
GLDemo_ErrorHandling    Template of the error routine, called by every
                        example with the status code of a failed command;
                        not started on its own. One case per status code,
                        where the integrator adds the reaction for the
                        safety concept of the application.

Error handling:
  Every GRIPLINK function returns a status code: 0 = success, 1..27 = error code of the GRIPLINK
  Controller (GRIPLINK Unified Command Set Reference Manual, chapter 4), 101..107 = error code of
  the plugin (GripLink_Kuka.dat). Caller pattern of the examples:

     res = GRIPLINK_<COMMAND>(...)
     IF res <> GL_E_SUCCESS THEN
         GLDemo_ErrorHandling(res)
         RETURN
     ENDIF

  The plugin shows a message with the command and the error text for every status code.
  GLDemo_ErrorHandling shows a message that the template has not been adapted yet. After
  GL_E_EKI_ERROR, GL_E_NO_REPLY and GL_E_CONNECTION_LOST the connection is closed: bring the cell
  into a safe state, then call GRIPLINK_CONNECT.

  Every example sets EkiShowMessageLevel to 0 before GRIPLINK_CONNECT: iiQKA.EthernetKRL then does
  not stop the program with an acknowledgement message, the command returns a status code. The
  value applies to all Ethernet connections and stays stored on the robot controller.

Quick start:
  1. Install the plugin and the Ethernet configuration GRIPLINK_KUKA_IF.xml as described in
     chapter 3 of the user manual and enter the IP address and port of the GRIPLINK Controller.
  2. Import the GLDemo_* files (.src and .dat). GLDemo_ErrorHandling is required by every example.
  3. Set the port and the other parameters in the .dat file of the example.
  4. Select and start GLDemo_ConnectionCheck. It shows the connection and the device state of
     every port; no device is moved.
  5. Make sure that the fingers can move freely, then select and start GLDemo_SimpleGrip.
  In T1 a program runs only while the start key is held.

Device states (GL_DS_* in GripLink_Kuka.dat):
  Code  Name                   Description
  ----  ---------------------  ------------------------------------------
     0  GL_DS_NOT_CONNECTED    No device connected
     1  GL_DS_NOT_INITIALIZED  Device is not initialized
     2  GL_DS_DISABLED         Idle, waiting for a command
     3  GL_DS_RELEASED         Part released
     4  GL_DS_NO_PART          No part found
     5  GL_DS_HOLDING          Holding a part
     6  GL_DS_ENABLED          Enabled (sensors)
     7  GL_DS_FAULT            Fault; use GLDemo_FaultRecovery

Command annotation:
  The FLEXGRIP and FLEXRELEASE calls are preceded by a comment line with their parameters:
  Annotation  Unit     Parameter
  ----------  -------  ---------------------------------------------------------------
  pos         mm       Target finger position (FLEXGRIP: no-part limit)
  F           N        Gripping force (FLEXGRIP only)
  spd         mm/s     Finger speed (0: FLEXGRIP automatic calculation, FLEXRELEASE
                       default value)
  acc         mm/s2    Finger acceleration (0 = default value)
  doBlock     -        1 (wait): the command waits until the motion is complete
                       0 (no wait): the command returns immediately after the start

Hardware required:
  KUKA robot controller with iiQKA.OS2 and iiQKA.EthernetKRL; a GRIPLINK Controller (e.g.
  GRIPLINK-ET4 with an IO-Link servo gripper) reachable via Ethernet. IP address (default
  192.168.1.40) and port (10001) are set in GRIPLINK_KUKA_IF.xml.
