org.openpnp.spi

Interface MotionPlanner

All Superinterfaces:

PropertySheetHolder, Solutions.Subject

All Known Implementing Classes:

AbstractMotionPlanner, NullMotionPlanner, ReferenceAdvancedMotionPlanner

public interface MotionPlanner
extends PropertySheetHolder, Solutions.Subject

The MotionPlanner coordinates motion, homing etc. across multiple drivers. It has a similar interface as the drivers themselves and acts as a black box to abstract from the complexities of multiple, mixed drivers.

In OpenPnP, the Head does not move on it's own. It is moved by the moving of attached objects: Nozzles, Cameras, Actuators, so-called HeadMountables. The HeadMountables specify by which axes they are moved. The axes are in turn assigned to the Driver. When you move a HeadMountable the MotionPlanner will determine which axes are involved and call the drivers accordingly.

The Motion planner may also perform advanced motion planning i.e. it might reorder, blend and interpolate the original moveTo() commands in order to improve performance, reduce machine vibrations etc.

These are the most important tasks:

• Perform home() commands across drivers.
• Accept a sequence of original moveTo() commands.
• Coordinate motion across multiple drivers.
• For advanced MotionPlanners, perform optimization on the sequence.
• As soon as the motion is commited i.e. when waiting for completion, command the drivers to plan and execute the plan.
• Provide access to the planned motion over time for coordination, simulation, visualization etc.

A MotionPlanner can be a simple proxy, just sending commands directly to the drivers. See the NullMotionPlanner. Future advanced MotionPlanners can do nth order Kinematics control, motion blending etc.

The MotionPlanner is an envelope planner i.e. it will only plan the maximum velocity, acceleration, jerk allowed to the controller. It is not a real-time planner, therefore the real physical motion that is later executed by the controller, might be more constrained i.e. take more time. Having said that, it remains a goal to anticipate the controller's motion as good as possible, so that simulation and reality will be very similar and optimizations are purposeful.

An advanced Planner will first record the commands and it may (or may not yet) plan the moves. A waitForCompletion() will force the planning and generate the needed output commands. Note that proper envelope motion control is only possible for complete moves, because the the planner must know when to decelerate in time.

Sometimes, motion might be recorded but no immediate waitForCompletion() is wanted. The most prominent example is jogging, where the planner never knows if and when the user will press another button. In this case up-front envelope motion planning is impossible, at least for the deceleration part. Therefore motion control is mostly left to the hardware controller, perhaps with more conservative deceleration parameters.

The MotionPlanner must plan all the Axes of the machine, across all the Drivers. Therefore driver/controller specific behavior must be modeled per Axis. The MotionPlanner should also try to approximate coordinated motion across controllers. A best-effort approximation should be enough for PnP purposes.

Unless Length and Location are used, units are Millimeters and Seconds.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	MotionPlanner.CompletionType

Nested classes/interfaces inherited from interface org.openpnp.spi.PropertySheetHolder

PropertySheetHolder.PropertySheet

Method Summary

Modifier and Type	Method and Description
void	clearMotionPlanOlderThan(double time) Clear the motion planning older than the given real-time from the history of the motion planner.
Motion	getLastMotion() Get the last planned motion with displacement of axes.
double	getMinimumSpeed()
Motion	getMomentaryMotion(double time) Get the planned motion at a certain time.
void	home() Perform the homing operation.
boolean	isValidLocation(HeadMountable hm, AxesLocation axesLocation)
void	moveTo(HeadMountable hm, AxesLocation axesLocation, double speed, Motion.MotionOption... options) Add a nominal moveTo() command to the motion sequence.
void	setGlobalOffsets(AxesLocation axesLocation) Set the current physical or virtual axis positions to be reinterpreted as the specified coordinates.
void	waitForCompletion(HeadMountable hm, MotionPlanner.CompletionType completionType) Perform a coordinated wait for completion.

Methods inherited from interface org.openpnp.spi.PropertySheetHolder

getChildPropertySheetHolders, getPropertySheetHolderActions, getPropertySheetHolderIcon, getPropertySheetHolderTitle, getPropertySheets

Methods inherited from interface org.openpnp.model.Solutions.Subject

findIssues, getSubjectIcon, getSubjectText

Method Detail

home

void home()
   throws java.lang.Exception

Perform the homing operation. This calls the home() methods of the underlying drivers and resets any virtual axes.

Throws:

java.lang.Exception

setGlobalOffsets

void setGlobalOffsets(AxesLocation axesLocation)
               throws java.lang.Exception

Set the current physical or virtual axis positions to be reinterpreted as the specified coordinates. Used after visual homing and to reset a rotation angle after it has wrapped around. In G-Code parlance this is setting a global offset:

Parameters:

machine -

axesLocation -

Throws:

java.lang.Exception

See Also:

http://www.linuxcnc.org/docs/html/gcode/coordinates.html#_the_g92_commands, http://smoothieware.org/g92-cnc, https://github.com/synthetos/TinyG/wiki/Coordinate-Systems#offsets-to-the-offsets-g92

moveTo

void moveTo(HeadMountable hm,
            AxesLocation axesLocation,
            double speed,
            Motion.MotionOption... options)
     throws java.lang.Exception

Add a nominal moveTo() command to the motion sequence. Planner implementations are free to interpolate, reorder, overlap and even slightly change the motion within the constraints of safe OpenPnP machine logic. - Interpolation might include simulated jerk control for constant acceleration controllers etc. - Optimization might alter motion in the Safe Z Zone, like overlapping Nozzle rotations, Z<->XY motion blending, allowing uncoordinated X/Y moves for best acceleration etc.

Parameters:

hm - The HeadMountable having triggered the move. This is mostly for proprietary machine driver support and might only be a stand-in in some motion blending scenarios.

axesLocation -

speed -

options -

Throws:

java.lang.Exception

waitForCompletion

void waitForCompletion(HeadMountable hm,
                       MotionPlanner.CompletionType completionType)
                throws java.lang.Exception

Perform a coordinated wait for completion. This will force planning and issuing of motion commands to the driver(s) and waiting for completion on all the drivers involved. This must be issued before relying on a specific machine positioning e.g. before capturing camera frames etc.

Parameters:

hm - The HeadMountable to wait for. If a hm's axes map to only a sub-set of drivers, this will not wait for the other drivers and these are free to move on. If null, wait for all the drivers/machine axes.

completionType - The kind of completion wanted.

Throws:

java.lang.Exception

getMomentaryMotion

Motion getMomentaryMotion(double time)

Get the planned motion at a certain time. Works into the future as far as planned and into the past as far as retained. This is used to simulate Camera Views, to analyze excitation by acceleration to predict vibrations etc.

Parameters:

time -

Returns:

getLastMotion

Motion getLastMotion()

Get the last planned motion with displacement of axes.

Returns:

clearMotionPlanOlderThan

void clearMotionPlanOlderThan(double time)

Clear the motion planning older than the given real-time from the history of the motion planner. The MotionPlanner is free to do its own house-keeping and get rid of past planning data before this is called.

Parameters:

time - The start time of the motion to keep. This must be a time returned by waitForCompletion().

isValidLocation

boolean isValidLocation(HeadMountable hm,
                        AxesLocation axesLocation)

Parameters:

hm -

axesLocation -

Returns:

true if the location is valid, i.e. inside soft limits etc.

getMinimumSpeed

double getMinimumSpeed()

Returns:

The allowable minimum speed factor for motion planning. Limits the required precision for computations, interpolation, and decimal encoding in textual form (e.g. G-code).