viam-sdk 0.45.2__py3-none-win_amd64.whl

viam/components/gripper/service.py

@@ -0,0 +1,81 @@
+from grpclib.server import Stream
+
+from viam.proto.common import DoCommandRequest, DoCommandResponse, GetGeometriesRequest, GetGeometriesResponse
+from viam.proto.component.gripper import (
+    GrabRequest,
+    GrabResponse,
+    GripperServiceBase,
+    IsMovingRequest,
+    IsMovingResponse,
+    OpenRequest,
+    OpenResponse,
+    StopRequest,
+    StopResponse,
+)
+from viam.resource.rpc_service_base import ResourceRPCServiceBase
+from viam.utils import dict_to_struct, struct_to_dict
+
+from .gripper import Gripper
+
+
+class GripperRPCService(GripperServiceBase, ResourceRPCServiceBase[Gripper]):
+    """
+    gRPC Service for a Gripper
+    """
+
+    RESOURCE_TYPE = Gripper
+
+    async def Open(self, stream: Stream[OpenRequest, OpenResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        gripper = self.get_resource(name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        await gripper.open(extra=struct_to_dict(request.extra), timeout=timeout, metadata=stream.metadata)
+        response = OpenResponse()
+        await stream.send_message(response)
+
+    async def Grab(self, stream: Stream[GrabRequest, GrabResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        gripper = self.get_resource(name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        grabbed = await gripper.grab(extra=struct_to_dict(request.extra), timeout=timeout, metadata=stream.metadata)
+        response = GrabResponse(success=grabbed)
+        await stream.send_message(response)
+
+    async def Stop(self, stream: Stream[StopRequest, StopResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        gripper = self.get_resource(request.name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        await gripper.stop(extra=struct_to_dict(request.extra), timeout=timeout, metadata=stream.metadata)
+        await stream.send_message(StopResponse())
+
+    async def IsMoving(self, stream: Stream[IsMovingRequest, IsMovingResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        gripper = self.get_resource(name)
+        is_moving = await gripper.is_moving()
+        response = IsMovingResponse(is_moving=is_moving)
+        await stream.send_message(response)
+
+    async def DoCommand(self, stream: Stream[DoCommandRequest, DoCommandResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        gripper = self.get_resource(request.name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        result = await gripper.do_command(command=struct_to_dict(request.command), timeout=timeout, metadata=stream.metadata)
+        response = DoCommandResponse(result=dict_to_struct(result))
+        await stream.send_message(response)
+
+    async def GetGeometries(self, stream: Stream[GetGeometriesRequest, GetGeometriesResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        arm = self.get_resource(request.name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        geometries = await arm.get_geometries(extra=struct_to_dict(request.extra), timeout=timeout)
+        response = GetGeometriesResponse(geometries=geometries)
+        await stream.send_message(response)

viam/components/input/__init__.py

@@ -0,0 +1,15 @@
+from viam.resource.registry import Registry, ResourceRegistration
+
+from .client import ControllerClient
+from .input import Control, ControlFunction, Controller, Event, EventType
+from .service import InputControllerRPCService
+
+__all__ = [
+    "Controller",
+    "Control",
+    "ControlFunction",
+    "Event",
+    "EventType",
+]
+
+Registry.register_api(ResourceRegistration(Controller, InputControllerRPCService, lambda name, channel: ControllerClient(name, channel)))

viam/components/input/client.py

@@ -0,0 +1,194 @@
+import asyncio
+from threading import Lock, RLock
+from time import time
+from typing import Any, Dict, List, Mapping, Optional
+
+from google.protobuf.struct_pb2 import Struct
+from grpclib import GRPCError, Status
+from grpclib.client import Channel
+
+import viam
+from viam.errors import NotSupportedError
+from viam.logging import getLogger
+from viam.proto.common import DoCommandRequest, DoCommandResponse, Geometry
+from viam.proto.component.inputcontroller import (
+    GetControlsRequest,
+    GetControlsResponse,
+    GetEventsRequest,
+    GetEventsResponse,
+    InputControllerServiceStub,
+    StreamEventsRequest,
+    StreamEventsResponse,
+    TriggerEventRequest,
+)
+from viam.resource.rpc_client_base import ReconfigurableResourceRPCClientBase, ResourceRPCClientBase
+from viam.utils import ValueTypes, dict_to_struct, get_geometries, struct_to_dict
+
+from .input import Control, ControlFunction, Controller, Event, EventType
+
+LOGGER = getLogger(__name__)
+
+
+class ControllerClient(Controller, ReconfigurableResourceRPCClientBase):
+    """gRPC client for an Input Controller"""
+
+    def __init__(self, name: str, channel: Channel):
+        self.channel = channel
+        self.client = InputControllerServiceStub(channel)
+        self.callbacks: Dict[Control, Dict[EventType, Optional[ControlFunction]]] = {}
+        self._lock = RLock()
+        self._stream_lock = Lock()
+        self._is_streaming = False
+        self._is_stream_ready = False
+        self._callback_extra: Struct = dict_to_struct({})
+        super().__init__(name)
+
+    async def get_controls(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> List[Control]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = GetControlsRequest(controller=self.name, extra=dict_to_struct(extra))
+        response: GetControlsResponse = await self.client.GetControls(request, timeout=timeout, metadata=md)
+        return [Control(control) for control in response.controls]
+
+    async def get_events(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> Dict[Control, Event]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = GetEventsRequest(controller=self.name, extra=dict_to_struct(extra))
+        response: GetEventsResponse = await self.client.GetEvents(request, timeout=timeout, metadata=md)
+        return {Control(event.control): Event.from_proto(event) for (event) in response.events}
+
+    def register_control_callback(
+        self,
+        control: Control,
+        triggers: List[EventType],
+        function: Optional[ControlFunction],
+        extra: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ):
+        md = kwargs.get("metadata", self.Metadata())
+        self._callback_extra = dict_to_struct(extra)
+        with self._lock:
+            callbacks = self.callbacks.get(control, {})
+            for trigger in triggers:
+                if trigger == EventType.BUTTON_CHANGE:
+                    callbacks[EventType.BUTTON_PRESS] = function
+                    callbacks[EventType.BUTTON_RELEASE] = function
+                else:
+                    callbacks[trigger] = function
+            self.callbacks[control] = callbacks
+
+        def handle_task_result(task: asyncio.Task):
+            try:
+                result = task.result()
+                LOGGER.debug(f"Task {task.get_name()} returned with result {result}")
+            except asyncio.CancelledError:
+                pass
+            except Exception:
+                LOGGER.exception("Exception raised by task = %r", task)
+
+        task = asyncio.create_task(self._stream_events(md), name=f"{viam._TASK_PREFIX}-input_stream_events")
+        task.add_done_callback(handle_task_result)
+
+    def reset_channel(self, channel: Channel):
+        super().reset_channel(channel)
+        with self._lock:
+            for control, callback in self.callbacks.items():
+                for event_type, func in callback.items():
+                    self.register_control_callback(control, [event_type], func)
+
+    async def trigger_event(
+        self,
+        event: Event,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = TriggerEventRequest(controller=self.name, event=event.proto, extra=dict_to_struct(extra))
+        try:
+            await self.client.TriggerEvent(request, timeout=timeout, metadata=md)
+        except GRPCError as e:
+            if e.status == Status.UNIMPLEMENTED and ("does not support triggering events" in e.message if e.message else False):
+                raise NotSupportedError(f"Input controller named {self.name} does not support triggering events")
+            raise e
+
+    async def _stream_events(self, metadata: ResourceRPCClientBase.Metadata):
+        with self._stream_lock:
+            if self._is_streaming:
+                return
+            self._is_streaming = True
+
+        if not self.callbacks:
+            return
+
+        md = metadata.proto
+        request = StreamEventsRequest(controller=self.name, events=[], extra=self._callback_extra)
+        with self._lock:
+            for control, callbacks in self.callbacks.items():
+                event = StreamEventsRequest.Events(
+                    control=control,
+                    events=[et for (et, func) in callbacks.items() if func is not None],
+                    cancelled_events=[et for (et, func) in callbacks.items() if func is None],
+                )
+                request.events.append(event)
+
+        try:
+            async with self.client.StreamEvents.open(metadata=md) as stream:
+                await stream.send_message(request, end=True)
+                self._send_connection_status(True)
+                reply: StreamEventsResponse
+                async for reply in stream:
+                    event = reply.event
+                    self._execute_callback(Event.from_proto(event))
+        except Exception as e:
+            LOGGER.error(e)
+        finally:
+            self._send_connection_status(False)
+            with self._stream_lock:
+                self._is_streaming = False
+                self._is_stream_ready = False
+
+    def _send_connection_status(self, connected: bool):
+        for control in self.callbacks.keys():
+            event = Event(time=time(), event=EventType.CONNECT if connected else EventType.DISCONNECT, control=control, value=0)
+            self._execute_callback(event)
+
+    def _execute_callback(self, event: Event):
+        try:
+            callbacks = self.callbacks[event.control]
+            callback = callbacks.get(event.event, None)
+            all_callback = callbacks.get(EventType.ALL_EVENTS, None)
+        except KeyError:
+            return
+
+        if callback is not None:
+            callback(event)
+        if all_callback is not None:
+            all_callback(event)
+
+    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 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)

viam/components/input/input.py

@@ -0,0 +1,297 @@
+import abc
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any, Callable, Dict, Final, List, Optional
+
+from google.protobuf.timestamp_pb2 import Timestamp
+from typing_extensions import Self
+
+from viam.components.component_base import ComponentBase
+from viam.errors import NotSupportedError
+from viam.proto.component.inputcontroller import Event as PBEvent
+from viam.resource.types import API, RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT
+
+
+class EventType(str, Enum):
+    """
+    Represents the type of input event.
+    """
+
+    ALL_EVENTS = "AllEvents"
+    """
+    Callbacks registered for this event will be called in ADDITION to other registered event callbacks.
+    """
+
+    CONNECT = "Connect"
+    """
+    Sent at controller initialization, and on reconnects.
+    """
+
+    DISCONNECT = "Disconnect"
+    """
+    If unplugged, or wireless/network times out.
+    """
+
+    BUTTON_PRESS = "ButtonPress"
+    """
+    Typical key press.
+    """
+
+    BUTTON_RELEASE = "ButtonRelease"
+    """
+    Key release.
+    """
+
+    BUTTON_HOLD = "ButtonHold"
+    """
+    Key is held down. This wil likely be a repeated event.
+    """
+
+    BUTTON_CHANGE = "ButtonChange"
+    """
+    Both up and down for convenience during registration, not typically emitted.
+    """
+
+    POSITION_CHANGE_ABSOLUTE = "PositionChangeAbs"
+    """
+    Absolute position is reported via Value, a la joysticks.
+    """
+
+    POSITION_CHANGE_RELATIVE = "PositionChangeRel"
+    """
+    Relative position is reported via Value, a la mice, or simulating axes with up/down buttons.
+    """
+
+
+class Control(str, Enum):
+    """
+    Control identifies the input (specific Axis or Button) of a controller.
+    """
+
+    # Axes
+    ABSOLUTE_X = "AbsoluteX"
+    ABSOLUTE_Y = "AbsoluteY"
+    ABSOLUTE_Z = "AbsoluteZ"
+    ABSOLUTE_RX = "AbsoluteRX"
+    ABSOLUTE_RY = "AbsoluteRY"
+    ABSOLUTE_RZ = "AbsoluteRZ"
+    ABSOLUTE_HAT0_X = "AbsoluteHat0X"
+    ABSOLUTE_HAT0_Y = "AbsoluteHat0Y"
+
+    # Buttons
+    BUTTON_SOUTH = "ButtonSouth"
+    BUTTON_EAST = "ButtonEast"
+    BUTTON_WEST = "ButtonWest"
+    BUTTON_NORTH = "ButtonNorth"
+    BUTTON_LT = "ButtonLT"
+    BUTTON_RT = "ButtonRT"
+    BUTTON_LT2 = "ButtonLT2"
+    BUTTON_RT2 = "ButtonRT2"
+    BUTTON_L_THUMB = "ButtonLThumb"
+    BUTTON_R_THUMB = "ButtonRThumb"
+    BUTTON_SELECT = "ButtonSelect"
+    BUTTON_START = "ButtonStart"
+    BUTTON_MENU = "ButtonMenu"
+    BUTTON_RECORD = "ButtonRecord"
+    BUTTON_E_STOP = "ButtonEStop"
+
+    # Pedals
+    ABSOLUTE_PEDAL_ACCELERATOR = "AbsolutePedalAccelerator"
+    ABSOLUTE_PEDAL_BRAKE = "AbsolutePedalBrake"
+    ABSOLUTE_PEDAL_CLUTCH = "AbsolutePedalClutch"
+
+
+@dataclass
+class Event:
+    time: float
+    """seconds since epoch"""
+
+    event: EventType
+
+    control: Control
+
+    value: float
+    """0 or 1 for buttons, -1.0 to +1.0 for axes"""
+
+    @property
+    def proto(self):
+        dt = datetime.fromtimestamp(self.time)
+        timestamp = Timestamp()
+        timestamp.FromDatetime(dt)
+        return PBEvent(time=timestamp, event=self.event.value, control=self.control.value, value=self.value)
+
+    @classmethod
+    def from_proto(cls, proto: PBEvent) -> Self:
+        dt = proto.time.ToDatetime()
+        return cls(dt.timestamp(), EventType(proto.event), Control(proto.control), proto.value)
+
+
+ControlFunction = Callable[[Event], None]
+
+
+class Controller(ComponentBase):
+    """
+    Controller is a logical "container" more than an actual device
+    Could be a single gamepad, or a collection of digitalInterrupts
+    and analogReaders, a keyboard, etc.
+
+    ::
+
+        from viam.components.input import Control, Controller, EventType
+
+    For more information, see `Input Controller component <https://docs.viam.com/dev/reference/apis/components/input-controller/>`_.
+    """
+
+    API: Final = API(  # pyright: ignore [reportIncompatibleVariableOverride]
+        RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, "input_controller"
+    )
+
+    @abc.abstractmethod
+    async def get_controls(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> List[Control]:
+        """
+        Returns a list of Controls provided by the Controller
+
+        ::
+
+            # Get the controller from the machine.
+            my_controller = Controller.from_robot(
+                robot=machine, "my_controller")
+
+            # Get the list of Controls provided by the controller.
+            controls = await my_controller.get_controls()
+
+            # Print the list of Controls provided by the controller.
+            print(f"Controls: {controls}")
+
+        Returns:
+            List[Control]: List of controls provided by the Controller
+
+        For more information, see `Input Controller component <https://docs.viam.com/dev/reference/apis/components/input-controller/#getcontrols>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def get_events(
+        self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs
+    ) -> Dict[Control, Event]:
+        """
+        Returns the most recent Event for each input
+        (which should be the current state)
+
+        ::
+
+            # Get the controller from the machine.
+            my_controller = Controller.from_robot(
+                robot=machine, "my_controller")
+
+            # Get the most recent Event for each Control.
+            recent_events = await my_controller.get_events()
+
+            # Print out the most recent Event for each Control.
+            print(f"Recent Events: {recent_events}")
+
+        Returns:
+            Dict[Control, Event]: The most recent event for each input
+
+        For more information, see `Input Controller component <https://docs.viam.com/dev/reference/apis/components/input-controller/#getevents>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    def register_control_callback(
+        self,
+        control: Control,
+        triggers: List[EventType],
+        function: Optional[ControlFunction],
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ):
+        """
+        Register a function that will fire on given EventTypes for a given
+        Control
+
+        ::
+
+            from viam.components.input import Control, EventType
+
+            # Define a function to handle pressing the Start Menu Button "BUTTON_START" on
+            # your controller, printing out the start time.
+            def print_start_time(event):
+                print(f"Start Menu Button was pressed at this time: {event.time}")
+
+
+            # Define a function that handles the controller.
+            async def handle_controller(controller):
+                # Get the list of Controls on the controller.
+                controls = await controller.get_controls()
+
+                # If the "BUTTON_START" Control is found, register the function
+                # print_start_time to fire when "BUTTON_START" has the event "ButtonPress"
+                # occur.
+                if Control.BUTTON_START in controls:
+                    controller.register_control_callback(
+                        Control.BUTTON_START, [EventType.BUTTON_PRESS], print_start_time)
+                else:
+                    print("Oops! Couldn't find the start button control! Is your "
+                        "controller connected?")
+                    exit()
+
+                while True:
+                    await asyncio.sleep(1.0)
+
+
+            async def main():
+                # ... < INSERT CONNECTION CODE FROM MACHINE'S CODE SAMPLE TAB >
+
+                # Get your controller from the machine.
+                my_controller = Controller.from_robot(
+                    robot=machine, "my_controller")
+
+                # Run the handleController function.
+                await handle_controller(my_controller)
+
+                # ... < INSERT ANY OTHER CODE FOR MAIN FUNCTION >
+
+        Args:
+            control (Control): The control to register the function for
+            triggers (List[EventType]): The events that will
+                trigger the function
+            function (ControlFunction): The function to run on
+                specific triggers
+
+        For more information, see `Input Controller component <https://docs.viam.com/dev/reference/apis/components/input-controller/#registercontrolcallback>`_.
+        """
+        ...
+
+    async def trigger_event(
+        self,
+        event: Event,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> None:  # Explicitly return None for typechecking, as this is technically a NoReturn default implementation
+        """Directly send an Event (such as a button press) from external code
+
+        ::
+
+            # Get your controller from the machine.
+            my_controller = Controller.from_robot(
+                robot=machine, "my_controller")
+
+            # Define a "Button is Pressed" event for the control BUTTON_START.
+            button_is_pressed_event = Event(
+                time(), EventType.BUTTON_PRESS, Control.BUTTON_START, 1.0)
+
+            # Trigger the event on your controller. Set this trigger to timeout if it has
+            # not completed in 7 seconds.
+            await my_controller.trigger_event(event=button_is_pressed_event, timeout=7.0)
+
+        Args:
+            event (Event): The event to trigger
+
+        For more information, see `Input Controller component <https://docs.viam.com/dev/reference/apis/components/input-controller/#triggerevent>`_.
+        """
+        raise NotSupportedError(f"Input controller named {self.name} does not support triggering events")