viam-sdk 0.3.0__py3-none-linux_armv6l.whl → 0.66.0__py3-none-linux_armv6l.whl

viam/components/board/board.py

@@ -1,117 +1,180 @@
 import abc
-from dataclasses import dataclass
+import sys
 from datetime import timedelta
-from multiprocessing import Queue
-from typing import Any, Callable, Dict, Final, List, Optional
+from typing import Any, Dict, Final, List, Optional
 
-from viam.proto.common import BoardStatus
-from viam.proto.component.board import PowerMode
-from viam.resource.types import RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, Subtype
+from viam.proto.component.board import PowerMode, ReadAnalogReaderResponse, StreamTicksResponse
+from viam.resource.types import API, RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT
+from viam.streams import Stream
 
 from ..component_base import ComponentBase
 
-PostProcessor = Callable[[int], int]
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias
+else:
+    from typing_extensions import TypeAlias
+
+Tick = StreamTicksResponse
+TickStream = Stream[Tick]
 
 
 class Board(ComponentBase):
     """
     Board represents a physical general purpose compute board that contains various
-    components such as analog readers, and digital interrupts.
+    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/>`_.
     """
 
-    SUBTYPE: Final = Subtype(RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, "board")
+    API: Final = API(  # pyright: ignore [reportIncompatibleVariableOverride]
+        RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, "board"
+    )
 
-    @dataclass
-    class Attributes:
-        remote: bool
+    class Analog:
         """
-        Indicates whether this board is accessed over a remote connection, e.g. gRPC.
+        Analog represents an analog pin reader or writer that resides on a Board.
         """
 
-    class AnalogReader(ComponentBase):
+        name: str
+        """The name of the analog pin"""
+
+        Value: "TypeAlias" = ReadAnalogReaderResponse
         """
-        AnalogReader represents an analog pin reader that resides on a Board.
+        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>`_.
         """
 
+        def __init__(self, name: str):
+            self.name = name
+
         @abc.abstractmethod
-        async def read(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> int:
+        async def read(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> Value:
             """
-            Read the current value.
+            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:
-                int: The current value.
+                Value: The current value, including the min, max, and step_size of the reader.
+
+            For more information, see `Board component Analog API <https://docs.viam.com/dev/reference/apis/components/board/#analog-api>`_.
             """
             ...
 
-    class DigitalInterrupt(ComponentBase):
+        @abc.abstractmethod
+        async def write(self, value: int, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs):
+            """
+            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)
+
+            Args:
+                value (int): Value to write to the analog writer.
+
+            For more information, see `Board component Analog API <https://docs.viam.com/dev/reference/apis/components/board/#analog-api>`_.
+            """
+            ...
+
+    class 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 <https://docs.viam.com/dev/reference/apis/components/board/#digital_interrupts>`_.
         """
 
+        name: str
+        """The name of the digital interrupt."""
+
+        def __init__(self, name: str):
+            self.name = name
+
         @abc.abstractmethod
         async def value(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> int:
             """
             Get the current value of the interrupt,
             which is based on the type of interrupt.
 
-            Returns:
-                int: The current value.
-            """
-            ...
+            ::
 
-        @abc.abstractmethod
-        async def tick(self, high: bool, nanos: int):
-            """
-            This method is to be called either manually if the interrupt
-            is a proxy to some real hardware interrupt or for tests.
+                my_board = Board.from_robot(robot=machine, name="my_board")
 
-            Args:
-                high (bool): If the signal of the interrupt is high.
-                nanos (int): Nanoseconds from an arbitrary point in time,
-                    but always increasing and always needs to be accurate.
-                    Using ``time.time_ns()`` would be acceptable.
-            """
-            ...
+                # Get the DigitalInterrupt "my_example_digital_interrupt".
+                interrupt = await my_board.digital_interrupt_by_name(
+                    name="my_example_digital_interrupt")
 
-        @abc.abstractmethod
-        async def add_callback(self, queue: Queue):
-            """
-            Add a callback to be sent the low/high value on ``tick()``.
+                # Get the amount of times this DigitalInterrupt has been interrupted with a
+                # tick.
+                count = await interrupt.value()
 
-            Args:
-                queue (Queue): The receiving queue.
-            """
-            ...
-
-        @abc.abstractmethod
-        async def add_post_processor(self, processor: PostProcessor):
-            """
-            Add a post processor that should be used to modify what
-            is returned by ``self.value()``
+            Returns:
+                int: The current value.
 
-            Args:
-                processor (PostProcessor): The post processor to add.
+            For more information, see
+            `Board component DigitalInterrupt API <https://docs.viam.com/dev/reference/apis/components/board/#digitalinterrupt-api>`_.
             """
             ...
 
-    class GPIOPin(ComponentBase):
+    class GPIOPin:
         """
-        Abstract representation of an individual GPIO pin on a board
+        Abstract representation of an individual GPIO pin on a board.
         """
 
+        name: str
+        """The name of the GPIO pin."""
+
+        def __init__(self, name: str):
+            self.name = name
+
         @abc.abstractmethod
         async def set(self, high: bool, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs):
             """
             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)
+
             Args:
                 high (bool): When true, sets the pin to high. When false, sets the pin to low.
+
+            For more information, see `GPIOPin API <https://docs.viam.com/dev/reference/apis/components/board/#gpiopin-api>`_.
             """
             ...
 
@@ -120,8 +183,20 @@ class Board(ComponentBase):
             """
             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:
                 bool: Indicates if the state of the pin is high.
+
+            For more information, see `GPIOPin API <https://docs.viam.com/dev/reference/apis/components/board/#gpiopin-api>`_.
             """
             ...
 
@@ -130,8 +205,20 @@ class Board(ComponentBase):
             """
             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:
                 float: The duty cycle.
+
+            For more information, see `GPIOPin API <https://docs.viam.com/dev/reference/apis/components/board/#gpiopin-api>`_.
             """
             ...
 
@@ -140,8 +227,21 @@ class Board(ComponentBase):
             """
             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)
+
             Args:
                 duty_cycle (float): The duty cycle.
+
+            For more information, see `GPIOPin API <https://docs.viam.com/dev/reference/apis/components/board/#gpiopin-api>`_.
             """
             ...
 
@@ -150,8 +250,20 @@ class Board(ComponentBase):
             """
             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:
                 int: The PWM frequency.
+
+            For more information, see `GPIOPin API <https://docs.viam.com/dev/reference/apis/components/board/#gpiopin-api>`_.
             """
             ...
 
@@ -168,21 +280,42 @@ class Board(ComponentBase):
             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)
+
             Args:
                 frequency (int): The frequency, in Hz.
+
+            For more information, see `GPIOPin API <https://docs.viam.com/dev/reference/apis/components/board/#gpiopin-api>`_.
             """
             ...
 
     @abc.abstractmethod
-    async def analog_reader_by_name(self, name: str) -> AnalogReader:
+    async def analog_by_name(self, name: str) -> Analog:
         """
-        Get an AnalogReader by ``name``.
+        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")
 
         Args:
             name (str): Name of the analog reader to be retrieved.
 
         Returns:
-            AnalogReader: The analog reader.
+            Analog: The analog reader or writer.
+
+        For more information, see `Board component <https://docs.viam.com/dev/reference/apis/components/board/#analogbyname>`_.
         """
         ...
 
@@ -191,11 +324,21 @@ class Board(ComponentBase):
         """
         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")
+
         Args:
             name (str): Name of the digital interrupt.
 
         Returns:
-            DigitalInterrupt: the digital interrupt.
+            DigitalInterrupt: The digital interrupt.
+
+        For more information, see `Board component <https://docs.viam.com/dev/reference/apis/components/board/#digitalinterruptbyname>`_.
         """
         ...
 
@@ -204,61 +347,74 @@ class Board(ComponentBase):
         """
         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")
+
         Args:
             name (str): Name of the GPIO pin.
 
         Returns:
-            GPIOPin: the pin.
+            GPIOPin: The pin.
+
+        For more information, see `Board component <https://docs.viam.com/dev/reference/apis/components/board/#gpiopinbyname>`_.
         """
         ...
 
     @abc.abstractmethod
-    async def analog_reader_names(self) -> List[str]:
+    async def set_power_mode(
+        self,
+        mode: PowerMode.ValueType,
+        duration: Optional[timedelta] = None,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
         """
-        Get the names of all known analog readers.
+        Set the board to the indicated power mode.
 
-        Returns:
-            List[str]: The names of the analog readers..
-        """
-        ...
+        ::
 
-    @abc.abstractmethod
-    async def digital_interrupt_names(self) -> List[str]:
-        """
-        Get the names of all known digital interrupts.
+            my_board = Board.from_robot(robot=machine, name="my_board")
 
-        Returns:
-            List[str]: The names of the digital interrupts.
-        """
-        ...
+            # Set the power mode of the board to OFFLINE_DEEP.
+            status = await my_board.set_power_mode(mode=PowerMode.POWER_MODE_OFFLINE_DEEP)
 
-    @abc.abstractmethod
-    async def status(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> BoardStatus:
-        """
-        Return the current status of the board.
+        Args:
+            mode (PowerMode): The desired power mode.
+            duration (Optional[timedelta]): Requested duration to stay in power mode.
 
-        Returns:
-            viam.proto.common.BoardStatus: the status.
+        For more information, see `Board component <https://docs.viam.com/dev/reference/apis/components/board/#setpowermode>`_.
         """
         ...
 
     @abc.abstractmethod
-    async def model_attributes(self) -> Attributes:
+    async def stream_ticks(self, interrupts: List[DigitalInterrupt], *, timeout: Optional[float] = None, **kwargs) -> TickStream:
         """
-        Get the attributes related to the model of this board.
+        Stream digital interrupt ticks.
 
-        Returns:
-            Attributes: The attributes.
-        """
-        ...
+        ::
+
+
+            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}")
 
-    @abc.abstractmethod
-    async def set_power_mode(
-        self, mode: PowerMode.ValueType, duration: Optional[timedelta] = None, *, timeout: Optional[float] = None, **kwargs
-    ):
-        """
-        Set the board to the indicated power mode.
 
         Args:
-            mode: the desired power mode
+            interrupts (List[DigitalInterrupt]) : list of digital interrupts to receive ticks from.
+
+        Returns:
+            TickStream: stream of ticks.
+
+        For more information, see `Board component <https://docs.viam.com/dev/reference/apis/components/board/#streamticks>`_.
         """
+        ...