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{}
• type ExecutionID
• type ListPlanStatusesReq
• type Localizer
  • func NewMovementSensorLocalizer(ms movementsensor.MovementSensor, origin *geo.Point, ...) Localizer
  • func NewSLAMLocalizer(slam slam.Service) Localizer
• type MotionConfiguration
• type MoveOnGlobeReq
  • func (r MoveOnGlobeReq) String() string
• type MoveOnMapReq
• type ObstacleDetectorName
• type Plan
  • func (p Plan) ToProto() *pb.Plan
• 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 PlanStep
  • func (s PlanStep) ToProto() *pb.PlanStep
• 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 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.

Types

type ExecutionID

type ExecutionID = uuid.UUID

ExecutionID uniquely identifies an execution.

type ListPlanStatusesReq

type ListPlanStatusesReq struct {
	OnlyActivePlans bool
	Extra           map[string]interface{}
}

ListPlanStatusesReq describes the request to the ListPlanStatuses interface method. If OnlyActivePlans is true then only active plans will be returned. Also contains an Extra parameter.

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.

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      resource.Name
	Destination        *geo.Point
	Heading            float64
	MovementSensorName resource.Name
	Obstacles          []*spatialmath.GeoObstacle
	MotionCfg          *MotionConfiguration
	Extra              map[string]interface{}
}

MoveOnGlobeReq describes the request to the GetPlan interface method. Contains the ComponentName the returned plan(s) should be associated with, an optional ExecutionID and an Extra parameter.

func (MoveOnGlobeReq) String

func (r MoveOnGlobeReq) String() string

type MoveOnMapReq

type MoveOnMapReq struct {
	ComponentName resource.Name
	Destination   spatialmath.Pose
	SlamName      resource.Name
	Extra         map[string]interface{}
}

MoveOnMapReq describes a request to MoveOnMap.

type ObstacleDetectorName

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

ObstacleDetectorName pairs a vision service name with a camera name.

type Plan

type Plan struct {
	ID            PlanID
	ComponentName resource.Name
	ExecutionID   ExecutionID
	Steps         []PlanStep
}

Plan represnts a motion plan. Has a unique ID, ComponentName, ExecutionID and a sequence of Steps which can be executed to follow the plan.

func (Plan) ToProto

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

ToProto converts a Plan to a *pb.Plan.

type PlanHistoryReq

type PlanHistoryReq struct {
	ComponentName resource.Name
	LastPlanOnly  bool
	ExecutionID   ExecutionID
	Extra         map[string]interface{}
}

PlanHistoryReq describes the request to the PlanHistory interface method. Contains the ComponentName the returned plan(s) should be associated with, an optional ExecutionID and an Extra parameter. If LastPlanOnly is set to true then only the most recent plan for the component & execution in question is returned.

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 PlanStep

type PlanStep map[resource.Name]spatialmath.Pose

PlanStep represents a single step of the plan Describes the pose each resource described by the plan should move to at that step.

func (PlanStep) ToProto

func (s PlanStep) ToProto() *pb.PlanStep

ToProto converts a Step to a *pb.PlanStep.

type PlanWithStatus

type PlanWithStatus struct {
	Plan          Plan
	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,
		componentName resource.Name,
		destination spatialmath.Pose,
		slamName resource.Name,
		extra map[string]interface{},
	) (bool, error)
	MoveOnGlobe(
		ctx context.Context,
		componentName resource.Name,
		destination *geo.Point,
		heading float64,
		movementSensorName resource.Name,
		obstacles []*spatialmath.GeoObstacle,
		motionConfig *MotionConfiguration,
		extra map[string]interface{},
	) (bool, error)
	MoveOnGlobeNew(
		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 resource.Name
	Extra         map[string]interface{}
}

StopPlanReq describes the request to the StopPlan interface method. Contains the ComponentName of the plan which should be stopped & an Extra parameter.