viam.components.board
=====================

.. py:module:: viam.components.board


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/viam/components/board/board/index
   /autoapi/viam/components/board/client/index
   /autoapi/viam/components/board/service/index


Attributes
----------

.. autoapisummary::

   viam.components.board.Tick
   viam.components.board.TickStream


Classes
-------

.. autoapisummary::

   viam.components.board.Board


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

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

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


   Board represents a physical general purpose compute board that contains various
   components such as analog readers/writers, and digital interrupts.

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

   ::

       from viam.components.board import Board

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


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

      The API of the Resource


   .. py:class:: Analog(name: str)

      Analog represents an analog pin reader or writer that resides on a Board.


      .. py:attribute:: name
         :type:  str

         The name of the analog pin


      .. py:attribute:: Value
         :type:  TypeAlias
         :value: ReadAnalogReaderResponse


         Value contains the result of reading an analog reader. It contains the raw data read,
         the reader's minimum and maximum possible values, and its step size (the minimum possible
         change between values it can read).

         For more information, see `analogs <https://docs.viam.com/dev/reference/apis/components/board/#analogs>`_.


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

         :async:


         Read the current value from the reader.

         ::

             my_board = Board.from_robot(robot=machine, name="my_board")

             # Get the Analog "my_example_analog_reader".
             reader = await my_board.analog_by_name(
                 name="my_example_analog_reader")

             # Get the value of the digital signal "my_example_analog_reader" has most
             # recently measured.
             reading = await reader.read()

         :returns: The current value, including the min, max, and step_size of the reader.
         :rtype: Value

         For more information, see `Board component Analog API <https://docs.viam.com/dev/reference/apis/components/board/#analog-api>`_.



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

         :async:


         Write a value to the Analog writer.

         ::

             my_board = Board.from_robot(robot=machine, name="my_board")

             # Get the Analog "my_example_analog_writer".
             writer = await my_board.analog_by_name(
                 name="my_example_analog_writer")

             await writer.write(42)

         :param value: Value to write to the analog writer.
         :type value: int

         For more information, see `Board component Analog API <https://docs.viam.com/dev/reference/apis/components/board/#analog-api>`_.




   .. py:class:: DigitalInterrupt(name: str)

      DigitalInterrupt represents a configured interrupt on the Board that
      when interrupted, calls the added callbacks. Post processors can
      be added to modify what Value it ultimately returns.

      For more information, see `digital_interrupts <https://docs.viam.com/dev/reference/apis/components/board/#digital_interrupts>`_.


      .. py:attribute:: name
         :type:  str

         The name of the digital interrupt.


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

         :async:


         Get the current value of the interrupt,
         which is based on the type of interrupt.

         ::

             my_board = Board.from_robot(robot=machine, name="my_board")

             # Get the DigitalInterrupt "my_example_digital_interrupt".
             interrupt = await my_board.digital_interrupt_by_name(
                 name="my_example_digital_interrupt")

             # Get the amount of times this DigitalInterrupt has been interrupted with a
             # tick.
             count = await interrupt.value()

         :returns: The current value.
         :rtype: int

         For more information, see
         `Board component DigitalInterrupt API <https://docs.viam.com/dev/reference/apis/components/board/#digitalinterrupt-api>`_.




   .. py:class:: GPIOPin(name: str)

      Abstract representation of an individual GPIO pin on a board.


      .. py:attribute:: name
         :type:  str

         The name of the GPIO pin.


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

         :async:


         Set the pin to either low or high.

         ::

             my_board = Board.from_robot(robot=machine, name="my_board")

             # Get the GPIOPin with pin number 15.
             pin = await my_board.gpio_pin_by_name(name="15")

             # Set the pin to high.
             await pin.set(high=True)

         :param high: When true, sets the pin to high. When false, sets the pin to low.
         :type high: bool

         For more information, see `GPIOPin API <https://docs.viam.com/dev/reference/apis/components/board/#gpiopin-api>`_.



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

         :async:


         Get the high/low state of the pin.

         ::

             my_board = Board.from_robot(robot=machine, name="my_board")

             # Get the GPIOPin with pin number 15.
             pin = await my_board.gpio_pin_by_name(name="15")

             # Get if it is true or false that the state of the pin is high.
             high = await pin.get()

         :returns: Indicates if the state of the pin is high.
         :rtype: bool

         For more information, see `GPIOPin API <https://docs.viam.com/dev/reference/apis/components/board/#gpiopin-api>`_.



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

         :async:


         Get the pin's given duty cycle.

         ::

             my_board = Board.from_robot(robot=machine, name="my_board")

             # Get the GPIOPin with pin number 15.
             pin = await my_board.gpio_pin_by_name(name="15")

             # Get if it is true or false that the state of the pin is high.
             duty_cycle = await pin.get_pwm()

         :returns: The duty cycle.
         :rtype: float

         For more information, see `GPIOPin API <https://docs.viam.com/dev/reference/apis/components/board/#gpiopin-api>`_.



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

         :async:


         Set the pin to the given ``duty_cycle``.

         ::

             my_board = Board.from_robot(robot=machine, name="my_board")

             # Get the GPIOPin with pin number 15.
             pin = await my_board.gpio_pin_by_name(name="15")

             # Set the duty cycle to .6, meaning that this pin will be in the high state for
             # 60% of the duration of the PWM interval period.
             await pin.set_pwm(duty_cycle=.6)

         :param duty_cycle: The duty cycle.
         :type duty_cycle: float

         For more information, see `GPIOPin API <https://docs.viam.com/dev/reference/apis/components/board/#gpiopin-api>`_.



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

         :async:


         Get the PWM frequency of the pin.

         ::

             my_board = Board.from_robot(robot=machine, name="my_board")

             # Get the GPIOPin with pin number 15.
             pin = await my_board.gpio_pin_by_name(name="15")

             # Get the PWM frequency of this pin.
             freq = await pin.get_pwm_frequency()

         :returns: The PWM frequency.
         :rtype: int

         For more information, see `GPIOPin API <https://docs.viam.com/dev/reference/apis/components/board/#gpiopin-api>`_.



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

         :async:


         Set the pin to the given PWM ``frequency`` (in Hz).
         When ``frequency`` is 0, it will use the board's default PWM frequency.

         ::

             my_board = Board.from_robot(robot=machine, name="my_board")

             # Get the GPIOPin with pin number 15.
             pin = await my_board.gpio_pin_by_name(name="15")

             # Set the PWM frequency of this pin to 1600 Hz.
             high = await pin.set_pwm_frequency(frequency=1600)

         :param frequency: The frequency, in Hz.
         :type frequency: int

         For more information, see `GPIOPin API <https://docs.viam.com/dev/reference/apis/components/board/#gpiopin-api>`_.




   .. py:method:: analog_by_name(name: str) -> Analog
      :abstractmethod:

      :async:


      Get an Analog (reader or writer) by ``name``.

      ::

          my_board = Board.from_robot(robot=machine, name="my_board")

          # Get the Analog "my_example_analog_reader".
          reader = await my_board.analog_by_name(name="my_example_analog_reader")

      :param name: Name of the analog reader to be retrieved.
      :type name: str

      :returns: The analog reader or writer.
      :rtype: Analog

      For more information, see `Board component <https://docs.viam.com/dev/reference/apis/components/board/#analogbyname>`_.



   .. py:method:: digital_interrupt_by_name(name: str) -> DigitalInterrupt
      :abstractmethod:

      :async:


      Get a DigitalInterrupt by ``name``.

      ::

          my_board = Board.from_robot(robot=machine, name="my_board")

          # Get the DigitalInterrupt "my_example_digital_interrupt".
          interrupt = await my_board.digital_interrupt_by_name(
              name="my_example_digital_interrupt")

      :param name: Name of the digital interrupt.
      :type name: str

      :returns: The digital interrupt.
      :rtype: DigitalInterrupt

      For more information, see `Board component <https://docs.viam.com/dev/reference/apis/components/board/#digitalinterruptbyname>`_.



   .. py:method:: gpio_pin_by_name(name: str) -> GPIOPin
      :abstractmethod:

      :async:


      Get a GPIO Pin by ``name``.

      ::

          my_board = Board.from_robot(robot=machine, name="my_board")

          # Get the GPIOPin with pin number 15.
          pin = await my_board.gpio_pin_by_name(name="15")

      :param name: Name of the GPIO pin.
      :type name: str

      :returns: The pin.
      :rtype: GPIOPin

      For more information, see `Board component <https://docs.viam.com/dev/reference/apis/components/board/#gpiopinbyname>`_.



   .. py:method:: set_power_mode(mode: viam.proto.component.board.PowerMode.ValueType, duration: Optional[datetime.timedelta] = None, *, timeout: Optional[float] = None, **kwargs)
      :abstractmethod:

      :async:


      Set the board to the indicated power mode.

      ::

          my_board = Board.from_robot(robot=machine, name="my_board")

          # Set the power mode of the board to OFFLINE_DEEP.
          status = await my_board.set_power_mode(mode=PowerMode.POWER_MODE_OFFLINE_DEEP)

      :param mode: The desired power mode.
      :type mode: PowerMode
      :param duration: Requested duration to stay in power mode.
      :type duration: Optional[timedelta]

      For more information, see `Board component <https://docs.viam.com/dev/reference/apis/components/board/#setpowermode>`_.



   .. py:method:: stream_ticks(interrupts: List[DigitalInterrupt], *, timeout: Optional[float] = None, **kwargs) -> TickStream
      :abstractmethod:

      :async:


      Stream digital interrupt ticks.

      ::


          my_board = Board.from_robot(robot=machine, name="my_board")
          di8 = await my_board.digital_interrupt_by_name(name="8")
          di11 = await my_board.digital_interrupt_by_name(name="11")

          # Iterate over stream of ticks from pins 8 and 11.
          async for tick in await my_board.stream_ticks([di8, di11]):
              print(f"Pin {tick.pin_name} changed to {'high' if tick.high else 'low'} at {tick.time}")


      :param interrupts: list of digital interrupts to receive ticks from.
      :type interrupts: List[DigitalInterrupt]

      :returns: stream of ticks.
      :rtype: TickStream

      For more information, see `Board component <https://docs.viam.com/dev/reference/apis/components/board/#streamticks>`_.



   .. 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()




.. py:data:: Tick

.. py:data:: TickStream