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

The builtin motion service accepts the following optional configuration attributes:

AttributeTypeDefaultDescription
log_file_pathstring(none)Path to write planning debug logs.
plan_file_pathstring(none)Path to write plan output files.
plan_directory_include_trace_idboolfalseInclude trace ID in plan output directory names.
log_planner_errorsboolfalseLog planning errors to the log file.
log_slow_plan_threshold_msint(none)Log plans that take longer than this threshold in milliseconds.
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": {
    "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).

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