Manage Machines with Viam's Machine Management API

package main

import (
  "context"

  "go.viam.com/rdk/logging"
  "go.viam.com/rdk/robot/client"
  "go.viam.com/rdk/utils"
)

func main() {
  logger := logging.NewLogger("client")
  machine, err := client.New(
      context.Background(),
      "ADDRESS FROM THE VIAM APP",
      logger,
      client.WithDialOptions(utils.WithEntityCredentials(
      // Replace "<API-KEY-ID>" (including brackets) with your machine's
      // API Key ID
      "<API-KEY-ID>",
      utils.Credentials{
          Type:    utils.CredentialsTypeAPIKey,
        // Replace "<API-KEY>" (including brackets) with your machine's API key
        Payload: "<API-KEY>",
    })),
  )
  if err != nil {
      logger.Fatal(err)
  }

  defer machine.Close(context.Background())
  logger.Info("Resources:")
  logger.Info(machine.ResourceNames())
}

You can use this code to connect to your machine and instantiate a robot client that you can then use with the Robot API. As an example, this code uses the instantiated robot client to return the configured resources. Remember to always close the connection (using Close()) when done.

Import the time package, then add a timeout to your context using WithTimeout:

// Import the time package in addition to the other imports:
import (
  ...
  "time"
  ...
)

// Edit your main() to configure a timeoutContext, then pass this context to the dial invocation:
func main() {
  ctx := context.Background()
  timeoutContext, cancel := context.WithTimeout(ctx, 10*time.Second)
  defer cancel()
  machine, err := client.New(
      timeoutContext,
      "ADDRESS FROM THE VIAM APP",
      logger,
      client.WithDialOptions(rpc.WithEntityCredentials(
      // Replace "<API-KEY-ID>" (including brackets) with your machine's
      // API key ID
      "<API-KEY-ID>",
      rpc.Credentials{
          Type:    rpc.CredentialsTypeAPIKey,
        // Replace "<API-KEY>" (including brackets) with your machine's API key
        Payload: "<API-KEY>",
    })),
  )
}

The example above shows a timeout of 10 seconds configured.

Parameters:

• ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
• qs ([]resource.DiscoveryQuery): A list of tuples of API and model that you want to retrieve the component configurations corresponding to.

Returns:

• ([]resource.Discovery): The search query qs and the corresponding list of discovered component configurations as an interface called Results. Results may be comprised of primitives, a list of primitives, maps with string keys (or at least can be decomposed into one), or lists of the forementioned type of maps.
• (error): An error, if one occurred.

Example:

// Define a new discovery query.
q := resource.NewDiscoveryQuery(camera.API, resource.Model{Name: "webcam", Family: resource.DefaultModelFamily})

// Define a list of discovery queries and get potential component configurations with these queries.
out, err := machine.DiscoverComponents(context.Background(), []resource.DiscoveryQuery{q})

For more information, see the Go SDK Docs.

Parameters:

• queries (DiscoveryQuery[]): An array of tuples of API and model that you want to retrieve the component configurations corresponding to.

Returns:

• (Discovery[]): List of discovered component configurations.

// Define a new discovery query.
const q = new proto.DiscoveryQuery(acme.API, resource.Model{Name: "some model"})

// Define an array of discovery queries.
let qs:  proto.DiscoveryQuery[] = [q]

// Get the array of discovered component configurations.
const componentConfigs = await machine.discoverComponents(queries);

For more information, see the Typescript SDK Docs.

Parameters:

• ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

• (*framesystem.Config): The configuration of the given machine’s frame system.
• (error): An error, if one occurred.

Example:

// Print the frame system configuration
frameSystem, err := machine.FrameSystemConfig(context.Background())
fmt.Println(frameSystem)

For more information, see the Go SDK Docs.

Parameters:

• transforms (Transform[]): An optional array of additional transforms.

Returns:

• (FrameSystemConfig[]): An array of individual parts that make up a machine’s frame system.

For more information, see the TypeScript SDK Docs.

// Get the frame system configuration
console.log("FrameSytemConfig:", await robot.frameSystemConfig());

Parameters:

• ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
• pose (*referenceframe.PoseInFrame): The pose that should be transformed.
• dst (string): The name of the reference pose to transform the given pose to.
• additionalTransforms ([]*referenceframe.LinkInFrame): Any additional transforms.

Returns:

• (*referenceframe.PoseInFrame): Transformed pose in frame.
• (error): An error, if one occurred.

Example:

import (
  "go.viam.com/rdk/referenceframe"
  "go.viam.com/rdk/spatialmath"
)

baseOrigin := referenceframe.NewPoseInFrame("test-base", spatialmath.NewZeroPose())
movementSensorToBase, err := machine.TransformPose(context.Background(), baseOrigin, "my-movement-sensor", nil)

For more information, see the Go SDK Docs.

Parameters:

• ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
• resourceNames ([]resource.Name): A list of resource names for components you want the status of. If no names are passed in, all resource statuses are returned.

Returns:

• ([]Status): The Status of each resource queried. If no resource was provided as a parameter, the status of all resources is returned.
• (error): An error, if one occurred.

Example:

status, err := machine.Status(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

• resourceNames (commonApi.ResourceName[]): An optional array of ResourceNames for components you want the status of. If no names are passed in, all resource statuses are returned.

Returns:

• (robotApi.Status[]): An array containing the status of each resource.

For more information, see the TypeScript SDK Docs.

// Get the status of the resources on the machine.
const status = await machine.getStatus();

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:

• (error): An error, if one occurred.

Example:

// Cancel all current and outstanding operations for the machine and stop all actuators and movement.
err := machine.StopAll(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

• None

Returns:

• None

For more information, see the TypeScript SDK Docs.

// Cancel all current and outstanding operations for the machine and stop all actuators and movement.
await machine.stopAll();

Parameters:

• ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

• (cloud.Metadata): App-related metadata containing the primary organization ID, location ID, and robot part ID for a machine running on the Viam app.
• (error): An error, if one occurred.

Example:

metadata, err := machine.CloudMetadata(context.Background())
primary_org_id := metadata.PrimaryOrgID
location_id := metadata.LocationID
machine_id := metadata.MachineID
machine_part_id := metadata.MachinePartID

For more information, see the Go SDK Docs.

Parameters:

• None.

Returns:

• Future<CloudMetadata>

Example:

var metadata = await machine.getCloudMetadata();

For more information, see the Flutter SDK Docs.

Parameters:

• ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

• (VersionResponse)
• (error): An error, if one occurred.

For more information, see the Go SDK Docs.

Parameters:

• url String (required)
• options RobotClientOptions (required)

Returns:

• Future<RobotClient>

Example:

// Example usage; see your machine's CONNECT tab for your machine's address and API key.

Future<void> connectToViam() async {
  const host = '<YOUR ROBOT ADDRESS>.viam.cloud';
  // Replace "<API-KEY-ID>" (including brackets) with your machine's API key ID
  const apiKeyID = '<API-KEY-ID>';
  // Replace "<API-KEY>" (including brackets) with your machine's API key
  const apiKey = '<API-KEY>';

  final machine = await RobotClient.atAddress(
    host,
    RobotClientOptions.withApiKey(apiKeyID, apiKey),
  );
}

For more information, see the Flutter SDK Docs.

Parameters:

• None.

Returns:

• Future<void>

Example:

await machine.refresh();

For more information, see the Flutter 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:

// Shut down the robot.
err := machine.Shutdown(context.Background())

For more information, see the Go 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:

// Cleanly close the underlying connections and stop any periodic tasks,
err := machine.Close(context.Background())

For more information, see the Go SDK Docs.

Parameters:

• None.

Returns:

• Future<void>

Example:

await machine.close();

For more information, see the Flutter SDK Docs.

Parameters:

• None

Returns:

• None

For more information, see the TypeScript SDK Docs.

// Cleanly close the underlying connections and stop any periodic tasks
await machine.disconnect();