robot

Documentation

Overview

Package robot defines the robot which is the root of all robotic parts.

Index

• func AllResourcesByName(r Robot, name string) []resource.Resource
• func NamesByAPI(r Robot, api resource.API) []string
• func ResourceFromProtoMessage(robot Robot, msg *dynamic.Message, api resource.API) (interface{}, resource.Name, error)
• func ResourceFromRobot[T resource.Resource](robot Robot, name resource.Name) (T, error)
• func TypeAndMethodDescFromMethod(r Robot, method string) (*resource.RPCAPI, *desc.MethodDescriptor, error)
• type LocalRobot
• type MachineStatus
• type RemoteRobot
• type RestartModuleRequest
  • func (rmr *RestartModuleRequest) MatchesModule(mod config.Module) bool
• type Robot
• type SessionManager
  • func NewSessionManager(robot Robot, heartbeatWindow time.Duration) *SessionManager
  • func (m *SessionManager) All() []*session.Session
  • func (m *SessionManager) AssociateResource(id uuid.UUID, resourceName resource.Name)
  • func (m *SessionManager) Close()
  • func (m *SessionManager) FindByID(ctx context.Context, id uuid.UUID, ownerID string) (*session.Session, error)
  • func (m *SessionManager) ServerInterceptors() session.ServerInterceptors
  • func (m *SessionManager) Start(ctx context.Context, ownerID string) (*session.Session, error)
  • func (m *SessionManager) StreamServerInterceptor(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, ...) error
  • func (m *SessionManager) UnaryServerInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, ...) (interface{}, error)
• type Status
• type VersionResponse
  • func Version() (VersionResponse, error)

Functions

func AllResourcesByName

func AllResourcesByName(r Robot, name string) []resource.Resource

AllResourcesByName returns an array of all resources that have this short name. NOTE: this function queries by the shortname rather than the fully qualified resource name which is not recommended practice and may become deprecated in the future.

func NamesByAPI

func NamesByAPI(r Robot, api resource.API) []string

NamesByAPI is a helper for getting all names from the given Robot given the API.

func ResourceFromProtoMessage

func ResourceFromProtoMessage(
	robot Robot,
	msg *dynamic.Message,
	api resource.API,
) (interface{}, resource.Name, error)

ResourceFromProtoMessage attempts to find out the name/resource associated with a gRPC message.

func ResourceFromRobot

func ResourceFromRobot[T resource.Resource](robot Robot, name resource.Name) (T, error)

ResourceFromRobot returns a resource from a robot.

func TypeAndMethodDescFromMethod

func TypeAndMethodDescFromMethod(r Robot, method string) (*resource.RPCAPI, *desc.MethodDescriptor, error)

TypeAndMethodDescFromMethod attempts to determine the resource API and its respective gRPC method information from the given robot and method path. If nothing can be found, grpc.UnimplementedError is returned.

Types

type LocalRobot

type LocalRobot interface {
	Robot

	// Config returns a config representing the current state of the robot.
	Config() *config.Config

	// Reconfigure instructs the robot to safely reconfigure itself based
	// on the given new config.
	Reconfigure(ctx context.Context, newConfig *config.Config)

	// StartWeb starts the web server, will return an error if server is already up.
	StartWeb(ctx context.Context, o weboptions.Options) error

	// StopWeb stops the web server, will be a noop if server is not up.
	StopWeb()

	// WebAddress returns the address of the web service.
	WebAddress() (string, error)

	// ModuleAddress returns the address (path) of the unix socket modules use to contact the parent.
	ModuleAddress() (string, error)

	// ExportResourcesAsDot exports the resource graph as a DOT representation for
	// visualization.
	// DOT reference: https://graphviz.org/doc/info/lang.html
	ExportResourcesAsDot(index int) (resource.GetSnapshotInfo, error)
}

A LocalRobot is a Robot that can have its parts modified.

type MachineStatus

type MachineStatus struct {
	Resources []resource.Status
	Config    config.Revision
}

MachineStatus encapsulates the current status of the robot.

type RemoteRobot

type RemoteRobot interface {
	Robot

	// Connected returns whether the remote is connected or not.
	Connected() bool
}

A RemoteRobot is a Robot that was created through a connection.

type RestartModuleRequest

type RestartModuleRequest struct {
	ModuleID   string
	ModuleName string
}

RestartModuleRequest is a go mirror of a proto message.

func (*RestartModuleRequest) MatchesModule

func (rmr *RestartModuleRequest) MatchesModule(mod config.Module) bool

MatchesModule returns true if the passed-in module matches its name / ID.

type Robot

type Robot interface {
	// DiscoverComponents returns discovered component configurations.
	DiscoverComponents(ctx context.Context, qs []resource.DiscoveryQuery) ([]resource.Discovery, error)

	// RemoteByName returns a remote robot by name.
	RemoteByName(name string) (Robot, bool)

	// ResourceByName returns a resource by name
	ResourceByName(name resource.Name) (resource.Resource, error)

	// RemoteNames returns the names of all known remote robots.
	RemoteNames() []string

	// ResourceNames returns a list of all known resource names.
	ResourceNames() []resource.Name

	// ResourceRPCAPIs returns a list of all known resource RPC APIs.
	ResourceRPCAPIs() []resource.RPCAPI

	// ProcessManager returns the process manager for the robot.
	ProcessManager() pexec.ProcessManager

	// OperationManager returns the operation manager the robot is using.
	OperationManager() *operation.Manager

	// SessionManager returns the session manager the robot is using.
	SessionManager() session.Manager

	// PackageManager returns the package manager the robot is using.
	PackageManager() packages.Manager

	// Logger returns the logger the robot is using.
	Logger() logging.Logger

	// FrameSystemConfig returns the individual parts that make up a robot's frame system
	FrameSystemConfig(ctx context.Context) (*framesystem.Config, error)

	// TransformPose will transform the pose of the requested poseInFrame to the desired frame in the robot's frame system.
	TransformPose(
		ctx context.Context,
		pose *referenceframe.PoseInFrame,
		dst string,
		additionalTransforms []*referenceframe.LinkInFrame,
	) (*referenceframe.PoseInFrame, 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.
	TransformPointCloud(ctx context.Context, srcpc pointcloud.PointCloud, srcName, dstName string) (pointcloud.PointCloud, error)

	// Status takes a list of resource names and returns their corresponding statuses. If no names are passed in, return all statuses.
	Status(ctx context.Context, resourceNames []resource.Name) ([]Status, error)

	// CloudMetadata returns app-related information about the robot.
	CloudMetadata(ctx context.Context) (cloud.Metadata, error)

	// Close attempts to cleanly close down all constituent parts of the robot.
	Close(ctx context.Context) error

	// StopAll cancels all current and outstanding operations for the robot and stops all actuators and movement
	StopAll(ctx context.Context, extra map[resource.Name]map[string]interface{}) error

	// RestartModule reloads a module as if its config changed
	RestartModule(ctx context.Context, req RestartModuleRequest) error

	// Shutdown shuts down the robot.
	Shutdown(ctx context.Context) error

	// MachineStatus returns the current status of the robot.
	MachineStatus(ctx context.Context) (MachineStatus, error)

	// Version returns version information about the robot.
	Version(ctx context.Context) (VersionResponse, error)
}

A Robot encompasses all functionality of some robot comprised of parts, local and remote.

DiscoverComponents example:

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

ResourceNames example:

resource_names := machine.ResourceNames()

FrameSystemConfig example:

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

TransformPose example:

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

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

Status example:

status, err := machine.Status(ctx)

CloudMetadata example:

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

Close example:

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

StopAll example:

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

Shutdown example:

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

type SessionManager

type SessionManager struct {
	// contains filtered or unexported fields
}

SessionManager holds sessions for a particular robot and manages their lifetime.

func NewSessionManager

func NewSessionManager(robot Robot, heartbeatWindow time.Duration) *SessionManager

NewSessionManager creates a new manager for holding sessions.

func (*SessionManager) All

func (m *SessionManager) All() []*session.Session

All returns all active sessions.

func (*SessionManager) AssociateResource

func (m *SessionManager) AssociateResource(id uuid.UUID, resourceName resource.Name)

AssociateResource associates a session ID to a monitored resource such that when a session expires, if a resource is currently associated with that ID based on the order of AssociateResource calls, then it will have its resourc stopped. If id is uuid.Nil, this has no effect other than disassociation with a session. Be sure to include any remote information in the name.

func (*SessionManager) Close

func (m *SessionManager) Close()

Close stops the session manager but will not explicitly expire any sessions.

func (*SessionManager) FindByID

func (m *SessionManager) FindByID(ctx context.Context, id uuid.UUID, ownerID string) (*session.Session, error)

FindByID finds a session by the given ID. If found, a heartbeat is triggered, extending the lifetime of the session. If ownerID is in use but the session in question has a different owner, this is a security violation and we report back no session found.

func (*SessionManager) ServerInterceptors

func (m *SessionManager) ServerInterceptors() session.ServerInterceptors

ServerInterceptors returns gRPC interceptors to work with sessions.

func (*SessionManager) Start

func (m *SessionManager) Start(ctx context.Context, ownerID string) (*session.Session, error)

Start creates a new session that expects at least one heartbeat within the configured window.

func (*SessionManager) StreamServerInterceptor

func (m *SessionManager) StreamServerInterceptor(
	srv interface{},
	ss grpc.ServerStream,
	info *grpc.StreamServerInfo,
	handler grpc.StreamHandler,
) error

StreamServerInterceptor associates the current session (if present) in the current context before passing it to the stream response handler.

func (*SessionManager) UnaryServerInterceptor

func (m *SessionManager) UnaryServerInterceptor(
	ctx context.Context,
	req interface{},
	info *grpc.UnaryServerInfo,
	handler grpc.UnaryHandler,
) (interface{}, error)

UnaryServerInterceptor associates the current session (if present) in the current context before passing it to the unary response handler.

type Status

type Status struct {
	Name             resource.Name
	LastReconfigured time.Time
	Status           interface{}
}

Status holds a resource name, the time that resource was last reconfigured (or built), and its corresponding status. Status.Status is expected to be comprised of string keys and values comprised of primitives, list of primitives, maps with string keys (or at least can be decomposed into one), or lists of the forementioned type of maps. Results with other types of data are not guaranteed.

type VersionResponse

type VersionResponse struct {
	Platform   string
	Version    string
	APIVersion string
}

VersionResponse encapsulates the version info of the robot.

func Version

func Version() (VersionResponse, error)

Version returns platform, version and API version of the robot. platform will always be `rdk` If built without a version tag, will be dev-<git hash>.