viam.components.gripper
=======================

.. py:module:: viam.components.gripper


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/viam/components/gripper/client/index
   /autoapi/viam/components/gripper/gripper/index
   /autoapi/viam/components/gripper/service/index


Classes
-------

.. autoapisummary::

   viam.components.gripper.KinematicsFileFormat
   viam.components.gripper.Gripper


Package Contents
----------------

.. py:class:: KinematicsFileFormat

   Bases: :py:obj:`_KinematicsFileFormat`


.. py:class:: Gripper(name: str, *, logger: Optional[logging.Logger] = None)

   Bases: :py:obj:`viam.components.component_base.ComponentBase`


   Gripper represents a physical robotic gripper.

   This acts as an abstract base class for any drivers representing specific
   gripper implementations. This cannot be used on its own. If the ``__init__()`` function is
   overridden, it must call the ``super().__init__()`` function.

   ::

       from viam.components.gripper import Gripper

   For more information, see `Gripper component <https://docs.viam.com/dev/reference/apis/components/gripper/>`_.


   .. py:attribute:: API
      :type:  Final

      The API of the Resource


   .. py:class:: HoldingStatus

      HoldingStatus represents whether the gripper is currently holding onto an object. The
      additional ``meta`` attribute contains other optional contextual information (i.e. confidence
      interval, pressure, etc.)


      .. py:attribute:: is_holding_something
         :type:  bool


      .. py:attribute:: meta
         :type:  Optional[Dict[str, Any]]
         :value: None




   .. py:method:: open(*, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs)
      :abstractmethod:

      :async:


      Open the gripper.

      ::

          my_gripper = Gripper.from_robot(robot=machine, name="my_gripper")

          # Open the gripper.
          await my_gripper.open()

      For more information, see `Gripper component <https://docs.viam.com/dev/reference/apis/components/gripper/#open>`_.



   .. py:method:: grab(*, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> bool
      :abstractmethod:

      :async:


      Instruct the gripper to grab.

      ::

          my_gripper = Gripper.from_robot(robot=machine, name="my_gripper")

          # Grab with the gripper.
          grabbed = await my_gripper.grab()

      :returns: Indicates if the gripper grabbed something.
      :rtype: bool

      For more information, see `Gripper component <https://docs.viam.com/dev/reference/apis/components/gripper/#grab>`_.



   .. py:method:: is_holding_something(*, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> HoldingStatus
      :abstractmethod:

      :async:


      Get information about whether the gripper is currently holding onto an object.

      ::

          my_gripper = Gripper.from_robot(robot=machine, name="my_gripper")

          # Grab with the gripper.
          holding_status = await my_gripper.is_holding_something()
          # get the boolean result
          is_holding_something = holding_status.is_holding_something

      :returns: see documentation on `HoldingStatus` for more information
      :rtype: HoldingStatus

      For more information, see `Gripper component <https://docs.viam.com/dev/reference/apis/components/gripper/#grab>`_.




   .. py:method:: stop(*, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs)
      :abstractmethod:

      :async:


      Stop the gripper. It is assumed the gripper stops immediately.

      ::

          my_gripper = Gripper.from_robot(robot=machine, name="my_gripper")

          # Stop the gripper.
          await my_gripper.stop()

      For more information, see `Gripper component <https://docs.viam.com/dev/reference/apis/components/gripper/#stop>`_.



   .. py:method:: is_moving() -> bool
      :abstractmethod:

      :async:


      Get if the gripper is currently moving.

      ::

          my_gripper = Gripper.from_robot(robot=machine, name="my_gripper")

          # Check whether the gripper is currently moving.
          moving = await my_gripper.is_moving()
          print('Moving:', moving)

      :returns: Whether the gripper is moving.
      :rtype: bool

      For more information, see `Gripper component <https://docs.viam.com/dev/reference/apis/components/gripper/#is_moving>`_.



   .. py:method:: get_kinematics(*, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> Tuple[viam.components.gripper.KinematicsFileFormat.ValueType, bytes]
      :abstractmethod:

      :async:


      Get the kinematics information associated with the gripper.

      ::

          my_gripper = Gripper.from_robot(robot=machine, name="my_gripper")

          # Get the kinematics information associated with the gripper.
          kinematics = await my_gripper.get_kinematics()

          # Get the format of the kinematics file.
          k_file = kinematics[0]

          # Get the byte contents of the file.
          k_bytes = kinematics[1]

      :returns: A tuple containing two values; the first [0] value represents the format of the
                file, either in URDF format (``KinematicsFileFormat.KINEMATICS_FILE_FORMAT_URDF``) or
                Viam's kinematic parameter format (spatial vector algebra) (``KinematicsFileFormat.KINEMATICS_FILE_FORMAT_SVA``),
                and the second [1] value represents the byte contents of the file.
      :rtype: Tuple[KinematicsFileFormat.ValueType, bytes]

      For more information, see `Gripper component <https://docs.viam.com/dev/reference/apis/components/gripper/#getkinematics>`_.



   .. py:method:: from_robot(robot: viam.robot.client.RobotClient, name: str) -> typing_extensions.Self
      :classmethod:


      Get the component named ``name`` from the provided robot.

      :param robot: The robot
      :type robot: RobotClient
      :param name: The name of the component
      :type name: str

      :returns: The component, if it exists on the robot
      :rtype: Self



   .. py:method:: do_command(command: Mapping[str, ValueTypes], *, timeout: Optional[float] = None, **kwargs) -> Mapping[str, ValueTypes]
      :abstractmethod:

      :async:


      Send/Receive arbitrary commands to the Resource

      ::

          command = {"cmd": "test", "data1": 500}
          result = await component.do_command(command)

      :param command: The command to execute
      :type command: Mapping[str, ValueTypes]

      :raises NotImplementedError: Raised if the Resource does not support arbitrary commands

      :returns: Result of the executed command
      :rtype: Mapping[str, ValueTypes]



   .. py:method:: get_geometries(*, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None) -> List[viam.proto.common.Geometry]
      :async:


      Get all geometries associated with the component, in their current configuration, in the
      `frame <https://docs.viam.com/operate/mobility/define-geometry/>`__ of the component.

      ::

          geometries = await component.get_geometries()

          if geometries:
              # Get the center of the first geometry
              print(f"Pose of the first geometry's centerpoint: {geometries[0].center}")

      :returns: The geometries associated with the Component.
      :rtype: List[Geometry]



   .. py:method:: get_resource_name(name: str) -> viam.proto.common.ResourceName
      :classmethod:


      Get the ResourceName for this Resource with the given name

      ::

          # Can be used with any resource, using an arm as an example
          my_arm_name = Arm.get_resource_name("my_arm")

      :param name: The name of the Resource
      :type name: str

      :returns: The ResourceName of this Resource
      :rtype: ResourceName



   .. py:method:: get_operation(kwargs: Mapping[str, Any]) -> viam.operations.Operation

      Get the ``Operation`` associated with the currently running function.

      When writing custom resources, you should get the ``Operation`` by calling this function and check to see if it's cancelled.
      If the ``Operation`` is cancelled, then you can perform any necessary (terminating long running tasks, cleaning up connections, etc.
      ).

      :param kwargs: The kwargs object containing the operation
      :type kwargs: Mapping[str, Any]

      :returns: The operation associated with this function
      :rtype: viam.operations.Operation



   .. py:method:: close()
      :async:


      Safely shut down the resource and prevent further use.

      Close must be idempotent. Later configuration may allow a resource to be "open" again.
      If a resource does not want or need a close function, it is assumed that the resource does not need to return errors when future
      non-Close methods are called.

      ::

          await component.close()