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
).
Important
The generic service API only supports the DoCommand
method.
If you use the generic subtype, your module needs to define any and all service functionality and pass it through DoCommand
.
Whenever possible, it is best to use an existing service API instead of generic so that you do not have to replicate code.
If you want to use most of an existing API but need just a few other functions, try using the DoCommand
endpoint and extra parameters to add custom functionality to an existing subtype, instead of using the generic service.
Supported models
Built-in models
For configuration information, click on the model name:
Model | Description |
---|---|
fake | A 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.
API key and API key ID
By default, the sample code does not include your machine API key and API key ID. We strongly recommend that you add your API key and API key ID as an environment variable and import this variable into your development environment as needed.
To show your machine’s API key and API key ID in the sample code, toggle Include secret on the CONNECT tab’s Code sample page.
Caution
Do not share your API key or machine address publicly. Sharing this information could compromise your system security by allowing unauthorized access to your machine, or to the computer running your machine.
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 Name | Description |
---|---|
DoCommand | Send or receive model-specific commands. |
Close | Safely 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:
command
(Dict[str, Any]): The command to execute.
Returns:
- (Dict[str, Any]): Result of the executed command.
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:
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{}): Result of the executed command.
- (error): An error, if one occurred.
myGeneric, err := generic.FromRobot(robot, "my_generic_service")
resp, err := myGeneric.DoCommand(ctx, map[string]interface{}{"command": "example"})
For more information, see the Go SDK Code.
Parameters:
command
(AttributeMap): The command to execute.
Returns:
- (AttributeMap): Result of the executed command.
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.
myGeneric, err := generic.FromRobot(robot, "my_generic")
err := myGeneric.Close(ctx)
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.
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!