Motion Service API

from viam.services.motion import MotionClient

Parameters:

• component_name (viam.proto.common.ResourceName) (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. world_state includes obstacles and transforms:

  • Obstacles: Geometries located at a pose relative to some frame. When solving a motion plan with movable frames that contain inherent geometries, the solved path is constrained such that none of those inherent geometries intersect with the obstacles. Important considerations:
    • If a motion begins with a component already in collision with an obstacle, collisions between that specific component and that obstacle will not be checked.
    • The motion service assumes that obstacles are static. If a worldstate obstacle is physically attached to a part of the robot such that it will move with the robot, specify it with transforms.
    • Obstacles are defined by a pose and a geometry with dimensions. The pose location is the point at the center of the geometry.
    • Obstacle locations are defined with respect to the origin of the specified frame. Their poses are relative to the origin of the specified frame. An obstacle associated with the frame of an arm with a pose of {X: 0, Y: 0, Z: -10} is interpreted as being 10mm below the base of the arm, not 10mm below the end effector. This is different from destination and component_name, where poses are relative to the distal end of a frame.
  • Transforms: A list of PoseInFrame messages that specify other transformations to temporarily add to the frame system at solve time. Transforms can be used to account for geometries that are attached to the robot but not configured as robot components. For example, you could use a transform to represent the volume of a marker held in your machine’s gripper. Transforms are not added to the config or carried into later processes.

• 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).

Example:

resource_name = Arm.get_resource_name("externalFrame")
success = await MotionServiceClient.move(resource_name, ...)

For more information, see the Python SDK Docs.

Parameters:

• component_name (viam.proto.common.ResourceName) (required): The ResourceName of the base to move.

• destination (viam.proto.common.Pose) (required): The destination, which can be any Pose with respect to the SLAM map’s origin.

• slam_service_name (viam.proto.common.ResourceName) (required): The ResourceName of the SLAM service from which the SLAM map is requested.

• configuration (viam.proto.service.motion.MotionConfiguration) (optional): The configuration you want to set across this machine for this motion service. This parameter and each of its fields are optional.

• obstacle_detectors (Iterable[ObstacleDetector]): The names of each vision service and camera resource pair you want to use for transient obstacle avoidance.

• position_polling_frequency_hz (float): The frequency in hz to poll the position of the machine.

• obstacle_polling_frequency_hz (float): The frequency in hz to poll the vision service for new obstacles.

• plan_deviation_m (float): The distance in meters that the machine can deviate from the motion plan. By default this is set to 2.6 m which is an appropriate value for outdoor usage. When you use the MoveOnMap() method from the CONTROL tab, the default is overwritten to 0.5 m for testing.

• linear_m_per_sec (float): Linear velocity this machine should target when moving.

• angular_degs_per_sec (float): Angular velocity this machine should target when turning.

• obstacles (Sequence[viam.proto.common.Geometry]) (optional): Obstacles, specified in the SLAM frame coordinate system, to be considered when planning the motion of the component.

• 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:

• (str): ExecutionID of the MoveOnMap call.

Example:

motion = MotionClient.from_robot(robot=machine, name="builtin")

# Get the ResourceNames of the base component and SLAM service
my_base_resource_name = Base.get_resource_name("my_base")
my_slam_service_name = SLAMClient.get_resource_name("my_slam_service")

# Define a destination pose with respect to the origin of the map from the SLAM service "my_slam_service"
my_pose = Pose(y=10)

# Move the base component to the destination pose of Y=10, a location of
# (0, 10, 0) in respect to the origin of the map
execution_id = await motion.move_on_map(component_name=my_base_resource_name,
                                        destination=my_pose,
                                        slam_service_name=my_slam_service_name)

For more information, see the Python SDK Docs.

Parameters:

• component_name (viam.proto.common.ResourceName) (required): The ResourceName of the base to move.

• destination (viam.proto.common.GeoPoint) (required): The location of the component’s destination, represented in geographic notation as a GeoPoint (lat, lng).

• movement_sensor_name (viam.proto.common.ResourceName) (required): The ResourceName of the movement sensor that you want to use to check the machine’s location.

• obstacles (Sequence[viam.proto.common.GeoGeometry]) (optional): Obstacles to consider when planning the motion of the component, with each represented as a GeoGeometry.

  • Default: None

• heading (float) (optional): The compass heading, in degrees, that the machine’s movement sensor should report at the destination point.

  • Range: [0-360) 0: North, 90: East, 180: South, 270: West
  • Default: None

• configuration (viam.proto.service.motion.MotionConfiguration) (optional): The configuration you want to set across this machine for this motion service. This parameter and each of its fields are optional.

• obstacle_detectors (Iterable[ObstacleDetector]): The names of each vision service and camera resource pair you want to use for transient obstacle avoidance.

• position_polling_frequency_hz (float): The frequency in hz to poll the position of the machine.

• obstacle_polling_frequency_hz (float): The frequency in hz to poll the vision service for new obstacles.

• plan_deviation_m (float): The distance in meters that the machine can deviate from the motion plan.

• linear_m_per_sec (float): Linear velocity this machine should target when moving.

• angular_degs_per_sec (float): Angular velocity this machine should target when turning.

• bounding_regions (Sequence[viam.proto.common.GeoGeometry]) (optional): Set of obstacles which the robot must remain within while navigating.

• 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:

• (str): ExecutionID of the MoveOnGlobe call.

Example:

motion = MotionClient.from_robot(robot=machine, name="builtin")

# Get the ResourceNames of the base and movement sensor
my_base_resource_name = Base.get_resource_name("my_base")
mvmnt_sensor_resource_name = MovementSensor.get_resource_name(
    "my_movement_sensor")
#  Define a destination GeoPoint at the GPS coordinates [0, 0]
my_destination = movement_sensor.GeoPoint(latitude=0, longitude=0)

# Move the base component to the designated geographic location, as reported by the movement sensor
execution_id = await motion.move_on_globe(
    component_name=my_base_resource_name,
    destination=my_destination,
    movement_sensor_name=mvmnt_sensor_resource_name)

For more information, see the Python SDK Docs.

Parameters:

• component_name (viam.proto.common.ResourceName) (required): The ResourceName of the piece of the machine whose pose is returned.

• destination_frame (str) (required): The name of the frame with respect to which the component’s pose is reported.

• supplemental_transforms (Sequence[viam.proto.common.Transform]) (optional): A list of Transform objects. A Transform represents an additional frame which is added to the machine’s frame system. It consists of the following fields:

  • pose_in_observer_frame: Provides the relationship between the frame being added and another frame.
  • physical_object: An optional Geometry can be added to the frame being added.
  • reference_frame: Specifies the name of the frame which will be added to the frame system.

  When supplemental_transforms are provided, a frame system is created within the context of the GetPose function. This new frame system builds off the machine’s frame system and incorporates the Transforms provided. If the result of adding the Transforms results in a disconnected frame system, an error is thrown.

• 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:

• (viam.proto.common.PoseInFrame): Pose of the given component and the frame in which it was observed.

Example:

# Note that the example uses the ``Arm`` class, but any component class that inherits from ``ComponentBase`` will work
# (``Base``, ``Gripper``, etc).

# Create a `component_name`:
component_name = Arm.get_resource_name("arm")

from viam.components.gripper import Gripper
from viam.services.motion import MotionClient

# Assume that the connect function is written and will return a valid machine.
robot = await connect()

motion = MotionClient.from_robot(robot=machine, name="builtin")
gripperName = Gripper.get_resource_name("my_gripper")
gripperPoseInWorld = await motion.get_pose(component_name=gripperName,
                                        destination_frame="world")

The following code example gets the pose of the tip of a gripper named my_gripper which is attached to the end of an arm, in the “world” reference_frame:

from viam.components.gripper import Gripper
from viam.services.motion import MotionClient

# Assume that the connect function is written and will return a valid machine.
robot = await connect()

motion = MotionClient.from_robot(robot=robot, name="builtin")
gripperName = Gripper.get_resource_name("my_gripper")
gripperPoseInWorld = await motion.get_pose(component_name=gripperName,
                                           destination_frame="world")

For a more complicated example, take the same scenario and get the pose of the same gripper with respect to an object situated at a location (100, 200, 0) relative to the “world” frame:

from viam.components.gripper import Gripper
from viam.services.motion import MotionClient
from viam.proto.common import Transform, PoseInFrame, Pose

# Assume that the connect function is written and will return a valid machine.
robot = await connect()

motion = MotionClient.from_robot(robot=robot, name="builtin")
objectPose = Pose(x=100, y=200, z=0, o_x=0, o_y=0, o_z=1, theta=0)
objectPoseInFrame = PoseInFrame(reference_frame="world", pose=objectPose)
objectTransform = Transform(reference_frame="object",
                            pose_in_observer_frame=objectPoseInFrame)
gripperName = Gripper.get_resource_name("my_gripper")
gripperPoseInObjectFrame = await motion.get_pose(
  component_name=gripperName,
  destination_frame="world",
  supplemental_transforms=objectTransform
)

For more information, see the Python SDK Docs.

Parameters:

• component_name (viam.proto.common.ResourceName) (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.
• 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:

• None.

Example:

motion = MotionClient.from_robot(robot=machine, name="builtin")

# Assuming a `move_on_globe()` started the execution
# Stop the base component which was instructed to move by `move_on_globe()`
# or `move_on_map()`
my_base_resource_name = Base.get_resource_name("my_base")
await motion.stop_plan(component_name=mvmnt_sensor)

For more information, see the Python SDK Docs.

Parameters:

• only_active_plans (bool) (required): If supplied, the response will filter out any plans that are not executing.
• 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:

• (Sequence[viam.proto.service.motion.PlanStatusWithID]): List of last known statuses with the associated IDs of all plans within the TTL ordered by timestamp in ascending order.

Example:

motion = MotionClient.from_robot(robot=machine, name="builtin")
# List the plan statuses of the motion service within the TTL
resp = await motion.list_plan_statuses()

For more information, see the Python SDK Docs.

Parameters:

• component_name (viam.proto.common.ResourceName) (required): The component to stop.
• last_plan_only (bool) (required): If supplied, the response will only return the last plan for the component / execution.
• execution_id (str) (optional): If supplied, the response will only return plans with the provided execution_id.
• 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:

• (viam.proto.service.motion.GetPlanResponse): The current PlanWithStatus & replan history which matches the request.

Example:

motion = MotionClient.from_robot(robot=machine, name="builtin")
my_base_resource_name = Base.get_resource_name("my_base")
# Get the plan(s) of the base component which was instructed to move by `MoveOnGlobe()` or `MoveOnMap()`
resp = await motion.get_plan(component_name=my_base_resource_name)

For more information, see the Python SDK Docs.

Parameters:

• ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
• deps (Dependencies): The resource dependencies.
• conf (Config): The resource configuration.

Returns:

• (error): An error, if one occurred.

For more information, see the Go SDK Docs.

Parameters:

• robot (viam.robot.client.RobotClient) (required): The robot.
• name (str) (required): The name of the service.

Returns:

• (typing_extensions.Self): The service, if it exists on the robot.

Example:

async def connect() -> RobotClient:
    # Replace "<API-KEY>" (including brackets) with your API key and "<API-KEY-ID>" with your API key ID
    options = RobotClient.Options.with_api_key("<API-KEY>", "<API-KEY-ID>")
    # Replace "<MACHINE-URL>" (included brackets) with your machine's connection URL or FQDN
    return await RobotClient.at_address("<MACHINE-URL>", options)

async def main():
    robot = await connect()

    # Can be used with any resource, using the motion service as an example
    motion = MotionClient.from_robot(robot=machine, name="builtin")

    robot.close()

For more information, see the Python SDK Docs.

Parameters:

• command (Mapping[str, ValueTypes]) (required): The command to execute.
• 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:

• (Mapping[str, viam.utils.ValueTypes]): Result of the executed command.

Example:

my_motion_svc = MotionClient.from_robot(robot=machine, "builtin")

my_command = {
  "cmnd": "dosomething",
  "someparameter": 52
}

await my_motion_svc.do_command(command=my_command)

For more information, see the Python SDK Docs.

Parameters:

• name (str) (required): The name of the Resource.

Returns:

• (viam.proto.common.ResourceName): The ResourceName of this Resource.

Example:

my_motion_svc_name = MotionClient.get_resource_name("my_motion_svc")

For more information, see the Python SDK Docs.

Parameters:

• None.

Returns:

• None.

Example:

my_motion_svc = MotionClient.from_robot(robot=machine, name="my_motion_svc")
await my_motion_svc.close()

For more information, see the Python SDK Docs.