Feature / Global Axes and Framework for Enhanced Motion Control

[markmaker]

Description

This PR represents an extensive rework of "all things motion" in OpenPnP. It exposes axes globally in the Machine Model and provides easy and universal setup in the GUI rather the machine.xml as before. It lays the groundwork for many possible Motion Control extensions.

Some highlights:

1. Axes can be defined as global Machine objects and setup in the Machine Setup GUI. They are no longer a proprietary part of the GcodeDriver.
2. Transformed Axes can be defined on top of the physical Controller Axes.
   
3. Axes are assigned to a Driver.
   
4. Axes can be easily mapped to HeadMountables.
   
5. Many settings are now universally available on each axis. Backlash Offset, Soft Limits etc. everything has been unified for easy, repetitive setup. Each axis can now specify individual feed-rate, acceleration and jerk limits.
   
6. Rotary axes can finally have very different feed-rates (degrees vs. mm). Rotary axes can be wrapped around, i.e. they will no longer "wind up" the angle coordinate.
   
7. Multiple Drivers can be mixed (GcodeDrivers and others). They are now treated uniformly (no sub-drivers). All axis specific setup has been removed from the GcodeDriver, the Wizard much simplified.
   
8. Actuators are explicitly assigned to a Driver. There is no more ambiguity, which (sub-) driver handles the Actuator.
   
9. Visual Homing is now universally available on all drivers. It can be managed on the Head.
   
10. The machine simulation (NullDriver, ImageCamera etc.) was greatly enhanced to thoroughly test the substantial rework. An "imperfect" machine has been created to simulate non-squareness, nozzle tip runout, homing error, camera lag, vibration etc. to test the counter-measures, such as non-squareness compensation, nozzle tip calibration, visual homing, camera settling, etc.
11. It also uses "intelligent" pick and place location detection based on the ImageCamera's machine table image. If the simulation tries to pick or place at the wrong location, an exception is thrown (i.e. the UnitTest fails, if SampleJobTest.imperfectMachine is enabled).
    
12. The simulation has been enhanced to provide the now needed precision. Both simulation cameras now render with sub-pixel precision, allowing for much better vision precision. Drawing errors at the table edge have been fixed in the ImageCamera.
13. Virtual Z and C axes can be mapped to down-looking cameras. Those can store and modify coordinates when switching back and forth between a tool and the camera.
    
14. A new MotionPlanner coordinates all motion across the drivers. It has a very similar interface to what the Drivers had before and it must now be used instead. It can plan the motion by predicting the profiles. Both 2nd order (constant acceleration) and 3rd order (jerk controlled) motion control models are supported (at the same time). Motion can therefore even be coordinated across multiple drivers (approximation).
15. Controller Motion is "shaped" by the MotionPlanner, it sets feedrates, acceleration limits and even jerk limits (if you have them) dynamically. For instance, if you set the Speed [%] in the Machine Controls or on a part etc., it now controls all the limits in time-relative manner. So if you set 50%, the move will take exactly twice as long. Not only the feed-rate is reduced, acceleration is reduced to the power of two and jerk to the power of three. The move acts exactly as seen in slow-motion, the acceleration and jerk phases will happen at the same locations along the path.
16. The MotionPlanner is the basis for advanced future developments, where the motion plan can be optimized with motion blending, collision evasion etc. The current implementation is aptly named NullMotionPlanner and does simply execute moves one by one.
17. Much more...
18. Existing machine.xml should be automatically migrated for all users of OpenPnP 2.0. A few minor exceptions have been discussed and dismissed in the group.

Credit: Most images shown here are from the automatically migrated machine definition by Bill. Thanks, Bill!

Justification

The justification has been discussed and confirmed in the group.
https://groups.google.com/g/openpnp/c/bEVZvYoXO98/m/hl14FcspBwAJ

Instructions for Use

Full instructions for new users (Wiki) will take much additional time. I would like to call for some help with that, perhaps in the group.

For existing users with machine.xml experience, this should be mostly easy. After some fun with simulation, there is a rudimentary after-migration guide further down.

Simulation Test

For those who just want to have a look, please use the "Imperfect machine" simulation.

machine.zip

Have a look around. Play with the Simulation settings.

Why not try ridiculous vibrations and then test Camera Settling... :-)

Load and run the pnp-test.job.xml as described here.

Real World Test - General Note of Caution!

The motion control rework and the auto-migration has been very carefully crafted and thoroughly tested, as far as possible on my rather simple single nozzle machine. But I cannot give any guarantees whatsoever! Please be very careful when testing this on the real machine. Keep your hand on the Emergency Button. Baby steps first.

Make sure you have switched off auto-homing on the Machine, so you can enable the machine and then try some small Jogs first:

Note, the migration should create a workable machine. But in order to use some of the new features, we need to tweak some things.

Remember: When you fiddle with the Machine Setup: Always Backup, Backup, Backup!

Try get rid of Pre-Move Commands

The controller should be driven in true multi Axis mode i.e. so that all Axes can be driven directly and in any combination. If you have a Smoothieware Controller, you certainly don't need Pre-Move Commands anymore. Configure the controller for multi-axes setup.

Then switch them off in the driver:

You then need to change your MOVE_TO_COMMANDs as shown below.

Axis Letters and Variables

Each Axis has a letter designator as used in G-code. You can now specify the proper Letter on the Axis:

Warning: The migration takes a simple guess, but if you want to use this feature, please check each axis carefully!

New universal MOVE_TO_COMMAND

Now you need to rework your MOVE_TO_COMMAND and use the Axis Letters instead of the generic Axis Type names (X, Y, Z, Rotation). Most users will at least have to replace Rotation with the proper Axis Letter. While we're at it, we can insert the proper G-code to set acceleration (and possibly jerk) limits on the move command:

The command must now include all your controller axes, so if you have multiple Z and/or C axes, you need to list them all with their controller letters in the Default MOVE_TO_COMMAND. In that case you almost certainly have other MOVE_TO_COMMAND on individual HeadMountables with different axes mapped trough slightly different G-code. Remember how complicated this was? Get rid of those!

Congratulations! You now have one simple and universal MOVE_TO_COMMAND per driver. That's not just easier, it is also a preparation for the future! OpenPnP is now able to move all the axes at once. The MotionPlanner is not there yet, but it could pre-rotate all the nozzles at once, using the travel time to bottom vision.

New SET_GLOBAL_OFFSETS_COMMAND

After Visual Homing, OpenPnP must set the physical axis position to new global offsets. This was formerly done with the POST_VISION_HOME_COMMAND (this command is still working in "legacy mode" as long as no SET_GLOBAL_OFFSETS_COMMAND is defined).

The same comand should now also be used wrapping around a rotary axis. Therefore a new universal SET_GLOBAL_OFFSETS_COMMAND is introduced, that gives OpenPnP the ability to reset any axis to new coordinates.

You can move the old command over to SET_GLOBAL_OFFSETS_COMMAND. Then again list all the axes of your controller and use the proper controller Axis Letters as variables:

You can now the delete the old POST_VISION_HOME_COMMAND:

Switch on Letter Variables Mode

GcodeDriver can now be switched into Letter Variables mode:

Enable Rotary Axis Wrap-Around

Because we have the SET_GLOBAL_OFFSETS_COMMAND defined, we can switch rotary axis Wrap-Around on:

Once the wrap around occurs, OpenPnP will rest the controller to the wrapped coordinate. this works similar to a Modulo operation.

Try rotating all in the same direction until it wraps around. Look at the DRO.

Tune your Axes

Now that each Axis has its own set of feed-rate, acceleration and optionally jerk limit, you can tune those from the migration guesstimate. The rotary axes will certainly need revisiting. Formerly, they were driven with the same feed-rate limits as the linear axes, i.e. degrees were handled the same as millimeters. But 180mm is quite a long move, whereas a turn of 180° should be certainly faster.

Delete the Feed-Rate Limit on the Driver

For 3D-printers, router mills, laser cutters etc. it is important that they move at the same speed, regardless whether a move is parallel to an axis such as X, Y or in a diagonal. The extrusion, the milling, the laser cutting needs to be done at the same speed to be consistent. Therefore the feed-rate limit of a CNC machine is measured along the so-called tool-path. If the tool-path is a diagonal, the X and Y axes will move slower to accomodate that. For a 45° diagonal an axis moves at 1/√2 or about 71% of the nomal speed.

For PnP we don't need consistent speeds. We want the maximum speed available from the axes. If you delete the GcodeDriver's limit, the MotionPlanner will compensate that for you:

For diagonal moves your PnP machine will now be up to √2 or ~141% faster than before!

... unless you knew how to trick OpenPnP before.

Slow Motion ... or if you tricked OpenPnP before

The way the Speed [%] work has changed. The MotionPlanner will now also shape the acceleration (and perhaps even jerk) limit. The resulting motion will act as if in slow motion, it will be smoother and take longer as before. This might mean you can now increase the speed factors a bit with no harm. One example is the nozzle tip Tool Changer, where I observe much smoother operation now:

... or if you tricked OpenPnP before...

The trick was to set the feedrate to some very high number in the GcodeDriver, so it became ineffective and the axis limits set in your controller config would apply instead. The problem: your Speed [%] didn't really work then i.e. you needed to set ridiculously small percentages for effect. If you did this (I did), you certainly need to revise your nozzle tip Tool Changer and similar settings.

Implementation Details

1. The changes were extensively tested in simulation, new UnitTest were written, old ones expanded. Then a thorough test on my machine followed. Though I must say that I never tested a physical multi-nozzle machine, certain axis transforms remain therefore untested.
2. I did follow the coding style.
3. I made changes in the org.openpnp.spi or org.openpnp.model packages, roughly discussed in the group thread.
4. Succesful mvn test before submitting the Pull Request, including the "Imperfect Machine" unit test option.

You can enable the "Imperfect Machine" unit test option, by setting SampleJobTest.imperfectMachine to true. The test then takes about 2 min. on my machine. If this is acceptable, it could be permanently enabled.

[ian-arkver]

Hi Mark. This looks like a great improvement. Might it be worth squashing some of those commits? Also, there's much more (good) work done in this one PR than is implied by the title. The write-up is impressive.

Regards,
Ian

[markmaker]

Hi Ian

Thanks! I guess Jason could squash it when he merges it, Github has this option.

Personally, I don't believe much in (premature) squashing, because time and again it was valuable to trace one's own steps and retrieve some bits and pieces from earlier revisions (and you never know in advance). This PR has evolved quite a bit and it was thoroughly remodeled multiple times, some approaches wildly different and huge code blocks thrown out again (like a full numeric solver port from C).

_Mark

[ian-arkver]

That's a handy GH feature.

I tend to give my R&D branch a new name to keep it around for rework/posterity, then rebase interactive to get a cleaner version for public comment. As an occasional Linux kernel contributor and long time mailing list lurker I know they need the commits to be clean and concise for review.

Anyway, whatever Jason's happy with, ofc. :-)

Regards,
Ian

[markmaker]

Hi Ian

To be honest, I'm not a GitHub expert at all. It simply never occurred to me that someone might look at individual commits in a PR while it is not yet merged. Just the diff.

Technically, at that time, it is still a part of my forked repo, right? At least that's what the command-line instructions for a pull of this PR suggest:

git checkout -b "markmaker-feature/global-axes" "develop"
git pull https://github.com/markmaker/openpnp.git "feature/global-axes"

I understand that the PR should be squashed in the end, when it is merged into Jason's repo, so it appears as one commit at one time in history, can easily be reverted and blamed etc. I thought this insulation is exactly one of the reasons, why one uses the GitHub forking pattern.

But I'm open to suggestion. @vonnieda, any preferences/recipes?

_Mark

[ian-arkver]

Hi Mark,

Yes, your commits are absolutely your own and live in your forked repo, until the PR is merged - however Jason chooses to do that.

The only reason to squash them into more manageable chunks would be to help a code reviewer. Linux is obviously super-strict about that, but maybe openPnP is a bit more laid back. Maybe just looking at the final diff would be enough, but this is a big series.

Anyway, just my $0.02, and all projects and maintainers are different.

CU,
Ian

[markmaker]

Hi @vonnieda

Could we merge this into openpnp:test for non-developer users to be able to test it easily?

Thanks,
_Mark

[vonnieda]

Yea, will get it merged this evening. Sorry - been a busy week.

…

On Wed, Aug 12, 2020 at 2:04 AM markmaker ***@***.***> wrote: Hi @vonnieda <https://github.com/vonnieda> Could we merge this into openpnp:test for non-developer users to be able to test it easily? Thanks, _Mark — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1035 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAJAU44OU2OOLORPEH7VXGLSAI5HHANCNFSM4PZNZDTA> .

[vonnieda]

Merged! Thank you for all your work on this @markmaker - I'm very excited to start testing it!

[markmaker]

Wiki images. Do not delete.

---