An Arm represents a physical robot arm that exists in three-dimensional space. More...

#include "components/arm.hpp"

Inheritance diagram for viam::sdk::Arm:

Classes
struct	MoveOptions
	Movement specifications for move_through_joint_positions. More...

struct	trajectory_point
	A single waypoint in a streamed joint-space trajectory. More...

struct	trajectory_update
	An update emitted while a streamed trajectory executes. More...

Public Types
enum class	stream_outcome : std::uint8_t { k_completed = 0 , k_halted_by_update_handler }
	How a streamed trajectory execution ended. More...

using	MoveLimit = boost::variant<double, std::vector<double>>
	A movement limit: either a single scalar applied uniformly, or per-joint values.

Public Member Functions
pose	get_end_position ()
	Get the current position of the end of the arm.

virtual pose	get_end_position (const ProtoStruct &extra)=0
	Get the current position of the end of the arm.

void	move_to_position (const pose &pose)
	Move the end of the arm to.

virtual void	move_to_position (const pose &pose, const ProtoStruct &extra)=0
	Move the end of the arm to.

std::vector< double >	get_joint_positions ()
	Lists the joint positions in degrees of every joint on a robot arm.

virtual std::vector< double >	get_joint_positions (const ProtoStruct &extra)=0
	Lists the joint positions in degrees of every joint on a robot arm.

void	move_to_joint_positions (const std::vector< double > &positions)
	Move each joint on the arm to the corresponding angle specified in.

virtual void	move_to_joint_positions (const std::vector< double > &positions, const ProtoStruct &extra)=0
	Move each joint on the arm to the corresponding angle specified in.

void	move_through_joint_positions (const std::vector< std::vector< double > > &positions, const MoveOptions &options)
	Move each joint on the arm through the positions specified in.

virtual void	move_through_joint_positions (const std::vector< std::vector< double > > &positions, const MoveOptions &options, const ProtoStruct &extra)=0
	Move each joint on the arm through the positions specified in.

stream_outcome	move_through_joint_positions_streamed (const std::function< boost::optional< std::vector< trajectory_point > >()> &batch_source, const std::function< bool(trajectory_update)> &update_handler)
	Execute a stream of trajectory points in order.

virtual stream_outcome	move_through_joint_positions_streamed (const std::function< boost::optional< std::vector< trajectory_point > >()> &batch_source, const std::function< bool(trajectory_update)> &update_handler, const ProtoStruct &extra)=0
	Execute a stream of trajectory points in order.

virtual bool	is_moving ()=0
	Reports if the arm is in motion.

virtual ProtoStruct	get_status ()=0
	Get the status of the arm.

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

virtual::viam::sdk::KinematicsData	get_kinematics (const ProtoStruct &extra)=0
	Get the kinematics data associated with the arm.

inline ::viam::sdk::KinematicsData	get_kinematics ()
	Get the kinematics data associated with the arm.

virtual std::map< std::string, mesh >	get_3d_models (const ProtoStruct &extra)=0
	Returns `3DModel`s associated with the calling arm.

std::map< std::string, mesh >	get_3d_models ()
	Returns `3DModel`s associated with the calling arm.

std::vector< GeometryConfig >	get_geometries ()
	Returns `GeometryConfig`s associated with the calling arm.

virtual std::vector< GeometryConfig >	get_geometries (const ProtoStruct &extra)=0
	Returns `GeometryConfig`s associated with the calling arm.

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

Public Member Functions inherited from viam::sdk::Component
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.

void	set_log_level (log_level) const
	Set the log level for log messages originating from this Resource.

Public Member Functions inherited from viam::sdk::Stoppable
virtual void	stop (const ProtoStruct &extra)=0
	Stops a resource from running.

void	stop ()
	Stops a resource from running.

Protected Member Functions
	Arm (std::string name)

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

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

Additional Inherited Members
Protected Attributes inherited from viam::sdk::Resource
LogSource	logger_

Detailed Description

An Arm represents a physical robot arm that exists in three-dimensional space.

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

Member Enumeration Documentation

◆ stream_outcome

enum class viam::sdk::Arm::stream_outcome : std::uint8_t

strong

How a streamed trajectory execution ended.

Enumerator
k_completed	The trajectory ran to its natural end.
k_halted_by_update_handler	`update_handler` returned false, stopping the stream early.

Member Function Documentation

◆ api()

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

overridevirtual

Returns the API associated with a particular resource.

Implements viam::sdk::Resource.

◆ do_command()

virtual ProtoStruct viam::sdk::Arm::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::ArmClient.

◆ get_3d_models() [1/2]

std::map< std::string, mesh > viam::sdk::Arm::get_3d_models ( )

inline

Returns 3DModels associated with the calling arm.

Returns: A map of 3DModels associated with the calling arm

◆ get_3d_models() [2/2]

virtual std::map< std::string, mesh > viam::sdk::Arm::get_3d_models ( const ProtoStruct & extra )

pure virtual

Returns 3DModels associated with the calling arm.

Parameters

extra Any additional arguments to the method

Returns: A map of 3DModels associated with the calling arm

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

◆ get_end_position() [1/2]

pose viam::sdk::Arm::get_end_position ( )

inline

Get the current position of the end of the arm.

Returns: The pose representing the end position of the arm.

◆ get_end_position() [2/2]

virtual pose viam::sdk::Arm::get_end_position ( const ProtoStruct & extra )

pure virtual

Get the current position of the end of the arm.

Parameters

extra Any additional arguments to the method.

Returns: The pose representing the end position of the arm.

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

◆ get_geometries()

virtual std::vector< GeometryConfig > viam::sdk::Arm::get_geometries ( const ProtoStruct & extra )

pure virtual

Returns GeometryConfigs associated with the calling arm.

Parameters

extra Any additional arguments to the method

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

◆ get_joint_positions()

virtual std::vector< double > viam::sdk::Arm::get_joint_positions ( const ProtoStruct & extra )

pure virtual

Lists the joint positions in degrees of every joint on a robot arm.

Parameters

extra Any additional arguments to the method.

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

◆ get_kinematics() [1/2]

inline ::viam::sdk::KinematicsData viam::sdk::Arm::get_kinematics ( )

inline

Get the kinematics data associated with the arm.

Returns: A variant of kinematics data, with the type indicating the format of the data.

◆ get_kinematics() [2/2]

virtual::viam::sdk::KinematicsData viam::sdk::Arm::get_kinematics ( const ProtoStruct & extra )

pure virtual

Get the kinematics data associated with the arm.

Parameters

extra Any additional arguments to the method.

Returns: A variant of kinematics data; URDF variants may include meshes by filepath.

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

◆ get_status()

virtual ProtoStruct viam::sdk::Arm::get_status ( )

pure virtual

Get the status of the arm.

Returns: A ProtoStruct containing the status of the arm.

Implemented in viam::sdk::impl::ArmClient.

◆ is_moving()

virtual bool viam::sdk::Arm::is_moving ( )

pure virtual

Reports if the arm is in motion.

Implemented in viam::sdk::impl::ArmClient.

◆ move_through_joint_positions() [1/2]

void viam::sdk::Arm::move_through_joint_positions	(	const std::vector< std::vector< double > > &	positions,
		const MoveOptions &	options )

inline

Move each joint on the arm through the positions specified in.

Parameters

positions
options	optional specifications to be obeyed during the motion. TODO consider replacing vector vector with xtensor array, and also if it may be possible to specify or constrain dimensionality of the array in advance.

◆ move_through_joint_positions() [2/2]

virtual void viam::sdk::Arm::move_through_joint_positions	(	const std::vector< std::vector< double > > &	positions,
		const MoveOptions &	options,
		const ProtoStruct &	extra )

pure virtual

Move each joint on the arm through the positions specified in.

Parameters

positions
options	optional specifications to be obeyed during the motion.
extra	Any additional arguments to the method.

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

◆ move_through_joint_positions_streamed() [1/2]

stream_outcome viam::sdk::Arm::move_through_joint_positions_streamed	(	const std::function< boost::optional< std::vector< trajectory_point > >()> &	batch_source,
		const std::function< bool(trajectory_update)> &	update_handler )

inline

Execute a stream of trajectory points in order.

Parameters

batch_source	Pull-source for the next batch of waypoints.
update_handler	Handler invoked for each update the implementation emits.

Returns: How the stream ended.

◆ move_through_joint_positions_streamed() [2/2]

virtual stream_outcome viam::sdk::Arm::move_through_joint_positions_streamed	(	const std::function< boost::optional< std::vector< trajectory_point > >()> &	batch_source,
		const std::function< bool(trajectory_update)> &	update_handler,
		const ProtoStruct &	extra )

pure virtual

Execute a stream of trajectory points in order.

This is the streamed analogue of move_through_joint_positions. It is implemented on both sides of the RPC: an arm driver implements it to execute a trajectory, and the SDK arm client implements it to forward the call to a remote arm. Both sides must follow the contract below.

An implementation pulls the trajectory from batch_source and reports progress through update_handler until the stream is exhausted, it is asked to stop, or it faults. A fault is reported by throwing: a server-side implementation has its exception converted to a terminal gRPC status delivered to the remote caller, and a client-side implementation rethrows to its caller. An exception thrown out of update_handler is propagated the same way rather than swallowed, so neither callback is required to be noexcept.

Threading: because the stream is bidirectional, an implementation is permitted to invoke the two callbacks from different threads and to run them concurrently with each other. A caller must therefore not assume the callbacks are serialized against one another or pinned to a single thread, and must synchronize any mutable state it shares between them. A given callback is never invoked concurrently with itself.

Parameters

batch_source	Pull-source for the trajectory. Call it to obtain the next batch of waypoints; it yields `boost::none` once no more points are coming, after which the implementation should finish executing what it already has and return. Points arrive grouped into the batches the sender chose; an implementation that wants per-point handling iterates within each batch. Note that for servers, a disengaged return is ambiguous between end-of-stream and cancellation. Arm implementors are expected to explicitly check for cancellation.
update_handler	Sink for execution updates. Call it with each `trajectory_update` to report progress; it returns `true` to keep going and `false` to ask that the stream stop early, in which case the implementation should stop executing and return `stream_outcome::k_halted_by_update_handler`.
extra	Any additional arguments to the method.

Returns: stream_outcome::k_completed if the trajectory ran to its natural end, or stream_outcome::k_halted_by_update_handler if update_handler asked it to stop.

Implemented in viam::sdk::impl::ArmClient.

◆ move_to_joint_positions() [1/2]

void viam::sdk::Arm::move_to_joint_positions ( const std::vector< double > & positions )

inline

Move each joint on the arm to the corresponding angle specified in.

Parameters

positions

◆ move_to_joint_positions() [2/2]

virtual void viam::sdk::Arm::move_to_joint_positions	(	const std::vector< double > &	positions,
		const ProtoStruct &	extra )

pure virtual

Move each joint on the arm to the corresponding angle specified in.

Parameters

positions
extra	Any additional arguments to the method.

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

◆ move_to_position() [1/2]

void viam::sdk::Arm::move_to_position ( const pose & pose )

inline

Move the end of the arm to.

Parameters

pose.

◆ move_to_position() [2/2]

virtual void viam::sdk::Arm::move_to_position	(	const pose &	pose,
		const ProtoStruct &	extra )

pure virtual

Move the end of the arm to.

Parameters

pose.
pose	The destination pose for the arm.
extra	Any additional arguments to the method.

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

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

src/viam/sdk/components/arm.hpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ stream_outcome

Member Function Documentation

◆ api()

◆ do_command()

◆ get_3d_models() [1/2]

◆ get_3d_models() [2/2]

◆ get_end_position() [1/2]

◆ get_end_position() [2/2]

◆ get_geometries()

◆ get_joint_positions()

◆ get_kinematics() [1/2]

◆ get_kinematics() [2/2]

◆ get_status()

◆ is_moving()

◆ move_through_joint_positions() [1/2]

◆ move_through_joint_positions() [2/2]

◆ move_through_joint_positions_streamed() [1/2]

◆ move_through_joint_positions_streamed() [2/2]

◆ move_to_joint_positions() [1/2]

◆ move_to_joint_positions() [2/2]

◆ move_to_position() [1/2]

◆ move_to_position() [2/2]