Discovery service API

The discovery service API allows you to get a list of resources available to configure on a machine based on the hardware that is connected to or part of the machine. Discoverable resources can include components that are physically connected to the machine, as well as components that are available on the machine’s local network (depending on the implementation of the discovery service).

The discovery service supports the following methods:

Method NameDescription
DiscoverResourcesGet a list of component configs of all resources available to configure on a machine based on the hardware that is connected to or part of the machine.
GetResourceNameGet the ResourceName for this instance of the service.
DoCommandExecute model-specific commands.
CloseSafely shut down the resource and prevent further use.

API

DiscoverResources

Get a list of component configs of all resources available to configure on a machine based on the hardware that is connected to or part of the machine.

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:

my_discovery = DiscoveryClient.from_robot(machine, "my_discovery")

# Get the discovered resources
result = await my_discovery.discover_resources(
    "my_discovery",
)
discoveries = result.discoveries

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.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

Example:

  // Get the discovered resources of a Discovery Service.
  cfgs, err := myDiscoveryService.DiscoverResources(ctx, nil)
  if err != nil {
    logger.Fatal(err)
  }
   // Print out the discovered resources.
  for _, cfg := range cfgs {
    fmt.Printf("Name: %v\tModel: %v\tAPI: %v", cfg.Name, cfg.Model, cfg.API)
    fmt.Printf("Attributes: ", cfg.Attributes)
  }

For more information, see the Go SDK Docs.

Parameters:

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

Returns:

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

// Example:
var resources = await myDiscoveryService.discoverResources('myWebcam');

For more information, see the Flutter SDK Docs.

GetResourceName

Get the ResourceName for this instance of the service.

Parameters:

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

Returns:

Example:

my_discovery_svc_name = DiscoveryClient.get_resource_name("my_discovery_svc")

For more information, see the Python SDK Docs.

Parameters:

  • None.

Returns:

Example:

myDiscoverySvc, err := discovery.FromProvider(machine, "my_discovery_svc")

err = myDiscoverySvc.Name()

For more information, see the Go SDK Docs.

Parameters:

  • None.

Returns:

  • (string): The name of the resource.

Example:

discovery.name

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

For more information, see the Flutter SDK Docs.

DoCommand

Execute model-specific commands. If you are implementing your own generic service and want to add features that have no corresponding built-in API method, you can implement 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, viam.utils.ValueTypes]): : Result of the executed command.

Example:

my_discovery_svc = DiscoveryClient.from_robot(robot=machine, "my_discovery_svc")

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

await my_discovery_svc.do_command(command=my_command)

For more information, see the Python SDK Docs.

Parameters:

Returns:

Example:

myDiscoverySvc, err := discovery.FromProvider(machine, "my_discovery_svc")

command := map[string]interface{}{"cmd": "test", "data1": 500}
result, err := myDiscoverySvc.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:

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:

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.

Close

Safely shut down the resource and prevent further use.

Parameters:

  • None.

Returns:

  • None.

Example:

my_discovery_svc = DiscoveryClient.from_robot(robot=machine, name="my_discovery_svc")
await my_discovery_svc.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.

Example:

myDiscoverySvc, err := discovery.FromProvider(machine, "my_discovery_svc")

err = myDiscoverySvc.Close(context.Background())

For more information, see the Go SDK Docs.