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 save plans for debugging or replay, 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:

from viam.services.motion import MotionClient

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

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

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

Configuration attributes

Every machine includes a default motion service named builtin, which has no configuration. To set the attributes below, add a motion service with the model rdk:builtin:builtin to your machine’s configuration. In the Viam app, its configuration panel sets the plan-file and log attributes under Plan files and Logs. If you name the service builtin, it replaces the default service. With any other name, both services run, and your settings apply only to requests sent to the service you added.

All attributes are optional:

AttributeTypeDefaultDescription
log_file_pathstring(none)Path to write planning debug logs.
plan_file_pathstring(none)Directory to write plan files to. Required by log_planner_errors and log_slow_plan_threshold_ms; on its own, it writes nothing.
plan_directory_include_trace_idboolfalseInclude trace ID in plan output directory names.
log_planner_errorsboolfalseWrite a plan file for every request that fails to plan. A failed plan’s file holds the request only, with no trajectory.
log_slow_plan_threshold_msint(none)Write a plan file for every plan that takes longer than this many milliseconds. Set it to -1 to write a file for every plan. The Save motion plans toggle in the Viam app does this.
input_range_overrideobject(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:

{
  "name": "builtin",
  "api": "rdk:service:motion",
  "model": "rdk:builtin:builtin",
  "attributes": {
    "plan_file_path": "${environment.HOME}/.viam/plans",
    "log_planner_errors": true,
    "log_slow_plan_threshold_ms": 5000
  }
}

To replay saved plans in the 3D SCENE tab, sync the plan directory to the cloud; see Replay a saved plan in the 3D scene.

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

ParameterValueDescription
Planning timeout300 secondsMaximum time to search for a path.
Resolution2.0Constraint-checking granularity (mm or degrees per step).
Max IK solutions100Maximum inverse kinematics solutions to test for a direct path and seed the fallback search.
Smoothing iterations3 passes of sizes 10, 3, 1Path smoothing passes applied in sequence to cBiRRT fallback paths.
Collision buffer1e-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:

CommandDescription
"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 for the full flag reference.

What’s next