# 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:

1. Gathers the current positions of the machine’s components as defined with the [frame system](https://docs.viam.com/motion-planning/frame-system/overview/).
2. Plans the necessary motions to move a component to a given destination while obeying any [constraints you configure](https://docs.viam.com/reference/services/motion/constraints/).

The motion service can:

- use motion [planning algorithms](https://docs.viam.com/motion-planning/reference/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](https://docs.viam.com/motion-planning/frame-system/overview/).  
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](https://docs.viam.com/reference/services/motion/#tabset-referenceservicesmotion-3-0)
- [From within a module](https://docs.viam.com/reference/services/motion/#tabset-referenceservicesmotion-3-1)

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](https://docs.viam.com/reference/services/motion/#tabset-referenceservicesmotion-1-0)
- [Go](https://docs.viam.com/reference/services/motion/#tabset-referenceservicesmotion-1-1)

```python

```
Copy

```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](https://docs.viam.com/build-modules/dependencies/), using the resource name `builtin`.  
For example:

- [Python](https://docs.viam.com/reference/services/motion/#tabset-referenceservicesmotion-2-0)
- [Go](https://docs.viam.com/reference/services/motion/#tabset-referenceservicesmotion-2-1)

1. 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.

```python

```

Copy

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

```python

```

Copy

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

```python

```

Copy

```go

```

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](https://docs.viam.com/reference/apis/services/motion/) supports the following methods:

| Method Name | Description |
| --- | --- |
| [`Move`](https://docs.viam.com/reference/apis/services/motion/#move) | The `Move` method is the primary way to move multiple components, or to move any object to any other location. |
| [`MoveOnMap`](https://docs.viam.com/reference/apis/services/motion/#moveonmap) | Move a base component to a destination pose on a SLAM map. |
| [`MoveOnGlobe`](https://docs.viam.com/reference/apis/services/motion/#moveonglobe) | Move a base component to a destination GPS point, represented in geographic notation _(latitude, longitude)_. |
| [`GetPose`](https://docs.viam.com/reference/apis/services/motion/#getpose) | `GetPose` gets the location and orientation of a component within the frame system. |
| [`StopPlan`](https://docs.viam.com/reference/apis/services/motion/#stopplan) | Stop a base component being moved by an in progress `MoveOnGlobe` or `MoveOnMap` call. |
| [`ListPlanStatuses`](https://docs.viam.com/reference/apis/services/motion/#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`](https://docs.viam.com/reference/apis/services/motion/#getplan) | By default, returns the plan history of the most recent `MoveOnGlobe` or `MoveOnMap` call to move a base component. |
| [`Reconfigure`](https://docs.viam.com/reference/apis/services/motion/#reconfigure) | Reconfigure this resource. |
| [`FromRobot`](https://docs.viam.com/reference/apis/services/motion/#fromrobot) | Get the resource from the provided machine. |
| [`DoCommand`](https://docs.viam.com/reference/apis/services/motion/#docommand) | Execute model-specific commands that are not otherwise defined by the service API. |
| [`GetResourceName`](https://docs.viam.com/reference/apis/services/motion/#getresourcename) | Get the `ResourceName` for this instance of the motion service. |
| [`Close`](https://docs.viam.com/reference/apis/services/motion/#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](https://docs.viam.com/monitor/).

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.