Motion Service API
The motion service API allows you to give commands to your motion service for moving a machine based on a SLAM map or GPS coordinates or for moving a machine’s components from one location to another.
The motion service supports the following methods:
Method Name | Description |
---|---|
Move | The Move method is the primary way to move multiple components, or to move any object to any other location. |
MoveOnMap | Move a base component to a destination pose on a SLAM map. |
MoveOnGlobe | Move a base component to a destination GPS point, represented in geographic notation (latitude, longitude). |
GetPose | GetPose gets the location and orientation of a component within the frame system. |
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 All repeated fields are in chronological order. |
GetPlan | By default, returns the plan history of the most recent MoveOnGlobe or MoveOnMap call to move a base component. |
Reconfigure | Reconfigure this resource. |
FromRobot | Get the resource from the provided robot with the given name. |
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 with the given name. |
Close | Safely shut down the resource and prevent further use. |
Establish a connection
To get started using Viam’s SDKs to connect to and control your machine, go to your machine’s page on the Viam app, navigate to the CONNECT tab’s Code sample page, select your preferred programming language, and copy the sample code.
API key and API key ID
By default, the sample code does not include your machine API key and API key ID. We strongly recommend that you add your API key and API key ID as an environment variable and import this variable into your development environment as needed.
To show your machine’s API key and API key ID in the sample code, toggle Include API key on the CONNECT tab’s Code sample page.
Caution
Do not share your API key or machine address publicly. Sharing this information could compromise your system security by allowing unauthorized access to your machine, or to the computer running your machine.
When executed, this sample code creates a connection to your machine as a client.
Because the motion service is enabled by default, you don’t give it a "name"
while configuring it.
Use the name "builtin"
to access the built-in motion service in your code with methods like FromRobot()
that require a ResourceName
.
Be sure to import the motion package for the SDK you are using:
from viam.services.motion import MotionClient
import (
"go.viam.com/rdk/services/motion"
)
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:
- Construct a full kinematic chain from goal to destination including all movable components in between.
- Solve that chain to move the specified component frame to the destination while adhering to any constraints.
- Execute that movement to move the actual machine.
- 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.
Parameters:
component_name
(viam.proto.common.ResourceName) (required): TheResourceName
of the piece of the robot that should arrive at the destination. Note thatmove
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 thecomponent_name
frame should be moved to. Can be any pose, from the perspective of any component whose location is configured as aframe
.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
andcomponent_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.
- 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:
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:
motion = MotionClient.from_robot(robot=robot, name="builtin")
# Assumes a gripper configured with name "my_gripper" on the machine
gripper_name = Gripper.get_resource_name("my_gripper")
my_frame = "my_gripper_offset"
goal_pose = Pose(x=0, y=0, z=300, o_x=0, o_y=0, o_z=1, theta=0)
# Move the gripper
moved = await motion.move(component_name=gripper_name,
destination=PoseInFrame(reference_frame="myFrame",
pose=goal_pose),
world_state=worldState,
constraints={},
extra={})
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.componentName
(resource.Name): Theresource.Name
of the piece of the robot that should arrive at the destination. Note thatMove
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
(*referenceframe.PoseInFrame): Describes where thecomponent_name
should end up. Can be any pose, from the perspective of any component whose location is configured as aframe
. Note that the destination pose is relative to the distal end of the specified frame. This means that if thedestination
is the same as thecomponent_name
frame, for example an arm’s frame, then a pose of{X: 10, Y: 0, Z: 0}
will move that arm’s end effector by 10 mm in the localX
direction.worldState
(*referenceframe.WorldState): Data structure specifying information about the world around the machine. Used to augment the motion solving process.worldState
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
andcomponentName
, 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.
- 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:
constraints
(*motionplan.Constraints): Pass in optional motion constraints. By default, motion is unconstrained with the exception of obstacle avoidance.extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.
Returns:
- (bool): Whether the move was successful (
true
) or unsuccessful (false
). - (error): An error, if one occurred.
Example:
motionService, err := motion.FromRobot(machine, "builtin")
// Assumes a gripper configured with name "my_gripper" on the machine
gripperName := gripper.Named("my_gripper")
// Define a destination Pose
destination := referenceframe.NewPoseInFrame("world", spatialmath.NewPoseFromPoint(r3.Vector{X: 0.1, Y: 0.0, Z: 0.0}))
// Create obstacles
boxPose := spatialmath.NewPoseFromPoint(r3.Vector{X: 0.0, Y: 0.0, Z: 0.0})
boxDims := r3.Vector{X: 0.2, Y: 0.2, Z: 0.2} // 20cm x 20cm x 20cm box
obstacle, _ := spatialmath.NewBox(boxPose, boxDims, "obstacle_1")
geometryInFrame := referenceframe.NewGeometriesInFrame("base", []spatialmath.Geometry{obstacle})
obstacles := []*referenceframe.GeometriesInFrame{geometryInFrame}
// Create transforms
transform := referenceframe.NewLinkInFrame("gripper",
spatialmath.NewPoseFromPoint(r3.Vector{X: 0.1, Y: 0.0, Z: 0.1}), "transform_1", nil
)
transforms := []*referenceframe.LinkInFrame{transform}
// Create WorldState
worldState, err := referenceframe.NewWorldState(obstacles, transforms)
// Move gripper component
moved, err := motionService.Move(context.Background(), motion.MoveReq{
ComponentName: gripperName,
Destination: destination,
WorldState: WorldState
})
For more information, see the Go SDK Docs.
MoveOnMap
Move a base component to a destination pose on a SLAM map.
MoveOnMap()
is non blocking, meaning the motion service will move the component to the destination pose after MoveOnMap()
returns.
Each successful MoveOnMap()
call returns a unique ExecutionID
which you can use to identify all plans generated during the MoveOnMap()
call.
Info
If you specify a goal pose and the robot’s current position is already within the set PlanDeviationM
, then MoveOnMap
returns an error.
You can monitor the progress of the MoveOnMap()
call by querying GetPlan()
and ListPlanStatuses()
.
Use the machine’s position reported by the SLAM service to check the location of the machine.
MoveOnMap()
is intended for use with the navigation service, providing autonomous indoor navigation for rover bases.
Requirements
To use MoveOnMap()
, your SLAM service must implement GetPointCloudMap()
and GetPosition()
Make sure the SLAM service you use alongside this motion service supports the following methods in its model's implementation of the SLAM service API:
- It must support
GetPointCloudMap()
to report the SLAM map as a pointcloud. - It must support
GetPosition()
to report the machine’s current location on the SLAM map.
Parameters:
component_name
(viam.proto.common.ResourceName) (required): TheResourceName
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): TheResourceName
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 theMoveOnMap()
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=robot, 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:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.req
(MoveOnMapReq): AMoveOnMapReq
which contains the following values:ComponentName
(resource.Name): Theresource.Name
of the base to move.Destination
(spatialmath.Pose): The destination, which can be any Pose with respect to the SLAM map’s origin.SlamName
(resource.Name): Theresource.Name
of the SLAM service from which the SLAM map is requested.MotionConfig
(*MotionConfiguration): The configuration you want to set across this machine for this motion service. This parameter and each of its fields are optional.ObstacleDetectors
([]ObstacleDetectorName): The names of each vision service and camera resource pair you want to use for transient obstacle avoidance.PositionPollingFreqHz
(float64): The frequency in hz to poll the position of the machine.ObstaclePollingFreqHz
(float64): The frequency in hz to poll the vision service for new obstacles.PlanDeviationM
(float64): 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 CONTROL tab, the underlying calls toMoveOnMap()
use 0.5 m instead.LinearMPerSec
(float64): Linear velocity this machine should target when moving.AngularDegsPerSec
(float64): Angular velocity this machine should target when turning.
Obstacles
([]spatialmath.Geometry): Obstacles, specified in the SLAM frame coordinate system, to be considered when planning the motion of the component.Extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.
Returns:
- (ExecutionID): ExecutionID of the
MoveOnMap
call. - (error): An error, if one occurred.
Example:
// Assumes a base with the name "my_base" is configured on the machine
myBaseResourceName := base.Named("my_base")
mySLAMServiceResourceName := slam.Named("my_slam_service")
// Define a destination Pose
myPose := spatialmath.NewPoseFromPoint(r3.Vector{Y: 10})
// Move the base component to the destination pose
executionID, err := motionService.MoveOnMap(context.Background(), motion.MoveOnMapReq{
ComponentName: myBaseResourceName,
Destination: myPose,
SlamName: mySLAMServiceResourceName,
})
// MoveOnMap is a non-blocking method and this line can optionally be added to block until the movement is done
err = motion.PollHistoryUntilSuccessOrError(
context.Background(),
motionService,
time.Duration(time.Second),
motion.PlanHistoryReq{
ComponentName: myBaseResourceName,
ExecutionID: executionID,
},
)
For more information, see the Go SDK Docs.
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()
.
Info
If you specify a goal pose and the robot’s current position is already within the set PlanDeviationM
, MoveOnGlobe
returns an error.
You can monitor the progress of the MoveOnGlobe()
call by querying GetPlan()
and ListPlanStatuses()
.
MoveOnGlobe()
is intended for use with the navigation service, providing autonomous GPS navigation for rover bases.
Requirements
To use MoveOnGlobe()
, your movement sensor must be able to measure the GPS location and orientation of the machine.
Make sure the movement sensor you use supports usage of the following methods in its model's implementation of the movement sensor API.
- It must support
GetPosition()
to report the machine’s current GPS location. - It must also support either
GetCompassHeading()
orGetOrientation()
to report which way the machine is facing. - If your movement sensor provides multiple methods, your machine will default to using the values returned by
GetCompassHeading()
.
Stability Notice
The heading
parameter is experimental.
Specifying heading
in a request to MoveOnGlobe
is not currently recommended if the minimum turning radius of your component is greater than zero, as this combination may cause high latency in the motion planning algorithms.
Specifying obstacles
in a request to MoveOnGlobe()
will cause an error if you configure a "translation"
in the "geometries"
of any of the GeoGeometry
objects.
Translation in obstacles is not supported by the navigation service.
Parameters:
component_name
(viam.proto.common.ResourceName) (required): TheResourceName
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): TheResourceName
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 aGeoGeometry
.- Default:
None
- Default:
heading
(float) (optional): The compass heading, in degrees, that the machine’s movement sensor should report at thedestination
point.- Range:
[0-360)
0
: North,90
: East,180
: South,270
: West - Default:
None
- Range:
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=robot, 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:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.req
(MoveOnGlobeReq): AMoveOnGlobeReq
which contains the following values:componentName
(resource.Name): Theresource.Name
of the base to move.destination
(*geo.Point): The location of the component’s destination, represented in geographic notation as a Point (lat, lng).heading
(float64): The compass heading, in degrees, that the machine’s movement sensor should report at thedestination
point.- Range:
[0-360)
0: North, 90: East, 180: South, 270: West - Default:
0
- Range:
movementSensorName
(resource.Name): Theresource.Name
of the movement sensor that you want to use to check the machine’s location.obstacles
([]*spatialmath.GeoGeometry): Obstacles to consider when planning the motion of the component, with each represented as aGeoGeometry
.- Default:
nil
- Default:
motionConfig
(*MotionConfiguration): The configuration you want to set across this machine for this motion service. This parameter and each of its fields are optional.ObstacleDetectors
([]ObstacleDetectorName): The names of each vision service and camera resource pair you want to use for transient obstacle avoidance.PositionPollingFreqHz
(float64): The frequency in hz to poll the position of the machine.ObstaclePollingFreqHz
(float64): The frequency in hz to poll the vision service for new obstacles.PlanDeviationM
(float64): The distance in meters that the machine can deviate from the motion plan.LinearMPerSec
(float64): Linear velocity this machine should target when moving.AngularDegsPerSec
(float64): Angular velocity this machine should target when turning.
Returns:
- (ExecutionID): ExecutionID of the
MoveOnGlobe
call. - (error): An error, if one occurred.
Example:
// Assumes a base with the name "myBase" is configured on the machine
// Get the resource names of the base and movement sensor
myBaseResourceName := base.Named("myBase")
myMvmntSensorResourceName := movementsensor.Named("my_movement_sensor")
// Define a destination Point at the GPS coordinates [0, 0]
myDestination := geo.NewPoint(0, 0)
// Move the base component to the designated geographic location, as reported by the movement sensor
executionID, err := motionService.MoveOnGlobe(context.Background(), motion.MoveOnGlobeReq{
ComponentName: myBaseResourceName,
Destination: myDestination,
MovementSensorName: myMvmntSensorResourceName,
})
// Assumes there is an active MoveOnMap() or MoveonGlobe() in progress for myBase
// MoveOnGlobe is a non-blocking method and this line can optionally be added to block until the movement is done
err = motion.PollHistoryUntilSuccessOrError(
context.Background(),
motionService,
time.Duration(time.Second),
motion.PlanHistoryReq{
ComponentName: myBaseResourceName,
ExecutionID: executionID,
},
)
For more information, see the Go SDK Docs.
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.
You can use the supplemental_transforms
argument to augment the machine’s existing frame system with supplemental frames.
Parameters:
component_name
(viam.proto.common.ResourceName) (required): TheResourceName
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 ofTransform
objects. ATransform
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 optionalGeometry
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 theGetPose
function. This new frame system builds off the machine’s frame system and incorporates theTransform
s provided. If the result of adding theTransform
s 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=robot, 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:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.componentName
(resource.Name): Theresource.Name
of the piece of the machine whose pose is returned.destinationFrame
(string): The name of the frame with respect to which the component’s pose is reported.supplementalTransforms
([]*referenceframe.LinkInFrame): An optional list ofLinkInFrame
s. ALinkInFrame
represents an additional frame which is added to the machine’s frame system. It consists of:- a
PoseInFrame
: Provides the relationship between the frame being added and another frame. Geometry
: An optionalGeometry
can be added to the frame being added. WhensupplementalTransforms
are provided, a frame system is created within the context of theGetPose
function. This new frame system builds off the machine’s frame system and incorporates theLinkInFrame
s provided. If the result of adding theLinkInFrame
s results in a disconnected frame system, an error is thrown.
- a
extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.
Returns:
- (*referenceframe.PoseInFrame): The pose of the component.
- (error): An error, if one occurred.
Example:
// Insert code to connect to your machine.
// (see CONNECT tab of your machine's page in the Viam app)
// Assumes a gripper configured with name "my_gripper" on the machine
gripperName := gripper.Named("my_gripper")
// Access the motion service
motionService, err := motion.FromRobot(machine, "builtin")
if err != nil {
logger.Fatal(err)
}
myArmMotionPose, err := motionService.GetPose(context.Background(), my_gripper, referenceframe.World, nil, nil)
if err != nil {
logger.Fatal(err)
}
logger.Info("Position of myArm from the motion service:", myArmMotionPose.Pose().Point())
logger.Info("Orientation of myArm from the motion service:", myArmMotionPose.Pose().Orientation())
For more information, see the Go SDK Docs.
StopPlan
Stop a base component being moved by an in progress MoveOnGlobe
or MoveOnMap
call.
Parameters:
component_name
(viam.proto.common.ResourceName) (required): TheResourceName
of the piece of the robot that should arrive at the destination. Note thatmove
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:
# 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:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.req
(StopPlanReq): AStopPlanReq
which contains the following values:componentName
(resource.Name): Theresource.Name
of the base to stop.extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.
Returns:
- (error): An error, if one occurred.
Example:
motionService, err := motion.FromRobot(machine, "builtin")
myBaseResourceName := base.Named("myBase")
myMvmntSensorResourceName := movement_sensor.Named("my_movement_sensor")
myDestination := geo.NewPoint(0, 0)
// Assuming a `MoveOnGlobe()`` started the execution
// Stop the base component which was instructed to move by `MoveOnGlobe()` or `MoveOnMap()`
err := motionService.StopPlan(context.Background(), motion.StopPlanReq{
ComponentName: s.req.ComponentName,
})
For more information, see the Go SDK Docs.
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
All repeated fields are in chronological order.
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=robot, 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:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.req
(ListPlanStatusesReq): AListPlanStatusesReq
which contains the following values:onlyActivePlans
(bool): Iftrue
, the response will only return plans which are executing.extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.
Returns:
- ([]PlanStatusWithID): The state of a given plan at a point in time plus the
PlanId
,ComponentName
andExecutionID
the status is associated with. - (error): An error, if one occurred.
Example:
motionService, err := motion.FromRobot(machine, "builtin")
// Get the plan(s) of the base component's most recent execution i.e. `MoveOnGlobe()` or `MoveOnMap()` call.
planStatuses, err := motionService.ListPlanStatuses(context.Background(), motion.ListPlanStatusesReq{})
For more information, see the Go SDK Docs.
GetPlan
By default, returns the plan history of the most recent MoveOnGlobe
or MoveOnMap
call to move a base component.
The plan history for executions before the most recent can be requested by providing an ExecutionID
in the request.
Returns a result if both of the following conditions are met:
- the execution (call to
MoveOnGlobe
orMoveOnMap
) is still executing or changed state within the last 24 hours - the machine has not reinitialized
Plans never change.
Replans always create new plans.
Replans share the ExecutionID
of the previously executing plan.
All repeated fields are in chronological order.
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=robot, 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.req
(PlanHistoryReq): APlanHistoryReq
which contains the following values:componentName
(resource.Name): Theresource.Name
of the base to stop.lastPlanOnly
(bool): Iftrue
, the response will only return the last plan for the component / executionexecutionID
(ExecutionID): If non empty, the response will return the plans of the provided execution & component. Useful for retrieving plans from executions before the current execution.extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.
Returns:
- ([]PlanWithStatus): PlanWithStatus contains a plan, its current status, and all state changes that came prior sorted by ascending timestamp.
- (error): An error, if one occurred.
Example:
// Get the resource name of the base component
myBaseResourceName := base.Named("myBase")
// Get the plan history of the base component's most recent execution (e.g., MoveOnGlobe or MoveOnMap call)
planHistory, err := motionService.PlanHistory(context.Background(), motion.PlanHistoryReq{
ComponentName: myBaseResourceName,
})
For more information, see the Go SDK Docs.
Reconfigure
Reconfigure this resource. Reconfigure must reconfigure the resource atomically and in place.
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.
FromRobot
Get the resource from the provided robot with the given name.
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=robot, name="builtin")
robot.close()
For more information, see the Python SDK Docs.
DoCommand
Execute model-specific commands that are not otherwise defined by the service API.
For built-in service models, any model-specific commands available are covered with each model’s documentation.
If you are implementing your own motion service and add features that have no built-in API method, you can access them with DoCommand
.
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:
service = MotionClient.from_robot(robot, "builtin")
my_command = {
"cmnd": "dosomething",
"someparameter": 52
}
# Can be used with any resource, using the motion service as an example
await service.do_command(command=my_command)
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.cmd
(map[string]interface{}): The command to execute.
Returns:
- (map[string]interface{}): The command response.
- (error): An error, if one occurred.
Example:
myMotion, err := motion.FromRobot(machine, "my_motion")
command := map[string]interface{}{"cmd": "test", "data1": 500}
result, err := myMotion.DoCommand(context.Background(), command)
For more information, see the Go SDK Docs.
GetResourceName
Get the ResourceName
for this instance of the motion service with the given name.
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.
Close
Safely shut down the resource and prevent further use.
Parameters:
- None.
Returns:
- None.
Example:
await my_motion_svc.close()
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.
Returns:
- (error): An error, if one occurred.
Example:
myMotionSvc, err := motion.FromRobot(machine, "my_motion_svc")
err = myMotionSvc.Close(context.Background())
For more information, see the Go SDK Docs.
Have questions, or want to meet other people working on robots? Join our Community Discord.
If you notice any issues with the documentation, feel free to file an issue or edit this file.
Was this page helpful?
Glad to hear it! If you have any other feedback please let us know:
We're sorry about that. To help us improve, please tell us what we can do better:
Thank you!