Generic Service

The generic service subtype enables you to add support for unique types of services that do not already have an appropriate API defined for them.

For example, when writing code to manage simultaneous localization and mapping (SLAM) for your machine, it makes sense to use the existing SLAM API, which provides specific functionality required for generating accurate maps of an environment. However, if you want to create a new service to monitor your machine’s CPU and RAM usage for example, you need very different functionality that isn’t currently exposed in any API. Instead, you can use the generic service API to add support for your unique type of service, like local system monitoring, to your machine.

Use generic for a modular resource model that represents a unique type of service. If you are adding support for unique or proprietary hardware, rather than adding new high-level software functionality, use the generic component instead.

There are no built-in generic service models (other than fake).

Supported models

Built-in models

For configuration information, click on the model name:

ModelDescription
fakeA model used for testing a generic service.

Control your machine with Viam’s client SDK libraries

To get started using Viam’s SDKs to connect to and control your machine, navigate to your machine’s CONNECT tab on the Viam app and select the Code sample page. Select your preferred programming language, and copy the sample code generated.

When executed, this sample code will create a connection to your machine as a client. Then control your machine programmatically by getting your generic service from the machine with FromRobot and adding API method calls, as shown in the following examples.

Be sure to import the generic service package for the SDK you are using:

from viam.services.generic import Generic
import (
  "go.viam.com/rdk/services/generic"
)
#include <viam/sdk/services/generic/generic.hpp>

API

The generic service supports the following method:

Method NameDescription
DoCommandSend or receive model-specific commands.
CloseSafely shut down the resource and prevent further use.

DoCommand

Execute model-specific commands. If you are implementing your own generic service and add features that have no built-in API method, you can access them with DoCommand.

Parameters:

Returns:

my_generic = Generic.from_robot(robot=robot, name="my_generic_service")

raw_dict = {
  "command": "raw",
  "raw_input": "home"
}
await my_generic.do_command(raw_dict)

For more information, see the Python SDK Docs.

Parameters:

Returns:

resp, err := myGeneric.DoCommand(context.Background(), map[string]interface{}{"command": "example"})

For more information, see the Go SDK Code.

Parameters:

Returns:

auto my_generic = robot->resource_by_name<GenericService>("my_generic_service");
auto example = std::make_shared<ProtoType>(std::string("example"));
AttributeMap command =
    std::make_shared<std::unordered_map<std::string, std::shared_ptr<ProtoType>>>();
command->insert({{std::string("command"), example}});
auto resp = my_generic->do_command(command);

For more information, see the C++ SDK Docs

Close

Safely shut down the resource and prevent further use.

Parameters:

  • None

Returns:

  • None
my_generic = Generic.from_robot(robot, "my_generic")

await my_generic.close()

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

  • (error) : An error, if one occurred. Close will never return an error for a generic resource.
err := myGeneric.Close(context.Background())

For more information, see the Go SDK Docs.

There is no need to explicitly close a generic service’s resource in C++, as resource destruction is handled automatically by the generic service’s class destructor when variables exit scope.

Troubleshooting

You can find additional assistance in the Troubleshooting section.

You can also ask questions in the Community Discord and we will be happy to help.