Generic service API

The generic service API allows you to give commands to your generic services for running model-specific commands using DoCommand.

The generic service supports the following methods:

Method NameDescription
DoCommandExecute model-specific commands.
GetResourceNameGet the ResourceName for this instance of the generic service with the given name.
CloseSafely shut down the resource and prevent further use.

Establish a connection

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

When executed, this sample code creates a connection to your machine as a client.

from viam.services.generic import Generic

import (
  "go.viam.com/rdk/services/generic"
)

#include <viam/sdk/services/generic/generic.hpp>

API

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:

  • command (Mapping[str, ValueTypes]) (required): The command to execute.
  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

  • (Mapping[str, Any]): Result of the executed command.

Example:

service = Generic.from_robot(robot, "my_generic_service_svc")

my_command = {
  "cmnd": "dosomething",
  "someparameter": 52
}

# Can be used with any resource, using the motion service as an example
await service.do_command(command=my_command)

For more information, see the Python SDK Docs.

Parameters:

Returns:

Example:

myGenericService, err := generic.FromRobot(machine, "my_generic_service")

command := map[string]interface{}{"cmd": "test", "data1": 500}
result, err := myGenericService.DoCommand(context.Background(), command)

For more information, see the Go SDK Docs.

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

GetResourceName

Get the ResourceName for this instance of the generic service with the given name.

Parameters:

  • name (str) (required): The name of the Resource.

Returns:

Example:

my_generic_service_svc_name = Generic.get_resource_name("my_generic_service_svc")

For more information, see the Python SDK Docs.

Close

Safely shut down the resource and prevent further use.

Parameters:

  • None.

Returns:

  • None.

Example:

await my_generic_service.close()

For more information, see the Python 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.

Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.