viam-sdk 0.45.2__py3-none-win_amd64.whl

viam/components/input/service.py

@@ -0,0 +1,175 @@
+import asyncio
+from multiprocessing import Pipe
+from typing import Optional
+
+from grpclib.server import Stream
+from h2.exceptions import StreamClosedError
+
+import viam
+from viam.errors import NotSupportedError
+from viam.proto.common import DoCommandRequest, DoCommandResponse, GetGeometriesRequest, GetGeometriesResponse
+from viam.proto.component.inputcontroller import (
+    GetControlsRequest,
+    GetControlsResponse,
+    GetEventsRequest,
+    GetEventsResponse,
+    InputControllerServiceBase,
+    StreamEventsRequest,
+    StreamEventsResponse,
+    TriggerEventRequest,
+    TriggerEventResponse,
+)
+from viam.resource.rpc_service_base import ResourceRPCServiceBase
+from viam.utils import dict_to_struct, struct_to_dict
+
+from .input import Control, Controller, Event, EventType
+
+LOGGER = viam.logging.getLogger(__name__)
+
+
+class InputControllerRPCService(InputControllerServiceBase, ResourceRPCServiceBase[Controller]):
+    """
+    gRPC Service for an input controller
+    """
+
+    RESOURCE_TYPE = Controller
+
+    async def GetControls(self, stream: Stream[GetControlsRequest, GetControlsResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.controller
+        controller = self.get_resource(name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        controls = await controller.get_controls(extra=struct_to_dict(request.extra), timeout=timeout, metadata=stream.metadata)
+        response = GetControlsResponse(controls=[c.value for c in controls])
+        await stream.send_message(response)
+
+    async def GetEvents(self, stream: Stream[GetEventsRequest, GetEventsResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.controller
+        controller = self.get_resource(name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        events = await controller.get_events(extra=struct_to_dict(request.extra), timeout=timeout, metadata=stream.metadata)
+        pb_events = [e.proto for e in events.values()]
+        response = GetEventsResponse(events=pb_events)
+        await stream.send_message(response)
+
+    async def StreamEvents(self, stream: Stream[StreamEventsRequest, StreamEventsResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.controller
+        controller = self.get_resource(name)
+
+        loop = asyncio.get_running_loop()
+        # Using Pipes to send event data back to this function so it can be streamed to clients
+        # The write pipe is added to the callbacks for a control, so whenever that control sends a watched event,
+        # that event is sent through the pipe, where it will be read (further down) and sent over the stream
+        pipe_r, pipe_w = Pipe(duplex=False)
+
+        def ctrlFunc(event: Event):
+            try:
+                pipe_w.send(event)
+            except Exception as e:
+                LOGGER.error(e)
+                cleanup(e)
+
+        # Register the pipe callbacks
+        for event in request.events:
+            triggers = [EventType(et) for et in event.events]
+            if len(triggers):
+                controller.register_control_callback(
+                    Control(event.control),
+                    triggers,
+                    ctrlFunc,
+                    extra=struct_to_dict(request.extra),
+                )
+
+            cancelled_triggers = [EventType(et) for et in event.cancelled_events]
+            if len(cancelled_triggers):
+                controller.register_control_callback(
+                    Control(event.control),
+                    cancelled_triggers,
+                    None,
+                    extra=struct_to_dict(request.extra),
+                )
+
+        # Asynchronously wait for messages to come over the read pipe and run the READ function whenever the pipe is ready.
+        def read():
+            ev: Event = pipe_r.recv()
+            pb_ev = ev.proto
+            response = StreamEventsResponse(event=pb_ev)
+
+            async def send_message():
+                try:
+                    stream._cancel_done = False  # Undo hack, see below
+                    await stream.send_message(response)
+                except StreamClosedError:
+                    cleanup()
+                except Exception as e:
+                    cleanup(e)
+
+            loop.create_task(send_message(), name=f"{viam._TASK_PREFIX}-input_send_event")
+
+        loop.add_reader(pipe_r, read)
+
+        # HACK: Keep the stream open when this function returns.
+        # When the StreamEvents function returns, the Stream is closed. But we don't want the stream to close because we still need
+        # to send events to any clients who have registered callbacks.
+        # By setting ``stream._cancel_done`` to ``True``, this tricks grpclib into thinking it already closed the stream, so it doesn't
+        # perform any cleanup (like removing the stream). We eventually do want to actually close this stream, so we undo this hack
+        # every time we send a message. That way, the trailing metadata is sent when either the server closes or the client disconnects.
+        stream._cancel_done = True
+
+        # Remove ctrl functions when this stream is closed
+        def cleanup(exc: Optional[Exception] = None):
+            loop.remove_reader(pipe_r)
+            pipe_w.close()
+            pipe_r.close()
+            unregister_pipe_callbacks()
+            asyncio.create_task(stream.__aexit__(None, exc, None))
+
+        def unregister_pipe_callbacks():
+            for event in request.events:
+                triggers = [EventType(et) for et in event.events]
+                if len(triggers):
+                    controller.register_control_callback(
+                        Control(event.control),
+                        triggers,
+                        None,
+                        extra=struct_to_dict(request.extra),
+                    )
+
+    async def TriggerEvent(self, stream: Stream[TriggerEventRequest, TriggerEventResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.controller
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        controller = self.get_resource(name)
+        try:
+            pb_event = request.event
+            event = Event.from_proto(pb_event)
+            await controller.trigger_event(event, extra=struct_to_dict(request.extra), timeout=timeout, metadata=stream.metadata)
+        except NotSupportedError as e:
+            raise e.grpc_error
+
+        response = TriggerEventResponse()
+        await stream.send_message(response)
+
+    async def DoCommand(self, stream: Stream[DoCommandRequest, DoCommandResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        controller = self.get_resource(request.name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        result = await controller.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/motor/__init__.py

@@ -0,0 +1,11 @@
+from viam.resource.registry import Registry, ResourceRegistration
+
+from .client import MotorClient
+from .motor import Motor
+from .service import MotorRPCService
+
+__all__ = [
+    "Motor",
+]
+
+Registry.register_api(ResourceRegistration(Motor, MotorRPCService, lambda name, channel: MotorClient(name, channel)))

viam/components/motor/client.py

@@ -0,0 +1,168 @@
+from typing import Any, Dict, List, Mapping, Optional, Tuple
+
+from grpclib.client import Channel
+
+from viam.proto.common import DoCommandRequest, DoCommandResponse, Geometry
+from viam.proto.component.motor import (
+    GetPositionRequest,
+    GetPositionResponse,
+    GetPropertiesRequest,
+    GetPropertiesResponse,
+    GoForRequest,
+    GoToRequest,
+    IsMovingRequest,
+    IsMovingResponse,
+    IsPoweredRequest,
+    IsPoweredResponse,
+    MotorServiceStub,
+    ResetZeroPositionRequest,
+    SetPowerRequest,
+    SetRPMRequest,
+    StopRequest,
+)
+from viam.resource.rpc_client_base import ReconfigurableResourceRPCClientBase
+from viam.utils import ValueTypes, dict_to_struct, get_geometries, struct_to_dict
+
+from .motor import Motor
+
+
+class MotorClient(Motor, ReconfigurableResourceRPCClientBase):
+    """
+    gRPC client for the Motor component.
+    """
+
+    def __init__(self, name: str, channel: Channel):
+        self.channel = channel
+        self.client = MotorServiceStub(channel)
+        super().__init__(name)
+
+    async def set_power(
+        self,
+        power: float,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = SetPowerRequest(name=self.name, power_pct=power, extra=dict_to_struct(extra))
+        await self.client.SetPower(request, timeout=timeout, metadata=md)
+
+    async def go_for(
+        self,
+        rpm: float,
+        revolutions: float,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = GoForRequest(name=self.name, rpm=rpm, revolutions=revolutions, extra=dict_to_struct(extra))
+        await self.client.GoFor(request, timeout=timeout, metadata=md)
+
+    async def go_to(
+        self,
+        rpm: float,
+        position_revolutions: float,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = GoToRequest(name=self.name, rpm=rpm, position_revolutions=position_revolutions, extra=dict_to_struct(extra))
+        await self.client.GoTo(request, timeout=timeout, metadata=md)
+
+    async def set_rpm(
+        self,
+        rpm: float,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = SetRPMRequest(name=self.name, rpm=rpm, extra=dict_to_struct(extra))
+        await self.client.SetRPM(request, timeout=timeout, metadata=md)
+
+    async def reset_zero_position(
+        self,
+        offset: float,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = ResetZeroPositionRequest(name=self.name, offset=offset, extra=dict_to_struct(extra))
+        await self.client.ResetZeroPosition(request, timeout=timeout, metadata=md)
+
+    async def get_position(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> float:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = GetPositionRequest(name=self.name, extra=dict_to_struct(extra))
+        response: GetPositionResponse = await self.client.GetPosition(request, timeout=timeout, metadata=md)
+        return response.position
+
+    async def get_properties(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> Motor.Properties:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = GetPropertiesRequest(name=self.name, extra=dict_to_struct(extra))
+        response: GetPropertiesResponse = await self.client.GetProperties(request, timeout=timeout, metadata=md)
+        return Motor.Properties(position_reporting=response.position_reporting)
+
+    async def stop(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = StopRequest(name=self.name, extra=dict_to_struct(extra))
+        await self.client.Stop(request, timeout=timeout, metadata=md)
+
+    async def is_powered(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> Tuple[bool, float]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = IsPoweredRequest(name=self.name, extra=dict_to_struct(extra))
+        response: IsPoweredResponse = await self.client.IsPowered(request, timeout=timeout, metadata=md)
+        return response.is_on, response.power_pct
+
+    async def is_moving(self, *, timeout: Optional[float] = None, **kwargs) -> bool:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = IsMovingRequest(name=self.name)
+        response: IsMovingResponse = await self.client.IsMoving(request, timeout=timeout, metadata=md)
+        return response.is_moving
+
+    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/motor/motor.py

@@ -0,0 +1,301 @@
+import abc
+from dataclasses import dataclass
+from typing import Any, Dict, Final, Optional, Tuple
+
+from viam.resource.types import API, RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT
+
+from ..component_base import ComponentBase
+
+
+class Motor(ComponentBase):
+    """Motor represents a physical motor.
+
+    This acts as an abstract base class for any drivers representing specific
+    motor implementations. This cannot be used on its own. If the ``__init__()`` function is
+    overridden, it must call the ``super().__init__()`` function.
+
+    ::
+
+        from viam.components.motor import Motor
+
+    For more information, see `Motor component <https://docs.viam.com/dev/reference/apis/components/motor/>`_.
+    """
+
+    @dataclass
+    class Properties:
+        position_reporting: bool
+
+    API: Final = API(  # pyright: ignore [reportIncompatibleVariableOverride]
+        RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, "motor"
+    )
+
+    @abc.abstractmethod
+    async def set_power(
+        self,
+        power: float,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        """
+        Sets the "percentage" of power the motor should employ between -1 and 1.
+        When ``power`` is negative, the rotation will be in the backward direction.
+
+        ::
+
+            my_motor = Motor.from_robot(robot=machine, name="my_motor")
+
+            # Set the power to 40% forwards.
+            await my_motor.set_power(power=0.4)
+
+        Args:
+            power (float): Power between -1 and 1
+                (negative implies backwards).
+
+        For more information, see `Motor component <https://docs.viam.com/dev/reference/apis/components/motor/#setpower>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def go_for(
+        self,
+        rpm: float,
+        revolutions: float,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        """
+        Spin the motor the specified number of ``revolutions`` at specified ``rpm``.
+        When ``rpm`` or ``revolutions`` is a negative value, the rotation will be in the backward direction.
+        Note: if both ``rpm`` and ``revolutions`` are negative, the motor will spin in the forward direction.
+
+        ::
+
+            my_motor = Motor.from_robot(robot=machine, name="my_motor")
+
+            # Turn the motor 7.2 revolutions at 60 RPM.
+            await my_motor.go_for(rpm=60, revolutions=7.2)
+
+        Args:
+            rpm (float): Speed at which the motor should move in rotations per minute
+                (negative implies backwards).
+            revolutions (float): Number of revolutions the motor should run for
+                (negative implies backwards).
+
+        For more information, see `Motor component <https://docs.viam.com/dev/reference/apis/components/motor/#gofor>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def go_to(
+        self,
+        rpm: float,
+        position_revolutions: float,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        """
+        Spin the motor to the specified position (provided in revolutions from home/zero),
+        at the specified speed, in revolutions per minute.
+        Regardless of the directionality of the ``rpm`` this function will move
+        the motor towards the specified position.
+
+        ::
+
+            my_motor = Motor.from_robot(robot=machine, name="my_motor")
+
+            # Turn the motor to 8.3 revolutions from home at 75 RPM.
+            await my_motor.go_to(rpm=75, revolutions=8.3)
+
+        Args:
+            rpm (float): Speed at which the motor should rotate (absolute value).
+            position_revolutions (float): Target position relative to home/zero, in revolutions.
+
+        For more information, see `Motor component <https://docs.viam.com/dev/reference/apis/components/motor/#goto>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def set_rpm(
+        self,
+        rpm: float,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        """
+        Spin the motor indefinitely at the specified speed, in revolutions per minute.
+        Positive ``rpm`` will result in forward movement and negative ``rpm`` will result in backwards movement
+
+        ::
+
+            my_motor = Motor.from_robot(robot=machine, name="my_motor")
+
+            # Spin the motor at 75 RPM.
+            await my_motor.set_rpm(rpm=75)
+
+        Args:
+            rpm (float): Speed at which the motor should rotate.
+
+        For more information, see `Motor component <https://docs.viam.com/dev/reference/apis/components/motor/#setrpm>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def reset_zero_position(
+        self,
+        offset: float,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        """
+        Set the current position (modified by ``offset``) to be the new zero (home) position.
+
+        ::
+
+            my_motor = Motor.from_robot(robot=machine, name="my_motor")
+
+            # Set the current position as the new home position with no offset.
+            await my_motor.reset_zero_position(offset=0.0)
+
+        Args:
+            offset (float): The offset from the current position to new home/zero position.
+
+        For more information, see `Motor component <https://docs.viam.com/dev/reference/apis/components/motor/#resetzeroposition>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def get_position(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> float:
+        """
+        Report the position of the motor based on its encoder.
+        The value returned is the number of revolutions relative to its zero position.
+        This method will raise an exception if position reporting is not supported by the motor.
+
+        ::
+
+            my_motor = Motor.from_robot(robot=machine, name="my_motor")
+
+            # Get the current position of the motor.
+            position = await my_motor.get_position()
+
+        Returns:
+            float: Number of revolutions the motor is away from zero/home.
+
+        For more information, see `Motor component <https://docs.viam.com/dev/reference/apis/components/motor/#getposition>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def get_properties(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> Properties:
+        """
+        Report a dictionary mapping optional properties to
+        whether it is supported by this motor.
+
+        ::
+
+            my_motor = Motor.from_robot(robot=machine, name="my_motor")
+
+            # Report a dictionary mapping optional properties to whether it is supported by
+            # this motor.
+            properties = await my_motor.get_properties()
+
+            # Print out the properties.
+            print(f'Properties: {properties}')
+
+        Returns:
+            Properties: Map of feature names to supported status.
+
+        For more information, see `Motor component <https://docs.viam.com/dev/reference/apis/components/motor/#getproperties>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def stop(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        """
+        Stop the motor immediately, without any gradual step down.
+
+        ::
+
+            my_motor = Motor.from_robot(robot=machine, name="my_motor")
+
+            # Stop the motor.
+            await my_motor.stop()
+
+        For more information, see `Motor component <https://docs.viam.com/dev/reference/apis/components/motor/#stop>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def is_powered(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> Tuple[bool, float]:
+        """
+        Returns whether or not the motor is currently running.
+
+        ::
+
+            my_motor = Motor.from_robot(robot=machine, name="my_motor")
+
+            # Check whether the motor is currently running.
+            powered = await my_motor.is_powered()
+
+            print('Powered: ', powered)
+
+        Returns:
+            Tuple[bool, float]: A tuple containing two values; the first [0] value indicates whether the motor is currently powered, and
+                the second [1] value indicates the current power percentage of the motor.
+
+        For more information, see `Motor component <https://docs.viam.com/dev/reference/apis/components/motor/#ispowered>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def is_moving(self) -> bool:
+        """
+        Get if the motor is currently moving.
+
+        ::
+
+            my_motor = Motor.from_robot(robot=machine, name="my_motor")
+
+            # Check whether the motor is currently moving.
+            moving = await my_motor.is_moving()
+            print('Moving: ', moving)
+
+        Returns:
+            bool: Whether the motor is moving.
+
+        For more information, see `Motor component <https://docs.viam.com/dev/reference/apis/components/motor/#ismoving>`_.
+        """
+        ...