#include <mpp/interfaces/VehicleMotionInterface.h>

Inheritance diagram for mpp::VehicleMotionInterface:

Public Member Functions
	VehicleMotionInterface ()

virtual	~VehicleMotionInterface ()

virtual VehicleLocalizationState	get_localization ()=0

virtual VehicleOdometryState	get_odometry ()=0

virtual bool	motion_execute (const std::optional< CVehicleVelCmd::Ptr > &immediate, const std::optional< EnqueuedMotionCmd > &next)=0

virtual bool	supports_enqeued_motions () const

virtual bool	enqeued_motion_pending () const

virtual bool	enqeued_motion_timed_out () const

virtual std::optional< VehicleOdometryState >	enqued_motion_last_odom_when_triggered () const

virtual void	stop (const STOP_TYPE stopType)=0

virtual void	stop_watchdog ()

virtual void	start_watchdog ([[maybe_unused]] const size_t periodMilliseconds)

virtual double	robot_time () const

Event callbacks
virtual void	on_nav_end_due_to_error ()
	Callback if current navigation ended due to some error. More...

virtual void	on_nav_start ()
	Callback upon starting a new waypointsequence navigation. More...

virtual void	on_nav_end ()
	Callback if navigation ended by an accepted trigger or reached the last specified waypoint. More...

virtual void	on_path_seems_blocked ()
	Callback for when NavEngine cannot make progress to get increasingly closer to the final target during a certain period of time. It may indicate that the high-level path the vehicle is trying to follow is no longer valid due to a blocked way. On your user side, you could call NavEngine::cancel() and/or re-compute an alternative path and issue a new set of navigation waypoints or just report the error to the user. More...

virtual void	on_apparent_collision ()
	Callback when the NavEngine predicts a collision with an obstacle and needed to issue a stop command. More...

virtual void	on_waypoint_reached (const size_t waypoint_index, bool reached_skipped)
	Callback upon reaching a waypoint in a waypoint sequeunce. Mostly used for logging. More...

virtual void	on_cannot_get_closer_to_blocked_target ()
	Callback when NavEngine cannot reach a specified target location because there are obstacles at the specified target. More...

Detailed Description

The virtual interface between a path follower / plan executor and a real mobile platform (vehicle, robot), regarding controlling its motion.

To enable the use of this library with a new robot, the user must define a new class derived from this virtual class and implement all pure virtual and the desired virtual methods according to the docs below.

This class does not make assumptions about the kinematic model of the robot, so it can work with either Ackermann, differential-driven or holonomic robots. It will depend on the used PTGs, so checkout each PTG documentation for the lenght and meaning of velocity commands.

Assumptions: The platform...

has a global localization system (e.g. particle filter) with respect to some fixed global frame of reference map, see get_localization().
has odometry with a fixed global frame of reference odom, see get_odometry().
is able to execute motion primitives according to one or more PTGs,
is able to keep one immediately-running motion primitive and optionally another one in a queue, which will be executed when a given condition holds; see motion_execute(). This mechanism ensures accurately path following without computer-robot communication delays affecting the plan.

Constructor & Destructor Documentation

◆ VehicleMotionInterface()

mpp::VehicleMotionInterface::VehicleMotionInterface ( )

inline

◆ ~VehicleMotionInterface()

virtual mpp::VehicleMotionInterface::~VehicleMotionInterface ( )

virtual

Member Function Documentation

◆ enqeued_motion_pending()

virtual bool mpp::VehicleMotionInterface::enqeued_motion_pending ( ) const

inlinevirtual

Reimplement to return true if an enqueued motions has been received from motion_execute() and it is still waiting to be executed, or false otherwise (no action enqeued, or it was already triggered and executed).

◆ enqeued_motion_timed_out()

virtual bool mpp::VehicleMotionInterface::enqeued_motion_timed_out ( ) const

inlinevirtual

Reimplement to return true if an enqueued motions has been received from motion_execute() and it has timed out, or false otherwise (no action enqeued, or it was already triggered correctly).

◆ enqued_motion_last_odom_when_triggered()

virtual std::optional<VehicleOdometryState> mpp::VehicleMotionInterface::enqued_motion_last_odom_when_triggered ( ) const

inlinevirtual

Reimplement to return the exact odometry value at the precise moment that the last enqueued motion was executed by the vehicle motion controller. The optional<> should be empty only if no enqueued motion has been executed yet.

◆ get_localization()

virtual VehicleLocalizationState mpp::VehicleMotionInterface::get_localization ( )

pure virtual

Provides access to the vehicle localization data.

The implementation should not take too much time to return, so if it might take more than ~10ms to ask the robot for the instantaneous data, it may be good enough to return the latest cached values, updated in a parallel thread.

In case of a hardware/communication error, leave valid=false in the return structure.

Implemented in mpp::MVSIM_VehicleInterface.

◆ get_odometry()

virtual VehicleOdometryState mpp::VehicleMotionInterface::get_odometry ( )

pure virtual

Provides access to the vehicle odometry data.

The implementation should not take too much time to return, so if it might take more than ~10ms to ask the robot for the instantaneous data, it may be good enough to return the latest cached values, updated in a parallel thread.

In case of a hardware/communication error, leave valid=false in the return structure.

Implemented in mpp::MVSIM_VehicleInterface.

◆ motion_execute()

virtual bool mpp::VehicleMotionInterface::motion_execute	(	const std::optional< CVehicleVelCmd::Ptr > &	immediate,
		const std::optional< EnqueuedMotionCmd > &	next
	)

pure virtual

Sends a motion command to the vehicle "immediate" and "next" slots.

A vehicle may accept one or more different implementation-specific CVehicleVelCmd classes.

This method resets the watchdog timer started with startWatchdog()

The vehicle should be able to execute a motion primitive ("immediate" slot) and holding a pending one ("next" slot) which will be moved to the immediate slot when a given condition holds, leaving the "next" slot free.

Possible combinations of calls to this method:

1) immediate set, next not set: replaces whatever the vehicle was doing and executes the given immediate command, dropping possible former immediate and next commands.

2) immediate set, next set: replaces both vehicle execution "slots" with the given commands.

3) immediate not set, next set: should be received by a vehicle only while there is an "immediate" motion command under execution, and the "next" slot is free. This stores a new "next" motion command, leaving the currently-executing one untouched. When the "next condition" holds true, the "next" slot will replace the "immediate" slot and "next" will be free again.

4) immediate not set, next not set: This is a "NOP" motion command, which does not change anything but let the vehicle platform know that there is someone in charge checking the path following and the way is obstacles free and safe to keep moving.

Returns: false on any error.

See also: startWatchdog(), supports_enqeued_motions()

Implemented in mpp::MVSIM_VehicleInterface.

◆ on_apparent_collision()

virtual void mpp::VehicleMotionInterface::on_apparent_collision ( )

inlinevirtual

Callback when the NavEngine predicts a collision with an obstacle and needed to issue a stop command.

◆ on_cannot_get_closer_to_blocked_target()

virtual void mpp::VehicleMotionInterface::on_cannot_get_closer_to_blocked_target ( )

inlinevirtual

Callback when NavEngine cannot reach a specified target location because there are obstacles at the specified target.

◆ on_nav_end()

virtual void mpp::VehicleMotionInterface::on_nav_end ( )

inlinevirtual

Callback if navigation ended by an accepted trigger or reached the last specified waypoint.

◆ on_nav_end_due_to_error()

virtual void mpp::VehicleMotionInterface::on_nav_end_due_to_error ( )

inlinevirtual

Callback if current navigation ended due to some error.

◆ on_nav_start()

virtual void mpp::VehicleMotionInterface::on_nav_start ( )

inlinevirtual

Callback upon starting a new waypointsequence navigation.

◆ on_path_seems_blocked()

virtual void mpp::VehicleMotionInterface::on_path_seems_blocked ( )

inlinevirtual

Callback for when NavEngine cannot make progress to get increasingly closer to the final target during a certain period of time. It may indicate that the high-level path the vehicle is trying to follow is no longer valid due to a blocked way. On your user side, you could call NavEngine::cancel() and/or re-compute an alternative path and issue a new set of navigation waypoints or just report the error to the user.

See also: NavEngine::Configuration::timeoutNotGettingCloserGoal

◆ on_waypoint_reached()

virtual void mpp::VehicleMotionInterface::on_waypoint_reached	(	const size_t	waypoint_index,
		bool	reached_skipped
	)

inlinevirtual

Callback upon reaching a waypoint in a waypoint sequeunce. Mostly used for logging.

Parameters

waypoint_index	index of waypoint in the sequence
reached_skipped	whether it was reached(true) or skipped (false)

◆ robot_time()

virtual double mpp::VehicleMotionInterface::robot_time ( ) const

inlinevirtual

Returns clockwall time (UNIX timestamp as double) for real robots [default], simulated time in simulators.

◆ start_watchdog()

virtual void mpp::VehicleMotionInterface::start_watchdog ( [[maybe_unused] ] const size_t periodMilliseconds )

inlinevirtual

◆ stop()

virtual void mpp::VehicleMotionInterface::stop ( const STOP_TYPE stopType )

pure virtual

Stops the vehicle. Different levels of abruptness in the stop can be considered given the emergency condition or not of the command.

◆ stop_watchdog()

virtual void mpp::VehicleMotionInterface::stop_watchdog ( )

inlinevirtual

◆ supports_enqeued_motions()

virtual bool mpp::VehicleMotionInterface::supports_enqeued_motions ( ) const

inlinevirtual

Reimplement to return true if enqueued motions are supported in motion_execute()

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

/home/docs/checkouts/readthedocs.org/user_builds/selfdriving/checkouts/latest/mrpt_path_planning/include/mpp/interfaces/VehicleMotionInterface.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ VehicleMotionInterface()

◆ ~VehicleMotionInterface()

Member Function Documentation

◆ enqeued_motion_pending()

◆ enqeued_motion_timed_out()

◆ enqued_motion_last_odom_when_triggered()

◆ get_localization()

◆ get_odometry()

◆ motion_execute()

◆ on_apparent_collision()

◆ on_cannot_get_closer_to_blocked_target()

◆ on_nav_end()

◆ on_nav_end_due_to_error()

◆ on_nav_start()

◆ on_path_seems_blocked()

◆ on_waypoint_reached()

◆ robot_time()

◆ start_watchdog()

◆ stop()

◆ stop_watchdog()

◆ supports_enqeued_motions()