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).

Available models

For configuration information, click on the model name:

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:

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.

service = SERVICE.from_robot(robot, "builtin")  # replace SERVICE with the appropriate class

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)

// This example shows using DoCommand with an arm component.
myArm, err := arm.FromRobot(machine, "my_arm")

command := map[string]interface{}{"cmd": "test", "data1": 500}
result, err := myArm.DoCommand(context.Background(), 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);

GetResourceName

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

# Can be used with any resource, using an arm as an example
my_arm_name = my_arm.get_resource_name("my_arm")

Close

Safely shut down the resource and prevent further use.

await component.close()

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.