Motion service API

The motion service API allows you to give commands to your motion service for moving a mobile robot based on a SLAM map or GPS coordinates or for moving a machine’s components from one pose to another.

The motion service supports the following methods:

API

Move

The Move method is the primary way to move multiple components, or to move any object to any other location. Given a destination pose and a component to move to that destination, Move will:

1. Construct a full kinematic chain from goal to destination including all movable components in between.
2. Solve that chain to move the specified component frame to the destination while adhering to any constraints.
3. Execute that movement to move the actual machine.
4. Return whether or not this process succeeded.

The motion service takes the volumes associated with all configured machine components (local and remote) into account for each request to ensure that the machine does not collide with itself or other known objects.

• Python
• Go
• TypeScript

Parameters:

• component_name ( str) (required): The ResourceName of the piece of the robot that should arrive at the destination. Note that move moves the distal end of the component to the destination. For example, when moving a robotic arm, the piece that will arrive at the destination is the end effector attachment point, not the base of the arm.

• destination ( viam.proto.common.PoseInFrame) (required): Describes where the component_name frame should be moved to. Can be any pose, from the perspective of any component whose location is configured as a frame.

• world_state ( viam.proto.common.WorldState) (optional): Data structure specifying information about the world around the machine. Used to augment the motion solving process.

• constraints ( viam.proto.service.motion.Constraints) (optional): Pass in motion constraints. By default, motion is unconstrained with the exception of obstacle avoidance.

• extra (Mapping[ str, Any]) (optional): Extra options to pass to the underlying RPC call.

• timeout ( float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

• ( bool): Whether the move was successful (true) or unsuccessful (false).

MoveOnMap

Not supported by the builtin motion service

The builtin motion service no longer implements MoveOnMap and returns the error MoveOnMap not supported by builtin when called. The implementation was removed in rdk#5475 (November 2025).

MoveOnMap is still part of the motion service API, so a third-party module can implement it. Check the Viam registry for a motion-service module that supports it before relying on this method.

MoveOnGlobe

Move a base component to a destination GPS point, represented in geographic notation (latitude, longitude). Use a movement sensor to check the location of the machine.

MoveOnGlobe() is non blocking, meaning the motion service will move the component to the destination GPS point after MoveOnGlobe() returns.

Each successful MoveOnGlobe() call returns a unique ExecutionID which you can use to identify all plans generated during the MoveOnGlobe().

GetPose

GetPose gets the location and orientation of a component within the frame system. The return type of this function is a PoseInFrame describing the pose of the specified component with respect to the specified destination frame.

StopPlan

Stop a base component being moved by an in progress MoveOnGlobe or MoveOnMap call.

ListPlanStatuses

Returns the statuses of plans created by MoveOnGlobe or MoveOnMap calls that meet at least one of the following conditions since the motion service initialized:

• the plan’s status is in progress
• the plan’s status changed state within the last 24 hours

GetPlan

By default, returns the plan history of the most recent MoveOnGlobe or MoveOnMap call to move a base component.

Reconfigure

Reconfigure this resource. Reconfigure must reconfigure the resource atomically and in place.

FromRobot

Get the resource from the provided machine.

DoCommand

Execute model-specific commands that are not otherwise defined by the service API.

GetResourceName

Get the ResourceName for this instance of the motion service.

Close

Safely shut down the resource and prevent further use.