Motion service reference | Services

Motion service reference

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:

To access a motion service, use its name from the machine configuration.
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

Copy

To access a motion service, use its name from the machine 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.

Copy

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

Copy

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

Copy

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 machine.
`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.
`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.

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.