Update UBL documentation for Marlin 1.1.6

[bjarchi]

See MarlinFirmware/Marlin#8491 for discussion.

This is an update to the UBL documentation - mostly in unified_bed_leveling.md with some small additions to G029-ubl.md - to bring things up to date for Marlin 1.1.6. In particular, I added addenda related to using UBL without a (conforming) LCD display and to using UBL without a Z-probe. Also added a section specifically on using G29 P3 to fill in the mesh in 'smart' mode.

I consider this a first draft that may be ready for publication; I wanted to get eyes on the PR as early as possible since it is my first contribution to the project.

[Roxy-3D]

There is also still a line in configuration section that reads:

For delta printers define... (???)

For Delta printers... The mesh points should be filled in and valid within the DELTA_PRINTABLE_RADIUS. And there should be a border of valid mesh points just outside of the DELTA_PRINTABLE_RADIUS. This is necessary to insure the UBL System has all corners of the mesh cell defined for the entire printable area.

So however the Bed_Size and Printable_Radius are define by the user... The user should insure they have an extra circle of mesh points defined just outside the printable radius.

[bjarchi]

OK, fixed the mesh grid definition guidelines for both Cartesian and delta printers.

The only thing left that I wasn't sure about (and can't verify due to no LCD) are a couple of points in the 'no z probe' section related to using G29 P3 w/ vs w/o the C argument.

[Roxy-3D]

The only thing left that I wasn't sure about (and can't verify due to no LCD) are a couple of points in the 'no z probe' section related to using G29 P3 w/ vs w/o the C argument.

This is pretty simple... If a C is given, the P3 command knows that is what the user wants to use to fill the number of mesh points specified with an 'R' option. (The points will be done as close to the nozzles current location as possible.)

If the C is not given, that flips the G29 P3 into 'Smart Fill Mode' and it will apply its algorithms to fill in unprobed (or invalidated) mesh points. The algorithm is different for Cartesian and Delta's. For Cartesian's, it will fill in one line at a time in each direction. If the user has a large X or Y Probe_Offset, it is possible multiple G29 P3's will be needed to fill in everything. It would be easy enough to make it so a single G29 P3 fills everything in. But especially with a large X or Y _PROBE_OFFSET_FROM_EXTRUDER it is very possible the user needs more control and needs to edit some of the filled in points prior to filling in the next line.

[bjarchi]

OK very good.

This is pretty simple... If a C is given, the P3 command knows that is what the user wants to use to fill the number of mesh points specified with an 'R' option. (The points will be done as close to the nozzles current location as possible.)

So G29 P3 Cxxx Rn fills the nearest n points with whatever value is given by Cxxx

And without C & R it operates in smart fill mode one line at a time. On my machine it looks like it's filling that one line (I can probe 4x5 of a 5x5 mesh) with the same values as the nearest line. Is there any way to specify continuing the slope of the nearest cells, or is this a place where I then use M421 to nudge the mesh points?

How would the 'smart fill' algorithm handle the case where one asks to fill in points in the middle of a mesh? For example, user manually probed center and 4 corners of a 3x3 or 5x5 mesh and then wants to fill in the rest?

I'll push fixes to that last section (the P3 usage w/o probe) soon. Thanks again for taking the time to help me out here!

Edit: what's with the failing CI check? Seems to be a broken link in one of the LCD documents - I can try to fix, or not since it's not related to the topic of this PR.

[Roxy-3D]

So G29 P3 Cxxx Rn fills the nearest n points with whatever value is given by Cxxx

Yes. Except there is a hardly ever used sub-option here. Instead of using the nozzles position to search for the closest points to fill in... The user can specify X & Y for the starting search position. I'm not sure that is worth documenting. Or if so... Maybe just say the user can over ride the nozzle's location and shift the search to use an X & Y specified location.

And without C & R it operates in smart fill mode one line at a time. On my machine it looks like it's filling that one line (I can probe 4x5 of a 5x5 mesh) with the same values as the nearest line.

It depends on the direction of the bed tilt. UBL was designed to be as 'safe' as possible to use. If the bed is tilting upwards towards the undefined mesh points... That upward tilt will be extrapolated. If the bed is tilting downwards towards the undefined mesh points, the nearest mesh point is used just because that is safer and has less of a chance of gouging the nozzle into the glass.

The Delta's algorithms are different. But they seem to generate pretty reasonable results. Also, it might help to point out that on both the initial probing and the G26 pattern drawing... The nozzle expands outward from the starting location. That does result in some extra back and forth travel. But this was done deliberately because a 'flat' bed can only deviate so much from one position to the next. If everything is done with an increasing radius from the starting location, the user can watch and make sure the nozzle isn't going to be driven into the bed. If the nozzle starts getting too close, hopefully the user is alert enough to abort the current operation (with a press and hold of the Encoder Wheel).

Is there any way to specify continuing the slope of the nearest cells, or is this a place where I then use M421 to nudge the mesh points?

Yes. You can nudge the mesh points any where your want them. But really, there is no harm doing a G26 and seeing how far off they are. And then quickly edit them closer with a G29 P4 R. With that said, M421 will edit a mesh point if that makes sense to do.

How would the 'smart fill' algorithm handle the case where one asks to fill in points in the middle of a mesh? For example, user manually probed center and 4 corners of a 3x3 or 5x5 mesh and then wants to fill in the rest?

My guess is it won't work very well. I've never tried that. The algorithm's comments are this:

  /**
   * 'Smart Fill': Scan from the outward edges of the mesh towards the center.
   * If an invalid location is found, use the next two points (if valid) to
   * calculate a 'reasonable' value for the unprobed mesh point.
   */

You need two valid mesh points next to an invalid mesh point in order to determine if things are sloping up or down. And depending on the direction of the bed's slope, different things happen.

I'll push fixes to that last section (the P3 usage w/o probe) soon. Thanks again for taking the time to help me out here!

Thank You!

Edit: what's with the failing CI check? Seems to be a broken link in one of the LCD documents - I can try to fix, or not since it's not related to the topic of this PR.

Unknown.... But don't worry about it. When we are ready to merge, we can just force it if necessary. One way or the other.... Your updates will get there.

[bjarchi]

Yes. Except there is a hardly ever used sub-option here. Instead of using the nozzles position to search for the closest points to fill in... The user can specify X & Y for the starting search position. I'm not sure that is worth documenting. Or if so... Maybe just say the user can over ride the nozzle's location and shift the search to use an X & Y specified location.

OK, I've added a quick point on this in the section on filling in the mesh where I refer to using the C form of G29 P3 to fill with a constant.

As for the rest I think I have a good balance between enough detail and not overwhelming people, and all of the things I had labeled [check] have been resolved. I'm comfortable calling it 'finished,' pending feedback or edits from yourself or others.

Again, thank you for the discussion. This has been most illuminating!

Unknown.... But don't worry about it. When we are ready to merge, we can just force it if necessary. One way or the other.... Your updates will get there.

I tried to look into it briefly, and it looks like maybe a dead link from _development/lcd_language.md to a header file that's been renamed... but I'm not confident about that so I'm leaving it alone :)

[Roxy-3D]

I'm comfortable calling it 'finished,' pending feedback or edits from yourself or others.

I understand what you are trying to do with the [Z L] notations. But I'm having trouble. Does the [L] or the [Z] mean the text is invalid without that item? I'm sure I'm just having a brain fart. But maybe we can make those foot notes easier for the initiated to understand what they are saying??? (I'll look at it again closer in the morning. It is very possible the problem is sitting in front of my keyboard.)

[bjarchi]

Yeah I wasn't so sure about those once I finished everything. I tried to explain at the beginning of the synopsis (end of 1st para):

As much as possible, areas of the main documentation that differ when working without a display or without a z-probe are marked with [[L][noLcd]] and [[Z][noZ]], respectively. Note that operation without an LCD is still work-in-progress, and subject to change.

but I'm not sure it's really effective. Let me know what you think (or just remove them :)) once you've looked again with fresh eyes

[Roxy-3D]

There are not that many places where not having one of them makes a big difference. It maybe that we should just add an extra sentence at the end of the G29 P2, G29 P4 and G26 describing the impact of not having each of those options. (And of course... spell out that G29 P1 is not an option without a Z-Probe.)

It is much less of an issue... But the J mesh tilting commands are not available right now without a Z-Probe. In the future we plan to always have a 'Manual Probe' available on all systems (assuming there is an LCD Panel). So when that happens, the J commands will become available even without a Z-Probe.

UPDATE: Just a quick head's up... I've made a branch to make it so Bi-Linear can use the G26 Mesh Validation Tool. I'm not sure it makes sense to merge immediately. It might make sense to leave things the way they are until the v2.0.0 becomes the main branch. But I'm untangling things so Bi-Linear and the original Mesh leveling can use G26.

[bjarchi]

Sorry, I was pretty hosed today. I should have time to clean things up tomorrow.

There are not that many places where not having one of them makes a big difference. It maybe that we should just add an extra sentence at the end of the G29 P2, G29 P4 and G26 describing the impact of not having each of those options. (And of course... spell out that G29 P1 is not an option without a Z-Probe.)

This seems like a good way to go. Or even just emphasize the line in the first paragraph about things being different with no lcd or no probe, and handle all that stuff in the addenda.

It is much less of an issue... But the J mesh tilting commands are not available right now without a Z-Probe. In the future we plan to always have a 'Manual Probe' available on all systems (assuming there is an LCD Panel). So when that happens, the J commands will become available even without a Z-Probe.

Good to know. I'll see if it makes sense to work that into the UBL start page somewhere, or possibly the G29 UBL page. I'm thinking about copying the chart of 'useful gcode sequences' from the UBL start page to the G29 UBL page too, so there is some usage reference there.

UPDATE: Just a quick head's up... I've made a branch to make it so Bi-Linear can use the G26 Mesh Validation Tool. I'm not sure it makes sense to merge immediately. It might make sense to leave things the way they are until the v2.0.0 becomes the main branch. But I'm untangling things so Bi-Linear and the original Mesh leveling can use G26.

That's great!

What is the timeline for 2.0. becoming the main branch? And if I understand correctly, the plan is for it to run on both 32 bit ARM and 8-bit platforms - how does that work with taking advantage of the advanced functionality that ARM enables? Is there a reference doc somewhere for the plan and organization of 2.0.0? v2 seems like where I should jump in when I do have a chance to start contributing code.

[Roxy-3D]

Good to know. I'll see if it makes sense to work that into the UBL start page somewhere, or possibly the G29 UBL page. I'm thinking about copying the chart of 'useful gcode sequences' from the UBL start page to the G29 UBL page too, so there is some usage reference there.

Here is something else to consider... We have a 'Start up sequence' of G29 commands that should get the 'normal' user up and running. It probably makes sense to have a 'Start up sequence of G29 commands' for both the No-Z-Probe case and the No-LCD-Display case. Maybe we should have a separate section (with the appropriate start up sequence) for each topic??? What I'm thinking is in those sections we could have a discussion of what the issues are and maybe comments on each start up command describing what is being done???

What is the timeline for 2.0. becoming the main branch? And if I understand correctly, the plan is for it to run on both 32 bit ARM and 8-bit platforms - how does that work with taking advantage of the advanced functionality that ARM enables? Is there a reference doc somewhere for the plan and organization of 2.0.0? v2 seems like where I should jump in when I do have a chance to start contributing code.

Some of us have 32-bit platforms actually printing using the v2.0.0 branch. I am not quite at that point. But mostly that is because I'm trying to get UBL to be up and running correctly on the 32-bit platforms.

Mostly... v2.0.0 is the bugfix-v1.1.x branch with two changes. It has the HAL (Hardware Abstraction Layer) support for the 32-bit boards. And it has the code re-organized. Other than that, the two branches are very similar. The code and feature set has deliberately been kept as identical as possible. I don't know how long it will be until we are comfortable freezing the bugfix-v1.1.x branch. But my guess is it will be 3 or 4 weeks.

[bjarchi]

Here is something else to consider... We have a 'Start up sequence' of G29 commands that should get the 'normal' user up and running. It probably makes sense to have a 'Start up sequence of G29 commands' for both the No-Z-Probe case and the No-LCD-Display case. Maybe we should have a separate section (with the appropriate start up sequence) for each topic??? What I'm thinking is in those sections we could have a discussion of what the issues are and maybe comments on each start up command describing what is being done???

I did include this in the specific addenda for each of those cases - both a description of the issues, and a 'canonical' startup sequence. Maybe I need to call that out and link to the addenda in the line above that 'normal use' startup sequence?

Also, looking at the gcode entry for G29 J - is this command basically solely for using a low-res probe to touch up a mesh already in memory? What does J stand for here?

[Roxy-3D]

I did include this in the specific addenda for each of those cases - both a description of the issues, and a 'canonical' startup sequence. Maybe I need to call that out and link to the addenda in the line above that 'normal use' startup sequence?

Yeah... It is hard to see how things fit together without it merged. I was just looking at the diff's. @Bob-the-Kuhn Do you have any problem with us merging this so we can continue the work a little bit easier? Do you have any recommendations for how to clean up the Travis errors?

Also, looking at the gcode entry for G29 J - is this command basically solely for using a low-res probe to touch up a mesh already in memory? What does J stand for here?

The 'J' commands are mostly there for completeness. I don't use them. But an easy scenario where they would help is for the person that prints on glass. And they take the glass off of the bed after a print and put it in the freezer to release the print. If they are careless and put the glass back on the printer's bed with a small piece of plastic under the glass, that will cause the 'well tuned mesh' to be tilted. The 'J' commands will compensate for that tilt.

It really has nothing to do with the resolution of the Z-Probe. (Except the Z-Probe better be returning some what accurate numbers or you will be un-doing all the previous work of editing the mesh with G26 and G29 P4's.) 'J' is just one of the letters that was available. The feature used to use 'G' for Grid but the GCode nazi's felt that was such a blasphemous thing to do they couldn't live with it.

[bjarchi]

Yeah... It is hard to see how things fit together without it merged. I was just looking at the diff's. @Bob-the-Kuhn Do you have any problem with us merging this so we can continue the work a little bit easier? Do you have any recommendations for how to clean up the Travis errors?

I think I got the travis errors taken care of!

[bjarchi]

Let's not merge it quite yet - I haven't removed the [L] / [Z] tags and I agree that they make it hard to follow. I'll take care of that and the callout to the addenda above that gcode block and then I think it should be good to go.

FWIW, getting the Jekyll/buildroot system setup on my machine was pretty easy, and it makes it a lot easier to preview than just looking through the diffs. What platform do you work on?

[Roxy-3D]

FWIW, getting the Jekyll/buildroot system setup on my machine was pretty easy, and it makes it a lot easier to preview than just looking through the diffs. What platform do you work on?

I'm on Windows. And it does look like the Travis errors are gone now! We can merge any time you are comfortable. (I'm comfortable now just because what you have done is an improvement and we can continue the work...)

[bjarchi]

I'm on Windows. And it does look like the Travis errors are gone now! We can merge any time you are comfortable. (I'm comfortable now just because what you have done is an improvement and we can continue the work...)

I'm comfortable with merging now - I removed the [Z]/[L] tags and made the links to the addenda more explicit in the initial synopsis section, and added the 'quickstart' sequences as examples on G029-ubl

I'm on mac but I think the only difference would be getting the initial ruby environment set up. I've been interacting with Sineos on a PR related to the the k-factor tuning script, and he said that setup on Windows was pretty straightforward though.

[Roxy-3D]

OK... Merging now... And we can continue the discussion using the current rendering...

THANK YOU for the help!!!!!

[bjarchi]

I'll leave the branch on my fork open until we're satisfied with the updates.

I'm curious - I can see that the PR was successfully merged into master, but I don't see it rendered to the documentation on marlinfw.org, and I also don't see the changes reflected when I look at master on https://github.com/MarlinFirmware/MarlinDocumentation.

I assume there's some kind of manual build process that has to happen to publish changes to marlinfw.org, but shouldn't I see the changes in the main repo? Did I set up the PR incorrectly?

[Roxy-3D]

I believe the PR and merge happened correctly

I believe there is some secondary steps that have to be taken...

Probably @Bob-the-Kuhn or @thinkyhead can get the changes to show up. Let's give them a day to see this request for help....

[bjarchi]

I think something isn't right with how the PR was created or merged (although I'm not sure how... )

@Sineos had a PR merged more recently to update the linear advance docs, and I can see the results of that in the master branch of the docs repo now, but this PR still isn't showing up in master on github.

Edit: @thinkyhead I see you're mostly merging single commits rather than full branch history. Do you want me to squash/rebase the branch and then re-create the PR? I may need to create a new branch to do that, since I've been pushing to the branch on my side throughout development?

[Roxy-3D]

One of the options we have when we merge is a 'Squash and Merge'. That is what I did. It was Squashed when it got merged. @jbrazio Can you take a quick look and point us in the right direction?

[bjarchi]

One of the options we have when we merge is a 'Squash and Merge'. That is what I did. It was Squashed when it got merged. @jbrazio Can you take a quick look and point us in the right direction?

That's a good option to have! I've been working with git for a few years now, and I still find the manual rebase/squash workflow confusing (and prone to getting messed up)

[bjarchi]

Thanks @thinkyhead ! I don't know what you did but the changes are now visible in the main repo and on the documentation site.

Is there anything I should do differently the next time I set up a PR?

[Roxy-3D]

@bjarchi Hey! Is there any chance of getting you to consider something different? I'm thinking a short 5 minute video of the steps to bring up UBL would be very valuable. The idea came up here: MarlinFirmware/Marlin#7899 (comment)

[thinkyhead]

Is there anything I should do differently the next time I set up a PR?

Nah, you're good. I just had a bug in my publish procedure where it could miss the latest changes from upstream/master if it was publishing. I've revised my script so it should always get them.

[bjarchi]

@bjarchi Hey! Is there any chance of getting you to consider something different? I'm thinking a short 5 minute video of the steps to bring up UBL would be very valuable. The idea came up here: MarlinFirmware/Marlin#7899 (comment)

Sorry for the late reply; I didn't notice the new posts earlier.

This is certainly something I would consider, but I'm not sure I'm the best person for the job in this case...

• I have zero experience with videography. Plenty with still photography, but I've never made the leap into video recording and editing. I do have a CC subscription that should give me Premiere, though.
• Coming from a background in science, I place a lot of emphasis on written communication - to the point where I generally avoid video tutorials in favor of written documentation. In light of that, I'm not sure I'm the best to judge what should go in a video.

Given those caveats though, yes I'm willing to try. Things are pretty busy with work right now, though, so it would likely be the kind of thing I'd undertake during the winter holidays. Is that too slow?