Edit

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 Name	Description
`DoCommand`	Execute model-specific commands.
`GetResourceName`	Get the `ResourceName` for this instance of the generic service with the given name.
`Close`	Safely 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.

To show your machine’s API key in the sample code, toggle Include API key.

Caution: Keep your API key and machine address safe

We strongly recommend that you add your API key and machine address as an environment variable. Anyone with these secrets can access your machine, and the computer running your machine.

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.

Python
Go

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=machine, "my_generic_service_svc")

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

await service.do_command(command=my_command)

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.
cmd (map[string]interface{}): The command to execute.

Returns:

(map[string]interface{}): The command response.
(error): An error, if one occurred.

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.

GetResourceName

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

Python

Parameters:

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

Returns:

(viam.proto.common.ResourceName): The ResourceName of this Resource.

Example:

my_generic_service_name = Generic.get_resource_name("my_generic_service")

For more information, see the Python SDK Docs.

Close

Safely shut down the resource and prevent further use.

Python

Parameters:

None.

Returns:

None.

Example:

my_generic_service = Generic.from_robot(robot=machine, name="my_generic_service")
await my_generic_service.close()

For more information, see the Python SDK Docs.

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!