viam-sdk 0.45.2__py3-none-win_amd64.whl

viam/components/board/board.py

@@ -0,0 +1,414 @@
+import abc
+import sys
+from datetime import timedelta
+from typing import Any, Dict, Final, List, Optional
+
+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
+
+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/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/>`_.
+    """
+
+    API: Final = API(  # pyright: ignore [reportIncompatibleVariableOverride]
+        RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, "board"
+    )
+
+    class Analog:
+        """
+        Analog represents an analog pin reader or writer that resides on a Board.
+        """
+
+        name: str
+        """The name of the analog pin"""
+
+        Value: "TypeAlias" = 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>`_.
+        """
+
+        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) -> 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:
+                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>`_.
+            """
+            ...
+
+        @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.
+
+            ::
+
+                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:
+                int: The current value.
+
+            For more information, see
+            `Board component DigitalInterrupt API <https://docs.viam.com/dev/reference/apis/components/board/#digitalinterrupt-api>`_.
+            """
+            ...
+
+    class GPIOPin:
+        """
+        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>`_.
+            """
+            ...
+
+        @abc.abstractmethod
+        async def get(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> bool:
+            """
+            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>`_.
+            """
+            ...
+
+        @abc.abstractmethod
+        async def get_pwm(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> float:
+            """
+            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>`_.
+            """
+            ...
+
+        @abc.abstractmethod
+        async def set_pwm(self, duty_cycle: float, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs):
+            """
+            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>`_.
+            """
+            ...
+
+        @abc.abstractmethod
+        async def get_pwm_frequency(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> int:
+            """
+            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>`_.
+            """
+            ...
+
+        @abc.abstractmethod
+        async def set_pwm_frequency(
+            self,
+            frequency: int,
+            *,
+            extra: Optional[Dict[str, Any]] = None,
+            timeout: Optional[float] = None,
+            **kwargs,
+        ):
+            """
+            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_by_name(self, name: str) -> Analog:
+        """
+        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:
+            Analog: The analog reader or writer.
+
+        For more information, see `Board component <https://docs.viam.com/dev/reference/apis/components/board/#analogbyname>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def digital_interrupt_by_name(self, name: str) -> DigitalInterrupt:
+        """
+        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.
+
+        For more information, see `Board component <https://docs.viam.com/dev/reference/apis/components/board/#digitalinterruptbyname>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def gpio_pin_by_name(self, name: str) -> GPIOPin:
+        """
+        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.
+
+        For more information, see `Board component <https://docs.viam.com/dev/reference/apis/components/board/#gpiopinbyname>`_.
+        """
+        ...
+
+    @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.
+
+        ::
+
+            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)
+
+        Args:
+            mode (PowerMode): The desired power mode.
+            duration (Optional[timedelta]): Requested duration to stay in power mode.
+
+        For more information, see `Board component <https://docs.viam.com/dev/reference/apis/components/board/#setpowermode>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def stream_ticks(self, interrupts: List[DigitalInterrupt], *, timeout: Optional[float] = None, **kwargs) -> TickStream:
+        """
+        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}")
+
+
+        Args:
+            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>`_.
+        """
+        ...

viam/components/board/client.py

@@ -0,0 +1,241 @@
+from datetime import timedelta
+from typing import Any, Dict, List, Mapping, Optional
+
+from google.protobuf.duration_pb2 import Duration
+from grpclib.client import Channel
+from grpclib.client import Stream as ClientStream
+
+from viam.proto.common import DoCommandRequest, DoCommandResponse, Geometry
+from viam.proto.component.board import (
+    BoardServiceStub,
+    GetDigitalInterruptValueRequest,
+    GetDigitalInterruptValueResponse,
+    GetGPIORequest,
+    GetGPIOResponse,
+    PowerMode,
+    PWMFrequencyRequest,
+    PWMFrequencyResponse,
+    PWMRequest,
+    PWMResponse,
+    ReadAnalogReaderRequest,
+    SetGPIORequest,
+    SetPowerModeRequest,
+    SetPWMFrequencyRequest,
+    SetPWMRequest,
+    StreamTicksRequest,
+    StreamTicksResponse,
+    WriteAnalogRequest,
+)
+from viam.resource.rpc_client_base import ReconfigurableResourceRPCClientBase, ResourceRPCClientBase
+from viam.streams import StreamWithIterator
+from viam.utils import ValueTypes, dict_to_struct, get_geometries, struct_to_dict
+
+from .board import Board, TickStream
+
+
+class AnalogClient(Board.Analog):
+    def __init__(self, name: str, board: "BoardClient"):
+        self.board = board
+        super().__init__(name)
+
+    async def read(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> Board.Analog.Value:
+        md = kwargs.get("metadata", ResourceRPCClientBase.Metadata()).proto
+        request = ReadAnalogReaderRequest(board_name=self.board.name, analog_reader_name=self.name, extra=dict_to_struct(extra))
+        return await self.board.client.ReadAnalogReader(request, timeout=timeout, metadata=md)
+
+    async def write(
+        self,
+        value: int,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        md = kwargs.get("metadata", ResourceRPCClientBase.Metadata()).proto
+        request = WriteAnalogRequest(name=self.board.name, pin=self.name, value=value, extra=dict_to_struct(extra))
+        await self.board.client.WriteAnalog(request, timeout=timeout, metadata=md)
+
+
+class DigitalInterruptClient(Board.DigitalInterrupt):
+    def __init__(self, name: str, board: "BoardClient"):
+        self.board = board
+        super().__init__(name)
+
+    async def value(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> int:
+        md = kwargs.get("metadata", ResourceRPCClientBase.Metadata()).proto
+        request = GetDigitalInterruptValueRequest(board_name=self.board.name, digital_interrupt_name=self.name, extra=dict_to_struct(extra))
+        response: GetDigitalInterruptValueResponse = await self.board.client.GetDigitalInterruptValue(request, timeout=timeout, metadata=md)
+        return response.value
+
+
+class GPIOPinClient(Board.GPIOPin):
+    def __init__(self, name: str, board: "BoardClient"):
+        self.board = board
+        super().__init__(name)
+
+    async def get(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> bool:
+        md = kwargs.get("metadata", ResourceRPCClientBase.Metadata()).proto
+        request = GetGPIORequest(name=self.board.name, pin=self.name, extra=dict_to_struct(extra))
+        response: GetGPIOResponse = await self.board.client.GetGPIO(request, timeout=timeout, metadata=md)
+        return response.high
+
+    async def set(
+        self,
+        high: bool,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        md = kwargs.get("metadata", ResourceRPCClientBase.Metadata()).proto
+        request = SetGPIORequest(name=self.board.name, pin=self.name, high=high, extra=dict_to_struct(extra))
+        await self.board.client.SetGPIO(request, timeout=timeout, metadata=md)
+
+    async def get_pwm(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> float:
+        md = kwargs.get("metadata", ResourceRPCClientBase.Metadata()).proto
+        request = PWMRequest(name=self.board.name, pin=self.name, extra=dict_to_struct(extra))
+        response: PWMResponse = await self.board.client.PWM(request, timeout=timeout, metadata=md)
+        return response.duty_cycle_pct
+
+    async def set_pwm(
+        self,
+        duty_cycle: float,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        md = kwargs.get("metadata", ResourceRPCClientBase.Metadata()).proto
+        request = SetPWMRequest(name=self.board.name, pin=self.name, duty_cycle_pct=duty_cycle, extra=dict_to_struct(extra))
+        await self.board.client.SetPWM(request, timeout=timeout, metadata=md)
+
+    async def get_pwm_frequency(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> int:
+        md = kwargs.get("metadata", ResourceRPCClientBase.Metadata()).proto
+        request = PWMFrequencyRequest(name=self.board.name, pin=self.name, extra=dict_to_struct(extra))
+        response: PWMFrequencyResponse = await self.board.client.PWMFrequency(request, timeout=timeout, metadata=md)
+        return response.frequency_hz
+
+    async def set_pwm_frequency(
+        self,
+        frequency: int,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        md = kwargs.get("metadata", ResourceRPCClientBase.Metadata()).proto
+        request = SetPWMFrequencyRequest(name=self.board.name, pin=self.name, frequency_hz=frequency, extra=dict_to_struct(extra))
+        await self.board.client.SetPWMFrequency(request, timeout=timeout, metadata=md)
+
+
+class BoardClient(Board, ReconfigurableResourceRPCClientBase):
+    """
+    gRPC client for the Board component.
+    """
+
+    _analog_names: List[str]
+    _digital_interrupt_names: List[str]
+
+    def __init__(self, name: str, channel: Channel):
+        self.channel = channel
+        self.client = BoardServiceStub(channel)
+        self._analog_names = []
+        self._digital_interrupt_names = []
+        super().__init__(name)
+
+    async def analog_by_name(self, name: str) -> Board.Analog:
+        self._analog_names.append(name)
+        return AnalogClient(name, self)
+
+    async def digital_interrupt_by_name(self, name: str) -> Board.DigitalInterrupt:
+        self._digital_interrupt_names.append(name)
+        return DigitalInterruptClient(name, self)
+
+    async def gpio_pin_by_name(self, name: str) -> Board.GPIOPin:
+        return GPIOPinClient(name, self)
+
+    async def do_command(
+        self,
+        command: Mapping[str, ValueTypes],
+        *,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> Mapping[str, ValueTypes]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = DoCommandRequest(name=self.name, command=dict_to_struct(command))
+        response: DoCommandResponse = await self.client.DoCommand(request, timeout=timeout, metadata=md)
+        return struct_to_dict(response.result)
+
+    async def set_power_mode(
+        self,
+        mode: PowerMode.ValueType,
+        duration: Optional[timedelta] = None,
+        *,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        md = kwargs.get("metadata", self.Metadata()).proto
+        duration_pb: Optional[Duration] = None
+        if duration is not None:
+            duration_pb = [(d, d.FromTimedelta(duration)) for d in [Duration()]][0][0]
+        request = SetPowerModeRequest(name=self.name, power_mode=mode, duration=duration_pb)
+        await self.client.SetPowerMode(request, timeout=timeout, metadata=md)
+
+    async def get_geometries(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> List[Geometry]:
+        md = kwargs.get("metadata", self.Metadata())
+        return await get_geometries(self.client, self.name, extra, timeout, md)
+
+    async def stream_ticks(
+        self,
+        interrupts: List[Board.DigitalInterrupt],
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ) -> TickStream:
+        names = []
+        for di in interrupts:
+            names.append(di.name)
+        request = StreamTicksRequest(name=self.name, pin_names=names, extra=dict_to_struct(extra))
+
+        async def read():
+            md = kwargs.get("metadata", self.Metadata()).proto
+            tick_stream: ClientStream[StreamTicksRequest, StreamTicksResponse]
+            async with self.client.StreamTicks.open(metadata=md) as tick_stream:
+                try:
+                    await tick_stream.send_message(request, end=True)
+                    async for tick in tick_stream:
+                        yield tick
+                except Exception as e:
+                    raise (e)
+
+        return StreamWithIterator(read())