Advanced Usage
==============

Realtime control
----------------

.. youtube:: 55NyOWzFGxA

For realtime control use the realTimeMove method.

.. code-block:: python

    gripper.realTimeMove(requestedPosition=100)

The realTimeMove method is designed to be called in a loop with a high frequency. \
It will move the gripper to the requested position with a speed that depends on \
the distance to the target position. This allows for a smooth and responsive \
control of the gripper.

Joystick CLI Feature
--------------------
Position control
^^^^^^^^^^^^^^^^

pyRobotiqGripper includes a command-line interface (CLI) tool for controlling the \
gripper using a joystick, gamepad or a mouse.

This CLI requires the `all` extra.

To use the Joystick CLI, run the following command:

.. code-block:: bash

    pyrobotiqgripper-joystick

.. note::
    By defaut the application will automatically detect the \
    the port on which is connected the gripper. It expects that the gripper is connected to \
    the PC via USB and that a joystick is also connected to the PC.

You can also check the available options:

.. code-block:: bash

    pyrobotiqgripper-joystick --help

Here below is an example where the application is launched with mouse control and the \
gripper communication is done via Modbus RTU over TCP.

.. code-block:: bash

    pyrobotiqgripper-joystick --connection-type "RTU_VIA_TCP" --tcp-host 10.0.0.153 --tcp-port 2000 --joystick-id -1 --verbose 1

Speed control (Push Pull control)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Push-pull control drives the gripper directly from two live input signals instead of a
target position: a motion signal (open/close direction and speed) and a force signal
(grip force), read at high frequency from a joystick, gamepad or mouse axis.

To use it from the CLI, pass ``--control-method push-pull``:

.. code-block:: bash

    pyrobotiqgripper-joystick --control-method push-pull

- The motion axis (``--motion-axis``) controls direction and speed: pushing it one way
  closes the gripper, the other way opens it, and centered holds the current position.
  Speed follows the axis directly.
- The force axis (``--force-axis``) controls grip force. Force ramps up or down
  gradually while the axis is held away from center, like squeezing a trigger, rather
  than jumping straight to a value.
- Once the gripper grips an object (or reaches its target), pushing further in the same
  direction only re-engages the grip once the requested force or speed has increased
  meaningfully (``--force-nudge-threshold`` / ``--speed-nudge-threshold``, out of 255),
  so the fingers aren't repeatedly driven into the object on every control-loop tick.
  Reversing direction releases immediately, without needing to cross either threshold.

Use ``--joystick-id -1`` to control push-pull mode with the mouse instead of a
joystick/gamepad; ``--deadzone`` then sets the mouse dead zone described above. Pass
``--verbose 1`` to print the commanded speed/force/position on every call.

.. code-block:: python

    gripper.pushPullMove(pushPullMotionSignal=0.5, pushPullForceSignal=0.2)