Edit

Motion Service

The motion service enables your machine to plan and move itself or its components relative to itself, other machines, and the world. The motion service:

Gathers the current positions of the machine’s components as defined with the frame system.
Plans the necessary motions to move a component to a given destination while obeying any constraints you configure.

The motion service can:

use motion planning algorithms locally on your machine to plan coordinated motion across many components.
pass movement requests through to individual components which have implemented their own motion planning.

Configuration

You need to configure frames for your machine’s components with the frame system. This defines the spatial context within which the motion service operates.

The motion service itself is enabled on the machine by default, so you do not need to add any extra configuration to enable it.

Access the motion service in your code

Use the motion service in your code by creating a motion service client and then calling its methods. As with other resource clients, how you get the client depends on whether your code is part of a client application or a module:

From a client application
From within a module

To access the motion service built into viam-server from your client application code, use the resource name builtin to get a motion service client:

Python
Go

# Get a motion service client
motion_service = MotionClient.from_robot(machine, "builtin")

# Then use the motion service, for example:
moved = await motion_service.move(gripper_name, destination, world_state)

// Get a motion service client
motionService, err := motion.FromRobot(machine, "builtin")
if err != nil {
  logger.Fatal(err)
}

// Then use the motion service, for example:
moved, err := motionService.Move(context.Background(), motion.MoveReq{
  ComponentName: gripperName,
  Destination: destination,
  WorldState: worldState
})

If you created your own custom motion service, you can access it using the resource name you gave it in your machine’s configuration.

To access the motion service built into viam-server from your module code, you need to add the motion service as a module dependency, using the resource name builtin. For example:

Python
Go

Edit your validate_config function to add the builtin motion service as a dependency so that it is available to your module. You do not need to check for it in your config because the built-in motion service is always enabled.
```
@classmethod
def validate_config(
    cls, config: ComponentConfig
) -> Tuple[Sequence[str], Sequence[str]]:
    req_deps = []
    req_deps.append("builtin")
    return req_deps, []
```

Edit your reconfigure function to add the motion service as an instance variable so that you can use it in your module:

def reconfigure(
    self, config: ComponentConfig, dependencies: Mapping[ResourceName, ResourceBase]
):
    motion_resource = dependencies[Motion.get_resource_name("builtin")]
    self.motion_service = cast(MotionClient, motion_resource)

    return super().reconfigure(config, dependencies)

You can now use the motion service in your module, for example:

def move_around_in_some_way(self):
    moved = await self.motion_service.move(gripper_name, destination, world_state)
    return moved

The following example assumes your module uses AlwaysRebuild and does not have a Reconfigure function defined.

// Return the motion service as a dependency
func (cfg *Config) Validate(path string) ([]string, []string, error) {
  deps := []string{motion.Named("builtin").String()}
  return deps, nil, nil
}

// Then use the motion service, for example:
func (c *Component) MoveAroundInSomeWay() error {
  c.Motion, err = motion.FromDependencies(deps, "builtin")
  if err != nil {
    return nil, err
  }
  moved, err := c.Motion.Move(context.Background(), motion.MoveReq{
    ComponentName: gripperName,
    Destination: destination,
    WorldState: worldState
  })
  return moved, err
}

If you created your own custom motion service, you can access it using the resource name you gave it in your machine’s configuration. You’ll also need to check for it in your validate function, since it is not built into viam-server.

API

The motion service API supports the following methods:

Method Name	Description
`Move`	The `Move` method is the primary way to move multiple components, or to move any object to any other location.
`MoveOnMap`	Move a base component to a destination pose on a SLAM map.
`MoveOnGlobe`	Move a base component to a destination GPS point, represented in geographic notation (latitude, longitude).
`GetPose`	`GetPose` gets the location and orientation of a component within the frame system.
`StopPlan`	Stop a base component being moved by an in progress `MoveOnGlobe` or `MoveOnMap` call.
`ListPlanStatuses`	Returns the statuses of plans created by `MoveOnGlobe` or `MoveOnMap` calls that meet at least one of the following conditions since the motion service initialized: - the plan’s status is in progress - the plan’s status changed state within the last 24 hours All repeated fields are in chronological order.
`GetPlan`	By default, returns the plan history of the most recent `MoveOnGlobe` or `MoveOnMap` call to move a base component.
`Reconfigure`	Reconfigure this resource.
`FromRobot`	Get the resource from the provided robot with the given name.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the service API.
`GetResourceName`	Get the `ResourceName` for this instance of the motion service with the given name.
`Close`	Safely shut down the resource and prevent further use.

Test the motion service

You can test motion on your machine from the CONTROL tab.

Motion card on the Control tab

Enter x and y coordinates to move your machine to, then click the Move button to issue a MoveOnMap() request.

Info

The plan_deviation_m for MoveOnMap() on calls issued from the CONTROL tab is 0.5 m.

Next steps

The following tutorials contain complete example code for interacting with a robot arm through the arm component API, and with the motion service API, respectively:

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!