Motion service configuration | Reference

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:

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:

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:

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

What’s next