Edit

Control your generic component with the generic API

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

Example usage

See Deploy control logic for an example of how to use the generic component API, including how to call DoCommand() from the SDKs or the web UI.

The generic component supports the following method:

Method Name	Description	`viam-micro-server` Support
`GetGeometries`	Get all the geometries associated with the generic component in its current configuration, in the frame of the generic component.
`DoCommand`	Execute model-specific commands.
`GetResourceName`	Get the `ResourceName` for this generic component.
`Close`	Safely shut down the resource and prevent further use.

API

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.

Python
TypeScript

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:

(List[viam.proto.common.Geometry]): : The geometries associated with the Component.

Example:

my_generic_component = Generic.from_robot(robot=machine, name="my_generic_component")
geometries = await my_generic_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.

Parameters:

extra (None) (optional)
callOptions (CallOptions) (optional)

Returns:

(Promise<commonApi.Geometry[]>)

Example:

const generic = new VIAM.GenericComponentClient(
  machine,
  'my_generic_component'
);

// Get the geometries of this component
const geometries = await generic.getGeometries();
console.log('Geometries:', geometries);

For more information, see the TypeScript SDK Docs.

DoCommand

Execute model-specific commands. If you are implementing your own generic component and want to add features that have no corresponding built-in API method, you can implement them with DoCommand. Supported by viam-micro-server.

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:

my_generic_component = Generic.from_robot(robot=machine, name="my_generic_component")
command = {"cmd": "test", "data1": 500}
result = await my_generic_component.do_command(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:

myGenericComponent, err := generic.FromProvider(machine, "my_generic_component")

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

For more information, see the Go SDK Docs.

Parameters:

command (Struct) (required): The command to execute. Accepts either a Struct or a plain object, which will be converted automatically.
callOptions (CallOptions) (optional)

Returns:

(Promise<JsonValue>)

Example:

// Plain object (recommended)
const result = await resource.doCommand({
  myCommand: { key: 'value' },
});

// Struct (still supported)
import { Struct } from '@viamrobotics/sdk';

const result = await resource.doCommand(
  Struct.fromJson({ myCommand: { key: 'value' } })
);

For more information, see the TypeScript SDK Docs.

Parameters:

command Map<String, dynamic> (required)

Returns:

Future<Map<String, dynamic>>

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.

GetResourceName

Get the ResourceName for this generic component.

Parameters:

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

Returns:

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

Example:

my_generic_component_name = Generic.get_resource_name("my_generic_component")

For more information, see the Python SDK Docs.

Parameters:

None.

Returns:

(Name)

Example:

myGenericComponent, err := generic.FromProvider(machine, "my_generic_component")

err = myGenericComponent.Name()

For more information, see the Go SDK Docs.

Parameters:

None.

Returns:

(string): The name of the resource.

Example:

generic_component.name

For more information, see the TypeScript SDK Docs.

Parameters:

name String (required)

Returns:

ResourceName

Example:

final myGenericResourceName = myGeneric.getResourceName("my_generic");

For more information, see the Flutter SDK Docs.

Close

Safely shut down the resource and prevent further use.

Python

Parameters:

None.

Returns:

None.

Example:

my_generic_component = Generic.from_robot(robot=machine, name="my_generic_component")
await my_generic_component.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!