The Motion service coordinates motion planning across all components of a given robot.The Viam Motion planning service calculates a valid path that avoids self-collision by default. If additional constraints are supplied in the world_state message, the motion planning service will account for those as well. More...

#include "services/motion/motion.hpp"

Inheritance diagram for viam::sdk::Motion:

Classes
struct	collision_specification
	used to selectively apply obstacle avoidance to specific parts of the robot. More...

struct	constraints
	Specifies all constraints to be passed to Viam's motion planning, along with any optional parameters. More...

struct	linear_constraint
	Specifies that the component being moved should move linearly to its goal. More...

struct	orientation_constraint
	Specifies that the component being moved will not deviate its orientation beyond the specified threshold. More...

struct	plan
	Describes a motion plan. More...

struct	plan_status
	Describes the state of a given plan at a point in time. More...

struct	plan_status_with_id
	The motion plan status, plus plan ID, component name, and execution ID. More...

struct	plan_with_status
	Describes a plan, its current status, and all status changes that have occurred previously on that plan. More...

struct	steps
	An ordered list of plan steps. More...

Public Types
enum class	plan_state : uint8_t { k_in_progress , k_stopped , k_succeeded , k_failed }
	Describes the possible states a plan can be in.

Public Member Functions
API	api () const override
	Returns the `API` associated with a particular resource.

bool	move (const pose_in_frame &destination, const Name &name, const std::shared_ptr< WorldState > &world_state, const std::shared_ptr< constraints > &constraints)
	Moves any compononent on the robot to a specified destination.

virtual bool	move (const pose_in_frame &destination, const Name &name, const std::shared_ptr< WorldState > &world_state, const std::shared_ptr< constraints > &constraints, const ProtoStruct &extra)=0
	Moves any compononent on the robot to a specified destination.

std::string	move_on_map (const pose &destination, const Name &component_name, const Name &slam_name, const std::shared_ptr< motion_configuration > &motion_configuration, const std::vector< GeometryConfig > &obstacles)
	Moves any component on the robot to a specific destination on a SLAM map.

virtual std::string	move_on_map (const pose &destination, const Name &component_name, const Name &slam_name, const std::shared_ptr< motion_configuration > &motion_configuration, const std::vector< GeometryConfig > &obstacles, const ProtoStruct &extra)=0
	Moves any component on the robot to a specific destination on a SLAM map.

std::string	move_on_globe (const geo_point &destination, const boost::optional< double > &heading, const Name &component_name, const Name &movement_sensor_name, const std::vector< geo_geometry > &obstacles, const std::shared_ptr< motion_configuration > &motion_configuration, const std::vector< geo_geometry > &bounding_regions)
	Moves any component on the robot to a specific destination on a globe.

virtual std::string	move_on_globe (const geo_point &destination, const boost::optional< double > &heading, const Name &component_name, const Name &movement_sensor_name, const std::vector< geo_geometry > &obstacles, const std::shared_ptr< motion_configuration > &motion_configuration, const std::vector< geo_geometry > &bounding_regions, const ProtoStruct &extra)=0
	Moves any component on the robot to a specific destination on a globe.

pose_in_frame	get_pose (const Name &component_name, const std::string &destination_frame, const std::vector< WorldState::transform > &supplemental_transforms)
	Get the pose of any component on the robot.

virtual pose_in_frame	get_pose (const Name &component_name, const std::string &destination_frame, const std::vector< WorldState::transform > &supplemental_transforms, const ProtoStruct &extra)=0
	Get the pose of any component on the robot.

void	stop_plan (const Name &component_name)
	Stop a currently executing motion plan.

virtual void	stop_plan (const Name &component_name, const ProtoStruct &extra)=0
	Stop a currently executing motion plan.

plan_with_status	get_latest_plan (const Name &component_name)
	Returns the plan and state history of the most recent execution to move a component. Returns a result if the last execution is still executing, or changed state within the last 24 hours without an intervening robot reinitialization.

virtual plan_with_status	get_latest_plan (const Name &component_name, const ProtoStruct &extra)=0
	Returns the plan and state history of the most recent execution to move a component. Returns a result if the last execution is still executing, or changed state within the last 24 hours without an intervening robot reinitialization.

std::pair< plan_with_status, std::vector< plan_with_status > >	get_latest_plan_with_replan_history (Name component_name)
	Returns the plan, state history, and replan history of the most recent execution to move a component. Returns a result if the last execution is still executing, or changed state within the last 24 hours without an intervening robot reinitialization.

virtual std::pair< plan_with_status, std::vector< plan_with_status > >	get_latest_plan_with_replan_history (const Name &component_name, const ProtoStruct &extra)=0
	Returns the plan, state history, and replan history of the most recent execution to move a component. Returns a result if the last execution is still executing, or changed state within the last 24 hours without an intervening robot reinitialization.

plan_with_status	get_plan (const Name &component_name, const std::string &execution_id)
	Returns the plan and state history of the requested plan. Returns a result if the last execution is still executing, or changed state within the last 24 hours without an intervening robot reinitialization.

virtual plan_with_status	get_plan (const Name &component_name, const std::string &execution_id, const ProtoStruct &extra)=0
	Returns the plan and state history of the requested plan. Returns a result if the last execution is still executing, or changed state within the last 24 hours without an intervening robot reinitialization.

std::pair< plan_with_status, std::vector< plan_with_status > >	get_plan_with_replan_history (const Name &component_name, const std::string &execution_id)
	Returns the plan, state history, and replan history of the requested plan. Returns a result if the last execution is still executing, or changed state within the last 24 hours without an intervening robot reinitialization.

virtual std::pair< plan_with_status, std::vector< plan_with_status > >	get_plan_with_replan_history (const Name &component_name, const std::string &execution_id, const ProtoStruct &extra)=0
	Returns the plan, state history, and replan history of the requested plan. Returns a result if the last execution is still executing, or changed state within the last 24 hours without an intervening robot reinitialization.

std::vector< plan_status_with_id >	list_plan_statuses ()
	Returns the status of plans created by MoveOnGlobe requests. Includes statuses of plans that are executing, or are part of an executing that changed its state within the last 24 hours.

virtual std::vector< plan_status_with_id >	list_plan_statuses (const ProtoStruct &extra)=0
	Returns the status of plans created by MoveOnGlobe requests. Includes statuses of plans that are executing, or are part of an execution that changed its state within the last 24 hours.

std::vector< plan_status_with_id >	list_active_plan_statuses ()
	Returns the status of currently active plans created by MoveOnGlobe requests. Includes statuses of plans that are executing, or are part of an execution that changed its state within the last 24 hours.

virtual std::vector< plan_status_with_id >	list_active_plan_statuses (const ProtoStruct &extra)=0
	Returns the status of currently active plans created by MoveOnGlobe requests. Includes statuses of plans that are executing, or are part of an executing that changed its state within the last 24 hours.

virtual ProtoStruct	do_command (const ProtoStruct &command)=0
	Send/receive arbitrary commands to the resource.

Public Member Functions inherited from viam::sdk::Service
Name	get_resource_name () const override
	Returns the `Name` for a particular resource.

Public Member Functions inherited from viam::sdk::Resource
	Resource (std::string name)

virtual std::string	name () const
	Return the resource's name.

Protected Member Functions
	Motion (std::string name)

Protected Member Functions inherited from viam::sdk::Service
	Service (std::string name)

Protected Member Functions inherited from viam::sdk::Resource
Name	get_resource_name (const std::string &type) const

Detailed Description

The Motion service coordinates motion planning across all components of a given robot.

The Viam Motion planning service calculates a valid path that avoids self-collision by default. If additional constraints are supplied in the world_state message, the motion planning service will account for those as well.

This acts as an abstract base class to be inherited from by any drivers representing specific motion implementations. This class cannot be used on its own.

Member Function Documentation

◆ api()

API viam::sdk::Motion::api ( ) const

overridevirtual

Returns the API associated with a particular resource.

Implements viam::sdk::Resource.

◆ do_command()

virtual ProtoStruct viam::sdk::Motion::do_command ( const ProtoStruct & command )

pure virtual

Send/receive arbitrary commands to the resource.

Parameters

Command the command to execute.

Returns: The result of the executed command.

Implemented in viam::sdk::impl::MotionClient.

◆ get_latest_plan() [1/2]

plan_with_status viam::sdk::Motion::get_latest_plan ( const Name & component_name )

inline

Returns the plan and state history of the most recent execution to move a component. Returns a result if the last execution is still executing, or changed state within the last 24 hours without an intervening robot reinitialization.

Parameters

component_name The name of the component which the MoveOnGlobe request asked to move.

Returns: the plan and status of the most recent execution to move the requested component

◆ get_latest_plan() [2/2]

virtual plan_with_status viam::sdk::Motion::get_latest_plan	(	const Name &	component_name,
		const ProtoStruct &	extra )

pure virtual

Returns the plan and state history of the most recent execution to move a component. Returns a result if the last execution is still executing, or changed state within the last 24 hours without an intervening robot reinitialization.

Parameters

component_name	The name of the component which the MoveOnGlobe request asked to move.
extra	Any additional arguments to the method.

Returns: the plan and status of the most recent execution to move the requested component

Implemented in viam::sdk::impl::MotionClient, and viam::sdk::impl::MotionClient.

◆ get_latest_plan_with_replan_history() [1/2]

virtual std::pair< plan_with_status, std::vector< plan_with_status > > viam::sdk::Motion::get_latest_plan_with_replan_history	(	const Name &	component_name,
		const ProtoStruct &	extra )

pure virtual

Returns the plan, state history, and replan history of the most recent execution to move a component. Returns a result if the last execution is still executing, or changed state within the last 24 hours without an intervening robot reinitialization.

Parameters

component_name	The name of the component which the MoveOnGlobe request asked to move.
extra	Any additional arguments to the method.

Returns: a pair of (1) the plan and status and (2) the replan history of the most recent execution to move the requested component

Implemented in viam::sdk::impl::MotionClient, and viam::sdk::impl::MotionClient.

◆ get_latest_plan_with_replan_history() [2/2]

std::pair< plan_with_status, std::vector< plan_with_status > > viam::sdk::Motion::get_latest_plan_with_replan_history ( Name component_name )

inline

Returns the plan, state history, and replan history of the most recent execution to move a component. Returns a result if the last execution is still executing, or changed state within the last 24 hours without an intervening robot reinitialization.

Parameters

component_name The name of the component which the MoveOnGlobe request asked to move.

Returns: a pair of (1) the plan and status and (2) the replan history of the most recent execution to move the requested component

◆ get_plan() [1/2]

plan_with_status viam::sdk::Motion::get_plan	(	const Name &	component_name,
		const std::string &	execution_id )

inline

Returns the plan and state history of the requested plan. Returns a result if the last execution is still executing, or changed state within the last 24 hours without an intervening robot reinitialization.

Parameters

component_name	The name of the component which the MoveOnGlobe request asked to move.
execution_id	The execution id of the requested plan.

Returns: the plan and status of the requested execution's move the requested component

◆ get_plan() [2/2]

virtual plan_with_status viam::sdk::Motion::get_plan	(	const Name &	component_name,
		const std::string &	execution_id,
		const ProtoStruct &	extra )

pure virtual

Returns the plan and state history of the requested plan. Returns a result if the last execution is still executing, or changed state within the last 24 hours without an intervening robot reinitialization.

Parameters

component_name	The name of the component which the MoveOnGlobe request asked to move.
execution_id	The execution id of the requested plan.
extra	Any additional arguments to the method.

Returns: the plan and status of the requested execution's move the requested component

Implemented in viam::sdk::impl::MotionClient, and viam::sdk::impl::MotionClient.

◆ get_plan_with_replan_history() [1/2]

std::pair< plan_with_status, std::vector< plan_with_status > > viam::sdk::Motion::get_plan_with_replan_history	(	const Name &	component_name,
		const std::string &	execution_id )

inline

Returns the plan, state history, and replan history of the requested plan. Returns a result if the last execution is still executing, or changed state within the last 24 hours without an intervening robot reinitialization.

Parameters

component_name	The name of the component which the MoveOnGlobe request asked to move.
execution_id	The execution id of the requested plan.

Returns: a pair of (1) the plan and status and (2) the replan history of the most recent execution to move the requested component

◆ get_plan_with_replan_history() [2/2]

virtual std::pair< plan_with_status, std::vector< plan_with_status > > viam::sdk::Motion::get_plan_with_replan_history	(	const Name &	component_name,
		const std::string &	execution_id,
		const ProtoStruct &	extra )

pure virtual

Returns the plan, state history, and replan history of the requested plan. Returns a result if the last execution is still executing, or changed state within the last 24 hours without an intervening robot reinitialization.

Parameters

component_name	The name of the component which the MoveOnGlobe request asked to move.
execution_id	The execution id of the requested plan.
extra	Any additional arguments to the method.

Returns: a pair of (1) the plan and status and (2) the replan history of the most recent execution to move the requested component

Implemented in viam::sdk::impl::MotionClient, and viam::sdk::impl::MotionClient.

◆ get_pose() [1/2]

pose_in_frame viam::sdk::Motion::get_pose	(	const Name &	component_name,
		const std::string &	destination_frame,
		const std::vector< WorldState::transform > &	supplemental_transforms )

inline

Get the pose of any component on the robot.

Parameters

component_name	The component whose pose is being requested.
destination_frame	The reference frame in which the component's pose should be provided.
supplemental_transforms	Pose information on any additional reference frames that are needed to compute the component's pose.

Returns: The pose of the component.

◆ get_pose() [2/2]

virtual pose_in_frame viam::sdk::Motion::get_pose	(	const Name &	component_name,
		const std::string &	destination_frame,
		const std::vector< WorldState::transform > &	supplemental_transforms,
		const ProtoStruct &	extra )

pure virtual

Get the pose of any component on the robot.

Parameters

component_name	The component whose pose is being requested.
destination_frame	The reference frame in which the component's pose should be provided.
supplemental_transforms	Pose information on any additional reference frames that are needed to compute the component's pose.
extra	Any additional arguments to the method.

Returns: The pose of the component.

Implemented in viam::sdk::impl::MotionClient, and viam::sdk::impl::MotionClient.

◆ list_active_plan_statuses() [1/2]

std::vector< plan_status_with_id > viam::sdk::Motion::list_active_plan_statuses ( )

inline

Returns the status of currently active plans created by MoveOnGlobe requests. Includes statuses of plans that are executing, or are part of an execution that changed its state within the last 24 hours.

Returns: a vector of plan statuses.

◆ list_active_plan_statuses() [2/2]

virtual std::vector< plan_status_with_id > viam::sdk::Motion::list_active_plan_statuses ( const ProtoStruct & extra )

pure virtual

Returns the status of currently active plans created by MoveOnGlobe requests. Includes statuses of plans that are executing, or are part of an executing that changed its state within the last 24 hours.

Parameters

extra Any additional arguments to the method.

Returns: a vector of plan statuses.

Implemented in viam::sdk::impl::MotionClient, and viam::sdk::impl::MotionClient.

◆ list_plan_statuses() [1/2]

std::vector< plan_status_with_id > viam::sdk::Motion::list_plan_statuses ( )

inline

Returns the status of plans created by MoveOnGlobe requests. Includes statuses of plans that are executing, or are part of an executing that changed its state within the last 24 hours.

Returns: a vector of plan statuses.

◆ list_plan_statuses() [2/2]

virtual std::vector< plan_status_with_id > viam::sdk::Motion::list_plan_statuses ( const ProtoStruct & extra )

pure virtual

Returns the status of plans created by MoveOnGlobe requests. Includes statuses of plans that are executing, or are part of an execution that changed its state within the last 24 hours.

Parameters

extra Any additional arguments to the method.

Returns: a vector of plan statuses.

Implemented in viam::sdk::impl::MotionClient, and viam::sdk::impl::MotionClient.

◆ move() [1/2]

bool viam::sdk::Motion::move	(	const pose_in_frame &	destination,
		const Name &	name,
		const std::shared_ptr< WorldState > &	world_state,
		const std::shared_ptr< constraints > &	constraints )

inline

Moves any compononent on the robot to a specified destination.

Parameters

destination	Where to move the component to.
name	Name of the component to be moved.
world_state	Obstacles to avoid and transforms to add to the robot for the duration of the move.
constraints	Constraints to apply to how the robot will move.

Returns: Whether or not the move was successful.

◆ move() [2/2]

virtual bool viam::sdk::Motion::move	(	const pose_in_frame &	destination,
		const Name &	name,
		const std::shared_ptr< WorldState > &	world_state,
		const std::shared_ptr< constraints > &	constraints,
		const ProtoStruct &	extra )

pure virtual

Moves any compononent on the robot to a specified destination.

Parameters

destination	Where to move the component to.
name	Name of the component to be moved.
world_state	Obstacles to avoid and transforms to add to the robot for the duration of the move.
constraints	Constraints to apply to how the robot will move.
extra	Any additional arguments to the method.

Returns: Whether or not the move was successful.

Implemented in viam::sdk::impl::MotionClient, and viam::sdk::impl::MotionClient.

◆ move_on_globe() [1/2]

std::string viam::sdk::Motion::move_on_globe	(	const geo_point &	destination,
		const boost::optional< double > &	heading,
		const Name &	component_name,
		const Name &	movement_sensor_name,
		const std::vector< geo_geometry > &	obstacles,
		const std::shared_ptr< motion_configuration > &	motion_configuration,
		const std::vector< geo_geometry > &	bounding_regions )

inline

Moves any component on the robot to a specific destination on a globe.

Parameters

destination	The destination to move to.
heading	Optional compass heading to achieve at the destination in degrees [0-360).
component_name	The name of the component to move.
movement_sensor_name	The name of the movement sensor used to check robot location.
obstacles	Obstacles to be considered for motion planning.
motion_configuration	Optional set of motion configuration options.
bounding_regions	Set of obstacles which the robot must remain within while navigating.

Returns: The execution ID of the move_on_globe request.

◆ move_on_globe() [2/2]

virtual std::string viam::sdk::Motion::move_on_globe	(	const geo_point &	destination,
		const boost::optional< double > &	heading,
		const Name &	component_name,
		const Name &	movement_sensor_name,
		const std::vector< geo_geometry > &	obstacles,
		const std::shared_ptr< motion_configuration > &	motion_configuration,
		const std::vector< geo_geometry > &	bounding_regions,
		const ProtoStruct &	extra )

pure virtual

Moves any component on the robot to a specific destination on a globe.

Parameters

destination	The destination to move to.
heading	Optional compass heading to achieve at the destination in degrees [0-360).
component_name	The name of the component to move.
movement_sensor_name	The name of the movement sensor used to check robot location.
obstacles	Obstacles to be considered for motion planning.
motion_configuration	Optional set of motion configuration options.
bounding_regions	Set of obstacles which the robot must remain within while navigating.
extra	Any additional arguments to the method.

Returns: The execution_id of the move_on_globe request.

Implemented in viam::sdk::impl::MotionClient, and viam::sdk::impl::MotionClient.

◆ move_on_map() [1/2]

std::string viam::sdk::Motion::move_on_map	(	const pose &	destination,
		const Name &	component_name,
		const Name &	slam_name,
		const std::shared_ptr< motion_configuration > &	motion_configuration,
		const std::vector< GeometryConfig > &	obstacles )

inline

Moves any component on the robot to a specific destination on a SLAM map.

Parameters

destination	The destination to move to.
component_name	The component to move.
slam_name	The name of the slam service from which the SLAM map is requested.
motion_configuration	Optional set of motion configuration options.

Returns: The execution ID of the move_on_map request.

◆ move_on_map() [2/2]

virtual std::string viam::sdk::Motion::move_on_map	(	const pose &	destination,
		const Name &	component_name,
		const Name &	slam_name,
		const std::shared_ptr< motion_configuration > &	motion_configuration,
		const std::vector< GeometryConfig > &	obstacles,
		const ProtoStruct &	extra )

pure virtual

Moves any component on the robot to a specific destination on a SLAM map.

Parameters

destination	The destination to move to.
component_name	The component to move.
slam_name	The name of the slam service from which the SLAM map is requested.
motion_configuration	Optional set of motion configuration options.
extra	Any additional arguments to the method.

Returns: The execution ID of the move_on_map request.

Implemented in viam::sdk::impl::MotionClient, and viam::sdk::impl::MotionClient.

◆ stop_plan() [1/2]

void viam::sdk::Motion::stop_plan ( const Name & component_name )

inline

Stop a currently executing motion plan.

Parameters

component_name the component of the currently executing plan to stop.

◆ stop_plan() [2/2]

virtual void viam::sdk::Motion::stop_plan	(	const Name &	component_name,
		const ProtoStruct &	extra )

pure virtual

Stop a currently executing motion plan.

Parameters

component_name	the component of the currently executing plan to stop.
extra	Any additional arguments to the method.

Implemented in viam::sdk::impl::MotionClient, and viam::sdk::impl::MotionClient.

The documentation for this class was generated from the following file:

src/viam/sdk/services/motion.hpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation

◆ api()

◆ do_command()

◆ get_latest_plan() [1/2]

◆ get_latest_plan() [2/2]

◆ get_latest_plan_with_replan_history() [1/2]

◆ get_latest_plan_with_replan_history() [2/2]

◆ get_plan() [1/2]

◆ get_plan() [2/2]

◆ get_plan_with_replan_history() [1/2]

◆ get_plan_with_replan_history() [2/2]

◆ get_pose() [1/2]

◆ get_pose() [2/2]

◆ list_active_plan_statuses() [1/2]

◆ list_active_plan_statuses() [2/2]

◆ list_plan_statuses() [1/2]

◆ list_plan_statuses() [2/2]

◆ move() [1/2]

◆ move() [2/2]

◆ move_on_globe() [1/2]

◆ move_on_globe() [2/2]

◆ move_on_map() [1/2]

◆ move_on_map() [2/2]

◆ stop_plan() [1/2]

◆ stop_plan() [2/2]