Motion Service Configuration

The motion service enables your machine to plan and move its components relative to itself, other machines, and the world. The builtin motion service is enabled by default on every machine running viam-server. You do not need to add it to your configuration.

Builtin service limitations

The builtin motion service supports the Move() method for arms and gantries. The following methods return “not supported” errors from the builtin implementation and require a module or the navigation service:

• MoveOnMap(): requires a SLAM service (not recommended)
• MoveOnGlobe(): use the navigation service instead
• GetPlan(), ListPlanStatuses(), StopPlan(): only available with implementations that support MoveOnMap or MoveOnGlobe

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.FromRobot(machine, "builtin")
if err != nil {
    logger.Fatal(err)
}

Configuration attributes

The builtin motion service accepts the following optional configuration attributes:

Example configuration:

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

MotionConfiguration (per-request)

When calling MoveOnGlobe or MoveOnMap (through a supporting implementation), you can pass a MotionConfiguration to override per-request settings:

Planning defaults

The builtin motion service uses the following compiled defaults:

DoCommand

The builtin motion service supports the following commands through DoCommand:

CLI commands

The Viam CLI provides commands for inspecting and testing the motion service from the command line. These are useful for debugging frame configurations and testing motion without writing code.

All commands require the --part flag to identify the machine part.

print-config

Prints the frame system configuration for all parts.

viam machines motion print-config --part "my-machine-main"

print-status

Prints the current pose of every component relative to the world frame.

viam machines motion print-status --part "my-machine-main"

Output shows X, Y, Z position (mm) and orientation (OX, OY, OZ, Theta in degrees) for each frame.

get-pose

Gets the current pose of a specific component in the world frame.

viam machines motion get-pose --part "my-machine-main" --component "my-arm"

set-pose

Moves a component to a specified pose using the motion service. Only the position and orientation values you provide are changed; the rest are kept from the component’s current pose.

viam machines motion set-pose --part "my-machine-main" --component "my-arm" \
  --x 300 --y 200 --z 400

Available flags: --x, --y, --z (position in mm), --ox, --oy, --oz, --theta (orientation vector in degrees).

What’s next

• Motion Service API: full API reference.
• Motion Planning Algorithms: how the planner works.
• Configure Motion Constraints: restrict arm movement during planning.