client

package
v0.36.0-rc0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 5, 2024 License: AGPL-3.0 Imports: 44 Imported by: 11

README

Go client

The Go client for the Viam RDK can function as an SDK to connect to a robot.

Install

To install the Go SDK, run the following command from inside a Go module (use go mod init to create a module if you do not have one already).

	go get go.viam.com/rdk/robot/client

After adding the code below, you may have to run go mod tidy to add all required dependencies to your go.mod file.

Basic Usage

To connect to a robot as a client, you should instantiate a client.

	package main

	import (
		"context"

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

	func main() {
		logger := logging.NewDebugLogger("client")
		// this instantiates a robot client that is connected to the robot at <address>
		robot, err := client.New(
			context.Background(),
			"<address of robot>",
			logger,
			// credentials can be found in the Viam app if the robot is Viam managed
			// otherwise, credential keys can also be set through the config
			client.WithDialOptions(rpc.WithCredentials(rpc.Credentials{
				Type:    utils.CredentialsTypeRobotLocationSecret,
				Payload: "<robot secret>",
			})),
		)
		if err != nil {
			logger.Fatal(err)
		}
	}

If the robot is managed by Viam, you can also navigate to the robot page on app.viam.com, select the CONNECT tab, and copy the boilerplate code from the section labeled Golang SDK.

You can then query resources and also grab a resource by its name.

	logger.Info("Resources:")
  	logger.Info(robot.ResourceNames())

	// grab a motor by its name and query for its position
	m1, err := motor.FromRobot(robot, "motor1")
	if err != nil {
		logger.Fatal(err)
	}
	position, err := m1.Position(context.Background(), map[string]interface{}{})
	if err != nil {
		logger.Error(err)
	}

Remember to close the client at the end!

	robot.Close(context.Background())

Documentation

Overview

Package client contains a gRPC based robot.Robot client.

Index

Constants

View Source 
const RemoteTypeName = string("remote")

RemoteTypeName is the type name used for a remote. This is for internal use.

Variables

View Source 
var (
	// ErrMissingClientRegistration is used when there is no resource client registered for the API.
	ErrMissingClientRegistration = errors.New("resource client registration doesn't exist")
)
View Source 
var RemoteAPI = resource.APINamespaceRDK.WithType(RemoteTypeName).WithSubtype("")

RemoteAPI is the fully qualified API for a remote. This is for internal use.

Functions

func ExtractDialOptions 

func ExtractDialOptions(opts ...RobotClientOption) []rpc.DialOption

ExtractDialOptions extracts RPC dial options from the given options, if any exist.

Types

type RobotClient 

type RobotClient struct {
	resource.Named
	// contains filtered or unexported fields
}

RobotClient satisfies the robot.Robot interface through a gRPC based client conforming to the robot.proto contract.

func New 

func New(ctx context.Context, address string, clientLogger logging.ZapCompatibleLogger, opts ...RobotClientOption) (*RobotClient, error)

New constructs a new RobotClient that is served at the given address. The given context can be used to cancel the operation.

func (*RobotClient) Changed 

func (rc *RobotClient) Changed() <-chan bool

Changed watches for whether the remote has changed.

func (*RobotClient) Close 

func (rc *RobotClient) Close(ctx context.Context) error

Close closes the underlying client connections to the machine and stops any periodic tasks running in the client. 

err := machine.Close(ctx.Background())

func (*RobotClient) CloudMetadata added in v0.23.0 

func (rc *RobotClient) CloudMetadata(ctx context.Context) (cloud.Metadata, error)

CloudMetadata returns app-related information about the machine. 

metadata, err := machine.CloudMetadata(ctx.Background())

func (*RobotClient) Connected 

func (rc *RobotClient) Connected() bool

Connected exposes whether a robot client is connected to the remote.

func (*RobotClient) DiscoverComponents 

func (rc *RobotClient) DiscoverComponents(ctx context.Context, qs []resource.DiscoveryQuery) ([]resource.Discovery, error)

DiscoverComponents takes a list of discovery queries and returns corresponding component configurations. 

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

// Define a list of discovery queries.
qs := []resource.DiscoverQuery{q}

// Get component configurations with these queries.
component_configs, err := machine.DiscoverComponents(ctx.Background(), qs)

func (*RobotClient) FrameSystemConfig 

func (rc *RobotClient) FrameSystemConfig(ctx context.Context) (*framesystem.Config, error)

FrameSystemConfig returns the configuration of the frame system of a given machine. 

frameSystem, err := machine.FrameSystemConfig(context.Background(), nil)

func (*RobotClient) Log added in v0.21.0 

func (rc *RobotClient) Log(ctx context.Context, log zapcore.Entry, fields []zap.Field) error

Log sends a log entry to the server. To be used by Golang modules wanting to log over gRPC and not by normal Golang SDK clients.

func (*RobotClient) Logger 

func (rc *RobotClient) Logger() logging.Logger

Logger returns the logger being used for this robot.

func (*RobotClient) MachineStatus added in v0.35.0 

func (rc *RobotClient) MachineStatus(ctx context.Context) (robot.MachineStatus, error)

MachineStatus returns the current status of the robot.

func (*RobotClient) OperationManager 

func (rc *RobotClient) OperationManager() *operation.Manager

OperationManager returns nil.

func (*RobotClient) PackageManager added in v0.2.15 

func (rc *RobotClient) PackageManager() packages.Manager

PackageManager returns nil.

func (*RobotClient) ProcessManager 

func (rc *RobotClient) ProcessManager() pexec.ProcessManager

ProcessManager returns a useless process manager for the sake of satisfying the robot.Robot interface. Maybe it should not be part of the interface!

func (*RobotClient) Reconfigure added in v0.2.36 

func (rc *RobotClient) Reconfigure(ctx context.Context, deps resource.Dependencies, conf resource.Config) error

Reconfigure always returns an unsupported error.

func (*RobotClient) Refresh 

func (rc *RobotClient) Refresh(ctx context.Context) (err error)

Refresh manually updates the underlying parts of this machine. 

err := machine.Refresh(ctx)

func (*RobotClient) RefreshEvery 

func (rc *RobotClient) RefreshEvery(ctx context.Context, every time.Duration)

RefreshEvery refreshes the machine on the interval given by every until the given context is done.

func (*RobotClient) RemoteByName 

func (rc *RobotClient) RemoteByName(name string) (robot.Robot, bool)

RemoteByName returns a remote machine by name. It is assumed to exist on the other end. Right now this method is unimplemented.

func (*RobotClient) RemoteNames 

func (rc *RobotClient) RemoteNames() []string

RemoteNames returns the names of all known remotes.

func (*RobotClient) ResourceByName 

func (rc *RobotClient) ResourceByName(name resource.Name) (resource.Resource, error)

ResourceByName returns resource by name.

func (*RobotClient) ResourceNames 

func (rc *RobotClient) ResourceNames() []resource.Name

ResourceNames returns a list of all known resource names connected to this machine. 

resource_names := machine.ResourceNames()

func (*RobotClient) ResourceRPCAPIs added in v0.2.36 

func (rc *RobotClient) ResourceRPCAPIs() []resource.RPCAPI

ResourceRPCAPIs returns a list of all known resource APIs.

func (*RobotClient) RestartModule added in v0.26.0 

func (rc *RobotClient) RestartModule(ctx context.Context, req robot.RestartModuleRequest) error

RestartModule restarts a running module by name or ID.

func (*RobotClient) SessionManager added in v0.2.5 

func (rc *RobotClient) SessionManager() session.Manager

SessionManager returns nil.

func (*RobotClient) SetParentNotifier 

func (rc *RobotClient) SetParentNotifier(f func())

SetParentNotifier set the notifier function, robot client will use that the relay changes.

func (*RobotClient) Shutdown added in v0.29.0 

func (rc *RobotClient) Shutdown(ctx context.Context) error

Shutdown shuts down the robot. May return DeadlineExceeded error if shutdown request times out, or if robot server shuts down before having a chance to send a response. May return Unavailable error if server is unavailable, or if robot server is in the process of shutting down when response is ready.

func (*RobotClient) Status 

func (rc *RobotClient) Status(ctx context.Context, resourceNames []resource.Name) ([]robot.Status, error)

Status returns the status of the resources on the machine. You can provide a list of ResourceNames for which you want statuses. If no names are passed in, the status of every resource available on the machine is returned. 

status, err := machine.Status(ctx.Background())

func (*RobotClient) StopAll 

func (rc *RobotClient) StopAll(ctx context.Context, extra map[resource.Name]map[string]interface{}) error

StopAll cancels all current and outstanding operations for the machine and stops all actuators and movement. 

err := machine.StopAll(ctx.Background())

func (*RobotClient) TransformPointCloud added in v0.2.11 

func (rc *RobotClient) TransformPointCloud(ctx context.Context, srcpc pointcloud.PointCloud, srcName, dstName string,
) (pointcloud.PointCloud, error)

TransformPointCloud will transform the pointcloud to the desired frame in the robot's frame system. Do not move the robot between the generation of the initial pointcloud and the receipt of the transformed pointcloud because that will make the transformations inaccurate. TODO(RSDK-1197): Rather than having to apply a transform to every point using ApplyOffset, implementing the suggested ticket would mean simply adding the transform to a field in the point cloud struct, and then returning the updated struct. Would be super fast.

func (*RobotClient) TransformPose 

func (rc *RobotClient) TransformPose(
	ctx context.Context,
	query *referenceframe.PoseInFrame,
	destination string,
	additionalTransforms []*referenceframe.LinkInFrame,
) (*referenceframe.PoseInFrame, error)

TransformPose will transform the pose of the requested poseInFrame to the desired frame in the robot's frame system. 

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

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

func (*RobotClient) Version added in v0.36.0 

func (rc *RobotClient) Version(ctx context.Context) (robot.VersionResponse, error)

Version returns version information about the robot.

type RobotClientOption 

type RobotClientOption interface {
	// contains filtered or unexported methods
}

RobotClientOption configures how we set up the connection. Cribbed from https://github.com/grpc/grpc-go/blob/aff571cc86e6e7e740130dbbb32a9741558db805/dialoptions.go#L41

func WithCheckConnectedEvery 

func WithCheckConnectedEvery(checkConnectedEvery time.Duration) RobotClientOption

WithCheckConnectedEvery returns a RobotClientOption for how often to check connection to the robot.

func WithDialOptions 

func WithDialOptions(opts ...rpc.DialOption) RobotClientOption

WithDialOptions returns a RobotClientOption which sets the options for making gRPC connections to other servers.

func WithDisableSessions added in v0.2.5 

func WithDisableSessions() RobotClientOption

WithDisableSessions returns a RobotClientOption that disables session support.

func WithReconnectEvery 

func WithReconnectEvery(reconnectEvery time.Duration) RobotClientOption

WithReconnectEvery returns a RobotClientOption for how often to reconnect the robot.

func WithRefreshEvery 

func WithRefreshEvery(refreshEvery time.Duration) RobotClientOption

WithRefreshEvery returns a RobotClientOption for how often to refresh the status/parts of the robot.

func WithRemoteName added in v0.2.2 

func WithRemoteName(remoteName string) RobotClientOption

WithRemoteName returns a RobotClientOption setting the name of the remote robot.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.