com.kuka.nav.fleet
Interface FleetManager

All Superinterfaces:

CustomActionRegistry

public interface FleetManager
extends CustomActionRegistry

Interface providing methods to control a mobile robot fleet.

Method Summary

<C extends GraphMotionContainerBase> void	addListener(BaseGraphMotionListener<C> listener) Adds the specified fleet motion listener.
CoordinatedGraphMotionContainer	execute(CoordinatedGraphMotionListener listener, GraphMotion... graphMotions) Submits an array of GraphMotions for execution and blocks until the motions' execution has been finished (i.e., the corresponding CoordinatedGraphMotionContainer's state is GraphMotionState.FINALIZED).
CoordinatedGraphMotionContainer	execute(GraphMotion... graphMotions) Submits an array of GraphMotions for execution and blocks until the motions' execution has been finished (i.e., the corresponding CoordinatedGraphMotionContainer's state is GraphMotionState.FINALIZED).
GraphMotionContainer	execute(GraphMotion graphMotion) Submits a GraphMotion for execution and blocks until the motion's execution has been finished (i.e., the corresponding GraphMotionContainer's state is GraphMotionState.FINALIZED).
GraphMotionContainer	execute(GraphMotionListener listener, GraphMotion graphMotion) Submits a GraphMotion for execution and blocks until the motion's execution has been finished (i.e., the corresponding GraphMotionContainer's state is GraphMotionState.FINALIZED).
CoordinatedGraphMotionContainer	executeAsync(CoordinatedGraphMotionListener listener, GraphMotion... graphMotions) Submits an array of GraphMotions for execution and returns control after the completion of the three phases described below.
CoordinatedGraphMotionContainer	executeAsync(GraphMotion... graphMotions) Submits an array of GraphMotions for execution and returns control immediately after completion of the three phases described in executeAsync(CoordinatedGraphMotionListener, GraphMotion...).
GraphMotionContainer	executeAsync(GraphMotion graphMotion) Submits a GraphMotion for execution and returns control immediately after completion of the three phases described in executeAsync(CoordinatedGraphMotionListener, GraphMotion...).
GraphMotionContainer	executeAsync(GraphMotionListener listener, GraphMotion graphMotion) Submits a GraphMotion for execution and returns control immediately after completion of the three phases described in executeAsync(CoordinatedGraphMotionListener, GraphMotion...).
Collection<Conflict>	getConflicts() Returns an immutable collection of all found conflicts between all active graph motions.
Collection<Conflict>	getConflicts(ConflictFilter filter) Returns an immutable collection of all found conflicts, that are accepted by the specified filter, between all active graph motions.
TopologyGraph	getGraph() Returns the graph currently used by the fleet manager to plan routes.
Collection<GraphMotionContainer>	getGraphMotionContainers() Returns a collection of the execution containers of currently active and queued graph motions.
List<GraphMotionContainer>	getGraphMotionContainers(com.kuka.nav.robot.MobileRobot mobileRobot) Returns a collection of the execution containers of currently active and queued graph motions for a certain robot instance.
boolean	hasCoordinatedGraphMotionListeners() Indicates whether this fleet manager contains coordinated graph motion listeners.
boolean	hasGraphMotionListeners() Indicates whether this fleet manager contains graph motion listeners.
GraphMotionContainer	plan(GraphMotion graphMotion) Submits the given graph motion for planning but pends execution of the motion until resume() is called.
<C extends GraphMotionContainerBase> void	removeListener(BaseGraphMotionListener<C> listener) Removes the specified listener.
ReplanResult	replan(GraphMotionContainer container) Re-plans the given container, pending execution of the resulting plan and returns a re-planning result indicating whether re-planning succeeded or not.
void	resume() Releases the lock held on the fleet manager and resumes execution of all pending graph motion containers.
void	rollback() Rolls back all pending graph motion containers.
void	setFailedMotionCallback(CorrectPlansCallback callback) Sets this fleet manager's callback which is used to correct plans that cannot be completed any more because some other graph motion was cancelled or failed.

Methods inherited from interface com.kuka.nav.fleet.actions.CustomActionRegistry

addEdgeCustomAction, addNodeCustomAction, getEdgeCustomAction, getNodeCustomAction

Method Detail

getGraph

TopologyGraph getGraph()

Returns the graph currently used by the fleet manager to plan routes.

Returns:

the currently used graph

execute

GraphMotionContainer execute(GraphMotion graphMotion)

Submits a GraphMotion for execution and blocks until the motion's execution has been finished (i.e., the corresponding GraphMotionContainer's state is GraphMotionState.FINALIZED). Returns a GraphMotionContainer providing access to state, possible error, runtime information, etc of the graph motion.

Parameters:

graphMotion - the graph motion to execute

Returns:

a container providing access to state and runtime information of the graph motion.

See Also:

executeAsync(CoordinatedGraphMotionListener, GraphMotion...)

execute

GraphMotionContainer execute(GraphMotionListener listener,
                             GraphMotion graphMotion)

Submits a GraphMotion for execution and blocks until the motion's execution has been finished (i.e., the corresponding GraphMotionContainer's state is GraphMotionState.FINALIZED). Returns a GraphMotionContainer providing access to state, possible error, runtime information, etc of the graph motion.

The provided listener will receive all notifications from the returned graph motion container and notifications from this container only.

Parameters:

listener - a graph motion listener, will receive all notifications from the returned graph motion container and those notifications only

graphMotion - the graph motion to execute

Returns:

a container providing access to state and runtime information of the graph motion.

See Also:

executeAsync(CoordinatedGraphMotionListener, GraphMotion...)

executeAsync

GraphMotionContainer executeAsync(GraphMotion graphMotion)

Submits a GraphMotion for execution and returns control immediately after completion of the three phases described in executeAsync(CoordinatedGraphMotionListener, GraphMotion...). Returns a GraphMotionContainer providing access to state, possible error, runtime information, etc of the graph motion. The conatiner's GraphMotionState and runtime information are updated regularly.

Parameters:

graphMotion - the graph motion to execute

Returns:

a container providing access to state and runtime information of the graph motion.

See Also:

executeAsync(CoordinatedGraphMotionListener, GraphMotion...)

executeAsync

GraphMotionContainer executeAsync(GraphMotionListener listener,
                                  GraphMotion graphMotion)

Submits a GraphMotion for execution and returns control immediately after completion of the three phases described in executeAsync(CoordinatedGraphMotionListener, GraphMotion...). Returns a GraphMotionContainer providing access to state, possible error, runtime information, etc of the graph motion. The conatiner's GraphMotionState and runtime information are updated regularly.

The provided listener will receive all notifications from the returned graph motion container and notifications from this container only.

Parameters:

listener - a graph motion listener, will receive all notifications from the returned graph motion container and those notifications only

graphMotion - the graph motion to execute

Returns:

a container providing access to state and runtime information of the graph motion.

See Also:

executeAsync(CoordinatedGraphMotionListener, GraphMotion...)

execute

CoordinatedGraphMotionContainer execute(GraphMotion... graphMotions)

Submits an array of GraphMotions for execution and blocks until the motions' execution has been finished (i.e., the corresponding CoordinatedGraphMotionContainer's state is GraphMotionState.FINALIZED). Returns a CoordinatedGraphMotionContainer providing access to state, possible error, runtime information, GraphMotionContainers of the single motions, etc.

Parameters:

graphMotions - the graph motions to execute

Returns:

a container providing access to state and runtime information of the graph motions.

See Also:

executeAsync(CoordinatedGraphMotionListener, GraphMotion...)

execute

CoordinatedGraphMotionContainer execute(CoordinatedGraphMotionListener listener,
                                        GraphMotion... graphMotions)

Submits an array of GraphMotions for execution and blocks until the motions' execution has been finished (i.e., the corresponding CoordinatedGraphMotionContainer's state is GraphMotionState.FINALIZED). Returns a CoordinatedGraphMotionContainer providing access to state, possible error, runtime information, GraphMotionContainers of the single motions, etc.

The provided listener will receive all notifications from the returned coordinated graph motion container and notifications from this container only.

Parameters:

listener - a coordinated graph motion listener, will receive all notifications from the returned coordinated graph motion container and those notifications only

graphMotions - the graph motions to execute

Returns:

a container providing access to state and runtime information of the graph motions.

See Also:

executeAsync(CoordinatedGraphMotionListener, GraphMotion...)

executeAsync

CoordinatedGraphMotionContainer executeAsync(CoordinatedGraphMotionListener listener,
                                             GraphMotion... graphMotions)

Submits an array of GraphMotions for execution and returns control after the completion of the three phases described below. Returns a CoordinatedGraphMotionContainer providing access to the state, possible error, runtime information, GraphMotionContainers of the single motions, etc. The conatiner's GraphMotionState and runtime information are updated regularly.

The provided listener will receive all notifications from the returned coordinated graph motion container and notifications from this container only.

Execution comprises the following three phases in the given order (note that each phase's behavior may differ according to the underlying implementation of the fleet manager). If one of the phases fails the subsequent phases are not conducted.

1. Disposition: According to the motions' DispatcherFilters and the current fleet's state suitable robots are chosen for each of the given graph motions. All robots that are assigned to a graph, unlocked or locked in the calling thread's lock context (i.e., the same thread acquired a lock on the robot by calling ILockable.lock()), and not already reserved by the fleet manager for some other motion are suitable. Any robot that was chosen during disposition and not already locked in the calling thread's lock context will be locked by the fleet manager in that lock context. If no suitable robot is available for one motion a finalized CoordinatedGraphMotionContainer with a RequiredResourceUnavailableException holding a corresponding error message is returned.
2. Planning: For the dispatched robots and according to the current fleet's state paths to the motions's goal nodes are planned. If no path can be found for one of the robots within 10 seconds a finalized CoordinatedGraphMotionContainer with a NoPlanFoundException holding a corresponding error message is returned.
   Note for coupled planning: Any pair of possible goal poses (position of the goal node with all possible orientations at this node) for which a collision is detected is removed from the goal state, i.e. it can happen that even though there is a collision free goal configuration the FleetManager returns with a NoPlanFoundException. To avoid this behavior use the method GraphMotion.setGoalOrientation(double) to specify a collision free goal configuration.
3. Execution: The plan computed in the previous phase is submitted for execution on the corresponding robots. Execution phase attempts to maximally parallelize execution of the plans such that robots only possibly have to wait at nodes where simultaneous execution would cause a conflict. Parallelization also takes the current fleet's state and graph motions currently being executed into account. Note, that this phase is completed once all given motions have been submitted for execution. Actual execution of the motion will happen asynchronously after control has been returned.

   If the plan cannot be parallelized a finalized CoordinatedGraphMotionContainer with a CorruptPlanException holding a corresponding error message is returned. A parallelized plan is submitted for execution and if an error occurs during execution a finalized CoordinatedGraphMotionContainer with an exception holding a corresponding error message is returned. Note that failure or cancellation of a single one of the given motions will cause cancellation of all other motions in the given array.

If the lock in whose context the graph motions are executed gets lost at any time during execution, the graph motion will be cancelled. Upon finalization of a graph motion all robots that were locked by the fleet manager in the calling thread's locking context will be unlocked. Those that were already locked will stay so.

Parameters:

listener - a coordinated graph motion listener, will receive all notifications from the returned coordinated graph motion container and those notifications only

graphMotions - the graph motions to execute

Returns:

a container providing access to state and runtime information of the graph motion.

executeAsync

CoordinatedGraphMotionContainer executeAsync(GraphMotion... graphMotions)

Submits an array of GraphMotions for execution and returns control immediately after completion of the three phases described in executeAsync(CoordinatedGraphMotionListener, GraphMotion...). Returns a CoordinatedGraphMotionContainer providing access to the state, possible error, runtime information, GraphMotionContainers of the single motions, etc. The conatiner's GraphMotionState and runtime information are updated regularly.

Parameters:

graphMotions - the graph motions to execute

Returns:

a container providing access to state and runtime information of the graph motion.

See Also:

executeAsync(CoordinatedGraphMotionListener, GraphMotion...)

plan

GraphMotionContainer plan(GraphMotion graphMotion)

Submits the given graph motion for planning but pends execution of the motion until resume() is called. This means that only the first two phases with regard to execution of graph motions (cf. executeAsync(CoordinatedGraphMotionListener, GraphMotion...)) are performed. The third phase is only performed upon resumption. The returned graph motion container is in state GraphMotionState.PENDING and allows access to the chosen robot, the found plan, etc. If necessary it is possible to re-plan this container even before it goes to states GraphMotionState.EXECUTING for the first time by calls to replan(GraphMotionContainer).

Any call to this method will pause execution of all graph motions currently being executed in the sense that the executing robots will finish those motions that have already been queued, but no new motions will be queued. Furthermore, calls to this method require a lock on the fleet manager. If this lock is held by a thread different from the calling thread, then this method blocks until the lock-holding thread releases the lock. Lock and pause are released by calling resume().

If execution has not yet been resumed a call to rollback() will cancel any pending GraphMotionContainer which resulted from a call to this method.

Any call to one of the execute(com.kuka.nav.fleet.GraphMotion)- or executeAsync(com.kuka.nav.fleet.GraphMotion)-methods by the lock-holding thread will result in a failed (coordinated) graph motion container. Calls to these methods coming from other threads will be blocked until the lock-holding thread releases the lock. Furthermore, it should be avoided to perform any blocking operations while holding the lock. In particular, any thread holding the fleet manager lock must never wait for any graph motion container to be finished or finalized while holding the lock (in this case any call to any one of the GraphMotionContainer respectively CoordinatedGraphMotionContainer-methods waiting for the corresponding container to be finished or finalized will throw an IllegalStateException).

The behavior with regard to robot-specific locks is the same as the one for normal execution of graph motions (cf. executeAsync(CoordinatedGraphMotionListener, GraphMotion...)).

Parameters:

graphMotion - the graph motion to be planned

Returns:

a graph motion container providing access to state (GraphMotionState.PENDING until execution is resumed) and runtime information of the graph motion.

See Also:

resume(), rollback(), replan(GraphMotionContainer)

replan

ReplanResult replan(GraphMotionContainer container)

Re-plans the given container, pending execution of the resulting plan and returns a re-planning result indicating whether re-planning succeeded or not. The container's state will change to GraphMotionState.PENDING (if it was not GraphMotionState.FINISHED or GraphMotionState.FINALIZED, yet). Execution can be resumed by calling resume(). Re-planning will fail if the container has already been finished or finalized or if all motions to the motion's goal node have already been queued.

If the container should be re-planned with changed parameters the corresponding graph motion has to be retrieved from the container and adapted accordingly before calls to this method. Note that such changes only become active if re-planning is actually triggered. Changing a parameter without invoking re-planning will not affect the motion container. The following parameters of a graph motion may be changed:

1. via nodes
2. black-list
3. white-list
4. goal node
5. priority (Note that changing the priority also affects the resolution of waiting relations with regard to this graph motion container when further graph motions are commanded in the future. The changed priority will be kept even if re-planning fails.)

Any call to this method will pause execution of all graph motions currently being executed in the sense that the executing robots will finish those motions that have already been queued, but no new motions will be queued. Furthermore, calls to this method require a lock on the fleet manager. If this lock is held by a thread different from the calling thread, then this method blocks until the lock-holding thread releases the lock. Lock and pause are released by calling resume().

If the calling thread holds the lock on the fleet manager (possibly because of previous calls to plan(GraphMotion) or replan(GraphMotionContainer)) an arbitrary number of calls to this method can be made for the same container. Should re-planning fail the container's plan will be restored to the plan that was present before the call to this method. If execution has not yet been resumed a call to rollback() will restore any pending container which went to state GraphMotionState.EXECUTING at least once to the plan it held before the call to this method because of which it went to state GraphMotionState.PENDING.

Any call to one of the execute(com.kuka.nav.fleet.GraphMotion)- or executeAsync(com.kuka.nav.fleet.GraphMotion)-methods by the lock-holding thread will result in a failed (coordinated) graph motion container. Calls to these methods coming from other threads will be blocked until the lock-holding thread releases the lock. Furthermore, it should be avoided to perform any blocking operations while holding the lock. In particular, any thread holding the fleet manager lock must never wait for any graph motion container to be finished or finalized while holding the lock (in this case any call to any one of the GraphMotionContainer respectively CoordinatedGraphMotionContainer-methods waiting for the corresponding container to be finished or finalized will throw an IllegalStateException).

Parameters:

container - the container

Returns:

the re-plan result.

See Also:

resume(), rollback(), plan(GraphMotion), GraphMotionContainerBase.replan()

resume

void resume()

Releases the lock held on the fleet manager and resumes execution of all pending graph motion containers. All pending containers will change to GraphMotionState.EXECUTING. All information stored for rolling back re-planned pending graph motion containers will be cleared, i.e., it is not possible to restore the plans of these containers any more.

Does not have any effect and returns immediately if the calling thread does not hold the lock on the fleet manager.

See Also:

rollback(), plan(GraphMotion), replan(GraphMotionContainer)

rollback

void rollback()

Rolls back all pending graph motion containers. Pending graph motion containers that never started executing will be cancelled and finalized. Pending graph motion containers that have been to state GraphMotionState.EXECUTING at least once will be restored. They will regain the plan they were following the last time they were in state GraphMotionState.EXECUTING and they will stay in state GraphMotionState.PENDING.

This method neither resumes execution nor releases any lock held on the fleet manager. Does not have any effect and returns immediately if the calling thread does not hold the lock on the fleet manager.

See Also:

resume(), plan(GraphMotion), replan(GraphMotionContainer)

setFailedMotionCallback

void setFailedMotionCallback(CorrectPlansCallback callback)

Sets this fleet manager's callback which is used to correct plans that cannot be completed any more because some other graph motion was cancelled or failed.

Parameters:

callback - the callback to be set

getGraphMotionContainers

Collection<GraphMotionContainer> getGraphMotionContainers()

Returns a collection of the execution containers of currently active and queued graph motions.

Returns:

the graph motion containers

getGraphMotionContainers

List<GraphMotionContainer> getGraphMotionContainers(com.kuka.nav.robot.MobileRobot mobileRobot)

Returns a collection of the execution containers of currently active and queued graph motions for a certain robot instance.

Parameters:

mobileRobot - the mobile robot to get the graph motion containers of

Returns:

the graph motion containers dispatched to the given mobile robot

getConflicts

Collection<Conflict> getConflicts()

Returns an immutable collection of all found conflicts between all active graph motions. The result is equivalent to getConflicts(ConflictFilter) when called with ConflictFilters.all().

Note that the returned collection is immutable and thus will not be updated when the state of a conflict changes.

Returns:

a collection of all found conflicts

See Also:

getConflicts(ConflictFilter)

getConflicts

Collection<Conflict> getConflicts(ConflictFilter filter)

Returns an immutable collection of all found conflicts, that are accepted by the specified filter, between all active graph motions.

Note that the returned collection is immutable and thus will not be updated when the state of a conflict changes.

Parameters:

filter - the filter to be applied for each conflict

Returns:

a collection of all found conflicts, accepted by the specified filter

See Also:

getConflicts()

hasGraphMotionListeners

boolean hasGraphMotionListeners()

Indicates whether this fleet manager contains graph motion listeners.

Returns:

true, if this fleet manager has listeners

hasCoordinatedGraphMotionListeners

boolean hasCoordinatedGraphMotionListeners()

Indicates whether this fleet manager contains coordinated graph motion listeners.

Returns:

true, if this fleet manager has listeners

addListener

<C extends GraphMotionContainerBase> void addListener(BaseGraphMotionListener<C> listener)

Adds the specified fleet motion listener. The listener will receive notifications from all active containers of the specified container type.

Type Parameters:

C - type of the containers from which the listener will receive notifications

Parameters:

listener - the listener to be added.

Throws:

IllegalArgumentException - if the listener is null or the same listener is already registered or the given listener is neither a GraphMotionListener nor a CoordinatedGraphMotionListener.

removeListener

<C extends GraphMotionContainerBase> void removeListener(BaseGraphMotionListener<C> listener)

Removes the specified listener.

Type Parameters:

C - type of the containers from which the removed listener received notifications

Parameters:

listener - listener to remove