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

viam/components/audio_in/service.py

@@ -0,0 +1,83 @@
+from grpclib.server import Stream
+from h2.exceptions import StreamClosedError
+
+from viam.logging import getLogger
+from viam.proto.common import (
+    DoCommandRequest,
+    DoCommandResponse,
+    GetGeometriesRequest,
+    GetGeometriesResponse,
+    GetPropertiesRequest,
+    GetPropertiesResponse,
+)
+from viam.proto.component.audioin import AudioInServiceBase, GetAudioRequest, GetAudioResponse
+from viam.resource.rpc_service_base import ResourceRPCServiceBase
+from viam.utils import dict_to_struct, struct_to_dict
+
+from .audio_in import AudioIn
+
+LOGGER = getLogger(__name__)
+
+
+class AudioInRPCService(AudioInServiceBase, ResourceRPCServiceBase[AudioIn]):
+    """
+    gRPC Service for a generic audio in.
+    """
+
+    RESOURCE_TYPE = AudioIn
+
+    async def GetAudio(self, stream: Stream[GetAudioRequest, GetAudioResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        audio_in = self.get_resource(name)
+        audio_stream = await audio_in.get_audio(
+            codec=request.codec,
+            duration_seconds=request.duration_seconds,
+            previous_timestamp_ns=request.previous_timestamp_nanoseconds,
+            metadata=stream.metadata,
+        )
+        async for response in audio_stream:
+            try:
+                response.request_id = request.request_id
+                await stream.send_message(response)
+            except StreamClosedError:
+                return
+            except Exception as e:
+                LOGGER.error(e)
+                return
+
+    async def GetProperties(self, stream: Stream[GetPropertiesRequest, GetPropertiesResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        audio_in = self.get_resource(name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        properties = await audio_in.get_properties(
+            timeout=timeout,
+            metadata=stream.metadata,
+        )
+        await stream.send_message(properties)
+
+    async def DoCommand(self, stream: Stream[DoCommandRequest, DoCommandResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        audio_in = self.get_resource(name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        result = await audio_in.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/audio_out/__init__.py

@@ -0,0 +1,21 @@
+from viam.media.audio import AudioCodec
+from viam.proto.common import AudioInfo
+from viam.resource.registry import Registry, ResourceRegistration
+
+from .audio_out import AudioOut
+from .client import AudioOutClient
+from .service import AudioOutRPCService
+
+__all__ = [
+    "AudioOut",
+    "AudioInfo",
+    "AudioCodec",
+]
+
+Registry.register_api(
+    ResourceRegistration(
+        AudioOut,
+        AudioOutRPCService,
+        lambda name, channel: AudioOutClient(name, channel),
+    )
+)

viam/components/audio_out/audio_out.py

@@ -0,0 +1,72 @@
+import abc
+import sys
+from typing import Any, Dict, Final, Optional
+
+from viam.proto.common import GetPropertiesResponse
+from viam.resource.types import API, RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT
+
+from ..component_base import ComponentBase
+from . import AudioInfo
+
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias
+else:
+    from typing_extensions import TypeAlias
+
+
+class AudioOut(ComponentBase):
+    """AudioOut represents a component that can play audio.
+
+    This acts as an abstract base class for any drivers representing specific
+    audio output implementations. This cannot be used on its own. If the ``__init__()`` function is
+    overridden, it must call the ``super().__init__()`` function.
+    """
+
+    API: Final = API(  # pyright: ignore [reportIncompatibleVariableOverride]
+        RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, "audio_out"
+    )
+
+    Properties: "TypeAlias" = GetPropertiesResponse
+
+    @abc.abstractmethod
+    async def play(
+        self,
+        data: bytes,
+        info: Optional[AudioInfo] = None,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> None:
+        """
+        Play the given audio data.
+
+        ::
+
+            my_audio_out = AudioOut.from_robot(robot=machine, name="my_audio_out")
+
+            # With audio info
+            audio_info = AudioInfo(codec=AudioCodec.PCM16, sample_rate_hz=44100, num_channels=2)
+            await my_audio_out.play(audio_data, audio_info)
+
+            # Without audio info (when codec encodes information within audio_data)
+            await my_audio_out.play(audio_data)
+
+        Args:
+            data: audio bytes to play
+            info: (optional) information about the audio data such as codec, sample rate, and channel count
+        """
+
+    @abc.abstractmethod
+    async def get_properties(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs) -> Properties:
+        """
+        Get the audio output device's properties.
+
+        ::
+
+            my_audio_out = AudioOut.from_robot(robot=machine, name="my_audio_out")
+            properties = await my_audio_out.get_properties()
+
+        Returns:
+            Properties: The properties of the audio output device
+        """

viam/components/audio_out/client.py

@@ -0,0 +1,67 @@
+from typing import Any, Dict, List, Mapping, Optional
+
+from grpclib.client import Channel
+
+from viam.proto.common import DoCommandRequest, DoCommandResponse, Geometry, GetPropertiesRequest, GetPropertiesResponse
+from viam.proto.component.audioout import AudioOutServiceStub, PlayRequest
+from viam.resource.rpc_client_base import ReconfigurableResourceRPCClientBase
+from viam.utils import ValueTypes, dict_to_struct, get_geometries, struct_to_dict
+
+from .audio_out import AudioInfo, AudioOut
+
+
+class AudioOutClient(AudioOut, ReconfigurableResourceRPCClientBase):
+    """gRPC client for AudioOut component."""
+
+    def __init__(self, name: str, channel: Channel) -> None:
+        self.channel = channel
+        self.client = AudioOutServiceStub(channel)
+        super().__init__(name)
+
+    async def play(
+        self,
+        data: bytes,
+        info: Optional[AudioInfo] = None,
+        *,
+        extra: Optional[Dict[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> None:
+        if extra is None:
+            extra = {}
+
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = PlayRequest(
+            name=self.name,
+            audio_data=data,
+            audio_info=info,
+            extra=dict_to_struct(extra),
+        )
+        await self.client.Play(request, timeout=timeout, metadata=md)
+
+    async def get_properties(
+        self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None, **kwargs
+    ) -> AudioOut.Properties:
+        if extra is None:
+            extra = {}
+
+        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 response
+
+    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/audio_out/service.py

@@ -0,0 +1,63 @@
+from grpclib.server import Stream
+
+from viam.proto.common import (
+    DoCommandRequest,
+    DoCommandResponse,
+    GetGeometriesRequest,
+    GetGeometriesResponse,
+    GetPropertiesRequest,
+    GetPropertiesResponse,
+)
+from viam.proto.component.audioout import (
+    AudioOutServiceBase,
+    PlayRequest,
+    PlayResponse,
+)
+from viam.resource.rpc_service_base import ResourceRPCServiceBase
+from viam.utils import dict_to_struct, struct_to_dict
+
+from .audio_out import AudioOut
+
+
+class AudioOutRPCService(AudioOutServiceBase, ResourceRPCServiceBase[AudioOut]):
+    """gRPC service for AudioOut component."""
+
+    RESOURCE_TYPE = AudioOut
+
+    async def Play(self, stream: Stream[PlayRequest, PlayResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        audio_out = self.get_resource(name)
+        # Check if audio_info was provided in the request
+        audio_info = request.audio_info if request.HasField("audio_info") else None
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        await audio_out.play(request.audio_data, audio_info, extra=struct_to_dict(request.extra), timeout=timeout, metadata=stream.metadata)
+        await stream.send_message(PlayResponse())
+
+    async def GetProperties(self, stream: Stream[GetPropertiesRequest, GetPropertiesResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        audio_out = self.get_resource(name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        properties = await audio_out.get_properties(extra=struct_to_dict(request.extra), timeout=timeout, metadata=stream.metadata)
+        await stream.send_message(properties)
+
+    async def DoCommand(self, stream: Stream[DoCommandRequest, DoCommandResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        audio_out = self.get_resource(request.name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        result = await audio_out.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
+        audio_out = self.get_resource(request.name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        geometries = await audio_out.get_geometries(extra=struct_to_dict(request.extra), timeout=timeout)
+        response = GetGeometriesResponse(geometries=geometries)
+        await stream.send_message(response)

viam/components/base/__init__.py

@@ -1,18 +1,13 @@
-from viam.proto.common import ActuatorStatus, Vector3
-from viam.proto.robot import Status
+from viam.proto.common import Vector3
 from viam.resource.registry import Registry, ResourceRegistration
-from viam.utils import message_to_struct
 
 from .base import Base
 from .client import BaseClient
 from .service import BaseRPCService
 
-__all__ = ["Base", "Vector3"]
+__all__ = [
+    "Base",
+    "Vector3",
+]
 
-
-async def create_status(component: Base) -> Status:
-    s = ActuatorStatus(is_moving=await component.is_moving())
-    return Status(name=Base.get_resource_name(component.name), status=message_to_struct(s))
-
-
-Registry.register_subtype(ResourceRegistration(Base, BaseRPCService, lambda name, channel: BaseClient(name, channel), create_status))
+Registry.register_api(ResourceRegistration(Base, BaseRPCService, lambda name, channel: BaseClient(name, channel)))

viam/components/base/base.py

@@ -1,7 +1,8 @@
 import abc
+from dataclasses import dataclass
 from typing import Any, Dict, Final, Optional
 
-from viam.resource.types import RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, Subtype
+from viam.resource.types import API, RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT
 
 from ..component_base import ComponentBase
 from . import Vector3
@@ -14,9 +15,23 @@ class Base(ComponentBase):
     This acts as an abstract base class for any drivers representing specific
     base implementations. This cannot be used on its own. If the ``__init__()`` function is
     overridden, it must call the ``super().__init__()`` function.
+
+    ::
+
+        from viam.components.base import Base
+
+    For more information, see `Base component <https://docs.viam.com/dev/reference/apis/components/base/>`_.
     """
 
-    SUBTYPE: Final = Subtype(RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, "base")
+    API: Final = API(  # pyright: ignore [reportIncompatibleVariableOverride]
+        RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_COMPONENT, "base"
+    )
+
+    @dataclass
+    class Properties:
+        width_meters: float
+        turning_radius_meters: float
+        wheel_circumference_meters: float
 
     @abc.abstractmethod
     async def move_straight(
@@ -34,11 +49,23 @@ class Base(ComponentBase):
         When ``distance`` or ``velocity`` is 0, the base will stop.
         This method blocks until completed or cancelled.
 
+        ::
+
+            my_base = Base.from_robot(robot=machine, name="my_base")
+
+            # Move the base 40 mm at a velocity of 90 mm/s, forward.
+            await my_base.move_straight(distance=40, velocity=90)
+
+            # Move the base 40 mm at a velocity of -90 mm/s, backward.
+            await my_base.move_straight(distance=40, velocity=-90)
+
         Args:
             distance (int): The distance (in millimeters) to move.
                 Negative implies backwards.
             velocity (float): The velocity (in millimeters per second) to move.
                 Negative implies backwards.
+
+        For more information, see `Base component <https://docs.viam.com/dev/reference/apis/components/base/#movestraight>`_.
         """
         ...
 
@@ -58,11 +85,20 @@ class Base(ComponentBase):
         When ``velocity`` is 0, the base will stop.
         This method blocks until completed or cancelled.
 
+        ::
+
+            my_base = Base.from_robot(robot=machine, name="my_base")
+
+            # Spin the base 10 degrees at an angular velocity of 15 deg/sec.
+            await my_base.spin(angle=10, velocity=15)
+
         Args:
             angle (float): The angle (in degrees) to spin.
-                Negative implies backwards.
-            velocity (float): The angular velocity (in degrees per second).
-                to spin. Negative implies backwards.
+            velocity (float): The angular velocity (in degrees per second)
+                to spin.
+                Given a positive angle and a positive velocity, the base will turn to the left.
+
+        For more information, see `Base component <https://docs.viam.com/dev/reference/apis/components/base/#spin>`_.
         """
         ...
 
@@ -77,17 +113,47 @@ class Base(ComponentBase):
         **kwargs,
     ):
         """Set the linear and angular velocity of the Base
-        When ``linear`` is 0, the the base will spin.
-        When ``angular`` is 0, the the base will move in a straight line.
+        When ``linear`` is 0, the base will spin.
+        When ``angular`` is 0, the base will move in a straight line.
         When both ``linear`` and ``angular`` are 0, the base will stop.
         When ``linear`` and ``angular`` are both nonzero, the base will move in an arc,
         with a tighter radius if angular power is greater than linear power.
 
+        ::
+
+            my_base = Base.from_robot(robot=machine, name="my_base")
+
+            # Make your wheeled base move forward. Set linear power to 75%.
+            print("move forward")
+            await my_base.set_power(
+                linear=Vector3(x=0, y=.75, z=0),
+                angular=Vector3(x=0, y=0, z=0))
+
+            # Make your wheeled base move backward. Set linear power to -100%.
+            print("move backward")
+            await my_base.set_power(
+                linear=Vector3(x=0, y=-1.0, z=0),
+                angular=Vector3(x=0, y=0, z=0))
+
+            # Make your wheeled base spin left. Set angular power to 100%.
+            print("spin left")
+            await my_base.set_power(
+                linear=Vector3(x=0, y=0, z=0),
+                angular=Vector3(x=0, y=0, z=1))
+
+            # Make your wheeled base spin right. Set angular power to -75%.
+            print("spin right")
+            await my_base.set_power(
+                linear=Vector3(x=0, y=0, z=0),
+                angular=Vector3(x=0, y=0, z=-.75))
+
         Args:
             linear (Vector3): The linear component. Only the Y component is used
-                for wheeled base. Negative implies backwards.
+                for wheeled base. Positive implies forwards.
             angular (Vector3): The angular component. Only the Z component is used
                 for wheeled base. Positive turns left; negative turns right.
+
+        For more information, see `Base component <https://docs.viam.com/dev/reference/apis/components/base/#setpower>`_.
         """
         ...
 
@@ -104,10 +170,20 @@ class Base(ComponentBase):
         """
         Set the linear and angular velocities of the base.
 
+        ::
+
+            my_base = Base.from_robot(robot=machine, name="my_base")
+
+            # Set the linear velocity to 50 mm/sec and the angular velocity to
+            # 15 degree/sec.
+            await my_base.set_velocity(
+                linear=Vector3(x=0, y=50, z=0), angular=Vector3(x=0, y=0, z=15))
 
         Args:
             linear (Vector3): Velocity in mm/sec
             angular (Vector3): Velocity in deg/sec
+
+        For more information, see `Base component <https://docs.viam.com/dev/reference/apis/components/base/#setvelocity>`_.
         """
 
     @abc.abstractmethod
@@ -120,6 +196,18 @@ class Base(ComponentBase):
     ):
         """
         Stop the base.
+
+        ::
+
+            my_base = Base.from_robot(robot=machine, name="my_base")
+
+            # Move the base forward 10 mm at a velocity of 50 mm/s.
+            await my_base.move_straight(distance=10, velocity=50)
+
+            # Stop the base.
+            await my_base.stop()
+
+        For more information, see `Base component <https://docs.viam.com/dev/reference/apis/components/base/#stop>`_.
         """
         ...
 
@@ -128,7 +216,45 @@ class Base(ComponentBase):
         """
         Get if the base is currently moving.
 
+        ::
+
+            my_base = Base.from_robot(robot=machine, name="my_base")
+
+            # Check whether the base is currently moving.
+            moving = await my_base.is_moving()
+            print('Moving: ', moving)
+
         Returns:
             bool: Whether the base is moving.
+
+        For more information, see `Base component <https://docs.viam.com/dev/reference/apis/components/base/#ismoving>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def get_properties(self, *, timeout: Optional[float] = None, **kwargs) -> Properties:
+        """
+        Get the base width and turning radius
+
+        ::
+
+            my_base = Base.from_robot(robot=machine, name="my_base")
+
+            # Get the width and turning radius of the base
+            properties = await my_base.get_properties()
+
+            # Get the width
+            print(f"Width of base: {properties.width_meters}")
+
+            # Get the turning radius
+            print(f"Turning radius of base: {properties.turning_radius_meters}")
+
+            # Get the wheel circumference
+            print(f"Wheel circumference of base: {properties.wheel_circumference_meters}")
+
+        Returns:
+            Properties: The properties of the base
+
+        For more information, see `Base component <https://docs.viam.com/dev/reference/apis/components/base/#getproperties>`_.
         """
         ...