[RSDK-2227] Modular Services (#237)

Author: njooma

Makefile

@@ -2,7 +2,7 @@ clean:
 	find . -type d -name '__pycache__' | xargs rm -rf
 
 _lint:
-	flake8 --exclude=**/gen/**,*_grpc.py,*_pb2.py,*_pb2.pyi
+	flake8 --exclude=**/gen/**,*_grpc.py,*_pb2.py,*_pb2.pyi,.tox
 
 lint:
 	poetry run make _lint

examples/module/README

@@ -9,12 +9,14 @@ Modular resources allows you to define custom components and services, and add t
 For more information, see the [documentation](https://docs.viam.com/program/extend/modular-resources/).
 
 ## Project structure
-The definition of the new resources are in the `src` directory. Within this directory are the `proto` and `gizmo` subdirectories.
+The definition of the new resources are in the `src` directory. Within this directory are the `proto`, `gizmo`, and `summation` subdirectories.
 
-The `proto` directory contains the `gizmo.proto` definition of all the message types and calls that can be made to the component. It also has the compiled python output of the protobuf definition.
+The `proto` directory contains the `gizmo.proto` and `summation.proto` definitions of all the message types and calls that can be made to the Gizmo component and Summation service. It also has the compiled python output of the protobuf definition.
 
 The `gizmo` directory contains all the necessary definitions for creating a custom `Gizmo` component type. The `api.py` file defines what a `Gizmo` can do (mirroring the `proto` definition), implements the gRPC `GizmoService` for receiving calls, and the gRPC `GizmoClient` for making calls. See the [API docs](https://docs.viam.com/program/extend/modular-resources/#apis) for more info. The `my_gizmo.py` file in contains the unique implementation of a `Gizmo`. This is defined as a specific `Model`. See the [Model docs](https://docs.viam.com/program/extend/modular-resources/#models) for more info.
 
+Similarly, the `summation` directory contains the analogous definitions for the `Summation` service type. The files in this directory mirror the files in the `gizmo` directory.
+
 There is also a `main.py` file, which creates a module, adds the desired resources, and starts the module. This file is called by the `run.sh` script, which is the entrypoint for this module. Read further to learn how to connect this module to your robot.
 
 Outside the `src` directory, there is the `client.py` file. This can be used to test the module once it's connected to the robot. You will have to update the credentials and robot address in that file.
@@ -24,9 +26,9 @@ These steps assume that you have a robot available at [app.viam.com](app.viam.co
 
 The `run.sh` script is the entrypoint for this module. To connect this module with your robot, you must add this module's entrypoint to the robot's config. For example, this could be `/home/viam-python-sdk/examples/module/run.sh`. See the [documentation](https://docs.viam.com/program/extend/modular-resources/#use-a-modular-resource-with-your-robot) for more details.
 
-Once the module has been added to your robot, you will then need to add a component that uses the `MyGizmo` model. See the [documentation](https://docs.viam.com/program/extend/modular-resources/#configure-a-component-instance-for-a-modular-resource) for more details.
+Once the module has been added to your robot, you will then need to add a component that uses the `MyGizmo` model. See the [documentation](https://docs.viam.com/program/extend/modular-resources/#configure-a-component-instance-for-a-modular-resource) for more details. You can add a service in a similar manner.
 
-An example configuration for a Gizmo could look like this:
+An example configuration for a Gizmo component and a Summation service could look like this:
 ```json
 {
   "components": [
@@ -41,11 +43,24 @@ An example configuration for a Gizmo could look like this:
       "depends_on": []
     }
   ],
+  "services": [
+    {
+      "name": "mysum1",
+      "type": "summation",
+      "namespace": "acme",
+      "model": "acme:demo:mysum",
+      "attributes": {
+        "subtract": false
+      }
+    }
+  ],
   "modules": [
     {
-      "name": "gizmo-module",
+      "name": "my-module",
       "executable_path": "/home/viam-python-sdk/examples/module/run.sh"
     }
   ]
 }
 ```
+
+After the robot has started and connected to the module, you can use the provided `client.py` to connect to your robot and make calls to your custom, modular resources.Ø

examples/module/client.py

@@ -1,6 +1,7 @@
 import asyncio
 
 from src.gizmo import Gizmo
+from src.summation import SummationService
 
 from viam import logging
 from viam.robot.client import RobotClient
@@ -19,6 +20,7 @@ async def main():
     print("Resources:")
     print(robot.resource_names)
 
+    # ####### GIZMO ####### #
     gizmo = Gizmo.from_robot(robot, name="gizmo1")
     resp = await gizmo.do_one("arg1")
     print("do_one result:", resp)
@@ -38,6 +40,11 @@ async def main():
     # resp = await gizmo.do_one_bidi_stream(["arg1", "arg2", "arg3"])
     # print("do_one_bidi_stream result:", resp)
 
+    # ####### SUMMATION ####### #
+    summer = SummationService.from_robot(robot, name="mysum1")
+    sum = await summer.sum([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
+    print(f"The sum of the numbers [0, 10) is {sum}")
+
     await robot.close()
 
 

examples/module/src/gizmo/__init__.py

@@ -9,4 +9,4 @@
 
 Registry.register_subtype(ResourceRegistration(Gizmo, GizmoService, lambda name, channel: GizmoClient(name, channel)))
 
-Registry.register_component_model(Gizmo.SUBTYPE, MyGizmo.MODEL, MyGizmo.new)
+Registry.register_resource_creator(Gizmo.SUBTYPE, MyGizmo.MODEL, MyGizmo.new)

examples/module/src/gizmo/api.py

@@ -5,31 +5,32 @@
 the gRPC service that will handle calls to the component,
 and the gRPC client that will be able to make calls to this component.
 
-In this example, the ```Gizmo``` abstract class defines what functionality is required for all Gizmos. It extends ```BaseComponent```,
-as all component types must. It also defines its specific ```SUBTYPE```, which is used internally to keep track of supported types.
+In this example, the ``Gizmo`` abstract class defines what functionality is required for all Gizmos. It extends ``ComponentBase``,
+as all component types must. It also defines its specific ``SUBTYPE``, which is used internally to keep track of supported types.
 
-The ```GizmoService``` implements the gRPC service for the Gizmo. This will allow other robots and clients to make requests of the Gizmo.
-It extends both from ```GizmoServiceBase``` and ```ComponentServiceBase[Gizmo]```. The former is the gRPC service as defined by the proto,
+The ``GizmoService`` implements the gRPC service for the Gizmo. This will allow other robots and clients to make requests of the Gizmo.
+It extends both from ``GizmoServiceBase`` and ``ResourceRPCServiceBase[Gizmo]``. The former is the gRPC service as defined by the proto,
 and the latter is the class that all gRPC services for components must inherit from.
 
-Finally, the ```GizmoClient``` is the gRPC client for a Gizmo. It inherits from Gizmo since it implements all the same functions. The
+Finally, the ``GizmoClient`` is the gRPC client for a Gizmo. It inherits from Gizmo since it implements all the same functions. The
 implementations are simply gRPC calls to some remote Gizmo.
 
 To see how this custom modular component is registered, see the __init__.py file.
 To see the custom implementation of this component, see the my_gizmo.py file.
 """
 
 import abc
-from typing import Any, Dict, Final, List, Optional, Sequence
+from typing import Final, List, Mapping, Optional, Sequence
 
 from grpclib.client import Channel
 from grpclib.server import Stream
 
 from viam.components.component_base import ComponentBase
 from viam.components.generic.client import do_command
-from viam.components.service_base import ComponentServiceBase
 from viam.errors import ResourceNotFoundError
+from viam.resource.rpc_service_base import ResourceRPCServiceBase
 from viam.resource.types import RESOURCE_TYPE_COMPONENT, Subtype
+from viam.utils import ValueTypes
 
 from ..proto.gizmo_grpc import GizmoServiceBase, GizmoServiceStub
 from ..proto.gizmo_pb2 import (
@@ -72,7 +73,7 @@ async def do_two(self, arg1: bool, **kwargs) -> str:
         ...
 
 
-class GizmoService(GizmoServiceBase, ComponentServiceBase[Gizmo]):
+class GizmoService(GizmoServiceBase, ResourceRPCServiceBase[Gizmo]):
     """Example gRPC service for the Gizmo component"""
 
     RESOURCE_TYPE = Gizmo
@@ -82,7 +83,7 @@ async def DoOne(self, stream: Stream[DoOneRequest, DoOneResponse]) -> None:
         assert request is not None
         name = request.name
         try:
-            gizmo = self.get_component(name)
+            gizmo = self.get_resource(name)
         except ResourceNotFoundError as e:
             raise e.grpc_error
         resp = await gizmo.do_one(request.arg1)
@@ -97,7 +98,7 @@ async def DoOneClientStream(self, stream: Stream[DoOneClientStreamRequest, DoOne
             raise Exception("Unexpectedly received requests for multiple Gizmos")
         name = names[0]
         try:
-            gizmo = self.get_component(name)
+            gizmo = self.get_resource(name)
         except ResourceNotFoundError as e:
             raise e.grpc_error
         resp = await gizmo.do_one_client_stream(args)
@@ -109,7 +110,7 @@ async def DoOneServerStream(self, stream: Stream[DoOneServerStreamRequest, DoOne
         assert request is not None
         name = request.name
         try:
-            gizmo = self.get_component(name)
+            gizmo = self.get_resource(name)
         except ResourceNotFoundError as e:
             raise e.grpc_error
         resps = await gizmo.do_one_server_stream(request.arg1)
@@ -127,7 +128,7 @@ async def DoOneBiDiStream(self, stream: Stream[DoOneBiDiStreamRequest, DoOneBiDi
             if name != request.name:
                 raise Exception("Unexpectedly received requests for multiple Gizmos")
         try:
-            gizmo = self.get_component(name)
+            gizmo = self.get_resource(name)
         except ResourceNotFoundError as e:
             raise e.grpc_error
 
@@ -140,7 +141,7 @@ async def DoTwo(self, stream: Stream[DoTwoRequest, DoTwoResponse]) -> None:
         assert request is not None
         name = request.name
         try:
-            gizmo = self.get_component(name)
+            gizmo = self.get_resource(name)
         except ResourceNotFoundError as e:
             raise e.grpc_error
         resp = await gizmo.do_two(request.arg1)
@@ -191,8 +192,8 @@ async def do_two(self, arg1: bool) -> str:
 
     async def do_command(
         self,
-        command: Dict[str, Any],
+        command: Mapping[str, ValueTypes],
         *,
         timeout: Optional[float] = None,
-    ) -> Dict[str, Any]:
+    ) -> Mapping[str, ValueTypes]:
         return await do_command(self.channel, self.name, command, timeout=timeout)

examples/module/src/gizmo/my_gizmo.py

@@ -2,28 +2,28 @@
 
 from typing_extensions import Self
 
-from viam.components.component_base import ComponentBase
 from viam.module.types import Reconfigurable
 from viam.proto.app.robot import ComponentConfig
 from viam.proto.common import ResourceName
+from viam.resource.base import ResourceBase
 from viam.resource.types import Model, ModelFamily
 
 from ..gizmo.api import Gizmo
 
 
 class MyGizmo(Gizmo, Reconfigurable):
-    """This is the specific implementation of a ```Gizmo``` (defined in api.py).
+    """This is the specific implementation of a ``Gizmo`` (defined in api.py).
 
-    It inherits from Gizmo, as well conforms to the ```Reconfigurable``` protocol, which signifies that this component can be reconfigured.
-    It also specifies a function ```MyGizmo.new```, which conforms to the ```resource.types.ComponentCreator``` type, which is required
+    It inherits from Gizmo, as well conforms to the ``Reconfigurable`` protocol, which signifies that this component can be reconfigured.
+    It also specifies a function ``MyGizmo.new``, which conforms to the ``resource.ComponentCreator`` type, which is required
     for all models.
     """
 
     MODEL: ClassVar[Model] = Model(ModelFamily("acme", "demo"), "mygizmo")
     my_arg: str
 
     @classmethod
-    def new(cls, dependencies: Mapping[ResourceName, ComponentBase], config: ComponentConfig) -> Self:
+    def new(cls, config: ComponentConfig, dependencies: Mapping[ResourceName, ResourceBase]) -> Self:
         gizmo = cls(config.name)
         gizmo.my_arg = config.attributes.fields["arg1"].string_value
         return gizmo
@@ -51,5 +51,5 @@ async def do_one_bidi_stream(self, arg1: Sequence[str], **kwargs) -> Sequence[bo
     async def do_two(self, arg1: bool, **kwargs) -> str:
         return f"arg1={arg1}"
 
-    def reconfigure(self, config: ComponentConfig, dependencies: Mapping[ResourceName, ComponentBase]):
+    def reconfigure(self, config: ComponentConfig, dependencies: Mapping[ResourceName, ResourceBase]):
         self.my_arg = config.attributes.fields["arg1"].string_value

examples/module/src/main.py

@@ -4,6 +4,7 @@
 from viam.module.module import Module
 
 from .gizmo import Gizmo, MyGizmo
+from .summation import MySummationService, SummationService
 
 
 async def main(address: str):
@@ -16,6 +17,7 @@ async def main(address: str):
 
     module = Module(address)
     module.add_model_from_registry(Gizmo.SUBTYPE, MyGizmo.MODEL)
+    module.add_model_from_registry(SummationService.SUBTYPE, MySummationService.MODEL)
     await module.start()
 
 

examples/module/src/proto/summation.proto

@@ -0,0 +1,22 @@
+syntax = "proto3";
+
+package acme.service.summation.v1;
+
+import "google/api/annotations.proto";
+
+service SummationService {
+  rpc Sum(SumRequest) returns (SumResponse) {
+    option (google.api.http) = {
+      post: "/acme/api/v1/service/summation/{name}/sum"
+    };
+  }
+}
+
+message SumRequest {
+  string name = 1;
+  repeated double numbers = 2;
+}
+
+message SumResponse {
+  double sum = 1;
+}

examples/module/src/proto/summation_grpc.py

@@ -0,0 +1,40 @@
+# Generated by the Protocol Buffers compiler. DO NOT EDIT!
+# source: src/proto/summation.proto
+# plugin: grpclib.plugin.main
+import abc
+import typing
+
+import grpclib.const
+import grpclib.client
+
+if typing.TYPE_CHECKING:
+    import grpclib.server
+
+import google.api.annotations_pb2
+from .. import proto
+
+
+class SummationServiceBase(abc.ABC):
+    @abc.abstractmethod
+    async def Sum(self, stream: "grpclib.server.Stream[proto.summation_pb2.SumRequest, proto.summation_pb2.SumResponse]") -> None:
+        pass
+
+    def __mapping__(self) -> typing.Dict[str, grpclib.const.Handler]:
+        return {
+            "/acme.service.summation.v1.SummationService/Sum": grpclib.const.Handler(
+                self.Sum,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                proto.summation_pb2.SumRequest,
+                proto.summation_pb2.SumResponse,
+            ),
+        }
+
+
+class SummationServiceStub:
+    def __init__(self, channel: grpclib.client.Channel) -> None:
+        self.Sum = grpclib.client.UnaryUnaryMethod(
+            channel,
+            "/acme.service.summation.v1.SummationService/Sum",
+            proto.summation_pb2.SumRequest,
+            proto.summation_pb2.SumResponse,
+        )