Generic Component

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

For example, when using an arm component, it makes sense to use the arm API, which provides specific functionality an arm component needs, such as moving to position or stopping movement. However, if you want to use an LED display for example, you need very different functionality that isn’t currently exposed in any API. Instead, you can use the generic component API to add support for your unique type of hardware, like LED displays, to your machine.

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

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

Supported models

To use your generic component, check whether one of the following models supports it.

For configuration information, click on the model name:

Model
Description

Control your board with Viam’s client SDK libraries

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 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 component from the machine with FromRobot and adding API method calls, as shown in the following examples.

These examples assume you have a board called “my_board” configured as a component of your machine. If your board has a different name, change the name in the code.

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

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

API

The generic component supports the following method:

Method NameDescription
DoCommandExecute model-specific commands.
GetGeometriesGet all the geometries associated with the generic component in its current configuration, in the frame of the generic component.
FromRobotGet the resource from the provided robot with the given name.
GetResourceNameGet the ResourceName for this generic component with the given name.
CloseSafely shut down the resource and prevent further use.

DoCommand

Execute model-specific commands. If you are implementing your own generic component 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.

Raises:

  • (NotImplementedError): Raised if the Resource does not support arbitrary commands.

Example:

command = {"cmd": "test", "data1": 500}
result = component.do(command)

For more information, see the Python SDK Docs.

Parameters:

Returns:

Example:

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

For more information, see the Go SDK Docs.

Parameters:

Returns:

Example:

// Example using doCommand with an arm component
const command = {'cmd': 'test', 'data1': 500};
var result = myArm.doCommand(command);

For more information, see the Flutter SDK Docs.

Parameters:

Returns:

auto my_generic = robot->resource_by_name<GenericComponent>("my_generic_component");
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

GetGeometries

Get all the geometries associated with the generic component in its current configuration, in the frame of the generic component. The motion and navigation services use the relative position of inherent geometries to configured geometries representing obstacles for collision detection and obstacle avoidance while motion planning.

Parameters:

  • extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
  • 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:

Example:

geometries = await component.get_geometries()

if geometries:
    # Get the center of the first geometry
    print(f"Pose of the first geometry's centerpoint: {geometries[0].center}")

For more information, see the Python SDK Docs.

FromRobot

Get the resource from the provided robot with the given name.

Parameters:

Returns:

For more information, see the Flutter SDK Docs.

GetResourceName

Get the ResourceName for this generic component with the given name.

Parameters:

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

Returns:

Example:

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

For more information, see the Python SDK Docs.

Parameters:

Returns:

For more information, see the Flutter SDK Docs.

Close

Safely shut down the resource and prevent further use.

Parameters:

  • None.

Returns:

  • None.

Example:

await component.close()

For more information, see the Python SDK Docs.

There is no need to explicitly close a generic component’s resource in C++, as resource destruction is handled automatically by the generic component’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.