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; see Navigation service correspondence below for the mapping.

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. The motion service stores the value internally as millimeters, and the Go SDK’s MotionConfiguration struct exposes that millimeter form as PlanDeviationMM.

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,
})

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.