viam.components.board.client ============================ .. py:module:: viam.components.board.client Classes ------- .. autoapisummary:: viam.components.board.client.AnalogClient viam.components.board.client.DigitalInterruptClient viam.components.board.client.GPIOPinClient viam.components.board.client.BoardClient Module Contents --------------- .. py:class:: AnalogClient(name: str, board: BoardClient) Bases: :py:obj:`viam.components.board.board.Board.Analog` Analog represents an analog pin reader or writer that resides on a Board. .. py:attribute:: board .. py:method:: read(*, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> viam.components.board.board.Board.Analog.Value :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 `_. .. py:method:: write(value: int, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) :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 `_. .. py:class:: DigitalInterruptClient(name: str, board: BoardClient) Bases: :py:obj:`viam.components.board.board.Board.DigitalInterrupt` 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 `_. .. py:attribute:: board .. py:method:: value(*, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> int :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 `_. .. py:class:: GPIOPinClient(name: str, board: BoardClient) Bases: :py:obj:`viam.components.board.board.Board.GPIOPin` Abstract representation of an individual GPIO pin on a board. .. py:attribute:: board .. py:method:: get(*, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> bool :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 `_. .. py:method:: set(high: bool, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) :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 `_. .. py:method:: get_pwm(*, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> float :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 `_. .. py:method:: set_pwm(duty_cycle: float, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) :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 `_. .. py:method:: get_pwm_frequency(*, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> int :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 `_. .. py:method:: set_pwm_frequency(frequency: int, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) :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 `_. .. py:class:: BoardClient(name: str, channel: grpclib.client.Channel) Bases: :py:obj:`viam.components.board.board.Board`, :py:obj:`viam.resource.rpc_client_base.ReconfigurableResourceRPCClientBase` gRPC client for the Board component. .. py:attribute:: channel .. py:attribute:: client .. py:method:: analog_by_name(name: str) -> viam.components.board.board.Board.Analog :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 `_. .. py:method:: digital_interrupt_by_name(name: str) -> viam.components.board.board.Board.DigitalInterrupt :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 `_. .. py:method:: gpio_pin_by_name(name: str) -> viam.components.board.board.Board.GPIOPin :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 `_. .. py:method:: do_command(command: Mapping[str, viam.utils.ValueTypes], *, timeout: Optional[float] = None, **kwargs) -> Mapping[str, viam.utils.ValueTypes] :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:: set_power_mode(mode: viam.proto.component.board.PowerMode.ValueType, duration: Optional[datetime.timedelta] = None, *, timeout: Optional[float] = None, **kwargs) :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 `_. .. py:method:: get_geometries(*, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> List[viam.proto.common.Geometry] :async: Get all geometries associated with the component, in their current configuration, in the `frame `__ 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:: stream_ticks(interrupts: List[viam.components.board.board.Board.DigitalInterrupt], *, extra: Optional[Dict[str, Any]] = None, **kwargs) -> viam.components.board.board.TickStream :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 `_. .. 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:: 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()