viam-sdk 0.25.2__py3-none-linux_armv7l.whl → 0.62.0__py3-none-linux_armv7l.whl

viam/robot/client.py

@@ -1,4 +1,5 @@
 import asyncio
+import sys
 from dataclasses import dataclass
 from datetime import datetime
 from threading import RLock
@@ -16,23 +17,25 @@ from viam.proto.common import LogEntry, PoseInFrame, ResourceName, Transform
 from viam.proto.robot import (
     BlockForOperationRequest,
     CancelOperationRequest,
-    DiscoverComponentsRequest,
-    DiscoverComponentsResponse,
-    Discovery,
-    DiscoveryQuery,
     FrameSystemConfig,
     FrameSystemConfigRequest,
     FrameSystemConfigResponse,
     GetCloudMetadataRequest,
     GetCloudMetadataResponse,
+    GetMachineStatusRequest,
+    GetMachineStatusResponse,
+    GetModelsFromModulesRequest,
+    GetModelsFromModulesResponse,
     GetOperationsRequest,
     GetOperationsResponse,
-    GetStatusRequest,
-    GetStatusResponse,
+    GetVersionRequest,
+    GetVersionResponse,
     LogRequest,
+    ModuleModel,
     Operation,
     ResourceNamesRequest,
     ResourceNamesResponse,
+    RestartModuleRequest,
     RobotServiceStub,
     ShutdownRequest,
     StopAllRequest,
@@ -44,8 +47,8 @@ from viam.resource.base import ResourceBase
 from viam.resource.manager import ResourceManager
 from viam.resource.registry import Registry
 from viam.resource.rpc_client_base import ReconfigurableResourceRPCClientBase, ResourceRPCClientBase
-from viam.resource.types import RESOURCE_TYPE_COMPONENT, RESOURCE_TYPE_SERVICE, Subtype
-from viam.rpc.dial import DialOptions, ViamChannel, dial
+from viam.resource.types import API, RESOURCE_TYPE_COMPONENT, RESOURCE_TYPE_SERVICE
+from viam.rpc.dial import DialOptions, ViamChannel, _dial_inner, dial
 from viam.services.service_base import ServiceBase
 from viam.sessions_client import SessionsClient
 from viam.utils import datetime_to_timestamp, dict_to_struct
@@ -54,7 +57,7 @@ LOGGER = logging.getLogger(__name__)
 
 
 class RobotClient:
-    """gRPC client for a Robot. This class should be used for all interactions with a robot.
+    """gRPC client for a machine. This class should be used for all interactions with a machine.
 
     There are 2 ways to instantiate a robot client::
 
@@ -63,12 +66,12 @@ class RobotClient:
 
     You can use the client standalone or within a context::
 
-        robot = await RobotClient.at_address(...)
-        async with await RobotClient.with_channel(...) as robot: ...
+        machine = await RobotClient.at_address(...)
+        async with await RobotClient.with_channel(...) as machine: ...
 
-    You must ``close()`` the robot to release resources.
+    You must ``close()`` the machine to release resources.
 
-    Note: Robots used within a context are automatically closed UNLESS created with a channel. Robots created using ``with_channel`` are
+    Note: Machines used within a context are automatically closed UNLESS created with a channel. Machines created using ``with_channel`` are
     not automatically closed.
 
     Establish a Connection::
@@ -91,10 +94,10 @@ class RobotClient:
 
         async def main():
             # Make a RobotClient
-            robot = await connect()
+            machine = await connect()
             print('Resources:')
-            print(robot.resource_names)
-            await robot.close()
+            print(machine.resource_names)
+            await machine.close()
 
         if __name__ == '__main__':
             asyncio.run(main())
@@ -106,8 +109,8 @@ class RobotClient:
     class Options:
         refresh_interval: int = 0
         """
-        How often to refresh the status/parts of the robot in seconds.
-        If not set, the robot will not be refreshed automatically
+        How often to refresh the status of the parts of the machine in seconds.
+        If not set, the machine will not be refreshed automatically
         """
 
         dial_options: Optional[DialOptions] = None
@@ -122,12 +125,12 @@ class RobotClient:
 
         check_connection_interval: int = 10
         """
-        The frequency (in seconds) at which to check if the robot is still connected. 0 (zero) signifies no connection checks
+        The frequency (in seconds) at which to check if the machine is still connected. 0 (zero) signifies no connection checks
         """
 
         attempt_reconnect_interval: int = 1
         """
-        The frequency (in seconds) at which to attempt to reconnect a disconnected robot. 0 (zero) signifies no reconnection attempts
+        The frequency (in seconds) at which to attempt to reconnect a disconnected machine. 0 (zero) signifies no reconnection attempts
         """
 
         disable_sessions: bool = False
@@ -149,7 +152,7 @@ class RobotClient:
 
                 opts = RobotClient.Options.with_api_key(api_key, api_key_id)
 
-                robot = await RobotClient.at_address('<ADDRESS-FROM-THE-VIAM-APP>', opts)
+                machine = await RobotClient.at_address('<ADDRESS-FROM-THE-VIAM-APP>', opts)
 
             Args:
                 api_key (str): your API key
@@ -170,7 +173,7 @@ class RobotClient:
 
     @classmethod
     async def at_address(cls, address: str, options: Options) -> Self:
-        """Create a robot client that is connected to the robot at the provided address.
+        """Create a robot client that is connected to the machine at the provided address.
 
         ::
 
@@ -182,15 +185,15 @@ class RobotClient:
                     # Replace "<API-KEY-ID>" (including brackets) with your machine's API key ID
                     api_key_id='<API-KEY-ID>'
                 )
-                return await RobotClient.at_address('ADDRESS FROM THE VIAM APP', opts)
+                return await RobotClient.at_address('MACHINE ADDRESS', opts)
 
 
             async def main():
                 # Make a RobotClient
-                robot = await connect()
+                machine = await connect()
 
         Args:
-            address (str): Address of the robot (IP address, URL, etc.)
+            address (str): Address of the machine (IP address, URL, etc.)
             options (Options): Options for connecting and refreshing
 
         Returns:
@@ -200,15 +203,15 @@ class RobotClient:
         """
         logging.setLevel(options.log_level)
         channel = await dial(address, options.dial_options)
-        robot = await cls._with_channel(channel, options, True)
-        robot._address = address
-        return robot
+        machine = await cls._with_channel(channel, options, True, robot_addr=address)
+        machine._address = address
+        return machine
 
     @classmethod
     async def with_channel(cls, channel: Union[Channel, ViamChannel], options: Options) -> Self:
-        """Create a robot that is connected to a robot over the given channel.
+        """Create a machine that is connected to a machine over the given channel.
 
-        Any robots created using this method will *NOT* automatically close the channel upon exit.
+        Any machines created using this method will *NOT* automatically close the channel upon exit.
 
         ::
 
@@ -220,10 +223,10 @@ class RobotClient:
                 async with await dial('ADDRESS', DialOptions()) as channel:
                     return await RobotClient.with_channel(channel, RobotClient.Options())
 
-            robot = await connect_with_channel()
+            machine = await connect_with_channel()
 
         Args:
-            channel (ViamChannel): The channel that is connected to a robot, obtained by ``viam.rpc.dial``
+            channel (ViamChannel): The channel that is connected to a machine, obtained by ``viam.rpc.dial``
             options (Options): Options for refreshing. Any connection options will be ignored.
 
         Returns:
@@ -235,7 +238,9 @@ class RobotClient:
         return await cls._with_channel(channel, options, False)
 
     @classmethod
-    async def _with_channel(cls, channel: Union[Channel, ViamChannel], options: Options, close_channel: bool):
+    async def _with_channel(
+        cls, channel: Union[Channel, ViamChannel], options: Options, close_channel: bool, robot_addr: Optional[str] = None
+    ):
         """INTERNAL USE ONLY"""
 
         self = cls()
@@ -256,15 +261,15 @@ class RobotClient:
         self._options = options
         self._address = self._channel._path if self._channel._path else f"{self._channel._host}:{self._channel._port}"
         self._sessions_client = SessionsClient(
-            self._channel, self._address, self._options.dial_options, disabled=self._options.disable_sessions
+            self._channel, self._address, self._options.dial_options, disabled=self._options.disable_sessions, robot_addr=robot_addr
         )
 
         try:
             await self.refresh()
         except Exception:
-            LOGGER.error("Unable to establish a connection to the robot. Ensure the robot is online and reachable and try again.")
+            LOGGER.error("Unable to establish a connection to the machine. Ensure the machine is online and reachable and try again.")
             await self.close()
-            raise ConnectionError("Unable to establish a connection to the robot.")
+            raise ConnectionError("Unable to establish a connection to the machine.")
 
         if options.refresh_interval > 0:
             self._refresh_task = asyncio.create_task(
@@ -296,11 +301,11 @@ class RobotClient:
 
     async def refresh(self):
         """
-        Manually refresh the underlying parts of this robot
+        Manually refresh the underlying parts of this machine.
 
         ::
 
-            await robot.refresh()
+            await machine.refresh()
 
         For more information, see `Machine Management API <https://docs.viam.com/appendix/apis/robot/>`_.
         """
@@ -337,12 +342,12 @@ class RobotClient:
             else:
                 await self._manager.remove_resource(resourceName)
                 self._manager.register(
-                    Registry.lookup_subtype(Subtype.from_resource_name(resourceName)).create_rpc_client(resourceName.name, self._channel)
+                    Registry.lookup_api(API.from_resource_name(resourceName)).create_rpc_client(resourceName.name, self._channel)
                 )
         else:
             try:
                 self._manager.register(
-                    Registry.lookup_subtype(Subtype.from_resource_name(resourceName)).create_rpc_client(resourceName.name, self._channel)
+                    Registry.lookup_api(API.from_resource_name(resourceName)).create_rpc_client(resourceName.name, self._channel)
                 )
             except ResourceNotFoundError:
                 pass
@@ -375,7 +380,7 @@ class RobotClient:
                     connection_error = e
                     await asyncio.sleep(0.1)
             if connection_error:
-                msg = "Lost connection to robot."
+                msg = "Lost connection to machine."
                 if reconnect_every > 0:
                     msg += (
                         f" Attempting to reconnect to {self._address} every {reconnect_every} second{'s' if reconnect_every != 1 else ''}"
@@ -396,7 +401,7 @@ class RobotClient:
                 try:
                     self._sessions_client.reset()
 
-                    channel = await dial(self._address, self._options.dial_options)
+                    channel = await _dial_inner(self._address, self._options.dial_options)
 
                     client: RobotServiceStub
                     if isinstance(channel, Channel):
@@ -418,17 +423,21 @@ class RobotClient:
                         direct_dial_address=direct_dial_address,
                         dial_options=self._options.dial_options,
                         disabled=self._options.disable_sessions,
+                        robot_addr=self._address,
                     )
 
                     await self.refresh()
                     self._connected = True
-                    LOGGER.debug("Successfully reconnected robot")
+                    LOGGER.debug("Successfully reconnected machine")
                     break
                 except Exception as e:
                     LOGGER.error(f"Failed to reconnect, trying again in {reconnect_every}sec", exc_info=e)
                     self._sessions_client.reset()
                     self._close_channel()
                     await asyncio.sleep(reconnect_every)
+            if not self._connected:
+                # We failed to reconnect, sys.exit() so that this thread doesn't stick around forever.
+                sys.exit()
 
     def get_component(self, name: ResourceName) -> ComponentBase:
         """Get a component using its ResourceName.
@@ -437,7 +446,7 @@ class RobotClient:
         method for obtaining components.
         ::
 
-            arm = Arm.from_robot(robot=robot, name="my_arm")
+            arm = Arm.from_robot(robot=machine, name="my_arm")
 
         Because this function returns a generic ``ComponentBase`` rather than the specific
         component type, it will be necessary to cast the returned component to the desired component. This can be done using a few
@@ -445,14 +454,14 @@ class RobotClient:
 
         - Assertion::
 
-            arm = robot.get_component(Arm.get_resource_name("my_arm"))
+            arm = machine.get_component(Arm.get_resource_name("my_arm"))
             assert isinstance(arm, Arm)
             end_pos = await arm.get_end_position()
 
         - Explicit cast::
 
             from typing import cast
-            arm = robot.get_component(Arm.get_resource_name("my_arm"))
+            arm = machine.get_component(Arm.get_resource_name("my_arm"))
             arm = cast(Arm, arm)
             end_pos = await arm.get_end_position()
 
@@ -461,7 +470,7 @@ class RobotClient:
             - Note: If using an IDE, a type error may be shown which can be ignored.
             ::
 
-                arm: Arm = robot.get_component(Arm.get_resource_name("my_arm"))  # type: ignore
+                arm: Arm = machine.get_component(Arm.get_resource_name("my_arm"))  # type: ignore
                 end_pos = await arm.get_end_position()
 
         Args:
@@ -488,20 +497,20 @@ class RobotClient:
         method for obtaining services.
         ::
 
-            service = MyService.from_robot(robot=robot, name="my_service")
+            service = MyService.from_robot(robot=machine, name="my_service")
 
         Because this function returns a generic ``ServiceBase`` rather than a specific service type, it will be necessary to cast the
         returned service to the desired service. This can be done using a few methods:
 
         - Assertion::
 
-            service = robot.get_service(MyService.get_resource_name("my_service"))
+            service = machine.get_service(MyService.get_resource_name("my_service"))
             assert isinstance(service, MyService)
 
         - Explicit cast::
 
             from typing import cast
-            service = robot.get_service(MyService.get_resource_name("my_service"))
+            service = machine.get_service(MyService.get_resource_name("my_service"))
             service = cast(MyService, my_service)
 
         - Declare type on variable assignment
@@ -509,7 +518,7 @@ class RobotClient:
             - Note: If using an IDE, a type error may be shown which can be ignored.
             ::
 
-                service: MyService = robot.get_service(MyService.get_resource_name("my_service"))  # type: ignore
+                service: MyService = machine.get_service(MyService.get_resource_name("my_service"))  # type: ignore
 
         Args:
             name (viam.proto.common.ResourceName): The service's ResourceName
@@ -535,7 +544,7 @@ class RobotClient:
 
         ::
 
-            resource_names = robot.resource_names
+            resource_names = machine.resource_names
 
         Returns:
             List[viam.proto.common.ResourceName]: The list of resource names
@@ -560,7 +569,7 @@ class RobotClient:
 
         ::
 
-            await robot.close()
+            await machine.close()
 
         For more information, see `Machine Management API <https://docs.viam.com/appendix/apis/robot/>`_.
         """
@@ -596,44 +605,20 @@ class RobotClient:
     async def __aexit__(self, exc_type, exc_value, traceback):
         await self.close()
 
-    ##########
-    # STATUS #
-    ##########
-    async def get_status(self, components: Optional[List[ResourceName]] = None):
-        """
-        Get the status of the robot's components. You can optionally
-        provide a list of ``ResourceName`` for which you want statuses.
-
-        ::
-
-            # Get the status of the resources on the machine.
-            statuses = await robot.get_status()
-
-        Args:
-            components (Optional[List[viam.proto.common.ResourceName]]): Optional list of
-                ``ResourceName`` for components you want statuses.
-
-        For more information, see `Machine Management API <https://docs.viam.com/appendix/apis/robot/>`_.
-        """
-        names = components if components is not None else []
-        request = GetStatusRequest(resource_names=names)
-        response: GetStatusResponse = await self._client.GetStatus(request)
-        return list(response.status)
-
     ##############
     # OPERATIONS #
     ##############
 
     async def get_operations(self) -> List[Operation]:
         """
-        Get the list of operations currently running on the robot.
+        Get the list of operations currently running on the machine.
 
         ::
 
-            operations = await robot.get_operations()
+            operations = await machine.get_operations()
 
         Returns:
-            List[viam.proto.robot.Operation]: The list of operations currently running on a given robot.
+            List[viam.proto.robot.Operation]: The list of operations currently running on a given machine.
 
         For more information, see `Machine Management API <https://docs.viam.com/appendix/apis/robot/>`_.
         """
@@ -643,11 +628,11 @@ class RobotClient:
 
     async def cancel_operation(self, id: str):
         """
-        Cancels the specified operation on the robot.
+        Cancels the specified operation on the machine.
 
         ::
 
-            await robot.cancel_operation("INSERT OPERATION ID")
+            await machine.cancel_operation("INSERT OPERATION ID")
 
         Args:
             id (str): ID of operation to cancel.
@@ -659,12 +644,12 @@ class RobotClient:
 
     async def block_for_operation(self, id: str):
         """
-        Blocks on the specified operation on the robot. This function will only return when the specific operation
+        Blocks on the specified operation on the machine. This function will only return when the specific operation
         has finished or has been cancelled.
 
         ::
 
-            await robot.block_for_operation("INSERT OPERATION ID")
+            await machine.block_for_operation("INSERT OPERATION ID")
 
         Args:
             id (str): ID of operation to block on.
@@ -680,16 +665,16 @@ class RobotClient:
 
     async def get_frame_system_config(self, additional_transforms: Optional[List[Transform]] = None) -> List[FrameSystemConfig]:
         """
-        Get the configuration of the frame system of a given robot.
+        Get the configuration of the frame system of a given machine.
 
         ::
 
             # Get a list of each of the reference frames configured on the machine.
-            frame_system = await robot.get_frame_system_config()
+            frame_system = await machine.get_frame_system_config()
             print(f"frame system configuration: {frame_system}")
 
         Returns:
-            List[viam.proto.robot.FrameSystemConfig]: The configuration of a given robot's frame system.
+            List[viam.proto.robot.FrameSystemConfig]: The configuration of a given machine's frame system.
 
         For more information, see `Machine Management API <https://docs.viam.com/appendix/apis/robot/>`_.
         """
@@ -705,7 +690,24 @@ class RobotClient:
 
         ::
 
-            pose = await robot.transform_pose(PoseInFrame(), "origin")
+            from viam.proto.common import Pose, PoseInFrame
+
+            pose = Pose(
+                x=1.0,    # X coordinate in mm
+                y=2.0,    # Y coordinate in mm
+                z=3.0,    # Z coordinate in mm
+                o_x=0.0,  # X component of orientation vector
+                o_y=0.0,  # Y component of orientation vector
+                o_z=0.0,  # Z component of orientation vector
+                theta=0.0 # Orientation angle in degrees
+            )
+
+            pose_in_frame = PoseInFrame(
+                reference_frame="world",
+                pose=pose
+            )
+
+            transformed_pose = await machine.transform_pose(pose_in_frame, "world")
 
         Args:
 
@@ -724,40 +726,30 @@ class RobotClient:
     async def transform_point_cloud(self):
         raise NotImplementedError()
 
-    #######################
-    # COMPONENT DISCOVERY #
-    #######################
+    #################
+    # MODULE MODELS #
+    #################
 
-    async def discover_components(
+    async def get_models_from_modules(
         self,
-        queries: List[DiscoveryQuery],
-    ) -> List[Discovery]:
+    ) -> List[ModuleModel]:
         """
-        Get the list of discovered component configurations.
+        Get a list of all models provided by local and registry modules on the machine.
+        This includes models that are not currently configured on the machine.
 
         ::
 
-            # Define a new discovery query.
-            q = robot.DiscoveryQuery(subtype=acme.API, model="some model")
-
-            # Define a list of discovery queries.
-            qs = [q]
-
-            # Get component configurations with these queries.
-            component_configs = await robot.discover_components(qs)
+            # Get module models
+            module_models = await machine.get_models_from_modules(qs)
 
         Args:
 
-            queries (List[viam.proto.robot.DiscoveryQuery]): The list of component models to lookup configurations for.
-
         Returns:
-            List[Discovery]: A list of discovered component configurations.
-
-        For more information, see `Machine Management API <https://docs.viam.com/appendix/apis/robot/>`_.
+            List[ModuleModel]: A list of discovered models.
         """
-        request = DiscoverComponentsRequest(queries=queries)
-        response: DiscoverComponentsResponse = await self._client.DiscoverComponents(request)
-        return list(response.discovery)
+        request = GetModelsFromModulesRequest()
+        response: GetModelsFromModulesResponse = await self._client.GetModelsFromModules(request)
+        return list(response.models)
 
     ############
     # STOP ALL #
@@ -765,16 +757,12 @@ class RobotClient:
 
     async def stop_all(self, extra: Dict[ResourceName, Dict[str, Any]] = {}):
         """
-        Cancel all current and outstanding operations for the robot and stop all actuators and movement.
+        Cancel all current and outstanding operations for the machine and stop all actuators and movement.
 
         ::
 
-            # Cancel all current and outstanding operations for the robot and stop all actuators and movement.
-            await robot.stop_all()
-
-        ::
-
-            await robot.stop_all()
+            # Cancel all current and outstanding operations for the machine and stop all actuators and movement.
+            await machine.stop_all()
 
         Args:
             extra (Dict[viam.proto.common.ResourceName, Dict[str, Any]]): Any extra parameters to pass to the resources' ``stop`` methods,
@@ -817,11 +805,11 @@ class RobotClient:
 
     async def get_cloud_metadata(self) -> GetCloudMetadataResponse:
         """
-        Get app-related information about the robot.
+        Get app-related information about the machine.
 
         ::
 
-            metadata = machine.get_cloud_metadata()
+            metadata = await machine.get_cloud_metadata()
             print(metadata.machine_id)
             print(metadata.machine_part_id)
             print(metadata.primary_org_id)
@@ -844,10 +832,14 @@ class RobotClient:
         """
         Shutdown shuts down the machine.
 
+        ::
+
+            await machine.shutdown()
+
         Raises:
             GRPCError: Raised with DeadlineExceeded status if shutdown request times out, or if
-              robot server shuts down before having a chance to send a response. Raised with
-              status Unavailable if server is unavailable, or if robot server is in the process of
+              the machine server shuts down before having a chance to send a response. Raised with
+              status Unavailable if server is unavailable, or if machine server is in the process of
               shutting down when response is ready.
 
         For more information, see `Machine Management API <https://docs.viam.com/appendix/apis/robot/>`_.
@@ -867,3 +859,79 @@ class RobotClient:
                 raise e
             else:
                 raise e
+
+    ######################
+    # Get Version #
+    ######################
+
+    async def get_version(self) -> GetVersionResponse:
+        """
+        Get version information about the machine.
+
+        ::
+
+            result = await machine.get_version()
+            print(result.platform)
+            print(result.version)
+            print(result.api_version)
+
+        Returns:
+            viam.proto.robot.GetVersionResponse: Machine version related information.
+
+        For more information, see `Machine Management API <https://docs.viam.com/appendix/apis/robot/>`_.
+        """
+
+        request = GetVersionRequest()
+        return await self._client.GetVersion(request)
+
+    ######################
+    # Get Machine Status #
+    ######################
+
+    async def get_machine_status(self) -> GetMachineStatusResponse:
+        """
+        Get status information about the machine's resources and configuration.
+
+        ::
+
+            machine_status = await machine.get_machine_status()
+            machine_state = machine_status.state
+            resource_statuses = machine_status.resources
+            cloud_metadata = machine_status.resources[0].cloud_metadata
+            config_status = machine_status.config
+
+        Returns:
+            viam.proto.robot.GetMachineStatusResponse: current status of the machine (initializing or running), current status of the resources (List[ResourceStatus]) and the revision of the config of the machine.
+
+        For more information, see `Machine Management API <https://docs.viam.com/appendix/apis/robot/>`_.
+        """
+
+        request = GetMachineStatusRequest()
+        return await self._client.GetMachineStatus(request)
+
+    ##################
+    # Restart Module #
+    ##################
+
+    async def restart_module(self, id: Optional[str] = None, name: Optional[str] = None):
+        """
+        Restarts a module running on the machine with the given id or name.
+
+        ::
+
+            await machine.restart_module(id="namespace:module:model", name="my_model")
+
+        Args:
+            id (str): The id matching the module_id field of the registry module in your part configuration.
+            name (str): The name matching the name field of the local/registry module in your part configuration.
+
+        Raises:
+            GRPCError: If a module can't be found matching the provided ID or name.
+
+        For more information, see `Machine Management API <https://docs.viam.com/appendix/apis/robot/>`_.
+        """
+
+        id = id if id else ""
+        name = name if name else ""
+        request = RestartModuleRequest(module_id=id, module_name=name)
+        await self._client.RestartModule(request)