MotionConfiguration reference

MotionConfiguration is an optional message you pass to the motion service’s MoveOnGlobe and MoveOnMap calls to override defaults for a single execution. It is not used with Move, which is synchronous and does not expose per-call motion parameters.

The navigation service uses MoveOnGlobe internally and builds a MotionConfiguration from its own attributes. The Navigation service correspondence table at the bottom of this page shows which navigation attribute maps to which MotionConfiguration field.

Fields

ObstacleDetector

Each entry pairs a vision service with a camera:

The motion service queries each detector at obstacle_polling_frequency_hz and feeds the reported geometry to the planner for the remainder of the current execution.

Units

plan_deviation_m is meters at the API boundary. Internally the motion service stores it as millimeters (PlanDeviationMM), applying a x1000 conversion; the Go SDK exposes the millimeter form directly.

Usage

from viam.proto.service.motion import MotionConfiguration, ObstacleDetector
from viam.proto.common import GeoPoint

configuration = MotionConfiguration(
    obstacle_detectors=[
        ObstacleDetector(vision_service="obstacles", camera="front-cam"),
    ],
    position_polling_frequency_hz=2.0,
    obstacle_polling_frequency_hz=2.0,
    plan_deviation_m=5.0,
    linear_m_per_sec=0.5,
    angular_degs_per_sec=30.0,
)

execution_id = await motion_service.move_on_globe(
    component_name="my-base",
    destination=GeoPoint(latitude=40.6640, longitude=-73.9387),
    movement_sensor_name="my-gps",
    configuration=configuration,
)

import (
    geo "github.com/kellydunn/golang-geo"
    "go.viam.com/rdk/services/motion"
)

positionHz := 2.0
obstacleHz := 2.0
configuration := &motion.MotionConfiguration{
    ObstacleDetectors: []motion.ObstacleDetectorName{
        {VisionServiceName: "obstacles", CameraName: "front-cam"},
    },
    PositionPollingFreqHz: &positionHz,
    ObstaclePollingFreqHz: &obstacleHz,
    PlanDeviationMM:       5000, // 5 meters, stored as mm internally
    LinearMPerSec:         0.5,
    AngularDegsPerSec:     30.0,
}

executionID, err := motionService.MoveOnGlobe(ctx, motion.MoveOnGlobeReq{
    ComponentName:      "my-base",
    Destination:        geo.NewPoint(40.6640, -73.9387),
    MovementSensorName: "my-gps",
    MotionCfg:          configuration,
})

The Go SDK’s MotionConfiguration struct stores deviation as PlanDeviationMM (millimeters); the proto and Python SDK use plan_deviation_m (meters).

Navigation service correspondence

When you configure the navigation service, it builds a MotionConfiguration from its attributes on every internal MoveOnGlobe call. The attributes map to MotionConfiguration fields as follows:

The navigation service also has a replan_cost_factor attribute with no MotionConfiguration equivalent; it is a navigation-service-only tuning knob.

What’s next

• Motion service API: the methods that accept MotionConfiguration.
• Navigation service configuration: service-level defaults that become the MotionConfiguration for navigation-driven moves.
• Tune navigation: guidance for choosing specific values for your environment.