# Motion service configuration

The motion service plans and executes component motion: arm end-effector moves, base moves across a SLAM map, and base moves to a GPS coordinate. The builtin service ships with every machine running `viam-server`, so you do not need to add it to your configuration.

Most users never configure the motion service. Read this page if you need to log planning errors, cap planning threads, or narrow a joint’s range below its kinematic limits.

## Access the motion service

Use the resource name "builtin" to get the default motion service client:

- [Python](https://docs.viam.com/motion-planning/reference/motion-service/#tabset-motion-planningreferencemotion-service-1-0)
- [Go](https://docs.viam.com/motion-planning/reference/motion-service/#tabset-motion-planningreferencemotion-service-1-1)

```python
from viam.services.motion import MotionClient

motion_service = MotionClient.from_robot(machine, "builtin")
```

```go
import "go.viam.com/rdk/services/motion"

motionService, err := motion.FromProvider(machine, "builtin")
if err != nil {
    logger.Fatal(err)
}
```

## Configuration attributes

The builtin motion service accepts the following optional configuration attributes:

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `log_file_path` | string | (none) | Path to write planning debug logs. |
| `num_threads` | int | (system default) | Number of threads for parallel planning. |
| `plan_file_path` | string | (none) | Path to write plan output files. |
| `plan_directory_include_trace_id` | bool | false | Include trace ID in plan output directory names. |
| `log_planner_errors` | bool | false | Log planning errors to the log file. |
| `log_slow_plan_threshold_ms` | int | (none) | Log plans that take longer than this threshold in milliseconds. |
| `input_range_override` | object | (none) | Narrow a joint’s allowed range below its kinematic limits. The value is a map from frame name to a map from joint index (string) to `{"min": <value>, "max": <value>}`. For example, `{"my-arm": {"3": {"min": 0, "max": 2}}}` restricts joint 3 of `my-arm` to the range 0-2. |

Example configuration:

```json
{
  "name": "builtin",
  "api": "rdk:service:motion",
  "model": "rdk:builtin:builtin",
  "attributes": {
    "log_planner_errors": true,
    "log_slow_plan_threshold_ms": 5000
  }
}
```

## Planning defaults

The builtin service compiles the defaults below into the binary. To change them at runtime, pass overrides through the `extra` map on a `Move` call (see the algorithms reference for the tunable list).

| Parameter | Value | Description |
| --- | --- | --- |
| Planning timeout | 300 seconds | Maximum time to search for a path. |
| Resolution | 2.0 | Constraint-checking granularity (mm or degrees per step). |
| Max IK solutions | 100 | Maximum inverse kinematics solutions to test for a direct path and seed the fallback search. |
| Smoothing iterations | 3 passes of sizes 10, 3, 1 | Path smoothing passes applied in sequence to cBiRRT fallback paths. |
| Collision buffer | 1e-8 mm (effectively zero) | Default buffer. Size obstacle geometries to include any safety margin, or pass `collision_buffer_mm` through the `extra` map on a Move call to override per request. |

## DoCommand

The builtin motion service supports the following commands through `DoCommand`:

| Command | Description |
| --- | --- |
| "plan" | Generate a motion plan without executing it. |
| "execute" | Execute a previously generated plan. |
| "executeCheckStart" | Execute a plan after verifying the arm is at the expected start position. |

## CLI commands

The Viam CLI provides `print-config`, `print-status`, `get-pose`, and `set-pose` for inspecting the motion service from the command line. See [Motion CLI commands](https://docs.viam.com/motion-planning/reference/cli-commands/) for the full flag reference.

## What’s next

- [Motion service API](https://docs.viam.com/motion-planning/reference/api/): full API reference.
- [How motion planning works](https://docs.viam.com/motion-planning/how-planning-works/): how the planner searches for collision-free paths.
- [Configure motion constraints](https://docs.viam.com/motion-planning/move-an-arm/constraints/): restrict arm movement during planning.