viam-sdk 0.45.2__py3-none-win_amd64.whl

viam/components/gantry/gantry.py

@@ -0,0 +1,156 @@
+import abc
+from typing import Any, Dict, Final, List, Optional
+
+from viam.resource.types import API, RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT
+
+from ..component_base import ComponentBase
+
+
+class Gantry(ComponentBase):
+    """
+    Gantry represents a physical Gantry and can be used for controlling gantries of N axes.
+
+    This acts as an abstract base class for any drivers representing specific
+    gantry implementations. This cannot be used on its own. If the ``__init__()`` function is
+    overridden, it must call the ``super().__init__()`` function.
+
+    ::
+
+        from viam.components.gantry import Gantry
+
+    For more information, see `Gantry component <https://docs.viam.com/dev/reference/apis/components/gantry/>`_.
+    """
+
+    API: Final = API(  # pyright: ignore [reportIncompatibleVariableOverride]
+        RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, "gantry"
+    )
+
+    @abc.abstractmethod
+    async def get_position(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> List[float]:
+        """
+        Get the positions of the axes of the gantry in millimeters.
+
+        ::
+
+            my_gantry = Gantry.from_robot(robot=machine, name="my_gantry")
+
+            # Get the current positions of the axes of the gantry in millimeters.
+            positions = await my_gantry.get_position()
+
+        Returns:
+            List[float]: A list of the position of the axes of the gantry in millimeters.
+
+        For more information, see `Gantry component <https://docs.viam.com/dev/reference/apis/components/gantry/#getposition>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def move_to_position(
+        self,
+        positions: List[float],
+        speeds: List[float],
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        """
+        Move the axes of the gantry to the desired positions (mm) at the requested speeds (mm/sec).
+
+        ::
+
+            my_gantry = Gantry.from_robot(robot=machine, name="my_gantry")
+
+            # Create a list of positions for the axes of the gantry to move to. Assume in
+            # this example that the gantry is multi-axis, with 3 axes.
+            examplePositions = [1, 2, 3]
+
+            exampleSpeeds = [3, 9, 12]
+
+            # Move the axes of the gantry to the positions specified.
+            await my_gantry.move_to_position(
+                positions=examplePositions, speeds=exampleSpeeds)
+
+        Args:
+            positions (List[float]): A list of positions for the axes of the gantry to move to, in millimeters.
+            speeds (List[float]): A list of speeds in millimeters per second for the gantry to move at respective to each axis.
+
+        For more information, see `Gantry component <https://docs.viam.com/dev/reference/apis/components/gantry/#movetoposition>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def home(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> bool:
+        """
+        Run the homing sequence of the gantry to re-calibrate the axes with respect to the limit switches.
+
+        ::
+
+            my_gantry = Gantry.from_robot(robot=machine, name="my_gantry")
+
+            await my_gantry.home()
+
+        Returns:
+            bool: Whether the gantry has run the homing sequence successfully.
+
+        For more information, see `Gantry component <https://docs.viam.com/dev/reference/apis/components/gantry/#home>`_.
+        """
+
+    @abc.abstractmethod
+    async def get_lengths(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> List[float]:
+        """
+        Get the lengths of the axes of the gantry in millimeters.
+
+        ::
+
+            my_gantry = Gantry.from_robot(robot=machine, name="my_gantry")
+
+            # Get the lengths of the axes of the gantry in millimeters.
+            lengths_mm = await my_gantry.get_lengths()
+
+        Returns:
+            List[float]: A list of the lengths of the axes of the gantry in millimeters.
+
+        For more information, see `Gantry component <https://docs.viam.com/dev/reference/apis/components/gantry/#getlengths>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def stop(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs):
+        """
+        Stop all motion of the gantry. It is assumed that the gantry stops immediately.
+
+        ::
+
+            my_gantry = Gantry.from_robot(robot=machine, name="my_gantry")
+
+            # Stop all motion of the gantry. It is assumed that the gantry stops
+            # immediately.
+            await my_gantry.stop()
+
+        For more information, see `Gantry component <https://docs.viam.com/dev/reference/apis/components/gantry/#stop>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def is_moving(self) -> bool:
+        """
+        Get if the gantry is currently moving.
+
+        ::
+
+            my_gantry = Gantry.from_robot(robot=machine, name="my_gantry")
+
+            # Stop all motion of the gantry. It is assumed that the
+            # gantry stops immediately.
+            await my_gantry.stop()
+
+            # Print if the gantry is currently moving.
+            print(await my_gantry.is_moving())
+
+        Returns:
+            bool: Whether the gantry is moving.
+
+        For more information, see `Gantry component <https://docs.viam.com/dev/reference/apis/components/gantry/#ismoving>`_.
+        """
+        ...

viam/components/gantry/service.py

@@ -0,0 +1,113 @@
+from grpclib.server import Stream
+
+from viam.proto.common import DoCommandRequest, DoCommandResponse, GetGeometriesRequest, GetGeometriesResponse
+from viam.proto.component.gantry import (
+    GantryServiceBase,
+    GetLengthsRequest,
+    GetLengthsResponse,
+    GetPositionRequest,
+    GetPositionResponse,
+    HomeRequest,
+    HomeResponse,
+    IsMovingRequest,
+    IsMovingResponse,
+    MoveToPositionRequest,
+    MoveToPositionResponse,
+    StopRequest,
+    StopResponse,
+)
+from viam.resource.rpc_service_base import ResourceRPCServiceBase
+from viam.utils import dict_to_struct, struct_to_dict
+
+from .gantry import Gantry
+
+
+class GantryRPCService(GantryServiceBase, ResourceRPCServiceBase[Gantry]):
+    """
+    gRPC Service for a Gantry
+    """
+
+    RESOURCE_TYPE = Gantry
+
+    async def GetPosition(self, stream: Stream[GetPositionRequest, GetPositionResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        gantry = self.get_resource(name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        position = await gantry.get_position(extra=struct_to_dict(request.extra), timeout=timeout, metadata=stream.metadata)
+        response = GetPositionResponse(positions_mm=position)
+        await stream.send_message(response)
+
+    async def MoveToPosition(self, stream: Stream[MoveToPositionRequest, MoveToPositionResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        gantry = self.get_resource(name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        await gantry.move_to_position(
+            list(request.positions_mm),
+            list(request.speeds_mm_per_sec),
+            extra=struct_to_dict(request.extra),
+            timeout=timeout,
+            metadata=stream.metadata,
+        )
+        response = MoveToPositionResponse()
+        await stream.send_message(response)
+
+    async def Home(self, stream: Stream[HomeRequest, HomeResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        gantry = self.get_resource(name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        homed = await gantry.home(extra=struct_to_dict(request.extra), timeout=timeout, metadata=stream.metadata)
+        response = HomeResponse(homed=homed)
+        await stream.send_message(response)
+
+    async def GetLengths(self, stream: Stream[GetLengthsRequest, GetLengthsResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        gantry = self.get_resource(name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        lengths = await gantry.get_lengths(extra=struct_to_dict(request.extra), timeout=timeout, metadata=stream.metadata)
+        response = GetLengthsResponse(lengths_mm=lengths)
+        await stream.send_message(response)
+
+    async def Stop(self, stream: Stream[StopRequest, StopResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        gantry = self.get_resource(name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        await gantry.stop(extra=struct_to_dict(request.extra), timeout=timeout, metadata=stream.metadata)
+        response = StopResponse()
+        await stream.send_message(response)
+
+    async def IsMoving(self, stream: Stream[IsMovingRequest, IsMovingResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        gantry = self.get_resource(name)
+        is_moving = await gantry.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
+        gantry = self.get_resource(request.name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        result = await gantry.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/generic/__init__.py

@@ -0,0 +1,18 @@
+import viam.gen.component.generic.v1.generic_pb2  # Need this import for Generic service descriptors to resolve
+from viam.resource.registry import Registry, ResourceRegistration
+
+from .client import GenericClient
+from .generic import Generic
+from .service import GenericRPCService
+
+__all__ = [
+    "Generic",
+]
+
+Registry.register_api(
+    ResourceRegistration(
+        Generic,
+        GenericRPCService,
+        lambda name, channel: GenericClient(name, channel),
+    )
+)

viam/components/generic/client.py

@@ -0,0 +1,62 @@
+from typing import Any, Dict, List, Mapping, Optional
+
+from grpclib import GRPCError, Status
+from grpclib.client import Channel
+
+from viam.proto.common import DoCommandRequest, DoCommandResponse, Geometry
+from viam.proto.component.generic import GenericServiceStub
+from viam.resource.rpc_client_base import ReconfigurableResourceRPCClientBase, ResourceRPCClientBase
+from viam.utils import ValueTypes, dict_to_struct, get_geometries, struct_to_dict
+
+from .generic import Generic
+
+
+class GenericClient(Generic, ReconfigurableResourceRPCClientBase):
+    """
+    gRPC client for the Generic component.
+    """
+
+    def __init__(self, name: str, channel: Channel):
+        self.channel = channel
+        self.client = GenericServiceStub(channel)
+        super().__init__(name)
+
+    async def do_command(
+        self,
+        command: Mapping[str, Any],
+        *,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> Mapping[str, Any]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = DoCommandRequest(name=self.name, command=dict_to_struct(command))
+        try:
+            response: DoCommandResponse = await self.client.DoCommand(request, timeout=timeout, metadata=md)
+        except GRPCError as e:
+            if e.status == Status.UNIMPLEMENTED:
+                raise NotImplementedError()
+            raise e
+
+        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)
+
+
+async def do_command(
+    channel: Channel, name: str, command: Mapping[str, ValueTypes], *, timeout: Optional[float] = None, **kwargs
+) -> Mapping[str, ValueTypes]:
+    """Convenience method to allow component clients to execute ``do_command`` functions
+
+    Args:
+        channel (Channel): A gRPC channel
+        name (str): The name of the component
+        command (Dict[str, Any]): The command to execute
+
+    Returns:
+        Dict[str, Any]: The result of the executed command
+    """
+    md = kwargs.get("metadata", ResourceRPCClientBase.Metadata()).proto
+    client = GenericClient(name, channel)
+    return await client.do_command(command, timeout=timeout, metadata=md)

viam/components/generic/generic.py

@@ -0,0 +1,76 @@
+from typing import Final
+
+from viam.resource.types import API, RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT
+
+from ..component_base import ComponentBase
+
+
+class Generic(ComponentBase):
+    """
+    Generic component, which represents any type of component that can executes arbitrary commands
+
+    This acts as an abstract base class for any drivers representing generic components.
+    This cannot be used on its own. If the ``__init__()`` function is overridden, it must call the ``super().__init__()`` function.
+
+    To create a Generic component (an arbitrary component that can process commands), this ``Generic`` component should be subclassed
+    and the ``do_command`` function implemented.
+
+    ::
+
+        from viam.components.generic import Generic
+
+    Example::
+
+        class ComplexComponent(Generic):
+
+            async def do_command(
+                self,
+                command: Mapping[str, ValueTypes],
+                *,
+                timeout: Optional[float] = None,
+                **kwargs
+            ) -> Mapping[str, ValueTypes]:
+                result = {key: False for key in command.keys()}
+                for (name, args) in command.items():
+                    if name == 'on':
+                        self.on(*args)
+                        result[name] = True
+                    if name == 'set_frequency':
+                        self.set_frequency(*args)
+                        result[name] = True
+                    if name == 'get_frequency':
+                        result[name] = self.frequency
+                    if name == 'complex_command':
+                        self.complex_command(*args)
+                        result[name] = True
+                return result
+
+            def set_frequency(self, frequency: int):
+                self.frequency = frequency
+
+            def on(self, frequency: int, duration: int):
+                self.frequency = frequency
+                self.power = 1
+                task = threading.Timer(duration, self.off)
+                task.start()
+
+            def off(self):
+                self.power = 0
+
+            def complex_command(self, arg1, arg2, arg3):
+                ...
+
+    To execute commands, simply call the ``do_command`` function with the appropriate parameters.
+    ::
+
+        await component.do_command({'on': [300, 10]})
+        component.power  # 1
+        await asyncio.sleep(10)
+        component.power  # 0
+
+    For more information, see `Gantry component <https://docs.viam.com/dev/reference/apis/components/generic/>`_.
+    """
+
+    API: Final = API(  # pyright: ignore [reportIncompatibleVariableOverride]
+        RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, "generic"
+    )

viam/components/generic/service.py

@@ -0,0 +1,40 @@
+from grpclib import GRPCError, Status
+from grpclib.server import Stream
+
+from viam.components.component_base import ComponentBase
+from viam.proto.common import DoCommandRequest, DoCommandResponse, GetGeometriesRequest, GetGeometriesResponse
+from viam.proto.component.generic import GenericServiceBase
+from viam.resource.rpc_service_base import ResourceRPCServiceBase
+from viam.utils import dict_to_struct, struct_to_dict
+
+# from .generic import Generic
+
+
+class GenericRPCService(GenericServiceBase, ResourceRPCServiceBase):
+    """
+    gRPC Service for a Generic component
+    """
+
+    RESOURCE_TYPE = ComponentBase
+
+    async def DoCommand(self, stream: Stream[DoCommandRequest, DoCommandResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        component = self.get_resource(name)
+        try:
+            timeout = stream.deadline.time_remaining() if stream.deadline else None
+            result = await component.do_command(struct_to_dict(request.command), timeout=timeout, metadata=stream.metadata)
+        except NotImplementedError:
+            raise GRPCError(Status.UNIMPLEMENTED, f"``DO`` command is unimplemented for component named: {name}")
+        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
+        component = self.get_resource(request.name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        geometries = await component.get_geometries(extra=struct_to_dict(request.extra), timeout=timeout)
+        response = GetGeometriesResponse(geometries=geometries)
+        await stream.send_message(response)

viam/components/gripper/__init__.py

@@ -0,0 +1,11 @@
+from viam.resource.registry import Registry, ResourceRegistration
+
+from .client import GripperClient
+from .gripper import Gripper
+from .service import GripperRPCService
+
+__all__ = [
+    "Gripper",
+]
+
+Registry.register_api(ResourceRegistration(Gripper, GripperRPCService, lambda name, channel: GripperClient(name, channel)))

viam/components/gripper/client.py

@@ -0,0 +1,85 @@
+from typing import Any, Dict, List, Mapping, Optional
+
+from grpclib.client import Channel
+
+from viam.proto.common import DoCommandRequest, DoCommandResponse, Geometry
+from viam.proto.component.gripper import (
+    GrabRequest,
+    GrabResponse,
+    GripperServiceStub,
+    IsMovingRequest,
+    IsMovingResponse,
+    OpenRequest,
+    StopRequest,
+)
+from viam.resource.rpc_client_base import ReconfigurableResourceRPCClientBase
+from viam.utils import ValueTypes, dict_to_struct, get_geometries, struct_to_dict
+
+from .gripper import Gripper
+
+
+class GripperClient(Gripper, ReconfigurableResourceRPCClientBase):
+    """
+    gRPC client for the Gripper component
+    """
+
+    def __init__(self, name: str, channel: Channel):
+        self.channel = channel
+        self.client = GripperServiceStub(channel)
+        super().__init__(name)
+
+    async def open(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = OpenRequest(name=self.name, extra=dict_to_struct(extra))
+        await self.client.Open(request, timeout=timeout, metadata=md)
+
+    async def grab(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> bool:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = GrabRequest(name=self.name, extra=dict_to_struct(extra))
+        response: GrabResponse = await self.client.Grab(request, timeout=timeout, metadata=md)
+        return response.success
+
+    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_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/gripper/gripper.py

@@ -0,0 +1,114 @@
+import abc
+from typing import Any, Dict, Final, Optional
+
+from viam.components.component_base import ComponentBase
+from viam.resource.types import API, RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT
+
+
+class Gripper(ComponentBase):
+    """
+    Gripper represents a physical robotic gripper.
+
+    This acts as an abstract base class for any drivers representing specific
+    gripper implementations. This cannot be used on its own. If the ``__init__()`` function is
+    overridden, it must call the ``super().__init__()`` function.
+
+    ::
+
+        from viam.components.gripper import Gripper
+
+    For more information, see `Gripper component <https://docs.viam.com/dev/reference/apis/components/gripper/>`_.
+    """
+
+    API: Final = API(  # pyright: ignore [reportIncompatibleVariableOverride]
+        RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, "gripper"
+    )
+
+    @abc.abstractmethod
+    async def open(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        """
+        Open the gripper.
+
+        ::
+
+            my_gripper = Gripper.from_robot(robot=machine, name="my_gripper")
+
+            # Open the gripper.
+            await my_gripper.open()
+
+        For more information, see `Gripper component <https://docs.viam.com/dev/reference/apis/components/gripper/#open>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def grab(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> bool:
+        """
+        Instruct the gripper to grab.
+
+        ::
+
+            my_gripper = Gripper.from_robot(robot=machine, name="my_gripper")
+
+            # Grab with the gripper.
+            grabbed = await my_gripper.grab()
+
+        Returns:
+            bool: Indicates if the gripper grabbed something.
+
+        For more information, see `Gripper component <https://docs.viam.com/dev/reference/apis/components/gripper/#grab>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def stop(
+        self,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ):
+        """
+        Stop the gripper. It is assumed the gripper stops immediately.
+
+        ::
+
+            my_gripper = Gripper.from_robot(robot=machine, name="my_gripper")
+
+            # Stop the gripper.
+            await my_gripper.stop()
+
+        For more information, see `Gripper component <https://docs.viam.com/dev/reference/apis/components/gripper/#stop>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def is_moving(self) -> bool:
+        """
+        Get if the gripper is currently moving.
+
+        ::
+
+            my_gripper = Gripper.from_robot(robot=machine, name="my_gripper")
+
+            # Check whether the gripper is currently moving.
+            moving = await my_gripper.is_moving()
+            print('Moving:', moving)
+
+        Returns:
+            bool: Whether the gripper is moving.
+
+        For more information, see `Gripper component <https://docs.viam.com/dev/reference/apis/components/gripper/#is_moving>`_.
+        """
+        ...