Motion service API

Parameters:

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

Returns:

• (bool): Whether the move was successful (true) or unsuccessful (false).
• (error): An error, if one occurred.

Example:

motionService, err := motion.FromProvider(machine, "builtin")

// Assumes a gripper configured with name "my_gripper" on the machine
gripperName := "my_gripper"

// Define a destination Pose
destination := referenceframe.NewPoseInFrame("world", spatialmath.NewPoseFromPoint(r3.Vector{X: 0.1, Y: 0.0, Z: 0.0}))

// Create obstacles
boxPose := spatialmath.NewPoseFromPoint(r3.Vector{X: 0.0, Y: 0.0, Z: 0.0})
boxDims := r3.Vector{X: 0.2, Y: 0.2, Z: 0.2} // 20cm x 20cm x 20cm box
obstacle, _ := spatialmath.NewBox(boxPose, boxDims, "obstacle_1")

geometryInFrame := referenceframe.NewGeometriesInFrame("base", []spatialmath.Geometry{obstacle})
obstacles := []*referenceframe.GeometriesInFrame{geometryInFrame}

// Create transforms
transform := referenceframe.NewLinkInFrame("gripper",
  spatialmath.NewPoseFromPoint(r3.Vector{X: 0.1, Y: 0.0, Z: 0.1}), "transform_1", nil
)
transforms := []*referenceframe.LinkInFrame{transform}

// Create WorldState
worldState, err := referenceframe.NewWorldState(obstacles, transforms)

// Move gripper component

moved, err := motionService.Move(context.Background(), motion.MoveReq{
  ComponentName: gripperName,
  Destination: destination,
  WorldState: worldState
})

For more information, see the Go SDK Docs.

Parameters:

• destination (PlainMessage) (required): Destination to move to, which can a pose in the reference frame of any frame in the robot’s frame system.
• componentName (string) (required): Component on the robot to move to the specified destination.
• worldState (PlainMessage) (optional): Avoid obstacles by specifying their geometries in the world state. Augment the frame system of the robot by specifying additional transforms to add to it for the duration of the Move.
• constraints (PlainMessage) (optional): Constrain the way the robot will move.
• extra (None) (optional)
• callOptions (CallOptions) (optional)

Returns:

• (Promise): Whether the move was successful (true) or unsuccessful (false).

Example:

const motion = new VIAM.MotionClient(machine, 'builtin');

// Assumes a gripper configured with name "my_gripper"
cconst gripperName = "my_gripper";

const goalPose: VIAM.Pose = {
  x: -817,
  y: -230,
  z: 62,
  oX: -1,
  oY: 0,
  oZ: 0,
  theta: 90,
};
const goalPoseInFrame = new VIAM.PoseInFrame({
  referenceFrame: 'world',
  pose: goalPose,
});

// Move the gripper
const moved = await motion.move(goalPoseInFrame, gripperName);

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.

• req (MoveOnMapReq): A MoveOnMapReq which contains the following values:

• ComponentName (resource.Name): The resource.Name of the base to move.

• Destination (spatialmath.Pose): The destination, which can be any Pose with respect to the SLAM map’s origin.

• SlamName (resource.Name): The resource.Name of the SLAM service from which the SLAM map is requested.

• MotionConfig (*MotionConfiguration): The configuration you want to set across this machine for this motion service. This parameter and each of its fields are optional.

  • ObstacleDetectors ([]ObstacleDetectorName): The names of each vision service and camera resource pair you want to use for transient obstacle avoidance.
  • PositionPollingFreqHz (float64): The frequency in hz to poll the position of the machine.
  • ObstaclePollingFreqHz (float64): The frequency in hz to poll the vision service for new obstacles.
  • PlanDeviationM (float64): The distance in meters that the machine can deviate from the motion plan. By default this is set to 2.6 m which is an appropriate value for outdoor usage. When you use the CONTROL tab, the underlying calls to MoveOnMap() use 0.5 m instead.
  • LinearMPerSec (float64): Linear velocity this machine should target when moving.
  • AngularDegsPerSec (float64): Angular velocity this machine should target when turning.

• Obstacles ([]spatialmath.Geometry): Obstacles, specified in the SLAM frame coordinate system, to be considered when planning the motion of the component.

• Extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

• (ExecutionID): ExecutionID of the MoveOnMap call.
• (error): An error, if one occurred.

Example:

// Assumes a base with the name "my_base" is configured on the machine
myBaseResourceName := base.Named("my_base")
mySLAMServiceResourceName := slam.Named("my_slam_service")

// Define a destination Pose
myPose := spatialmath.NewPoseFromPoint(r3.Vector{Y: 10})

// Move the base component to the destination pose
executionID, err := motionService.MoveOnMap(context.Background(), motion.MoveOnMapReq{
  ComponentName: myBaseResourceName,
  Destination:   myPose,
  SlamName:      mySLAMServiceResourceName,
})

// MoveOnMap is a non-blocking method and this line can optionally be added to block until the movement is done
err = motion.PollHistoryUntilSuccessOrError(
  context.Background(),
  motionService,
  time.Duration(time.Second),
  motion.PlanHistoryReq{
    ComponentName: myBaseResourceName,
    ExecutionID:   executionID,
  },
)

For more information, see the Go SDK Docs.

Parameters:

• destination (PlainMessage) (required): Specify a destination to, which can be any Pose with respect to the SLAM map’s origin.
• componentName (string) (required): Component on the robot to move to the specified destination.
• slamServiceName (string) (required): Name of the SLAM service from which the SLAM map is requested.
• motionConfig (PlainMessage) (optional)
• obstacles (PlainMessage) (optional): Optional obstacles to be considered for motion planning.
• extra (None) (optional)
• callOptions (CallOptions) (optional)

Returns:

• (Promise)

Example:

const motion = new VIAM.MotionClient(machine, 'builtin');

// Define destination pose with respect to map origin
const myPose: VIAM.Pose = {
  x: 0,
  y: 10,
  z: 0,
  oX: 0,
  oY: 0,
  oZ: 0,
  theta: 0,
};

const baseName = 'my_base';
const slamServiceName = 'my_slam_service';

// Move the base to Y=10 (location of 0,10,0) relative to map origin
const executionId = await motion.moveOnMap(
  myPose,
  baseName,
  slamServiceName
);

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.

• req (MoveOnGlobeReq): A MoveOnGlobeReq which contains the following values:

• componentName (resource.Name): The resource.Name of the base to move.

• destination (*geo.Point): The location of the component’s destination, represented in geographic notation as a Point (lat, lng).

• heading (float64): The compass heading, in degrees, that the machine’s movement sensor should report at the destination point.

  • Range: [0-360) 0: North, 90: East, 180: South, 270: West
  • Default: 0

• movementSensorName (resource.Name): The resource.Name of the movement sensor that you want to use to check the machine’s location.

• obstacles ([]*spatialmath.GeoGeometry): Obstacles to consider when planning the motion of the component, with each represented as a GeoGeometry.

  • Default: nil

• motionConfig (*MotionConfiguration): The configuration you want to set across this machine for this motion service. This parameter and each of its fields are optional.

  • ObstacleDetectors ([]ObstacleDetectorName): The names of each vision service and camera resource pair you want to use for transient obstacle avoidance.
  • PositionPollingFreqHz (float64): The frequency in hz to poll the position of the machine.
  • ObstaclePollingFreqHz (float64): The frequency in hz to poll the vision service for new obstacles.
  • PlanDeviationM (float64): The distance in meters that the machine can deviate from the motion plan.
  • LinearMPerSec (float64): Linear velocity this machine should target when moving.
  • AngularDegsPerSec (float64): Angular velocity this machine should target when turning.

Returns:

• (ExecutionID): ExecutionID of the MoveOnGlobe call.
• (error): An error, if one occurred.

Example:

// Assumes a base with the name "myBase" is configured on the machine
// Get the resource names of the base and movement sensor
myBaseResourceName := base.Named("myBase")
myMvmntSensorResourceName := movementsensor.Named("my_movement_sensor")

// Define a destination Point at the GPS coordinates [0, 0]
myDestination := geo.NewPoint(0, 0)

// Move the base component to the designated geographic location, as reported by the movement sensor
executionID, err := motionService.MoveOnGlobe(context.Background(), motion.MoveOnGlobeReq{
  ComponentName:      myBaseResourceName,
  Destination:        myDestination,
  MovementSensorName: myMvmntSensorResourceName,
})

// Assumes there is an active MoveOnMap() or MoveonGlobe() in progress for myBase
//  MoveOnGlobe is a non-blocking method and this line can optionally be added to block until the movement is done
err = motion.PollHistoryUntilSuccessOrError(
  context.Background(),
  motionService,
  time.Duration(time.Second),
  motion.PlanHistoryReq{
    ComponentName: myBaseResourceName,
    ExecutionID:   executionID,
  },
)

For more information, see the Go SDK Docs.

Parameters:

• destination (PlainMessage) (required): Destination for the component to move to, represented as a GeoPoint.
• componentName (string) (required): The name of the component to move.
• movementSensorName (string) (required): The name of the Movement Sensor used to check the robot’s location.
• heading (number) (optional): Compass heading, in degrees, to achieve at destination.
• obstaclesList (PlainMessage) (optional): Obstacles to consider when planning the motion of the component.
• motionConfig (PlainMessage) (optional)
• boundingRegionsList (PlainMessage) (optional)
• extra (None) (optional)
• callOptions (CallOptions) (optional)

Returns:

• (Promise)

Example:

const motion = new VIAM.MotionClient(machine, 'builtin');

// Define destination at GPS coordinates [0,0]
const destination: VIAM.GeoPoint = {
  latitude: 40.7,
  longitude: -73.98,
};

const baseName = 'my_base';
const movementSensorName = 'my_movement_sensor';

// Move the base to the geographic location
const globeExecutionId = await motion.moveOnGlobe(
  destination,
  baseName,
  movementSensorName
);

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.

• componentName (string): The resource.Name of the piece of the machine whose pose is returned.

• destinationFrame (string): The name of the frame with respect to which the component’s pose is reported.

• supplementalTransforms ([]*referenceframe.LinkInFrame): An optional list of LinkInFrames. A LinkInFrame represents an additional frame which is added to the machine’s frame system. It consists of:

  • a PoseInFrame: Provides the relationship between the frame being added and another frame.
  • Geometry: An optional Geometry can be added to the frame being added. When supplementalTransforms are provided, a frame system is created within the context of the GetPose function. This new frame system builds off the machine’s frame system and incorporates the LinkInFrames provided. If the result of adding the LinkInFrames results in a disconnected frame system, an error is thrown.

• extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

• (*referenceframe.PoseInFrame): The pose of the component.
• (error): An error, if one occurred.

For more information, see the Go SDK Docs.

Parameters:

• componentName (string) (required)
• destinationFrame (string) (required)
• supplementalTransforms (PlainMessage) (required)
• extra (None) (optional)
• callOptions (CallOptions) (optional)

Returns:

• (Promise<commonApi.PoseInFrame>)

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.
• req (StopPlanReq): A StopPlanReq which contains the following values:
  • componentName (resource.Name): The resource.Name of the base to stop.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

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

Example:

motionService, err := motion.FromProvider(machine, "builtin")
myBaseResourceName := base.Named("myBase")

myMvmntSensorResourceName := movement_sensor.Named("my_movement_sensor")
myDestination := geo.NewPoint(0, 0)

// Assuming a `MoveOnGlobe()`` started the execution
// Stop the base component which was instructed to move by `MoveOnGlobe()` or `MoveOnMap()`
err := motionService.StopPlan(context.Background(), motion.StopPlanReq{
    ComponentName: s.req.ComponentName,
})

For more information, see the Go SDK Docs.

Parameters:

• componentName (string) (required): The component to stop.
• extra (None) (optional)
• callOptions (CallOptions) (optional)

Returns:

• (Promise)

Example:

const motion = new VIAM.MotionClient(machine, 'builtin');
const baseName = 'my_base';

// Stop the base component which was instructed to move
await motion.stopPlan(baseName);

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.
• req (ListPlanStatusesReq): A ListPlanStatusesReq which contains the following values:
  • onlyActivePlans (bool): If true, the response will only return plans which are executing.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

• ([]PlanStatusWithID): The state of a given plan at a point in time plus the PlanId, ComponentName and ExecutionID the status is associated with.
• (error): An error, if one occurred.

Example:

motionService, err := motion.FromProvider(machine, "builtin")

// Get the plan(s) of the base component's most recent execution i.e. `MoveOnGlobe()` or `MoveOnMap()` call.
planStatuses, err := motionService.ListPlanStatuses(context.Background(), motion.ListPlanStatusesReq{})

For more information, see the Go SDK Docs.

Parameters:

• onlyActivePlans (boolean) (optional): If true, the response will only return plans which are executing.
• extra (None) (optional)
• callOptions (CallOptions) (optional)

Returns:

• (Promise<motionApi.ListPlanStatusesResponse>)

Example:

const motion = new VIAM.MotionClient(machine, 'builtin');

// List plan statuses within the TTL
const response = await motion.listPlanStatuses();

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.
• req (PlanHistoryReq): A PlanHistoryReq which contains the following values:
  • componentName (resource.Name): The resource.Name of the base to stop.
  • lastPlanOnly (bool): If true, the response will only return the last plan for the component / execution
  • executionID (ExecutionID): If non empty, the response will return the plans of the provided execution & component. Useful for retrieving plans from executions before the current execution.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

• ([]PlanWithStatus): PlanWithStatus contains a plan, its current status, and all state changes that came prior sorted by ascending timestamp.
• (error): An error, if one occurred.

Example:

// Get the resource name of the base component
myBaseResourceName := base.Named("myBase")

// Get the plan history of the base component's most recent execution (e.g., MoveOnGlobe or MoveOnMap call)
planHistory, err := motionService.PlanHistory(context.Background(), motion.PlanHistoryReq{
  ComponentName: myBaseResourceName,
})

For more information, see the Go SDK Docs.

Parameters:

• componentName (string) (required): The component to query.
• lastPlanOnly (boolean) (optional)
• executionId (string) (optional)
• extra (None) (optional)
• callOptions (CallOptions) (optional)

Returns:

• (Promise<motionApi.GetPlanResponse>)

Example:

const motion = new VIAM.MotionClient(machine, 'builtin');
const baseName = 'my_base';

// Get the plan(s) of the base component
const response = await motion.getPlan(baseName);

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.
• cmd (map[string]interface{}): The command to execute.

Returns:

• (map[string]interface{}): The command response.
• (error): An error, if one occurred.

Example:

myMotionSvc, err := motion.FromProvider(machine, "my_motion_svc")

command := map[string]interface{}{"cmd": "test", "data1": 500}
result, err := myMotionSvc.DoCommand(context.Background(), command)

For more information, see the Go SDK Docs.

Parameters:

• command (Struct) (required): The command to execute. Accepts either a Struct or a plain object, which will be converted automatically.
• callOptions (CallOptions) (optional)

Returns:

• (Promise<JsonValue>)

Example:

// Plain object (recommended)
const result = await resource.doCommand({
  myCommand: { key: 'value' },
});

// Struct (still supported)
import { Struct } from '@viamrobotics/sdk';

const result = await resource.doCommand(
  Struct.fromJson({ myCommand: { key: 'value' } })
);

For more information, see the TypeScript SDK Docs.

Parameters:

• None.

Returns:

• (Name)

Example:

myMotionSvc, err := motion.FromProvider(machine, "my_motion_svc")

err = myMotionSvc.Name()

For more information, see the Go SDK Docs.

Parameters:

• None.

Returns:

• (string): The name of the resource.

Example:

motion.name

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:

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

Example:

myMotionSvc, err := motion.FromProvider(machine, "my_motion_svc")

err = myMotionSvc.Close(context.Background())

For more information, see the Go SDK Docs.