probe_as_z_home: Initial implementation and documentation

[nickweedon]

This pull request adds the ability to perform multiple probes when issuing a G28 command. More specifically it calls into the 'probe' logic to execute a probe in a way similar to what would be performed during bed mesh creation. Since it uses the same logic this means that the resulting probe also applies the same calc_probe_z_average method to the result.

The benefit of this feature is it allows users with less than perfect probing hardware to still have an unsupervised and reliable homing experience which is crucial to ensure print quality and preventing failed prints due to an incorrect Z homing. Bad homing can even lead to extruder jams and waste significant amounts of the 3D printer user's time. This is a feature that has been requested many times with one such example being Discourse: multiple-samples-on-home-z.

To configure this tool a new configuration section called [probe_as_z_home] should be placed anywhere in the config before the either [safe_z_homing] or [homing_override].

The implementation is completely decoupled from any particular homing or probing method and does not modify any existing code.

[vgdh]

great!

[github-actions]

Thank you for your contribution to Klipper. Unfortunately, a reviewer has not assigned themselves to this GitHub Pull Request. All Pull Requests are reviewed before merging, and a reviewer will need to volunteer. Further information is available at: https://www.klipper3d.org/CONTRIBUTING.html

There are some steps that you can take now:

1. Perform a self-review of your Pull Request by following the steps at: https://www.klipper3d.org/CONTRIBUTING.html#what-to-expect-in-a-review
   If you have completed a self-review, be sure to state the results of that self-review explicitly in the Pull Request comments. A reviewer is more likely to participate if the bulk of a review has already been completed.
2. Consider opening a topic on the Klipper Discourse server to discuss this work. The Discourse server is a good place to discuss development ideas and to engage users interested in testing. Reviewers are more likely to prioritize Pull Requests with an active community of users.
3. Consider helping out reviewers by reviewing other Klipper Pull Requests. Taking the time to perform a careful and detailed review of others work is appreciated. Regular contributors are more likely to prioritize the contributions of other regular contributors.

Unfortunately, if a reviewer does not assign themselves to this GitHub Pull Request then it will be automatically closed. If this happens, then it is a good idea to move further discussion to the Klipper Discourse server. Reviewers can reach out on that forum to let you know if they are interested and when they are available.

Best regards,
~ Your friendly GitIssueBot

PS: I'm just an automated script, not a human being.

[AchilleBailly]

This seems really nice ! I tested it and it works great indeed using the probe config.
However, passing the usual PROBE params to G28 does not work, it would be nice to do so, mainly to be able to do let's say 10 samples for homing but keep 1 or 2 samples when doing the bed mesh.
Do you think that would be possible ?

[nickweedon]

OK so just to clarify, this would be further extending this feature to allow the PROBE params to also be passed to G28.

Do I think this would be a useful change? Absolutely, I think it would be very useful as it would allow you to do a 'quick and dirty home' with just one probe if you just wanted to do a filament change for example and didn't care about precision.

However...
While it is totally possbile and even easy to make this change it would mean that I would actually need to change some existing code both in the 'Probe' and 'BLTouch' modules in order pass these parameters through. Since currently this change is very clean and does not modify any existing module code, I would like to keep it this way for now. I also don't want to add too much scope to this initial change.

If this PR gets approved however then I will create another PR with the change that you suggest :)

Sorry I can't implement this right away but thanks for the great idea!

[AchilleBailly]

Okay I understand you don't wanna have scope creep ahah

Though I quickly tested locally and it seems I can just pass arguments to the probe command this way (l.65-67 of probe_as_z_home.py):

 gcmd = self.gcode.create_gcode_command("PROBE", "PROBE", {"SAMPLES": self.sample_count})
 probe_session = probe.start_probe_session(gcmd)
 probe_session.run_probe(gcmd)

with self.sample_count retrieved from the config section of [probe_as_z_home].

[nickweedon]

@AchilleBailly Nice!
This option makes sense to me so I took your idea and added it to the PR.
I instead implemented this as a optional field in the [probe_as_z_home] config section called 'g28_probe_cmd_args' which allows us to pass additional arguments to the PROBE command.
FYI, I chose to go this route as opposed to adding the same fields in the [probe] section to the [probe_as_z_home] for these reasons:

1. Hard coding these fields would mean that they would need to be updated whenever the [probe] or [bltouch] code changes and adds a new field.
2. Passing these through dynamically does not appear possible since the code base will detect unused fields and raise an error. Additionally it would not be possible to validate these fields without refactoring [probe], [bltouch] and any other similar existing or future code.
3. Given the above limitations, using the 'g28_probe_cmd_args' field is slightly more intuitive IMO since it makes it clear to the user that this takes affect at run time and will not be validated as startup.

Let me know your thoughts though and thanks again for the idea!

[nickweedon]

@AchilleBailly As an aside, I am curious about why you choose to use a different sample count when homing? For me it makes sense to keep this the same as when doing other probing operations.

[vgdh]

@AchilleBailly As an aside, I am curious about why you choose to use a different sample count when homing? For me it makes sense to keep this the same as when doing other probing operations.

For example I do first home probing only once and when bed heated enough i do final probing 5 times.

[nickweedon]

@AchilleBailly As an aside, I am curious about why you choose to use a different sample count when homing? For me it makes sense to keep this the same as when doing other probing operations.

For example I do first home probing only once and when bed heated enough i do final probing 5 times.

That makes sense. I figured there would be use cases like this. I am also curious to know about @AchilleBailly 's use case where he wants to statically configure the probe to act differently during G28 (i..e. via the config, such as what is now possible via the more recent change i made to this PR)

@vgdh Hopefully if this change gets merged in then i will add a new PR to add that feature to be able to specify PROBE parameters via the G28 command. I wonder in the meantime if its possible to do similar via a some kind of jenky macro now with the new g28_probe_cmd_args configuration field I added?

[vgdh]

@AchilleBailly As an aside, I am curious about why you choose to use a different sample count when homing? For me it makes sense to keep this the same as when doing other probing operations.

For example I do first home probing only once and when bed heated enough i do final probing 5 times.

That makes sense. I figured there would be use cases like this. I am also curious to know about @AchilleBailly 's use case where he wants to statically configure the probe to act differently during G28 (i..e. via the config, such as what is now possible via the more recent change i made to this PR)

@vgdh Hopefully if this change gets merged in then i will add a new PR to add that feature to be able to specify PROBE parameters via the G28 command. I wonder in the meantime if its possible to do similar via a some kind of jenky macro now with the new g28_probe_cmd_args configuration field I added?

I wrote some crazy macro do to this functionality, that was not a simple thing 😁.
So it would be nice to have this from the box.

[nickweedon]

@vgdh & @AchilleBailly, yall might also like my other changes: #6778 and #6780.
Combining these with this change i managed to turn my potato 3D printer into a reliable "fire & forget" unit that prints perfect first layers every time.