motion

Documentation

Overview

Package motion is the service that allows you to plan and execute movements.

Index

• Constants
• Variables
• func Named(name string) resource.Name
• func NewRPCServiceServer(coll resource.APIResourceCollection[Service]) interface{}
• func PollHistoryUntilSuccessOrError(ctx context.Context, m Service, interval time.Duration, req PlanHistoryReq) error
• type ExecutionID
• type ListPlanStatusesReq
• type Localizer
  • func NewMovementSensorLocalizer(ms movementsensor.MovementSensor, origin *geo.Point, ...) Localizer
  • func NewSLAMLocalizer(slam slam.Service) Localizer
  • func TwoDLocalizer(l Localizer) Localizer
• type MotionConfiguration
• type MoveOnGlobeReq
  • func (r MoveOnGlobeReq) String() string
• type MoveOnMapReq
  • func (r MoveOnMapReq) String() string
• type ObstacleDetectorName
• type PlanHistoryReq
• type PlanID
• type PlanState
  • func (ps PlanState) String() string
  • func (ps PlanState) ToProto() pb.PlanState
• type PlanStatus
  • func (ps PlanStatus) ToProto() *pb.PlanStatus
• type PlanStatusWithID
  • func (ps PlanStatusWithID) ToProto() *pb.PlanStatusWithID
• type PlanWithMetadata
  • func (p PlanWithMetadata) Renderable() PlanWithMetadata
  • func (p PlanWithMetadata) ToProto() *pb.Plan
• type PlanWithStatus
  • func (pws PlanWithStatus) ToProto() *pb.PlanWithStatus
• type Service
  • func FromDependencies(deps resource.Dependencies, name string) (Service, error)
  • func FromRobot(r robot.Robot, name string) (Service, error)
  • func NewClientFromConn(ctx context.Context, conn rpc.ClientConn, remoteName string, ...) (Service, error)
• type StopPlanReq

Constants

const (
	// PlanStateUnspecified denotes an the Plan is in an unspecified state. This should never happen.
	PlanStateUnspecified = iota

	// PlanStateInProgress denotes an the Plan is in an in progress state. It is a temporary state.
	PlanStateInProgress

	// PlanStateStopped denotes an the Plan is in a stopped state. It is a terminal state.
	PlanStateStopped

	// PlanStateSucceeded denotes an the Plan is in a succeeded state. It is a terminal state.
	PlanStateSucceeded

	// PlanStateFailed denotes an the Plan is in a failed state. It is a terminal state.
	PlanStateFailed
)

const SubtypeName = "motion"

SubtypeName is the name of the type of service.

Variables

var API = resource.APINamespaceRDK.WithServiceType(SubtypeName)

API is a variable that identifies the motion service resource API.

var ErrGoalWithinPlanDeviation = errors.New("no need to move, already within planDeviationMM")

ErrGoalWithinPlanDeviation is an error describing when planning fails because there is nothing to be done.

var SLAMOrientationAdjustment = spatialmath.NewPoseFromOrientation(&spatialmath.OrientationVectorDegrees{OZ: 1, Theta: -90})

SLAMOrientationAdjustment is needed because a SLAM map pose has orientation of OZ=1, Theta=0 when the rover is intended to be pointing at the +X axis of the SLAM map. However, for a rover's relative planning frame, driving forwards increments +Y. Thus we must adjust where the rover thinks it is.

var TerminalStateSet = map[PlanState]struct{}{
	PlanStateStopped:   {},
	PlanStateSucceeded: {},
	PlanStateFailed:    {},
}

TerminalStateSet is a set that defines the PlanState values which are terminal i.e. which represent the end of a plan.

Functions

func Named

func Named(name string) resource.Name

Named is a helper for getting the named motion service's typed resource name.

func NewRPCServiceServer

func NewRPCServiceServer(coll resource.APIResourceCollection[Service]) interface{}

NewRPCServiceServer constructs a motion gRPC service server. It is intentionally untyped to prevent use outside of tests.

func PollHistoryUntilSuccessOrError

func PollHistoryUntilSuccessOrError(
	ctx context.Context,
	m Service,
	interval time.Duration,
	req PlanHistoryReq,
) error

PollHistoryUntilSuccessOrError polls `PlanHistory()` with `req` every `interval` until a terminal state is reached. An error is returned if the terminal state is Failed, Stopped or an invalid state or if the context has an error. nil is returned if the terminal state is Succeeded.

Types

type ExecutionID

type ExecutionID = uuid.UUID

ExecutionID uniquely identifies an execution.

type ListPlanStatusesReq

type ListPlanStatusesReq struct {
	// If true then only active plans will be returned.
	OnlyActivePlans bool
	Extra           map[string]interface{}
}

ListPlanStatusesReq describes the request to ListPlanStatuses().

type Localizer

type Localizer interface {
	CurrentPosition(context.Context) (*referenceframe.PoseInFrame, error)
}

Localizer is an interface which both slam and movementsensor can satisfy when wrapped respectively.

func NewMovementSensorLocalizer

func NewMovementSensorLocalizer(ms movementsensor.MovementSensor, origin *geo.Point, calibration spatialmath.Pose) Localizer

NewMovementSensorLocalizer creates a Localizer from a MovementSensor. An origin point must be specified and the localizer will return Poses relative to this point. A calibration pose can also be specified, which will adjust the location after it is calculated relative to the origin.

func NewSLAMLocalizer

func NewSLAMLocalizer(slam slam.Service) Localizer

NewSLAMLocalizer creates a new Localizer that relies on a slam service to report Pose.

func TwoDLocalizer

func TwoDLocalizer(l Localizer) Localizer

TwoDLocalizer will check the orientation of the pose of a localizer, and ensure that it is normal to the XY plane. If it is not, it will be altered such that it is (accounting for e.g. an ourdoor base with one wheel on a rock). If the orientation is such that the base is pointed directly up or down (or is upside-down), an error is returned. The alteration to ensure normality to the plane is done by transforming the (0,1,0) vector by the provided orientation, and then using atan2 on the new x and y values to determine the vector of travel that would be followed.

type MotionConfiguration

type MotionConfiguration struct {
	ObstacleDetectors     []ObstacleDetectorName
	PositionPollingFreqHz float64
	ObstaclePollingFreqHz float64
	PlanDeviationMM       float64
	LinearMPerSec         float64
	AngularDegsPerSec     float64
}

MotionConfiguration specifies how to configure a call

type MoveOnGlobeReq

type MoveOnGlobeReq struct {
	// ComponentName of the component to move
	ComponentName resource.Name
	// Goal destination the component should be moved to
	Destination *geo.Point
	// Heading the component should have a when it reaches the goal.
	// Range [0-360] Left Hand Rule (N: 0, E: 90, S: 180, W: 270)
	Heading float64
	// Name of the momement sensor which can be used to derive Position & Heading
	MovementSensorName resource.Name
	// Static obstacles that should be navigated around
	Obstacles []*spatialmath.GeoObstacle
	// Optional motion configuration
	MotionCfg *MotionConfiguration
	Extra     map[string]interface{}
}

MoveOnGlobeReq describes the request to the MoveOnGlobe interface method.

func (MoveOnGlobeReq) String

func (r MoveOnGlobeReq) String() string

type MoveOnMapReq

type MoveOnMapReq struct {
	ComponentName resource.Name
	Destination   spatialmath.Pose
	SlamName      resource.Name
	MotionCfg     *MotionConfiguration
	Obstacles     []spatialmath.Geometry
	Extra         map[string]interface{}
}

MoveOnMapReq describes a request to MoveOnMap.

func (MoveOnMapReq) String

func (r MoveOnMapReq) String() string

type ObstacleDetectorName

type ObstacleDetectorName struct {
	VisionServiceName resource.Name
	CameraName        resource.Name
}

ObstacleDetectorName pairs a vision service name with a camera name.

type PlanHistoryReq

type PlanHistoryReq struct {
	// ComponentName the returned plans should be associated with.
	ComponentName resource.Name
	// When true, only the most recent plan will be returned which matches the ComponentName & ExecutionID if one was provided.
	LastPlanOnly bool
	// Optional, when not uuid.Nil it specifies the ExecutionID of the plans that should be returned.
	// Can be used to query plans from executions before the most recent one.
	ExecutionID ExecutionID
	Extra       map[string]interface{}
}

PlanHistoryReq describes the request to PlanHistory().

type PlanID

type PlanID = uuid.UUID

PlanID uniquely identifies a Plan.

type PlanState

type PlanState uint8

PlanState denotes the state a Plan is in.

func (PlanState) String

func (ps PlanState) String() string

func (PlanState) ToProto

func (ps PlanState) ToProto() pb.PlanState

ToProto converts a PlanState to a pb.PlanState.

type PlanStatus

type PlanStatus struct {
	State     PlanState
	Timestamp time.Time
	Reason    *string
}

PlanStatus describes the state of a given plan at a point in time allong with an optional reason why the PlanStatus transitioned to that state.

func (PlanStatus) ToProto

func (ps PlanStatus) ToProto() *pb.PlanStatus

ToProto converts a PlanStatus to a *pb.PlanStatus.

type PlanStatusWithID

type PlanStatusWithID struct {
	PlanID        PlanID
	ComponentName resource.Name
	ExecutionID   ExecutionID
	Status        PlanStatus
}

PlanStatusWithID describes the state of a given plan at a point in time plus the PlanId, ComponentName and ExecutionID the status is associated with.

func (PlanStatusWithID) ToProto

func (ps PlanStatusWithID) ToProto() *pb.PlanStatusWithID

ToProto converts a PlanStatusWithID to a *pb.PlanStatusWithID.

type PlanWithMetadata

type PlanWithMetadata struct {
	// Unique ID of the plan
	ID PlanID
	// Name of the component the plan is planning for
	ComponentName resource.Name
	// Unique ID of the execution
	ExecutionID ExecutionID
	// The motionplan itself
	motionplan.Plan
	// The GPS point to anchor visualized plans at
	AnchorGeoPose *spatialmath.GeoPose
}

PlanWithMetadata represents a motion plan with additional metadata used by the motion service.

func (PlanWithMetadata) Renderable

func (p PlanWithMetadata) Renderable() PlanWithMetadata

Renderable returns a copy of the struct substituting its Plan for a GeoPlan consisting of smuggled global coordinates This will only be done if the AnchorGeoPose field is non-nil, otherwise the original struct will be returned.

func (PlanWithMetadata) ToProto

func (p PlanWithMetadata) ToProto() *pb.Plan

ToProto converts a Plan to a *pb.Plan.

type PlanWithStatus

type PlanWithStatus struct {
	Plan          PlanWithMetadata
	StatusHistory []PlanStatus
}

PlanWithStatus contains a plan, its current status, and all state changes that came prior sorted by ascending timestamp.

func (PlanWithStatus) ToProto

func (pws PlanWithStatus) ToProto() *pb.PlanWithStatus

ToProto converts a PlanWithStatus to a *pb.PlanWithStatus.

type Service

type Service interface {
	resource.Resource
	Move(
		ctx context.Context,
		componentName resource.Name,
		destination *referenceframe.PoseInFrame,
		worldState *referenceframe.WorldState,
		constraints *pb.Constraints,
		extra map[string]interface{},
	) (bool, error)
	MoveOnMap(
		ctx context.Context,
		req MoveOnMapReq,
	) (ExecutionID, error)
	MoveOnGlobe(
		ctx context.Context,
		req MoveOnGlobeReq,
	) (ExecutionID, error)
	GetPose(
		ctx context.Context,
		componentName resource.Name,
		destinationFrame string,
		supplementalTransforms []*referenceframe.LinkInFrame,
		extra map[string]interface{},
	) (*referenceframe.PoseInFrame, error)
	StopPlan(
		ctx context.Context,
		req StopPlanReq,
	) error
	ListPlanStatuses(
		ctx context.Context,
		req ListPlanStatusesReq,
	) ([]PlanStatusWithID, error)
	PlanHistory(
		ctx context.Context,
		req PlanHistoryReq,
	) ([]PlanWithStatus, error)
}

A Service controls the flow of moving components.

func FromDependencies

func FromDependencies(deps resource.Dependencies, name string) (Service, error)

FromDependencies is a helper for getting the named motion service from a collection of dependencies.

func FromRobot

func FromRobot(r robot.Robot, name string) (Service, error)

FromRobot is a helper for getting the named motion service from the given Robot.

func NewClientFromConn

func NewClientFromConn(
	ctx context.Context,
	conn rpc.ClientConn,
	remoteName string,
	name resource.Name,
	logger logging.Logger,
) (Service, error)

NewClientFromConn constructs a new Client from connection passed in.

type StopPlanReq

type StopPlanReq struct {
	// ComponentName of the plan which should be stopped
	ComponentName resource.Name
	Extra         map[string]interface{}
}

StopPlanReq describes the request to StopPlan().